PocketSprite Hardware Abstraction Layer¶

The PocketSprite has a fair amount of hardware, driven by various internal peripherals and GPIOs. It also has some internal communication with the bootloader to boot the various applications that may be installed on it. The HAL manages all this and more. For compatibility and upgradability, it is highly recommended to use the HAL to do low-level things instead of poking the hardware directly.

Header File¶

:component_file:`8bkc-components/8bkc-hal/include/8bkc-hal.h`

Functions¶

int kchal_get_hw_ver()¶

Get PocketSprite hardware version.

Return

-1 if hardware is not a PocketSprite
1 for initial revision of hardware

void kchal_init_sdk(int flags)¶

Initialize SDK.

This is used to initialize the SDK software, allowing SDK functions to be called. It does not initialize any of the hardware.

Warning

For normal use, it is not advised to call this function. Use kchal_init() instead.

Parameters

flags: Bitmap of KCHAL_INIT_* flags

void kchal_init_hw(int flags)¶

Initialize PocketSprite hardware.

This is used to initialize the PocketSprite hardware, allowing hardware-related SDK functions to work.

Warning

For normal use, it is not advised to call this function. Use kchal_init() instead.

Parameters

flags: Bitmap of KCHAL_INIT_* flags

void kchal_init()¶

Initialize PocketSprite SDK and hardware.

Before calling any of the other SDK functions, this function should normally be called. It essentially combines kchal_init_sdk() and kchal_init(). Please call this early in your apps main function.

void kchal_init_custom(int flags)¶

Initialize PocketSprite SDK and hardware in a custom fashion.

Same as kchal_init but takes flags to get custom behaviour

Parameters

flags: Bitmap of KCHAL_INIT_* flags

uint32_t kchal_get_keys()¶

Get keys pressed.

Return: A bitmap of the keys pressed; essentially an OR of all KC_BTN_* values of the keys pressed.

void kchal_wait_keys_released()¶

Wait until all buttons currently pressed are released.

Note: Any keys pressed while this routine is running will not be monitored.

void kchal_send_fb(const uint16_t *fb)¶

Send framebuffer to display.

Note

The kchal_fbval_rgb inline function provides an easy way to calculate pixel values starting from 8-bit RGB values.

Parameters

fb: Pointer to KC_SCREEN_W*KC_SCREEN_H (80x64) 16-bit values. The 16-bit values are defined in 5-6-5 RGB format (RRRRRGGG:GGGBBBBB), BUT with the two bytes swapped, so GGGBBBBB:RRRRRGGG.

void kchal_send_fb_partial(const uint16_t *fb, int x, int y, int h, int w)¶

Send partial framebuffer to display.

Parameters

fb: Pointer to h*w 16-bit values. Values are formatted as kchal_send_fb() describes.
x: Starting horizontal position

void kchal_sound_start(int rate, int buffsize)¶

Start sound subsystem.

This starts up the I2S peripheral and configures the DAC for sound output. It allows you to push a single sound stream to the speaker using kchal_sound_push.

Parameters

rate: Sample rate, in Hz.
buffsize: Buffer size, in bytes. Internally, I2S uses 32-bit samples, so the actual buffer is ((buffsize/4)/rate) seconds.

void kchal_sound_push(uint8_t *buf, int len)¶

Send samples to the sound subsystem.

This function is used to send a number of new samples to the sound subsystem. If the sound buffer is full, this function will block until it is empty enough to store the provided samples and only return then.

Before the data passed here is output to the speaker, it is attenuated by the volume setting first.

Parameters

buf: Samples, as unsigned bytes. (DC = 128)
len: Lenght, in bytes, of the sample buffer buf

void kchal_sound_stop()¶: Stop/deinitialize the audio subsystem.

void kchal_sound_mute(int doMute)¶

Mute audio.

Silences the speakers. Use this when e.g. a game is paused and no data is fed into the audio subsystem anymore using kchal_sound_push.

Parameters

doMute: 1 to mute, 0 to unmute again.

void kchal_power_down()¶

Power down the PocketSprite.

Does the little crt-powering-off animation and puts the PocketSprite in deep sleep, to wake again when the power button is pressed.

When the power button is pressed again, your application will re-start from scratch, with all but the RTC memory wiped clean. If you want to do any savestate saving, do it before you call this.

int kchal_get_chg_status()¶

Get the charging status of the PocketSprite.

Return: One of the KC_CHG_* values

void kchal_set_volume(uint8_t new_volume)¶

Set the volume.

Note: The volume set here is stored in nvram as well and will be kept over a restart or app change.

Parameters

Volume0: is muted, 255 is full volume.

uint8_t kchal_get_volume()¶

Get the current volume.

Return: Volume, 0 is muted, 255 is full volume.

void kchal_set_brightness(int brightness)¶

Set the brightness of the screen.

Parameters

Brightness.: 0 is lowest, 255 is full highest

uint8_t kchal_get_brightness()¶

Set the brightness of the screen.

Return: Brightness. 0 is lowest, 255 is full highest

void kchal_exit_to_chooser()¶

Exit to chooser.

Stops the current app and reboots into the chooser menu, where the user can e.g. select a different app to run. This function does not return.

void kchal_set_new_app(int fd)¶

Set new app to start after deep sleep.

Set a new app to start after deep sleep is over.

This function is mostly used for chooser use (to start a new, chosen app) but can also be used by individual apps. Call kchal_boot_into_new_app to actually reboot into the new app.

Parameters

fd: The AppFS fd of the app to start

int kchal_get_new_app()¶

Get app set by set_new_app.

Return: new app as set by kchal_set_new_app, possibly from the chooser or another app

void kchal_boot_into_new_app()¶

Boot into the app chosen using kchal_boot_into_new_app.

This function does not return.

int kchal_get_bat_mv()¶

Get the current battery voltage in millivolt.

Return: Current battery voltage

int kchal_get_bat_pct()¶

Get the estimated battery full-ness, in percent.

Return: Battery full-ness, 0-100. 0 is empty, 100 is entirely full.

void kchal_cal_adc()¶

Re-calibrate the ADC when the battery is fully charged.

Used during ATE. Please do not call from apps.

nvs_handle kchal_get_app_nvsh()¶

Get the NVS handle for the current app.

To facilitate storing things like high-scores, preferences etc, it is possible to use the NVS subsystem of esp-idf. To stop namespace clashes, the PocketSprite SDK allocates a namespace for each installed app. Use this call to get a handle to that namespace; feel free to save whatever fragment you like into it. Please do not use more than a few K here: the NVS partition is shared between all apps. For larger storage, please write to an AppFs file.

static uint16_t kchal_fbval_rgb(uint8_t r, uint8_t g, uint8_t b)¶

Calculate a value for a pixel in the OLED framebuffer from a triplet of 8-bit RGB values.

Parameters

r: Red value (0-255)
g: Green value (0-255)
b: Blue value (0-255)

Macros¶

KC_BTN_RIGHT¶: ‘Right’ on D-pad is pressed

KC_BTN_LEFT¶: ‘Left’ on D-pad is pressed

KC_BTN_UP¶: ‘Up’ on D-pad is pressed

KC_BTN_DOWN¶: ‘Down’ on D-pad is pressed

KC_BTN_START¶: ‘Start’ button is pressed

KC_BTN_SELECT¶: ‘Select’ button is pressed

KC_BTN_A¶: ‘A’ button is pressed

KC_BTN_B¶: ‘B’ button is pressed

KC_BTN_POWER¶: ‘Power’ button is pressed

KC_BTN_POWER_LONG¶: ‘Power’ button is pressed and held longer than 1.5 seconds

KC_CHG_NOCHARGER¶: No charger attached, running from battery

KC_CHG_CHARGING¶: Charger attached, internal battery is charging

KC_CHG_FULL¶: Charger attached, battery is fully charged.

KC_SCREEN_W¶: Screen width, excluding bezel area

KC_SCREEN_H¶: Screen height

KCHAL_INIT_NO_STDOUT_HDL¶: Do not install custom stdout handler