# PicoCalc words

zeptoforth has support for the PicoCalc, a device that provides a display, keyboard, speakers, and an SD card slot for boards that fit the pinout of a Raspberry Pi Pico 1 (including a Raspberry Pi Pico 1 W, Raspberry Pi Pico 2, Raspberry Pi Pico 2 W, Pimoroni Pico Plus 2, and Pimoroni Pico Plus 2 W). General directions as to the installation and use of zeptoforth on the PicoCalc are detailed in `USING_THE_PICOCALC.md` at the root of this directory tree. This file contains API documentation for the API exposed by the graphical and text-only PicoCalc terminal emulators.

Note that the core that the PicoCalc tasks run on defaults to core 1 of the RP2040 or RP2350, but can be manually set by defining a globally-visible constant in flash named `select-picocalc-tasks-core` prior to compiling PicoCalc support. This is useful if you are also installing zeptoIP on your PicoCalc, as zeptoIP runs very CPU-heavy tasks on core 1 which will significantly slow down the PicoCalc terminal emulator if it is also running on core 1.

### `picocalc-term`

The `picocalc-term` module contains the following words:

##### `term-console`
( -- )

Select the PicoCalc terminal emulator as the console for the current task. If the PicoCalc welcome message has not been displayed yet, display it on the PicoCalc screen. Also, set `term-cols` to the width of the PicoCalc terminal emulator in characters.

##### `with-term-lock`
( xt -- )

Carry out an operation with the PicoCalc terminal locked. Note that executing operations that print to the PicoCalc terminal should be avoided because they may block indefinitely.

##### `with-term-display`
( xt -- ) xt: ( display -- )

Carry out an operation against the PicoCalc terminal's display with the PicoCalc terminal locked. It is highly recommended that the user update the terminal's display or graphics drawn to it may not be displayed. Note that executing operations that print to the PicoCalc terminal should be avoided because they may block indefinitely.

##### `term-pixels-dim@`
( -- width height )

Get the terminal dimensions in pixels.

##### `term-dim@`
( -- width height )

Get the terminal dimensions in characters.

##### `term-char-dim@`
( -- width height )

Get the terminal character dimensions in pixels.

##### `term-font@`
( -- font )

Get the terminal font.

##### `read-battery`
( -- battery-level )

Read the battery level.

##### `set-backlight`
( desired-backlight-level -- actual-backlight-level )

Set the backlight level.

##### `read-backlight`
( -- backlight-level )

Read the backlight level.

##### `set-kbd-backlight`
( desired-kbd-backlight-level -- actual-kbd-backlight-level )

Set the keyboard backlight level.

##### `read-kbd-backlight`
( -- kbd-backlight-level )

Read the keyboard backlight level.

##### `visual-bell-enabled!`
( enabled -- )

Set visual bell enabled. This defaults to false.

##### `visual-bell-enabled@`
( -- enabled )

Get visual bell enabled. This defaults to false.

##### `audible-bell-enabled!`
( enabled -- )

Set audible bell enabled. This defaults to false.

##### `audible-bell-enabled@`
( -- enabled )

Get audible bell enabled. This defaults to false.

##### `screenshot-hook!`
( xt -- )

Set the screenshot hook. This defaults to 0, indicating no hook set.

##### `screenshot-hook@`
( -- xt )

Get the screenshot hook. This defaults to 0, indicating no hook set.

##### `raw-keys-enabled!`
( enabled -- )

Set raw keys enabled. This defaults to false. If the raw keys enabled setting changes, the key input queue is cleared.

##### `raw-keys-enabled@`
( -- enabled )

Get raw keys enabled. This defaults to false.

##### `raw-key>?`
( -- available )

Get whether a raw key is available. This always returns false when raw keys are not enabled.

##### `raw-key>`
( -- attributes key )

Get a raw key; the attributes and key returned here are in terms of those defined by the firmware installed on the PicoCalc's STM32 firmware. If raw keys are not enabled, this will block until they are enabled.

### `picocalc-sound`

The `picocalc-sound` module contains the following words:

##### `play-tone`
( end-tick D: pitch -- )

Generate a tone of *pitch* (an S31.32 value in Hz) ending at *end-tick* relative to `systick::systick-counter`, with ticks being 100 microsecond increments. Note that tones ending earlier override tones ending later, and a total of up to 8 tones are tracked at any one time.

##### `play-tone-for-duration`
( duration D: pitch -- )

Generate a tone of *pitch* (an S31.32 value in Hz) of *duration* ticks, with ticks being 100 microsecond increments. Note that tones ending earlier override tones ending later, and a total of up to 8 tones are tracked at any one time.

##### `beep`
( -- )

This is a convenience word to generate a 1245 Hz, i.e. D6#, tone for 125 milliseconds. This word is used internally to generate the audible bell.

### `picocalc-bios`

The `picocalc-bios` module contains the following words:

##### `emulate-keys?`
( -- flag )

This is a `value` that defaults to `false` that can be set to `true` to enable emulating key presses using the serial console as input. This is primarily of use for testing PicoCalc support without using an actual PicoCalc.

### `picocalc-screenshot`

Compiling `extra/rp_common/picocalc_screenshoto.fs` makes the following words available in the `picocalc-screenshot` module:

##### `screenshot-fs!`
( fs -- )

Set the FAT32 filesystem object for saving screenshots with Attention (Break (Shift-Escape) on the PicoCalc keyboard, Control-T on the serial and USB CDC consoles) `s`. This filesystem defaults to the SD card FAT32 filesystem first, if configured, or the PSRAM FAT32 filesystem second, if configured, or the on-board flash storage FAT32 filesystem third, if configured.

##### `screenshot-fs@`
( -- fs )

Get the FAT32 filesystem object for saving screenshots with the attention key combo.

##### `screenshot-path!`
( path-addr path-bytes -- )

Set the base path for saving screenshots with Attention (Break (Shift-Escape) on the PicoCalc keyboard, Control-T on the serial and USB CDC consoles) `s`. This path defaults to `/SCREEN`. Note that this directory will be automatically created if it does not exist when taking a screenshot with the console attention key combo, but its parent directorie(s) will not be automatically created.

##### `screenshot-path@`
( -- path-addr path-bytes )

Get the base path for saving screenshots with the attention key combo.

##### `take-screenshot`
( path-addr path-bytes fs -- )

This is the actual word that implements the taking of screenshots. Note that when this word is executed directly the display is _not_ flashed unlike when taking a screenshot with the console attention key combo.

### `picocalc-keys`

Compiling `extra/rp_common/picocalc_keys.fs` adds the `picocalc-keys` module.

This module makes use of raw keys, and ignores keypresses and key releases when raw keys are not enabled.

This module contains the following words:

##### `x-key-out-of-range`
( -- )

Keycode out of range exception. Note that for this purpose all keycodes in range 0 <= x < 256 are treated as valid even if they do not correspond to actual keys.

##### `clear-keymap`
( -- )

Clear the keycode map so that all keys are treated as not being pressed.

##### `reset-keymap`
( -- )

Reset the pressed and released states of all keys in the keycode map.

##### `reset-key`
( keycode -- )

Reset the pressed and released state of a single key in the keycode map by keycode.

##### `update-keymap`
( -- )

Update the keymap by reading any queued raw keys in a non-blocking fashion.

##### `wait-update-keymap`
( -- )

Update the keymap by waiting for a raw key to be queued and then reading any queued raw keys in a blocking fashion.

##### `keymap@`
( keycode -- pressed )

Get whether a given key is pressed by keycode up to the last time `update-keymap` or `wait-update-keymap` were called while raw keys were enabled.

##### `keymap-pressed@`
( keycode -- pressed )

Get whether a given key has been pressed since the last time that key was reset by keycode.

##### `keymap-released@`
( keycode -- released )

Get whether a given key has been released since the last time that key was reset by keycode.

### `fat32-tools`

Compiling `extra/rp_common/picocalc_fat32.fs` adds the following words to the `fat32-tools` module:

##### `blocks-fs@`
( -- fs )

This returns the FAT32 filesystem object for the on-board flash 'blocks' FAT32 filesystem if `extra/common/setup_blocks_fat32.fs` has been compiled before `extra/rp_common/picocalc_fat32.fs`.

##### `blocks-fs:`
( -- )

This sets the current FAT32 filesystem to the FAT32 filesystem object for the on-board flash 'blocks' FAT32 filesystem if `extra/common/setup_blocks_fat32.fs` has been compiled before `extra/rp_common/picocalc_fat32.fs`.

##### `sd-fs@`
( -- fs )

This returns the FAT32 filesystem object for the FAT32 filesystem in partition 0 of the SDHC or SDXC card inserted in your PicoCalc unless the constant `no-sd-fs` was defined in flash prior to compiling `extra/rp_common/picocalc_fat32.fs`.

##### `sd-fs:`
( -- )

This sets the current FAT32 filesystem to the FAT32 filesystem object for the FAT32 filesystem in partition 0 of the SDHC or SDXC card inserted in your PicoCalc unless the constant `no-sd-fs` was defined in flash prior to compiling `extra/rp_common/picocalc_fat32.fs`.

##### `psram-fs@`
( -- fs )

This returns the FAT32 filesystem object for the FAT32 filesystem in PSRAM if `extra/rp2350/setup_pico_plus_2_psram_fat32.fs` was compiled before compiling `extra/rp_common/picocalc_fat32.fs`.

##### `psram-fs:
( -- )

This sets the current FAT32 filesystem to the FAT32 filesystem object for the FAT32 filesystem in PSRAM if `extra/rp2350/setup_pico_plus_2_psram_fat32.fs` was compiled before compiling `extra/rp_common/picocalc_fat32.fs`.
