host_api.h

Go to the documentation of this file.

 
#ifndef CDC_BADGE_HOST_API_H
#define CDC_BADGE_HOST_API_H
 
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ------------------------------------------------------------------------- */
/* API Level                                                                 */
/* ------------------------------------------------------------------------- */
 
#define HOST_API_LEVEL_MAJOR  0
#define HOST_API_LEVEL_MINOR  8
#define HOST_API_LEVEL_STR    "0.8"
#define HOST_API_LEVEL_PACKED (((uint32_t)HOST_API_LEVEL_MAJOR << 16) | HOST_API_LEVEL_MINOR)
 
/* ------------------------------------------------------------------------- */
/* Return Codes                                                              */
/* ------------------------------------------------------------------------- */
 
#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

void host_log    (uint8_t level, const char* tag, const char* msg);

void host_log_hex(const char* tag, const char* label, const uint8_t* data, size_t len);


 
struct host_tm {
    uint16_t year;        /* 1900-3000 */
    uint8_t  month;       /* 1-12 */
    uint8_t  day;         /* 1-31 */
    uint8_t  hour;        /* 0-23 */
    uint8_t  minute;      /* 0-59 */
    uint8_t  second;      /* 0-59 */
    uint8_t  weekday;     /* 0=Sunday */
};

uint64_t host_uptime_ms        (void);

int64_t  host_unix_time        (void);

int      host_local_time       (struct host_tm* out);

int32_t  host_timezone_offset  (void);

bool     host_is_time_set      (void);


 
#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

uint16_t host_battery_mv         (void);

uint8_t  host_battery_pct        (void);

bool     host_is_usb_connected   (void);

uint8_t  host_power_source       (void);

uint8_t  host_charge_status      (void);

bool     host_is_battery_low     (void);

bool     host_is_battery_critical(void);

void     host_set_sleep_inhibit  (uint32_t on);



int host_random        (uint8_t* buf, size_t len);

int host_random_strict (uint8_t* buf, size_t len);

int host_sha256        (const uint8_t* data, size_t len, uint8_t out[32]);

int host_hmac_sha256   (const uint8_t* key, size_t klen,
                        const uint8_t* data, size_t dlen, uint8_t out[32]);

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]);

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);

int host_base32_encode(const uint8_t* in, size_t in_len, char* out, size_t out_size);

int host_base32_decode(const char* in, size_t in_len, uint8_t* out, size_t out_size);

int host_base64_encode(const uint8_t* in, size_t in_len, char* out, size_t out_size);

int host_base64_decode(const char* in, size_t in_len, uint8_t* out, size_t out_size);

int host_hex_encode   (const uint8_t* in, size_t in_len, char* out, size_t out_size);

int host_hex_decode   (const char* in, size_t in_len, uint8_t* out, size_t out_size);


 
#define ECC_CURVE_P256    0
#define ECC_CURVE_ED25519 1
 
/*
 * Retained memory (rmem) is allocated by name from a shared plugin pool.
 * Slots persist across reboot, plugin uninstall, and plugin reinstall as
 * long as the name remains declared in some installed plugin's
 * `capabilities.rmem`. Plugins declaring the same name share the same
 * physical slot (intentional, common scope).
 *
 * Name length: max 15 bytes excluding the trailing NUL.
 */
 
#define HOST_RMEM_NAME_MAX 15

int      host_rmem_read_named  (const char* name, uint8_t* buf, size_t* len);

int      host_rmem_write_named (const char* name, const uint8_t* buf, size_t len);

int      host_rmem_erase_named (const char* name);

bool     host_rmem_name_used   (const char* name);

uint16_t host_rmem_slot_size   (void);
 
/*
 * ECC keys are addressed by name, not by physical slot. The host maps each
 * declared name (manifest `capabilities.ecc`) to a slot in a reserved plugin
 * ECC pool and persists the mapping in NVS, so a key keeps its slot across
 * reboot and reinstall. The pool is small (ECC slots are scarce and reserved
 * for firmware features such as attestation and WebAuthn); growing it is a
 * firmware change.
 *
 * Name length: max HOST_ECC_NAME_MAX bytes excluding the trailing NUL.
 */
#define HOST_ECC_NAME_MAX 15

int      host_ecc_generate (const char* name, uint8_t curve);

int      host_ecc_import   (const char* name, const uint8_t* priv, uint8_t curve);

int      host_ecc_pubkey   (const char* name, uint8_t* pub, uint8_t curve);

int      host_ecc_delete   (const char* name);

bool     host_ecc_exists   (const char* name);

int      host_ecdsa_sign   (const char* name, const uint8_t* msg, size_t len, uint8_t sig[64]);

int      host_eddsa_sign   (const char* name, const uint8_t* msg, size_t len, uint8_t sig[64]);

int      host_se_chip_id   (uint8_t* serial, size_t* len);

int      host_se_fw_version(uint8_t* riscv, uint8_t* spect);


 
#define HTTP_GET    0
#define HTTP_POST   1
#define HTTP_PUT    2
#define HTTP_DELETE 3

int    host_http_open          (uint8_t method, const char* url, uint32_t timeout_ms);

int    host_http_set_header    (int handle, const char* key, const char* value);

int    host_http_set_body      (int handle, const uint8_t* body, size_t len);

int    host_http_perform       (int handle);

int    host_http_status        (int handle);

int    host_http_read_chunk    (int handle, uint8_t* buf, size_t buf_size, size_t* out_len);

size_t host_http_content_length(int handle);

int    host_http_close         (int handle);



#define HOST_SOCK_TCP  0
#define HOST_SOCK_UDP  1

int host_socket_open(uint8_t proto, const char* host, uint16_t port, uint32_t timeout_ms);

int host_socket_write(int handle, const uint8_t* data, size_t len, uint32_t timeout_ms);

int host_socket_read(int handle, uint8_t* out, size_t cap, uint32_t timeout_ms);

int host_socket_close(int handle);



int host_net_listen(uint16_t port, uint32_t action_id);

int host_net_accept(void);

int host_net_close(uint16_t port);



int host_set_resident(bool resident);


 
typedef struct {
    char    ssid[33];
    uint8_t bssid[6];
    int8_t  rssi;
    uint8_t channel;
    uint8_t auth_mode;
} wifi_scan_result_t;

int     host_wifi_request    (uint32_t timeout_ms);

int     host_wifi_release    (void);

bool    host_wifi_is_connected(void);

int     host_wifi_ssid       (char* out, size_t out_size);

int     host_wifi_ip         (char* out, size_t out_size);

int8_t  host_wifi_rssi       (void);

int     host_wifi_mac        (uint8_t out[6]);

int     host_wifi_start_scan (void);

bool    host_wifi_scan_done  (void);

int     host_wifi_scan_results(wifi_scan_result_t* out, size_t* count);


 
/* GATT characteristic property flags (BLE Core Spec Vol 3, Part G, 3.3.1.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

typedef struct {
    uint8_t  uuid[16];        
    uint8_t  properties;      
    uint8_t  reserved[3];
    uint32_t write_action_id; 
    uint32_t char_handle;     
} ble_char_def_t;

typedef struct {
    uint8_t  uuid[16];        
    uint8_t  num_chars;       
    uint8_t  reserved[3];
    uint32_t service_handle;  
} ble_service_def_t;

typedef struct {
    uint8_t addr[6];
    uint8_t addr_type;        
    int8_t  rssi;
    char    name[32];
} ble_scan_result_t;

typedef struct {
    uint8_t  uuid[16];
    uint16_t value_handle;
    uint8_t  properties;      
    uint8_t  reserved;
} ble_remote_char_t;
 
/* --- State (read-only) --- */

bool    host_ble_is_enabled       (void);

int     host_ble_mac              (uint8_t out[6]);

int     host_ble_device_name      (char* out, size_t out_size);

int8_t  host_ble_rssi             (void);
 
/* --- Peripheral (GATT server) --- */

int     host_ble_register_service (ble_service_def_t* def,
                                   ble_char_def_t* chars, uint32_t num_chars);

int     host_ble_unregister_service(uint32_t service_handle);

int     host_ble_send_notification(uint32_t char_handle, const uint8_t* data, size_t len);

int     host_ble_send_indication  (uint32_t char_handle, const uint8_t* data, size_t len);

int     host_ble_consume_write    (uint32_t char_handle, uint8_t* buf, size_t buf_size);
 
/* --- Central (GATT client) --- */

int     host_ble_scan_start       (uint32_t duration_ms);

bool    host_ble_scan_done        (void);

int     host_ble_scan_results     (ble_scan_result_t* out, size_t* count);

int     host_ble_connect          (const uint8_t addr[6], uint8_t addr_type);

uint32_t host_ble_conn_handle     (void);

int     host_ble_disconnect       (uint32_t conn);

int     host_ble_discover         (uint32_t conn, const uint8_t uuid[16], uint32_t action_id);

int     host_ble_consume_discovery(ble_remote_char_t* out, size_t* count);

int     host_ble_read_char        (uint32_t conn, uint16_t value_handle, uint32_t action_id);

int     host_ble_consume_read     (uint8_t* buf, size_t buf_size);

int     host_ble_write_char       (uint32_t conn, uint16_t value_handle,
                                   const uint8_t* data, size_t len, uint8_t with_response);

int     host_ble_subscribe        (uint32_t conn, uint16_t cccd_handle, uint32_t action_id);

int     host_ble_subscribe_char   (uint32_t conn, uint16_t value_handle, uint32_t action_id);

int     host_ble_consume_notification(uint16_t* value_handle_out, uint8_t* buf, size_t buf_size);

uint16_t host_ble_get_mtu         (uint32_t conn);

int     host_ble_on_write_complete(uint32_t action_id);



int host_nvs_get_blob (const char* key, uint8_t* buf, size_t* len);

int host_nvs_set_blob (const char* key, const uint8_t* buf, size_t len);

int host_nvs_get_u32  (const char* key, uint32_t* out);

int host_nvs_set_u32  (const char* key, uint32_t value);

int host_nvs_get_str  (const char* key, char* buf, size_t buf_size);

int host_nvs_set_str  (const char* key, const char* value);

int host_nvs_erase    (const char* key);

int host_nvs_erase_all(void);

int host_nvs_list_keys(char* out, size_t* out_len);



int host_fs_write (const char* name, const uint8_t* data, size_t len);

int host_fs_read  (const char* name, uint8_t* buf, size_t* len);

int host_fs_remove(const char* name);

int host_fs_size  (const char* name, size_t* out);

int host_fs_list  (char* out, size_t* out_len);

int host_fs_view  (const char* name);

int host_fs_view_image  (const char* name);

int host_fs_view_markdown  (const char* name);


 
typedef struct {
    const char* label;
    uint8_t     icon;
    bool        icon_disabled;
    uint32_t    item_id;
} ui_item_t;
 
/* CP437 glyph codes routed straight to Adafruit-GFX. cdc_log + plugin SDKs
 * mirror these. UI_ICON_NONE renders a default bullet point. */
#define UI_ICON_NONE            0
#define UI_ICON_SUCCESS         2
#define UI_ICON_ERROR           1
#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
 
/* Semantic aliases. Plugins are free to use either the CP437 name or
 * a semantic one - they map to the same byte. */
#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

int host_ui_push_toast      (const char* text, uint8_t icon, uint16_t duration_ms);

int host_ui_push_message    (const char* text, uint8_t icon, uint32_t duration_ms);

int host_ui_push_confirm    (const char* text, uint8_t icon, uint32_t action_id);

int host_ui_push_info       (const char* title, const char* body);

int host_ui_view_image      (const uint8_t* data, uint32_t len);

int host_ui_view_markdown   (const uint8_t* data, uint32_t len);

int host_browser_open       (const char* url);

int host_ui_push_context_menu(const char* title, const ui_item_t* items, uint16_t count,
                              uint32_t select_action_id);

int host_ui_push_t9_input   (const char* title, const char* initial,
                             uint16_t max_len, uint32_t action_id);

int host_ui_push_password   (const char* title, const char* initial,
                             uint16_t max_len, uint32_t action_id);

int host_ui_push_pin_entry  (const char* title, uint8_t max_len, uint8_t max_attempts,
                             uint32_t action_id);
 
/* On confirm fires action_id with user_data = 1 (read the value via
 * host_ui_consume_input_int); on cancel fires with user_data = 0 and no value
 * pending. The view pops itself before the action fires. */
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);
 
/* RGB color picker. On Y the host fires action_id with idx = packed RGB
 * (0xRRGGBB) and user_data = 1; on N it fires with user_data = 0 and no value
 * pending. The view pops itself first. Read the packed value via
 * host_ui_consume_input_int(). */
int host_ui_push_color_picker(uint8_t initial_r, uint8_t initial_g, uint8_t initial_b,
                              uint32_t action_id);
 
/* On confirm fires action_id with user_data = 1 (read via
 * host_ui_consume_input_int); on cancel fires with user_data = 0. Pops first. */
int host_ui_push_date       (const char* title, uint8_t d, uint8_t m, uint16_t y,
                             uint32_t action_id);
 
/* On confirm fires action_id with user_data = 1 (read via
 * host_ui_consume_input_int); on cancel fires with user_data = 0. Pops first. */
int host_ui_push_time       (const char* title, uint8_t h, uint8_t m, uint32_t action_id);

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);
 
/* Replace the plugin's currently-top list view with a fresh one. Falls back
 * to a plain push when the plugin has no list on top (e.g. on first call).
 * Use this for "refresh after toggle" patterns so the view stack does not
 * grow on every action. */
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);
 
/* Override the footer hint for the plugin's current top view (list, confirm,
 * T9, pin, slider, date or time). Pass NULL or an empty string to fall back
 * to the view's default hint. The text is copied internally so the caller
 * can free it after the call returns. Returns HOST_ERR_NOT_FOUND if the top
 * view is not owned by the plugin runtime. */
int host_ui_set_view_footer (const char* hint);

int host_ui_set_view_empty  (const char* text);
 
/* Wire hide/show callbacks on the plugin's current top view. `hide_action_id`
 * fires via plugin_on_action(hide_action_id, 0, 0) when the view is covered by
 * another view or modal; `show_action_id` fires when it becomes visible again.
 * Pass 0 for either id to leave that event unhooked. Returns HOST_ERR_NOT_FOUND
 * if the top view is not owned by the plugin runtime. */
int host_ui_set_view_lifecycle(uint32_t hide_action_id, uint32_t show_action_id);
 
/* Redraw a single row of the plugin's current top list view in place, without
 * re-pushing or fully re-rendering the list. The label, icon and item_id of
 * the given index are replaced from `item`; the new label is copied
 * internally. Only repaints when the plugin's list is the active top view and
 * the row is on screen (partial refresh). Returns HOST_ERR_NOT_FOUND if the
 * top view is not the plugin's list, HOST_ERR_INVALID_ARG on a bad index. */
int host_ui_update_list_item(uint16_t index, const ui_item_t* item);
 
/* Insert a new row into the plugin's current top list at `index` (later rows
 * shift down), then partial-repaint. The label is copied internally. `index`
 * is clamped to the current item count (append). Returns HOST_ERR_NOT_FOUND if
 * the top view is not the plugin's list. */
int host_ui_insert_list_item(uint16_t index, const ui_item_t* item);
 
/* Remove the row at `index` from the plugin's current top list (later rows
 * shift up), then partial-repaint. Returns HOST_ERR_NOT_FOUND if the top view
 * is not the plugin's list, HOST_ERR_INVALID_ARG on a bad index. */
int host_ui_remove_list_item(uint16_t index);

int host_ui_pop                (void);

int host_ui_pop_to_plugin      (void);

int host_ui_repaint            (void);

int host_ui_consume_input_text (char* out, size_t out_size);

int host_ui_consume_input_int  (int32_t* out);

int host_ui_acquire_exclusive  (void);

int host_ui_release_exclusive  (void);

int host_ui_set_inactivity     (uint32_t timeout_ms, uint32_t action_id);
 
/*
 * Blink the badge backlight as a visual "look at me" signal. Count is clamped
 * to 1..10, period_ms (each off- and on-phase) to 50..1000. Use 0 for either
 * argument to take the default (2 cycles, 150 ms). Blocks the calling task
 * for `2 * count * period_ms` milliseconds; the underlying LEDC PWM is
 * thread-safe so no framebuffer ordering is involved.
 */
int host_ui_wink               (uint8_t count, uint16_t period_ms);


 
/* Canvas widget event subtypes used as the user_data on the widget callback. */
#define CANVAS_WIDGET_CHANGED   1
#define CANVAS_WIDGET_COMMITTED 2
#define CANVAS_WIDGET_CANCELLED 3

int host_view_canvas_push          (const char* title, uint32_t key_action_id,
                                    uint32_t widget_action_id);

int host_view_canvas_get_body_size (uint16_t* w, uint16_t* h);

int host_view_canvas_set_footer    (const char* hint);

int host_view_canvas_clear         (void);
 
/* Flags for host_view_canvas_clear_ex(). */
#define HOST_CANVAS_CLEAR_KEEP_SPRITES 0x01 

int host_view_canvas_clear_ex      (uint32_t flags);

int host_view_canvas_set_text_size (uint8_t size);
 
#define HOST_FONT_BUILTIN   0  
#define HOST_FONT_BOLD_9PT  1  
#define HOST_FONT_BOLD_12PT 2  
#define HOST_FONT_BOLD_18PT 3  
#define HOST_FONT_BOLD_24PT 4  
#define HOST_FONT_COUNT     5  

int host_view_canvas_set_font      (uint8_t font_id);

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);

int host_view_canvas_set_text_color(bool inverted);

int host_view_canvas_set_shade     (uint8_t shade);

int host_view_canvas_draw_text     (int16_t x, int16_t y, const char* text);

int host_view_canvas_draw_text_aligned(int16_t x, int16_t y, int16_t w,
                                       const char* text, uint8_t align);

int host_view_canvas_draw_rect     (int16_t x, int16_t y, int16_t w, int16_t h, bool filled);

int host_view_canvas_draw_pixel    (int16_t x, int16_t y);

int host_view_canvas_draw_line     (int16_t x0, int16_t y0, int16_t x1, int16_t y1);

int host_view_canvas_draw_circle   (int16_t x, int16_t y, int16_t r, bool filled);

int host_view_canvas_draw_triangle (int16_t x0, int16_t y0, int16_t x1, int16_t y1,
                                    int16_t x2, int16_t y2, bool filled);

int host_view_canvas_draw_round_rect(int16_t x, int16_t y, int16_t w, int16_t h,
                                    int16_t r, bool filled);

int host_view_canvas_draw_bitmap   (int16_t x, int16_t y, int16_t w, int16_t h,
                                    const uint8_t* data, uint32_t len);

int host_view_canvas_hline         (int16_t x, int16_t y, int16_t w);

int host_view_canvas_vline         (int16_t x, int16_t y, int16_t h);

int host_view_canvas_commit        (bool full_refresh);

int host_view_canvas_elem_begin    (uint32_t elem_id);

int host_view_canvas_elem_end      (void);

int host_view_canvas_elem_set_offset(uint32_t elem_id, int16_t ox, int16_t oy);

int host_view_canvas_elem_move     (uint32_t elem_id, int16_t dx, int16_t dy);

int host_view_canvas_elem_show     (uint32_t elem_id, bool visible);

int host_view_canvas_elem_remove   (uint32_t elem_id);

int host_view_canvas_elem_clear    (uint32_t elem_id);

int host_view_canvas_elem_set_z    (uint32_t elem_id, int8_t z);

int host_view_canvas_elem_get_offset(uint32_t elem_id, int16_t* ox, int16_t* oy);

int host_view_canvas_elem_get_bounds(uint32_t elem_id, int16_t* x, int16_t* y,
                                     uint16_t* w, uint16_t* h);
 
/* Animation refresh policies for host_view_canvas_set_anim_policy(). */
#define HOST_CANVAS_ANIM_REFRESH_AUTO  0 /* flash-free while running, one FAST
                                            cleanup ~1 s after going idle    */
#define HOST_CANVAS_ANIM_REFRESH_LIGHT 1 /* never clean up automatically;
                                            plugin manages ghosting itself   */

int host_view_canvas_set_anim_policy(uint8_t refresh_policy, uint8_t max_fps);

int host_view_canvas_draw_sprite   (int16_t x, int16_t y, uint32_t sprite);

int host_view_canvas_set_ink       (bool white);

int host_view_canvas_marquee       (int16_t x, int16_t y, int16_t window_w,
                                    const char* text, uint16_t step_px,
                                    uint16_t frame_ms);

int host_view_canvas_add_slider    (uint32_t widget_id, int32_t min, int32_t max,
                                    int32_t initial, int32_t step);

int host_view_canvas_add_text      (uint32_t widget_id, uint16_t max_len, const char* initial);

int host_view_canvas_add_button    (uint32_t widget_id);

int host_view_canvas_remove_widget (uint32_t widget_id);

int host_view_canvas_set_value     (uint32_t widget_id, int32_t value);

int host_view_canvas_get_value     (uint32_t widget_id, int32_t* out);

int host_view_canvas_set_text      (uint32_t widget_id, const char* text);

int host_view_canvas_get_text      (uint32_t widget_id, char* out, size_t cap);

int host_view_canvas_set_focus     (uint32_t widget_id);

int host_view_canvas_get_focus     (uint32_t* out);

int host_view_canvas_set_key_repeat(uint16_t initial_ms, uint16_t repeat_ms);

int host_view_canvas_set_long_press_action(uint32_t action_id);



#define HOST_ANIM_MAX            16
#define HOST_ANIM_REPEAT_FOREVER 0xFFFF
 
/* Easing curves (fixed-point Penner subset). */
#define HOST_EASE_LINEAR        0
#define HOST_EASE_QUAD_IN       1
#define HOST_EASE_QUAD_OUT      2
#define HOST_EASE_QUAD_IN_OUT   3
#define HOST_EASE_CUBIC_IN      4
#define HOST_EASE_CUBIC_OUT     5
#define HOST_EASE_CUBIC_IN_OUT  6
#define HOST_EASE_OVERSHOOT     7  /* back-out: overshoots, then settles  */
#define HOST_EASE_BOUNCE        8  /* bounce-out: ball-drop rebound       */
#define HOST_EASE_STEP          9  /* holds the start, jumps at the end   */
#define HOST_EASE_ELASTIC      10  /* elastic-out: springy overshoot wobble */
 
/* Tween flags. */
#define HOST_ANIM_FLAG_FROM_CURRENT 0x01 /* ignore from_x/y, start at the
                                            element's live offset          */
#define HOST_ANIM_FLAG_YOYO         0x02 /* each repeat alternates direction */
#define HOST_ANIM_FLAG_HIDE_DONE    0x04 /* hide the element on completion   */
#define HOST_ANIM_FLAG_SHOW_START   0x08 /* show the element when the delay
                                            elapses                        */

typedef struct {
    uint32_t elem_id;        
    int16_t  from_x;         
    int16_t  from_y;
    int16_t  to_x;           
    int16_t  to_y;
    uint16_t duration_ms;    
    uint16_t delay_ms;       
    uint16_t repeat;         
    uint8_t  easing;         
    uint8_t  flags;          
    uint32_t done_action_id; 
    uint32_t start_after;    
} host_anim_t;

int host_anim_start(const host_anim_t* cfg);

int host_anim_cancel(uint32_t handle);

int host_anim_pause(uint32_t handle, bool paused);
 
/* Tween states returned by host_anim_state(). */
#define HOST_ANIM_STATE_DELAYED 0
#define HOST_ANIM_STATE_RUNNING 1
#define HOST_ANIM_STATE_PAUSED  2

int host_anim_state(uint32_t handle);

int host_anim_active_count(void);

int host_anim_blink(uint32_t elem_id, uint16_t period_ms, uint16_t count,
                    uint32_t done_action_id);



uint16_t host_display_width    (void);

uint16_t host_display_height   (void);

int      host_display_clear    (void);

int      host_display_draw_pixel(int16_t x, int16_t y, uint16_t color);

int      host_display_draw_line (int16_t x0, int16_t y0, int16_t x1, int16_t y1,
                                 uint16_t color);

int      host_display_draw_rect (int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color);

int      host_display_fill_rect (int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color);

int      host_display_draw_text (int16_t x, int16_t y, const char* text, uint8_t size,
                                 uint16_t color);

int      host_display_flush     (uint8_t refresh_mode);

bool     host_display_is_busy   (void);

int      host_display_set_backlight(uint16_t level);

uint16_t host_display_get_backlight(void);


 
#define HOST_LANG_EN 0
#define HOST_LANG_DE 1

int      host_i18n_tr_key          (const char* key,   char* out, uint32_t out_cap);

int      host_i18n_tr_meta         (const char* field, char* out, uint32_t out_cap);

int      host_i18n_tr_core         (const char* key,   char* out, uint32_t out_cap);

uint8_t  host_i18n_current_language(void);


 
#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_MODULE_EVENT      (1u << 15)
#define EVENT_DISPLAY_REFRESH   (1u << 16)

int host_event_subscribe  (uint32_t event_mask, uint32_t action_id);

int host_event_unsubscribe(uint32_t subscription_id);

int host_event_publish    (uint32_t module_event_subtype, uint32_t value);


 
#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

bool host_key_pressed     (uint8_t key);

int  host_key_consume_next(uint8_t* out_key);



int host_usb_cdc_write(const uint8_t* data, size_t len);



bool host_feature_enabled       (uint16_t feature_id);

int  host_get_firmware_version  (char* out, size_t out_size);

int  host_get_build_profile     (char* out, size_t out_size);

uint8_t host_cpu_load           (void);



int host_cmd_consume (char* out, size_t out_size);



#define HOST_MSG_PAYLOAD_MAX 4096
#define HOST_MSG_MIME_MAX 64

#define HOST_MSG_FLAG_PERSIST 0x01

int host_msg_register_handler(const char* mime_type, uint32_t action_id);

int host_msg_unregister_handler(const char* mime_type);

int host_msg_consume(uint8_t* buf, size_t buf_size, char* mime_out, size_t mime_size);

int host_msg_send_interactive(const char* mime_type, const uint8_t* data, size_t len,
                              uint32_t flags);

int host_msg_send(const uint8_t addr[6], uint8_t addr_type, const char* mime_type,
                  const uint8_t* data, size_t len, uint32_t flags);



#define HOST_EXT_FEATURE_NAME_MAX 33
#define HOST_EXT_FEATURE_PAYLOAD_MAX 32768
#define HOST_EXT_FEATURE_STATUS_DONE 0
#define HOST_EXT_FEATURE_STATUS_ERROR 1

int host_ext_feature_available(const char* feature);

int host_ext_feature_use(const char* feature, const uint8_t* data, size_t len,
                         uint32_t status_action_id);

int host_ext_feature_register_handler(const char* feature, uint32_t action_id);

int host_ext_feature_consume(uint8_t* buf, size_t buf_size,
                             char* feature_out, size_t feature_size);

int host_ext_feature_result(int32_t status_code);



#define HOST_VCARD_MAX_LEN 768

int host_vcard_get_own(char* out, size_t out_size);

int host_vcard_received_count(void);

int host_vcard_received_get(uint16_t index, char* out, size_t out_size);

int host_vcard_received_display(uint16_t index, char* out, size_t out_size);

int host_vcard_set_own(const char* vcard, size_t len);

int host_vcard_received_add(const char* vcard, size_t len);

int host_vcard_received_update(uint16_t index, const char* vcard, size_t len);

int host_vcard_received_delete(uint16_t index);



int host_qr_measure(const char* data, uint8_t max_version, uint8_t ecc,
                    uint16_t* out_modules);

int host_qr_render_bitmap(const char* data, uint8_t max_version, uint8_t ecc,
                          uint8_t scale, uint8_t quiet_modules,
                          uint8_t* out, size_t out_size,
                          uint16_t* out_stride_bytes, uint16_t* out_height_px);



int host_image_info(const uint8_t* data, size_t len, uint16_t* out_w, uint16_t* out_h);

int host_image_render(const uint8_t* data, size_t len, uint16_t target_w,
                      uint8_t* out, size_t out_size,
                      uint16_t* out_stride_bytes, uint16_t* out_height_px);



#define HOST_SURFACE_MAX_PER_PLUGIN 2
#define HOST_SURFACE_MAX_BYTES 65536

int host_surface_create(uint16_t w, uint16_t h);

int host_surface_destroy(uint32_t surface);

int host_surface_clear(uint32_t surface);

int host_surface_set_font(uint32_t surface, uint8_t font_id);

int host_surface_set_text_size(uint32_t surface, uint8_t size);

int host_surface_set_text_color(uint32_t surface, uint8_t inverted);

int host_surface_set_shade(uint32_t surface, uint8_t shade);

int host_surface_draw_text(uint32_t surface, int16_t x, int16_t y, const char* text);

int host_surface_draw_text_aligned(uint32_t surface, int16_t x, int16_t y, int16_t w,
                                   const char* text, uint8_t align);

int host_surface_measure_text(uint32_t surface, const char* text,
                              uint16_t* out_w, uint16_t* out_h);

int host_surface_draw_pixel(uint32_t surface, int16_t x, int16_t y);

int host_surface_draw_line(uint32_t surface, int16_t x0, int16_t y0, int16_t x1, int16_t y1);

int host_surface_draw_rect(uint32_t surface, int16_t x, int16_t y, int16_t w, int16_t h,
                           uint8_t filled);

int host_surface_draw_circle(uint32_t surface, int16_t x, int16_t y, int16_t r,
                             uint8_t filled);

int host_surface_draw_triangle(uint32_t surface, int16_t x0, int16_t y0,
                               int16_t x1, int16_t y1, int16_t x2, int16_t y2,
                               uint8_t filled);

int host_surface_draw_round_rect(uint32_t surface, int16_t x, int16_t y,
                                 int16_t w, int16_t h, int16_t r, uint8_t filled);

int host_surface_hline(uint32_t surface, int16_t x, int16_t y, int16_t w);

int host_surface_vline(uint32_t surface, int16_t x, int16_t y, int16_t h);

int host_surface_draw_bitmap(uint32_t surface, int16_t x, int16_t y,
                             int16_t w, int16_t h, const uint8_t* data, uint32_t len);

int host_surface_export(uint32_t surface, uint8_t* out, size_t out_size,
                        uint16_t* out_stride_bytes);

int host_surface_export_jpg(uint32_t surface, uint8_t quality,
                            uint8_t* out, size_t out_size, uint32_t* out_len);

int host_surface_draw_sprite(uint32_t surface, int16_t x, int16_t y, uint32_t sprite);



#define HOST_SPRITE_MAX_PER_CANVAS 8
#define HOST_SPRITE_MAX_FRAMES     32
#define HOST_SPRITE_ARENA_BYTES    65536
 
/* Playback modes. */
#define HOST_SPRITE_ONCE      0  /* play to the last frame and hold it     */
#define HOST_SPRITE_LOOP      1  /* wrap around; finite runs hold the last */
#define HOST_SPRITE_PING_PONG 2  /* forward then backward per cycle        */
 
/* Sprite flags. */
#define HOST_SPRITE_FLAG_OPAQUE 0x01 /* unset data bits paint white         */
#define HOST_SPRITE_FLAG_FLIP_H 0x02 /* mirror horizontally when drawn      */
#define HOST_SPRITE_FLAG_FLIP_V 0x04 /* mirror vertically when drawn        */
#define HOST_SPRITE_FLAG_ROT_90 0x08 /* rotate 90 deg clockwise (before the
                                        flips; combine for 180/270). The
                                        drawn box becomes h x w.            */

int host_sprite_create(uint16_t frame_w, uint16_t frame_h, uint16_t frame_count,
                       const uint8_t* frames, uint32_t len);

int host_sprite_create_from_surface(uint32_t surface, uint16_t frame_w,
                                    uint16_t frame_h, uint16_t frame_count);

int host_sprite_set_mask(uint32_t sprite, const uint8_t* mask, uint32_t len);

int host_sprite_create_from_image(const uint8_t* data, uint32_t len,
                                  uint16_t target_w, uint16_t frame_h);

int host_sprite_set_flags(uint32_t sprite, uint8_t flags);

int host_sprite_set_scale(uint32_t sprite, uint8_t scale);

int host_sprite_set_frame(uint32_t sprite, uint16_t frame);

int host_sprite_get_frame(uint32_t sprite, uint16_t* out);

int host_sprite_set_frame_durations(uint32_t sprite, const uint16_t* ms,
                                    uint16_t count);

int host_sprite_play(uint32_t sprite, uint8_t mode, uint16_t frame_ms,
                     uint16_t repeat, uint32_t done_action_id);

int host_sprite_stop(uint32_t sprite);

int host_sprite_destroy(uint32_t sprite);



#define HOST_STR_TARGET_CP437   0  /* GFX builtin glcdfont (default after splash) */
#define HOST_STR_TARGET_LATIN1  1  /* FreeMonoBold*pt8b fonts (Latin-1 indexed)   */

int host_str_to_display(const char* in, char* out, size_t out_size, uint32_t target);

int host_str_to_utf8(const char* in, char* out, size_t out_size);


 
#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

int host_gpio_set_direction(uint8_t pin, uint8_t direction);

int host_gpio_set_pull     (uint8_t pin, uint8_t pull);

int host_gpio_write        (uint8_t pin, bool level);

int host_gpio_read         (uint8_t pin, bool* level);

int host_gpio_release      (uint8_t pin);

int host_gpio_pwm_start    (uint8_t pin, uint32_t freq_hz, uint16_t duty_per_mille);

int host_gpio_pwm_set_duty (uint8_t pin, uint16_t duty_per_mille);

int host_gpio_pwm_stop     (uint8_t pin);

int host_adc_read          (uint8_t pin, uint16_t* raw, uint16_t* millivolt);

int host_i2c_write         (uint8_t bus, uint8_t addr, const uint8_t* data, size_t len);

int host_i2c_read          (uint8_t bus, uint8_t addr, uint8_t* data, size_t len);

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);

int host_i2c_scan          (uint8_t bus, uint8_t* found_addrs, size_t* count);

int host_sao_eeprom_read   (uint16_t offset, uint8_t* buf, size_t len);

int host_sao_eeprom_write  (uint16_t offset, const uint8_t* buf, size_t len);


 
#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

int      host_pixel_strip_init    (uint8_t gpio_pin, uint16_t num_pixels, uint8_t format);

int      host_pixel_strip_deinit  (void);

int      host_pixel_strip_set     (uint16_t index, uint8_t r, uint8_t g, uint8_t b);

int      host_pixel_strip_fill    (uint8_t r, uint8_t g, uint8_t b);

int      host_pixel_strip_clear   (void);

int      host_pixel_strip_refresh (void);

uint16_t host_pixel_strip_length  (void);

bool     host_pixel_strip_ready   (void);



int host_lockscreen_register_action  (const char* label_key, uint32_t action_id);

int host_lockscreen_unregister_action(void);

int host_lockscreen_alert            (const char* text, uint8_t icon, uint32_t action_id);

 
#ifdef __cplusplus
}
#endif
 
#endif /* CDC_BADGE_HOST_API_H */