CDC Badge OS plugin host API - canonical C ABI contract. More...

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

Classes
struct	host_tm
struct	wifi_scan_result_t
struct	ble_char_def_t
	One characteristic of a plugin GATT service (peripheral role). More...
struct	ble_service_def_t
	A plugin GATT service definition (peripheral role). Always primary. More...
struct	ble_scan_result_t
	One device from a central scan. More...
struct	ble_remote_char_t
	One characteristic discovered on a connected peer (central role). More...
struct	ui_item_t

Macros
#define	HOST_API_LEVEL_MAJOR 0
#define	HOST_API_LEVEL_MINOR 7
#define	HOST_API_LEVEL_STR "0.7"
#define	HOST_API_LEVEL_PACKED (((uint32_t)HOST_API_LEVEL_MAJOR << 16) \| HOST_API_LEVEL_MINOR)
#define	HOST_OK 0
#define	HOST_ERR_GENERIC -1
#define	HOST_ERR_INVALID_ARG -2
#define	HOST_ERR_NO_CAPABILITY -3
#define	HOST_ERR_NOT_FOUND -4
#define	HOST_ERR_TIMEOUT -5
#define	HOST_ERR_NO_MEMORY -6
#define	HOST_ERR_BUSY -7
#define	HOST_ERR_NOT_SUPPORTED -8
#define	HOST_ERR_RMEM_FULL -9
#define	LOG_LEVEL_ERROR 0
#define	LOG_LEVEL_WARN 1
#define	LOG_LEVEL_INFO 2
#define	LOG_LEVEL_DEBUG 3
#define	LOG_LEVEL_VERBOSE 4
#define	POWER_SRC_UNKNOWN 0
#define	POWER_SRC_BATTERY 1
#define	POWER_SRC_USB 2
#define	CHARGE_NOT_CHARGING 0
#define	CHARGE_PRE_CHARGE 1
#define	CHARGE_FAST 2
#define	CHARGE_DONE 3
#define	CHARGE_FAULT 4
#define	ECC_CURVE_P256 0
#define	ECC_CURVE_ED25519 1
#define	HOST_RMEM_NAME_MAX 15
#define	HOST_ECC_NAME_MAX 15
#define	HTTP_GET 0
#define	HTTP_POST 1
#define	HTTP_PUT 2
#define	HTTP_DELETE 3
#define	HOST_SOCK_TCP 0
	Protocol selector for host_socket_open.
#define	HOST_SOCK_UDP 1
#define	BLE_PROP_READ 0x02
#define	BLE_PROP_WRITE_NO_RSP 0x04
#define	BLE_PROP_WRITE 0x08
#define	BLE_PROP_NOTIFY 0x10
#define	BLE_PROP_INDICATE 0x20
#define	UI_ICON_NONE 0
#define	UI_ICON_SUCCESS 1 /* smiley */
#define	UI_ICON_ERROR 2 /* dark smiley */
#define	UI_ICON_HEART 3 /* favorite */
#define	UI_ICON_DIAMOND 4
#define	UI_ICON_CLUB 5
#define	UI_ICON_SPADE 6
#define	UI_ICON_BULLET 7
#define	UI_ICON_INVERSE_BULLET 8 /* remove / delete */
#define	UI_ICON_CIRCLE 9 /* info / hollow circle */
#define	UI_ICON_INVERSE_CIRCLE 0x0A
#define	UI_ICON_MALE 0x0B
#define	UI_ICON_FEMALE 0x0C
#define	UI_ICON_MUSIC 0x0D
#define	UI_ICON_NOTES 0x0E /* scene / playlist */
#define	UI_ICON_SUN 0x0F /* brightness / light */
#define	UI_ICON_PLAY 0x10 /* action / switch / submenu */
#define	UI_ICON_REVERSE_PLAY 0x11 /* back */
#define	UI_ICON_UPDOWN 0x12 /* cover / vertical adjust */
#define	UI_ICON_ALERT 0x13 /* double exclamation */
#define	UI_ICON_PARAGRAPH 0x14
#define	UI_ICON_SECTION 0x15
#define	UI_ICON_BAR 0x16 /* sensor / list / count */
#define	UI_ICON_UPDOWN_BAR 0x17
#define	UI_ICON_ARROW_UP 0x18
#define	UI_ICON_ARROW_DOWN 0x19
#define	UI_ICON_ARROW_RIGHT 0x1A
#define	UI_ICON_ARROW_LEFT 0x1B
#define	UI_ICON_ANGLE 0x1C
#define	UI_ICON_LEFTRIGHT 0x1D
#define	UI_ICON_TRIANGLE_UP 0x1E
#define	UI_ICON_TRIANGLE_DOWN 0x1F
#define	UI_ICON_INFO UI_ICON_CIRCLE
#define	UI_ICON_TASK UI_ICON_PLAY
#define	UI_ICON_REMOVE UI_ICON_INVERSE_BULLET
#define	UI_ICON_LIGHT UI_ICON_SUN
#define	UI_ICON_COVER UI_ICON_UPDOWN
#define	UI_ICON_SENSOR UI_ICON_BAR
#define	UI_ICON_SWITCH UI_ICON_PLAY
#define	UI_ICON_SCENE UI_ICON_NOTES
#define	UI_ICON_BACK UI_ICON_REVERSE_PLAY
#define	CANVAS_WIDGET_CHANGED 1
#define	CANVAS_WIDGET_COMMITTED 2
#define	CANVAS_WIDGET_CANCELLED 3
#define	HOST_FONT_BUILTIN 0
	Adafruit-GFX 6x8; CP437 codepoints for umlauts.
#define	HOST_FONT_BOLD_9PT 1
	FreeMonoBold 9pt; Latin-1 indexed.
#define	HOST_FONT_BOLD_12PT 2
	FreeMonoBold 12pt; Latin-1 indexed.
#define	HOST_FONT_BOLD_18PT 3
	FreeMonoBold 18pt; ASCII only.
#define	HOST_FONT_BOLD_24PT 4
	FreeMonoBold 24pt; ASCII only.
#define	HOST_FONT_COUNT 5
	Number of defined font ids.
#define	HOST_LANG_EN 0
#define	HOST_LANG_DE 1
#define	EVENT_KEY_PRESSED (1u << 0)
#define	EVENT_KEY_RELEASED (1u << 1)
#define	EVENT_KEY_LONG_PRESS (1u << 2)
#define	EVENT_POWER_USB_CONN (1u << 3)
#define	EVENT_POWER_USB_DISCONN (1u << 4)
#define	EVENT_POWER_CHARGING (1u << 5)
#define	EVENT_POWER_BATT_LOW (1u << 6)
#define	EVENT_POWER_BATT_CRIT (1u << 7)
#define	EVENT_SYSTEM_UNLOCK (1u << 8)
#define	EVENT_SYSTEM_LOCK (1u << 9)
#define	EVENT_SYSTEM_SLEEP (1u << 10)
#define	EVENT_SYSTEM_WAKE (1u << 11)
#define	EVENT_BLE_CONNECTED (1u << 12)
#define	EVENT_BLE_DISCONNECTED (1u << 13)
#define	EVENT_TIMER_TICK (1u << 14)
#define	EVENT_LANGUAGE_CHANGED (1u << 15)
#define	EVENT_MODULE_EVENT (1u << 16)
#define	KEY_0 0
#define	KEY_1 1
#define	KEY_2 2
#define	KEY_3 3
#define	KEY_4 4
#define	KEY_5 5
#define	KEY_6 6
#define	KEY_7 7
#define	KEY_8 8
#define	KEY_9 9
#define	KEY_Y 10
#define	KEY_N 11
#define	HOST_MSG_PAYLOAD_MAX 4096
	Maximum payload a plugin may send or receive in one transfer.
#define	HOST_MSG_MIME_MAX 64
	Maximum MIME type string length including the NUL.
#define	HOST_STR_TARGET_CP437 0 /* GFX builtin glcdfont (default after splash) */
	Target codepage for host_str_to_display().
#define	HOST_STR_TARGET_LATIN1 1 /* FreeMonoBoldpt8b fonts (Latin-1 indexed) /
#define	GPIO_DIR_IN 0
#define	GPIO_DIR_OUT 1
#define	GPIO_DIR_OUT_OD 2
#define	GPIO_PULL_NONE 0
#define	GPIO_PULL_UP 1
#define	GPIO_PULL_DOWN 2
#define	PIXEL_FORMAT_GRB 0 /* WS2812/WS2813/SK6812 */
#define	PIXEL_FORMAT_RGB 1
#define	PIXEL_FORMAT_GRBW 2 /* SK6812 RGBW (white byte = 0 for plugin-side use) */
#define	PIXEL_FORMAT_RGBW 3

Functions
void	host_log (uint8_t level, const char tag, const char msg)
	Write a single log line at the given level.
void	host_log_hex (const char tag, const char label, const uint8_t *data, size_t len)
	Write a labelled hex dump of a binary buffer at debug level.
uint64_t	host_uptime_ms (void)
	Monotonic milliseconds since boot.
int64_t	host_unix_time (void)
	Current Unix timestamp in seconds, or 0 if RTC not set.
int	host_local_time (struct host_tm *out)
	Fill out with the current local time broken into fields.
int32_t	host_timezone_offset (void)
	Configured timezone offset from UTC in seconds.
bool	host_is_time_set (void)
	True when the RTC has been synchronised at least once.
uint16_t	host_battery_mv (void)
	Battery voltage in millivolts.
uint8_t	host_battery_pct (void)
	Battery state of charge as 0..100 percent.
bool	host_is_usb_connected (void)
	True when USB VBUS is detected.
uint8_t	host_power_source (void)
	Active power source - one of POWER_SRC_*.
uint8_t	host_charge_status (void)
	Charger state machine value - one of CHARGE_*.
bool	host_is_battery_low (void)
	True when battery has crossed the low-warning threshold.
bool	host_is_battery_critical (void)
	True when battery has crossed the critical-shutdown threshold.
void	host_set_sleep_inhibit (uint32_t on)
	Hold or release a light-sleep inhibitor for the calling plugin. While any inhibitor is held the badge does not enter light sleep, so a background plugin keeps ticking. Keyed by the plugin id and released automatically when the plugin is unloaded.
int	host_random (uint8_t *buf, size_t len)
	Fill buf with hardware-RNG bytes; may fall back to PRNG.
int	host_random_strict (uint8_t *buf, size_t len)
	Fill buf with hardware-RNG bytes only; fails without TRNG.
int	host_sha256 (const uint8_t *data, size_t len, uint8_t out[32])
	SHA-256 hash of data into the 32-byte out.
int	host_hmac_sha256 (const uint8_t key, size_t klen, const uint8_t data, size_t dlen, uint8_t out[32])
	HMAC-SHA-256 of data under key into the 32-byte out.
int	host_aes_gcm_encrypt (const uint8_t key, const uint8_t iv, const uint8_t aad, size_t aad_len, const uint8_t pt, size_t pt_len, uint8_t *ct, uint8_t tag[16])
	AES-256-GCM encrypt.
int	host_aes_gcm_decrypt (const uint8_t key, const uint8_t iv, const uint8_t aad, size_t aad_len, const uint8_t ct, size_t ct_len, const uint8_t tag[16], uint8_t *pt)
	AES-256-GCM decrypt and verify.
int	host_base32_encode (const uint8_t in, size_t in_len, char out, size_t out_size)
	Base32-encode in into NUL-terminated out.
int	host_base32_decode (const char in, size_t in_len, uint8_t out, size_t out_size)
	Base32-decode in into raw bytes in out.
int	host_base64_encode (const uint8_t in, size_t in_len, char out, size_t out_size)
	Base64-encode in into NUL-terminated out.
int	host_base64_decode (const char in, size_t in_len, uint8_t out, size_t out_size)
	Base64-decode in into raw bytes in out.
int	host_hex_encode (const uint8_t in, size_t in_len, char out, size_t out_size)
	Lowercase-hex-encode in into NUL-terminated out.
int	host_hex_decode (const char in, size_t in_len, uint8_t out, size_t out_size)
	Hex-decode in (case-insensitive) into raw bytes in out.
int	host_rmem_read_named (const char name, uint8_t buf, size_t *len)
	Read a named retained-memory slot.
int	host_rmem_write_named (const char name, const uint8_t buf, size_t len)
	Write up to host_rmem_slot_size() bytes into a named rmem slot.
int	host_rmem_erase_named (const char *name)
	Erase the contents of a named rmem slot.
bool	host_rmem_name_used (const char *name)
	True if the named rmem slot currently holds data.
uint16_t	host_rmem_slot_size (void)
	Maximum payload bytes per rmem slot.
int	host_ecc_generate (const char *name, uint8_t curve)
	Generate a fresh ECC key for the named slot.
int	host_ecc_import (const char name, const uint8_t priv, uint8_t curve)
	Import an externally-generated private key for the named slot.
int	host_ecc_pubkey (const char name, uint8_t pub, uint8_t curve)
	Export the public key for the named slot.
int	host_ecc_delete (const char *name)
	Erase the named ECC key and free its pool slot.
bool	host_ecc_exists (const char *name)
	True when the named ECC key currently holds a key.
int	host_ecdsa_sign (const char name, const uint8_t msg, size_t len, uint8_t sig[64])
	ECDSA-sign Message transfer (badge-to-badge) with the P-256 named key; writes 64-byte raw sig.
int	host_eddsa_sign (const char name, const uint8_t msg, size_t len, uint8_t sig[64])
	Ed25519-sign Message transfer (badge-to-badge) with the named key; writes 64-byte signature.
int	host_se_chip_id (uint8_t serial, size_t len)
	Read the TROPIC01 chip serial / identity blob.
int	host_se_fw_version (uint8_t riscv, uint8_t spect)
	Read TROPIC01 firmware versions for the RISC-V CPU and SPECT core.
int	host_http_open (uint8_t method, const char *url, uint32_t timeout_ms)
	Open an HTTP request.
int	host_http_set_header (int handle, const char key, const char value)
	Add a request header before perform().
int	host_http_set_body (int handle, const uint8_t *body, size_t len)
	Stage a request body before perform().
int	host_http_perform (int handle)
	Send the request and read response headers.
int	host_http_status (int handle)
	HTTP response status code, or negative on error.
int	host_http_read_chunk (int handle, uint8_t buf, size_t buf_size, size_t out_len)
	Stream one response chunk into buf.
size_t	host_http_content_length (int handle)
	Response Content-Length, or 0 when unknown / chunked.
int	host_http_close (int handle)
	Release a request handle.
int	host_socket_open (uint8_t proto, const char *host, uint16_t port, uint32_t timeout_ms)
	Open an outbound connection to a single remote endpoint.
int	host_socket_write (int handle, const uint8_t *data, size_t len, uint32_t timeout_ms)
	Write bytes to the stream / send a datagram to the connected peer.
int	host_socket_read (int handle, uint8_t *out, size_t cap, uint32_t timeout_ms)
	Read bytes from the stream / receive a datagram from the connected peer.
int	host_socket_close (int handle)
	Close a socket handle.
int	host_wifi_request (uint32_t timeout_ms)
	Request the shared WiFi radio and wait up to timeout_ms for join.
int	host_wifi_release (void)
	Release the WiFi radio held by this plugin.
bool	host_wifi_is_connected (void)
	True when WiFi STA is associated and has an IP.
int	host_wifi_ssid (char *out, size_t out_size)
	Copy the currently joined SSID into out.
int	host_wifi_ip (char *out, size_t out_size)
	Copy the current IPv4 address as dotted decimal into out.
int8_t	host_wifi_rssi (void)
	Current AP signal strength in dBm.
int	host_wifi_mac (uint8_t out[6])
	Read the station MAC address.
int	host_wifi_start_scan (void)
	Start an asynchronous WiFi scan.
bool	host_wifi_scan_done (void)
	True when the scan started by host_wifi_start_scan has finished.
int	host_wifi_scan_results (wifi_scan_result_t out, size_t count)
	Read results from the last completed scan.
bool	host_ble_is_enabled (void)
	True when the BLE stack is initialised and advertising or connectable.
int	host_ble_mac (uint8_t out[6])
	Read the local BLE MAC address.
int	host_ble_device_name (char *out, size_t out_size)
	Copy the local BLE device name into out.
int8_t	host_ble_rssi (void)
	Signal strength of the active BLE link in dBm, or 0 when idle.
int	host_ble_register_service (ble_service_def_t def, ble_char_def_t chars, uint32_t num_chars)
	Register the plugin's GATT service and its characteristics.
int	host_ble_unregister_service (uint32_t service_handle)
	Tear down the plugin's registered GATT service.
int	host_ble_send_notification (uint32_t char_handle, const uint8_t *data, size_t len)
	Notify subscribers of a value on one of the plugin's characteristics.
int	host_ble_send_indication (uint32_t char_handle, const uint8_t *data, size_t len)
	Indicate (acknowledged notify) a value on a plugin characteristic.
int	host_ble_consume_write (uint32_t char_handle, uint8_t *buf, size_t buf_size)
	Pull the next queued inbound write for char_handle.
int	host_ble_scan_start (uint32_t duration_ms)
	Start a central scan for duration_ms milliseconds.
bool	host_ble_scan_done (void)
	True when the scan started by host_ble_scan_start() has finished.
int	host_ble_scan_results (ble_scan_result_t out, size_t count)
	Read results from the last central scan.
int	host_ble_connect (const uint8_t addr[6], uint8_t addr_type)
	Connect to a peer. Completion arrives as a BLE_CONNECTED event; read the resulting handle with host_ble_conn_handle().
uint32_t	host_ble_conn_handle (void)
	Current connection handle (central or peripheral), or 0 when idle.
int	host_ble_disconnect (uint32_t conn)
	Disconnect a connection.
int	host_ble_discover (uint32_t conn, const uint8_t uuid[16], uint32_t action_id)
	Discover the characteristics of one service on a connected peer. Completion fires action_id; read entries with host_ble_consume_discovery().
int	host_ble_consume_discovery (ble_remote_char_t out, size_t count)
	Pull discovered characteristics after a discovery action fires.
int	host_ble_read_char (uint32_t conn, uint16_t value_handle, uint32_t action_id)
	Start reading a peer characteristic by value handle. Completion fires action_id; read the value with host_ble_consume_read().
int	host_ble_consume_read (uint8_t *buf, size_t buf_size)
	Pull the value delivered by the last read action.
int	host_ble_write_char (uint32_t conn, uint16_t value_handle, const uint8_t *data, size_t len, uint8_t with_response)
	Write a value to a peer characteristic by value handle.
int	host_ble_subscribe (uint32_t conn, uint16_t cccd_handle, uint32_t action_id)
	Subscribe to notifications on a peer characteristic (by CCCD handle). Each notification fires action_id; read it with host_ble_consume_notification().
int	host_ble_consume_notification (uint16_t value_handle_out, uint8_t buf, size_t buf_size)
	Pull the next queued inbound notification.
int	host_nvs_get_blob (const char key, uint8_t buf, size_t *len)
	Read a binary blob from NVS.
int	host_nvs_set_blob (const char key, const uint8_t buf, size_t len)
	Write a binary blob to NVS.
int	host_nvs_get_u32 (const char key, uint32_t out)
	Read a uint32 value.
int	host_nvs_set_u32 (const char *key, uint32_t value)
	Write a uint32 value.
int	host_nvs_get_str (const char key, char buf, size_t buf_size)
	Read a NUL-terminated string.
int	host_nvs_set_str (const char key, const char value)
	Write a NUL-terminated string.
int	host_nvs_erase (const char *key)
	Delete a single key.
int	host_nvs_erase_all (void)
	Erase every key in the plugin's namespace.
int	host_nvs_list_keys (char out, size_t out_len)
	Enumerate the keys in the plugin's namespace.
int	host_fs_write (const char name, const uint8_t data, size_t len)
	Create or overwrite name with len bytes.
int	host_fs_read (const char name, uint8_t buf, size_t *len)
	Read name into buf.
int	host_fs_remove (const char *name)
	Delete name.
int	host_fs_size (const char name, size_t out)
	Write the byte size of name to *out.
int	host_fs_list (char out, size_t out_len)
	Enumerate the plugin's own files.
int	host_fs_view (const char *name)
	Open one of the plugin's own files in a scrollable on-screen text viewer (same as opening the file in the vFAT explorer). Useful for a bundled readme / help page.
int	host_ui_push_toast (const char *text, uint8_t icon, uint16_t duration_ms)
	Show a transient toast overlay.
int	host_ui_push_message (const char *text, uint8_t icon, uint32_t duration_ms)
	Show a blocking message view that auto-dismisses after duration_ms.
int	host_ui_push_confirm (const char *text, uint8_t icon, uint32_t action_id)
	Show a Y/N confirmation.
int	host_ui_push_info (const char title, const char body)
	Show a scrollable info screen with title and body.
int	host_ui_push_context_menu (const char title, const ui_item_t items, uint16_t count, uint32_t select_action_id)
	Show a context menu.
int	host_ui_push_t9_input (const char title, const char initial, uint16_t max_len, uint32_t action_id)
	Show a T9-style text entry.
int	host_ui_push_password (const char title, const char initial, uint16_t max_len, uint32_t action_id)
	Show a password entry (masked T9).
int	host_ui_push_pin_entry (const char *title, uint8_t max_len, uint8_t max_attempts, uint32_t action_id)
	Show a numeric PIN entry.
int	host_ui_push_slider (const char title, int32_t min, int32_t max, int32_t init, int32_t step, const char unit, uint32_t action_id)
	Show an integer slider.
int	host_ui_push_color_picker (uint8_t initial_r, uint8_t initial_g, uint8_t initial_b, uint32_t action_id)
	Show an RGB color picker.
int	host_ui_push_date (const char *title, uint8_t d, uint8_t m, uint16_t y, uint32_t action_id)
	Show a date picker.
int	host_ui_push_time (const char *title, uint8_t h, uint8_t m, uint32_t action_id)
	Show a time-of-day picker.
int	host_ui_push_list (const char title, const ui_item_t items, uint16_t count, uint32_t select_action_id, uint32_t menu_action_id)
	Show a list view.
int	host_ui_replace_list (const char title, const ui_item_t items, uint16_t count, uint32_t select_action_id, uint32_t menu_action_id)
	Replace the plugin's top list view in place; falls back to push when none.
int	host_ui_set_view_footer (const char *hint)
	Override the footer hint of the plugin's current top view.
int	host_ui_set_view_empty (const char *text)
	Override the empty-state text shown by an empty list view.
int	host_ui_set_view_lifecycle (uint32_t hide_action_id, uint32_t show_action_id)
	Register hide/show callbacks for the plugin's current top view.
int	host_ui_update_list_item (uint16_t index, const ui_item_t *item)
	Update one list row in place (partial redraw).
int	host_ui_insert_list_item (uint16_t index, const ui_item_t *item)
	Insert a list row at index (partial redraw).
int	host_ui_remove_list_item (uint16_t index)
	Remove the list row at index (partial redraw).
int	host_ui_pop (void)
	Pop the topmost view.
int	host_ui_pop_to_plugin (void)
	Pop back to the plugin's first view.
int	host_ui_repaint (void)
	Force a repaint of the current view.
int	host_ui_consume_input_text (char *out, size_t out_size)
	Read text input committed by the most recent input view.
int	host_ui_consume_input_int (int32_t *out)
	Read integer input committed by the most recent input view.
int	host_ui_acquire_exclusive (void)
	Claim exclusive UI ownership (block other plugins from pushing views).
int	host_ui_release_exclusive (void)
	Release a previously acquired exclusive UI lock.
int	host_ui_set_inactivity (uint32_t timeout_ms, uint32_t action_id)
	Arm an inactivity timer for the plugin's current view.
int	host_ui_wink (uint8_t count, uint16_t period_ms)
	Blink the backlight as a visual identification signal.
int	host_view_canvas_push (const char *title, uint32_t key_action_id, uint32_t widget_action_id)
	Push a new canvas view.
int	host_view_canvas_get_body_size (uint16_t w, uint16_t h)
	Read the drawable body region (excluding header/footer).
int	host_view_canvas_set_footer (const char *hint)
	Override the footer hint of the canvas.
int	host_view_canvas_clear (void)
	Clear all draw state and widgets.
int	host_view_canvas_set_text_size (uint8_t size)
	Set text size multiplier (Adafruit-GFX semantics).
int	host_view_canvas_set_font (uint8_t font_id)
	Switch the canvas font to one of the canonical HOST_FONT_* ids.
int	host_text_pick_font_that_fits (const char text, int16_t max_width_px, const uint8_t candidates, uint32_t count, uint8_t *out_font_id)
	Pick the largest HOST_FONT_* whose rendered `text` fits within `max_width_px`. Candidates are evaluated in array order; sort them from largest to smallest. Falls back to the last entry when nothing fits.
int	host_view_canvas_set_text_color (bool inverted)
	Switch between normal and inverted (white on black) text.
int	host_view_canvas_draw_text (int16_t x, int16_t y, const char *text)
	Draw text at (x, y) using the current text size/colour.
int	host_view_canvas_draw_text_aligned (int16_t x, int16_t y, int16_t w, const char *text, uint8_t align)
	Draw text within a horizontal box.
int	host_view_canvas_draw_rect (int16_t x, int16_t y, int16_t w, int16_t h, bool filled)
	Draw a rectangle outline or filled rectangle.
int	host_view_canvas_invert_rect (int16_t x, int16_t y, int16_t w, int16_t h)
	Invert all pixels inside the rectangle.
int	host_view_canvas_hline (int16_t x, int16_t y, int16_t w)
	Draw a horizontal line.
int	host_view_canvas_vline (int16_t x, int16_t y, int16_t h)
	Draw a vertical line.
int	host_view_canvas_commit (bool full_refresh)
	Flush draw state to the panel.
int	host_view_canvas_add_slider (uint32_t widget_id, int32_t min, int32_t max, int32_t initial, int32_t step)
	Add an integer slider widget bound to widget_id.
int	host_view_canvas_add_text (uint32_t widget_id, uint16_t max_len, const char *initial)
	Add a T9 text input widget bound to widget_id.
int	host_view_canvas_add_button (uint32_t widget_id)
	Add a focusable button widget bound to widget_id.
int	host_view_canvas_remove_widget (uint32_t widget_id)
	Remove a widget previously added to the canvas.
int	host_view_canvas_set_value (uint32_t widget_id, int32_t value)
	Set the integer value of a slider widget.
int	host_view_canvas_get_value (uint32_t widget_id, int32_t *out)
	Read the integer value of a slider widget.
int	host_view_canvas_set_text (uint32_t widget_id, const char *text)
	Set the text of a text-input widget.
int	host_view_canvas_get_text (uint32_t widget_id, char *out, size_t cap)
	Read the text of a text-input widget.
int	host_view_canvas_set_focus (uint32_t widget_id)
	Move keyboard focus to the given widget.
int	host_view_canvas_get_focus (uint32_t *out)
	Read the currently focused widget id, 0 if none.
int	host_view_canvas_set_key_repeat (uint16_t initial_ms, uint16_t repeat_ms)
	Configure key auto-repeat timing for the canvas.
int	host_view_canvas_set_long_press_action (uint32_t action_id)
	Set the action id fired on a canvas long-press.
uint16_t	host_display_width (void)
	Display width in pixels.
uint16_t	host_display_height (void)
	Display height in pixels.
int	host_display_clear (void)
	Clear the framebuffer to background.
int	host_display_draw_pixel (int16_t x, int16_t y, uint16_t color)
	Set a single pixel.
int	host_display_draw_line (int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint16_t color)
	Draw a line between two points.
int	host_display_draw_rect (int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color)
	Draw a rectangle outline.
int	host_display_fill_rect (int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color)
	Draw a filled rectangle.
int	host_display_draw_text (int16_t x, int16_t y, const char *text, uint8_t size, uint16_t color)
	Draw text using the default GFX font.
int	host_display_flush (uint8_t refresh_mode)
	Push the framebuffer to the panel using the given refresh mode.
bool	host_display_is_busy (void)
	True while the panel is processing a previous refresh.
int	host_i18n_tr_key (const char key, char out, uint32_t out_cap)
	Translate a plugin-local key into the current language.
int	host_i18n_tr_meta (const char field, char out, uint32_t out_cap)
	Read a metadata field (name, description, ...) from the plugin manifest.
int	host_i18n_tr_core (const char key, char out, uint32_t out_cap)
	Translate a core.* key from the firmware string table.
uint8_t	host_i18n_current_language (void)
	Active language code (HOST_LANG_*).
int	host_event_subscribe (uint32_t event_mask, uint32_t action_id)
	Subscribe to one or more events.
int	host_event_unsubscribe (uint32_t subscription_id)
	Cancel a subscription returned by host_event_subscribe.
int	host_event_publish (uint32_t module_event_subtype, uint32_t value)
	Publish an EVENT_MODULE_EVENT carrying subtype and value.
bool	host_key_pressed (uint8_t key)
	True while key is currently held down.
int	host_key_consume_next (uint8_t *out_key)
	Pop the next queued key press, if any.
int	host_usb_cdc_write (const uint8_t *data, size_t len)
	Write raw bytes to the USB-CDC TX stream.
bool	host_feature_enabled (uint16_t feature_id)
	True when the firmware was built with the given feature id enabled.
int	host_get_firmware_version (char *out, size_t out_size)
	Copy the firmware semver string into out.
int	host_get_build_profile (char *out, size_t out_size)
	Copy the build profile name (e.g. "release", "debug") into out.
uint8_t	host_cpu_load (void)
	Aggregate CPU load across all cores as 0..100 percent. Sampled on demand from FreeRTOS run-time stats and refreshed at most a few times per second; intermediate calls return the cached value. The first call after load returns 0 (no baseline yet).
int	host_cmd_consume (char *out, size_t out_size)
	Copy the pending command string into out, clearing it.
int	host_msg_register_handler (const char *mime_type, uint32_t action_id)
	Register that this plugin handles an incoming MIME type.
int	host_msg_unregister_handler (const char *mime_type)
	Drop a previously registered handler.
int	host_msg_consume (uint8_t buf, size_t buf_size, char mime_out, size_t mime_size)
	Pull the payload delivered by the most recent inbound message action.
int	host_msg_send_interactive (const char mime_type, const uint8_t data, size_t len)
	Send a typed payload via the firmware-owned interactive peer picker.
int	host_msg_send (const uint8_t addr[6], uint8_t addr_type, const char mime_type, const uint8_t data, size_t len)
	Send a typed payload directly to a known peer address (no picker).
int	host_str_to_display (const char in, char out, size_t out_size, uint32_t target)
	Decode HTML entities + UTF-8 in in into single-byte display characters in out.
int	host_str_to_utf8 (const char in, char out, size_t out_size)
	Convert CP437 display bytes in in to a UTF-8 string in out.
int	host_gpio_set_direction (uint8_t pin, uint8_t direction)
	Configure pin direction (one of GPIO_DIR_*).
int	host_gpio_set_pull (uint8_t pin, uint8_t pull)
	Configure internal pull resistor (one of GPIO_PULL_*).
int	host_gpio_write (uint8_t pin, bool level)
	Drive a digital output high/low.
int	host_gpio_read (uint8_t pin, bool *level)
	Sample a digital input.
int	host_gpio_release (uint8_t pin)
	Release the pin claim so other plugins can use it.
int	host_gpio_pwm_start (uint8_t pin, uint32_t freq_hz, uint16_t duty_per_mille)
	Start LEDC PWM on pin.
int	host_gpio_pwm_set_duty (uint8_t pin, uint16_t duty_per_mille)
	Update PWM duty without restarting the timer.
int	host_gpio_pwm_stop (uint8_t pin)
	Stop PWM and release the LEDC channel.
int	host_adc_read (uint8_t pin, uint16_t raw, uint16_t millivolt)
	Single-shot ADC read.
int	host_i2c_write (uint8_t bus, uint8_t addr, const uint8_t *data, size_t len)
	I2C write transaction.
int	host_i2c_read (uint8_t bus, uint8_t addr, uint8_t *data, size_t len)
	I2C read transaction.
int	host_i2c_write_read (uint8_t bus, uint8_t addr, const uint8_t wr, size_t wr_len, uint8_t rd, size_t rd_len)
	I2C write-then-read transaction with repeated start.
int	host_i2c_scan (uint8_t bus, uint8_t found_addrs, size_t count)
	Scan the I2C bus for responding addresses.
int	host_sao_eeprom_read (uint16_t offset, uint8_t *buf, size_t len)
	Read from the SAO addon EEPROM at byte offset.
int	host_sao_eeprom_write (uint16_t offset, const uint8_t *buf, size_t len)
	Write to the SAO addon EEPROM at byte offset.
int	host_pixel_strip_init (uint8_t gpio_pin, uint16_t num_pixels, uint8_t format)
	Initialise or reconfigure the global pixel strip.
int	host_pixel_strip_deinit (void)
	Tear down the global pixel strip.
int	host_pixel_strip_set (uint16_t index, uint8_t r, uint8_t g, uint8_t b)
	Set one pixel's RGB colour in the strip buffer.
int	host_pixel_strip_fill (uint8_t r, uint8_t g, uint8_t b)
	Fill every pixel with the same RGB colour.
int	host_pixel_strip_clear (void)
	Clear every pixel to off (0, 0, 0).
int	host_pixel_strip_refresh (void)
	Push the strip buffer out over the RMT bus.
uint16_t	host_pixel_strip_length (void)
	Number of pixels the strip was initialised with.
bool	host_pixel_strip_ready (void)
	True when the strip has been successfully initialised.
int	host_lockscreen_register_action (const char *label_key, uint32_t action_id)
	Publish (or replace) the plugin's lockscreen quick-action.
int	host_lockscreen_unregister_action (void)
	Remove the plugin's lockscreen quick-action.
int	host_lockscreen_alert (const char *text, uint8_t icon, uint32_t action_id)
	Raise a persistent Y/N alert over whatever is on screen, lock screen included, that stays until the user answers.

Detailed Description

CDC Badge OS plugin host API - canonical C ABI contract.

Mirrored from cdc-badge-os/components/plugin_manager/include/plugin_manager/host_api.h. A CI job in both repositories detects drift between the two copies.

All host functions are imported by the WASM plugin from the cdc module. Plugin lifecycle exports (plugin_init, plugin_on_enter, ...) are declared in plugin_lifecycle.h.

Definition in file host_api.h.

Macro Definition Documentation

◆ HOST_API_LEVEL_MAJOR

#define HOST_API_LEVEL_MAJOR 0

Definition at line 28 of file host_api.h.

Referenced by cdc::plugin_manager::CapabilityChecker::validate().

◆ HOST_API_LEVEL_MINOR

#define HOST_API_LEVEL_MINOR 7

Definition at line 29 of file host_api.h.

Referenced by cdc::plugin_manager::CapabilityChecker::validate().

◆ HOST_API_LEVEL_PACKED

#define HOST_API_LEVEL_PACKED (((uint32_t)HOST_API_LEVEL_MAJOR << 16) | HOST_API_LEVEL_MINOR)

Definition at line 31 of file host_api.h.

Referenced by cdc::os_ui::BackupManager::importFrom().

◆ HOST_API_LEVEL_STR

#define HOST_API_LEVEL_STR "0.7"

Definition at line 30 of file host_api.h.

Referenced by cdc::os_ui::BackupManager::exportTo(), cdc::os_ui::BackupManager::importFrom(), and cdc::plugin_manager::CapabilityChecker::validate().

◆ HOST_ERR_BUSY

#define HOST_ERR_BUSY -7

Definition at line 44 of file host_api.h.

Referenced by cdc::plugin_manager::PluginUiState::acquireExclusive(), host_ble_register_service(), host_lockscreen_alert(), host_msg_register_handler(), host_msg_send(), host_msg_send_interactive(), host_pixel_strip_clear(), host_pixel_strip_deinit(), host_pixel_strip_fill(), host_pixel_strip_init(), host_pixel_strip_refresh(), and host_pixel_strip_set().

◆ HOST_ERR_GENERIC

#define HOST_ERR_GENERIC -1

Definition at line 38 of file host_api.h.

Referenced by host_adc_read(), host_aes_gcm_decrypt(), host_aes_gcm_encrypt(), host_base64_decode(), host_ble_connect(), host_ble_discover(), host_ble_mac(), host_ble_read_char(), host_ble_scan_start(), host_ble_subscribe(), host_ble_write_char(), host_display_clear(), host_display_draw_line(), host_display_draw_pixel(), host_display_draw_rect(), host_display_draw_text(), host_display_fill_rect(), host_display_flush(), host_fs_write(), host_gpio_pwm_set_duty(), host_gpio_pwm_start(), host_gpio_set_direction(), host_gpio_set_pull(), host_gpio_write(), host_hmac_sha256(), host_http_open(), host_http_perform(), host_http_set_body(), host_http_set_header(), host_i2c_read(), host_i2c_scan(), host_i2c_write(), host_i2c_write_read(), host_key_consume_next(), host_pixel_strip_clear(), host_pixel_strip_fill(), host_pixel_strip_refresh(), host_pixel_strip_set(), host_sao_eeprom_read(), host_sao_eeprom_write(), host_se_chip_id(), host_se_fw_version(), host_sha256(), host_socket_open(), host_socket_read(), host_socket_write(), host_usb_cdc_write(), host_wifi_ip(), host_wifi_mac(), host_wifi_start_scan(), periph_send(), and cdc::plugin_manager::PluginUiState::releaseExclusive().

◆ HOST_ERR_INVALID_ARG

#define HOST_ERR_INVALID_ARG -2

Definition at line 39 of file host_api.h.

◆ HOST_ERR_NO_CAPABILITY

#define HOST_ERR_NO_CAPABILITY -3

Definition at line 40 of file host_api.h.

Referenced by cdc::plugin_manager::PluginUiState::acquireExclusive(), host_ble_connect(), host_ble_disconnect(), host_ble_discover(), host_ble_read_char(), host_ble_register_service(), host_ble_scan_results(), host_ble_scan_start(), host_ble_subscribe(), host_ble_unregister_service(), host_ble_write_char(), host_display_clear(), host_display_draw_line(), host_display_draw_pixel(), host_display_draw_rect(), host_display_draw_text(), host_display_fill_rect(), host_display_flush(), host_ecc_delete(), host_ecc_generate(), host_ecc_pubkey(), host_ecdsa_sign(), host_eddsa_sign(), host_event_subscribe(), host_i2c_read(), host_i2c_scan(), host_i2c_write(), host_i2c_write_read(), host_lockscreen_alert(), host_lockscreen_register_action(), host_lockscreen_unregister_action(), host_msg_register_handler(), host_msg_send(), host_msg_send_interactive(), host_nvs_list_keys(), host_pixel_strip_clear(), host_pixel_strip_deinit(), host_pixel_strip_fill(), host_pixel_strip_init(), host_pixel_strip_refresh(), host_pixel_strip_set(), host_rmem_erase_named(), host_rmem_read_named(), host_rmem_write_named(), host_sao_eeprom_read(), host_sao_eeprom_write(), host_socket_open(), host_socket_read(), host_socket_write(), host_usb_cdc_write(), and periph_send().

◆ HOST_ERR_NO_MEMORY

#define HOST_ERR_NO_MEMORY -6

◆ HOST_ERR_NOT_FOUND

#define HOST_ERR_NOT_FOUND -4

Definition at line 41 of file host_api.h.

◆ HOST_ERR_NOT_SUPPORTED

#define HOST_ERR_NOT_SUPPORTED -8

Definition at line 45 of file host_api.h.

Referenced by host_adc_read(), host_ecc_import(), and host_random_strict().

◆ HOST_ERR_RMEM_FULL

#define HOST_ERR_RMEM_FULL -9

Definition at line 46 of file host_api.h.

Referenced by host_rmem_write_named().

◆ HOST_ERR_TIMEOUT

#define HOST_ERR_TIMEOUT -5

Definition at line 42 of file host_api.h.

Referenced by host_socket_read(), host_socket_write(), and host_wifi_request().

◆ HOST_OK

#define HOST_OK 0

Definition at line 37 of file host_api.h.

Classes

Macros

Functions