ESP-IDF

Include the umbrella header to access the full API:

#include "hyperwisor.h"

Everything outbound takes a target_id — where the message is routed. Inside a command handler that is the from argument, so a reply, a widget update and a dialog all go back to whoever asked. Widget calls also take a widget_id. Most functions return esp_err_t (ESP_OK on success). The *_with_response variants return a cJSON * you own and must cJSON_Delete().

Lifecycle

esp_err_t hyperwisor_init(void);             /* NVS, Wi-Fi, state. Call first */
esp_err_t hyperwisor_enable_security(void);  /* create or load the on-chip identity */
esp_err_t hyperwisor_start(void);            /* connect and spawn the core task */

void app_main(void)
{
    hyperwisor_init();
    hyperwisor_register_cmd_handler("relay_control", handle_relay);  /* before start */
    hyperwisor_enable_security();
    hyperwisor_start();
}

Register handlers before hyperwisor_start(). A command arriving on the first connection is otherwise answered with “Unknown command”.

Device state

hyperwisor_state_t *hyperwisor_get_state(void);
void hyperwisor_state_lock(void);
void hyperwisor_state_unlock(void);

The struct carries device_id, ssid, user_id, product_id, version, and the flags wifi_connected, ip_ready, ws_connected, ap_mode_active, ntp_initialized, plus uptime_seconds. Take the lock if you read it from a task other than your handler.

Gate anything that needs the network on ip_ready, not wifi_connected. The latter goes true at association, roughly 850 ms before DHCP hands over an address — DNS cannot resolve in that window.

Connection state

bool hyperwisor_ws_is_connected(void);

if (hyperwisor_ws_is_connected()) {
    hyperwisor_update_widget_float(target_id, "w_temp", read_temp());
}

Receiving commands

esp_err_t hyperwisor_register_cmd_handler(const char *command,
                                          void (*handler)(const char *from, cJSON *payload));
void      hyperwisor_register_user_msg_cb(void (*cb)(const char *json_str, int len));
esp_err_t hyperwisor_cmd_process(const char *json_str);

register_user_msg_cb sees every inbound message — useful for debugging or a protocol of your own. cmd_process feeds a message in by hand. The handler gets the whole envelope, so use the helpers to dig into it:

cJSON *hyperwisor_cmd_find_command(cJSON *payload, const char *command);
cJSON *hyperwisor_cmd_find_action (cJSON *payload, const char *command, const char *action);
cJSON *hyperwisor_cmd_find_params (cJSON *payload, const char *command, const char *action);

static void handle_relay(const char *from, cJSON *payload)
{
    cJSON *params = hyperwisor_cmd_find_params(payload, "relay_control", "update");
    if (!params) return;

    cJSON *state = cJSON_GetObjectItem(params, "state");
    bool on = cJSON_IsString(state) && strcmp(state->valuestring, "true") == 0;
    gpio_set_level(RELAY_GPIO, on);

    cJSON *resp = cJSON_CreateObject();
    cJSON_AddStringToObject(resp, "status", "ok");
    hyperwisor_send_response(from, resp);
    cJSON_Delete(resp);
}

The dashboard sends parameters as strings — "true", not true. Write cJSON_IsBool() and nothing will happen.

Responding and emitting

esp_err_t hyperwisor_send_response(const char *to, cJSON *payload);
esp_err_t hyperwisor_emit(const char *target_id, const char *command,
                          const char *action, cJSON *params);
esp_err_t hyperwisor_send_to(const char *target_id, void (*payload_builder)(cJSON *payload));
cJSON    *hyperwisor_cmd_build_response(const char *from, cJSON *payload);

emit takes ownership of params — do not delete it yourself.

cJSON *p = cJSON_CreateObject();
cJSON_AddStringToObject(p, "relay", "1");
hyperwisor_emit(target_id, "relay_control", "update", p);   /* p is consumed */

Updating widgets

Push a value to a dashboard widget by its widget ID (needs HYPERWISOR_ENABLE_WIDGET).

Where do I get the widgetId? Select the widget in the Dashboard Designer and open General → Basic. The Widget ID field holds the value — use the copy button and paste it into your updateWidget / widget.* call. See Binding Data for the full model.

Widget ID in the General tab — Copy a widget's ID from General → Basic — this is the value your update calls reference.

esp_err_t hyperwisor_update_widget_string(const char *target_id, const char *widget_id, const char *value);
esp_err_t hyperwisor_update_widget_float (const char *target_id, const char *widget_id, float value);
esp_err_t hyperwisor_update_widget_float_array (const char *target_id, const char *widget_id, const float *values, int count);
esp_err_t hyperwisor_update_widget_int_array   (const char *target_id, const char *widget_id, const int   *values, int count);
esp_err_t hyperwisor_update_widget_string_array(const char *target_id, const char *widget_id, const char **values, int count);

hyperwisor_update_widget_float (target_id, "w_temp",   27.4f);   /* Gauge  */
hyperwisor_update_widget_string(target_id, "w_status", "OK");    /* Label  */

float pts[] = { 1.2f, 3.4f, 2.1f };
hyperwisor_update_widget_float_array(target_id, "w_chart", pts, 3);   /* Chart */

Specialised widgets

esp_err_t hyperwisor_update_countdown(const char *target_id, const char *widget_id,
                                      const char *hours, const char *minutes, const char *seconds);
esp_err_t hyperwisor_update_flight_attitude(const char *target_id, const char *widget_id,
                                            float roll, float pitch);
esp_err_t hyperwisor_update_heat_map(const char *target_id, const char *widget_id,
                                     const hyperwisor_heat_map_point_t *points, int count);
esp_err_t hyperwisor_update_3d_model (const char *target_id, const char *widget_id, const char *model_url);
esp_err_t hyperwisor_update_3d_widget(const char *target_id, const char *widget_id,
                                      const hyperwisor_3d_model_update_t *models, int count);
esp_err_t hyperwisor_update_widget_position(const char *target_id, const char *widget_id,
                                            int x, int y, int w, int h, int r);

/* Artificial horizon, in degrees */
hyperwisor_update_flight_attitude(target_id, "w_attitude", roll_deg, pitch_deg);

/* Heat map — x, y, value */
hyperwisor_heat_map_point_t pts[] = { {0,0,12}, {1,0,30}, {2,0,55} };
hyperwisor_update_heat_map(target_id, "w_heat", pts, 3);

hyperwisor_update_widget_position moves, resizes and rotates a widget from the device — r is rotation in degrees.

Telemetry and status

esp_err_t hyperwisor_send_sensor_data_logger(const char *target_id, const char *config_id,
                                             const char **names, const float *values, int count);
esp_err_t hyperwisor_send_device_status(const char *target_id);

const char *names[]  = { "temperature", "humidity" };
float       values[] = { 27.4f, 61.0f };
hyperwisor_send_sensor_data_logger(target_id, "cfg_room1", names, values, 2);

DEVICE_STATUS is answered by the library automatically — you do not need to register a handler for it. send_device_status is there for reporting unprompted.

Dialogs

esp_err_t hyperwisor_show_dialog(const char *target_id, const char *title,
                                 const char *description, const char *icon);
esp_err_t hyperwisor_info_dialog   (const char *target_id, const char *title, const char *description);
esp_err_t hyperwisor_warning_dialog(const char *target_id, const char *title, const char *description);
esp_err_t hyperwisor_success_dialog(const char *target_id, const char *title, const char *description);
esp_err_t hyperwisor_error_dialog  (const char *target_id, const char *title, const char *description);
esp_err_t hyperwisor_risk_dialog   (const char *target_id, const char *title, const char *description);

hyperwisor_success_dialog(target_id, "Done", "HVAC reached target temperature.");

Identity and security

esp_err_t hyperwisor_enable_security(void);
esp_err_t hyperwisor_get_public_key_b64(char *out_buf, size_t buf_len);
esp_err_t hyperwisor_hsc_register(const char *functions_base_url, const char *user_auth_token);
bool      hyperwisor_hsc_ready(void);
void      hyperwisor_hsc_erase(void);

Each device generates an ECDSA P-256 keypair in NVS. On connect the platform issues a challenge, the device signs it, and nothing the application sends leaves before auth_ok. The private key never leaves the chip; only the public key is ever shared.

char pub[128];
hyperwisor_get_public_key_b64(pub, sizeof(pub));   /* safe to print */
ESP_LOGI(TAG, "public key: %s", pub);

hyperwisor_hsc_register() registers the key against an account without the app — for a factory jig, or a device you provision yourself.

hyperwisor_hsc_erase() destroys the identity. The device generates a new keypair on the next boot and is an unknown device to the platform until that new key is registered.

Credentials

esp_err_t hyperwisor_set_credentials(const char *ssid, const char *password,
                                     const char *device_id, const char *user_id);
esp_err_t hyperwisor_set_wifi_credentials(const char *ssid, const char *password);
esp_err_t hyperwisor_set_device_id(const char *device_id);
esp_err_t hyperwisor_set_user_id(const char *user_id);
esp_err_t hyperwisor_set_api_keys(const char *api_key, const char *secret_key);
esp_err_t hyperwisor_clear_credentials(void);
bool      hyperwisor_has_credentials(void);
esp_err_t hyperwisor_get_device_id(char *out_buf, size_t buf_len);
esp_err_t hyperwisor_get_user_id (char *out_buf, size_t buf_len);

Everything is persisted in NVS. Normally you set none of this — the app writes it during provisioning.

Setting credentials in code does not replace provisioning. A device that skips it never registers its public key and is refused as unknown device, with no setup access point to fall back to. If you provision in code, call hyperwisor_hsc_register() as well.

Database

Read and write a product’s cloud tables straight from the device (needs HYPERWISOR_ENABLE_HTTP).

esp_err_t hyperwisor_db_insert(const char *product_id, const char *device_id,
                               const char *table_name, void (*data_builder)(cJSON *data));
esp_err_t hyperwisor_db_get   (const char *product_id, const char *table_name, int limit);
esp_err_t hyperwisor_db_update(const char *data_id, void (*data_builder)(cJSON *data));
esp_err_t hyperwisor_db_delete(const char *data_id);

Each has a *_with_response variant returning cJSON * that you must delete.

static void build_reading(cJSON *data)
{
    cJSON_AddNumberToObject(data, "temperature", 27.4);
    cJSON_AddStringToObject(data, "unit", "C");
}

hyperwisor_db_insert(product_id, device_id, "readings", build_reading);

Users

esp_err_t hyperwisor_authenticate_user(const char *email, const char *password);
cJSON    *hyperwisor_authenticate_user_with_response(const char *email, const char *password);

For devices with their own sign-in screen — a panel shared by several people.

SMS

esp_err_t hyperwisor_send_sms(const char *product_id, const char *to, const char *message);
cJSON    *hyperwisor_send_sms_with_response(const char *product_id, const char *to, const char *message);

Sends through the product’s configured SMS provider — see SMS in the Studio.

hyperwisor_send_sms(product_id, "+919999999999", "Tank level critical.");

Onboarding from the device

esp_err_t hyperwisor_onboard_device(const char *product_id, const char *user_id,
                                    const char *device_name, const char *device_identifier);
cJSON    *hyperwisor_onboard_device_with_response(const char *product_id, const char *user_id,
                                                  const char *device_name, const char *device_identifier);

Registers the device against a user’s account from firmware, for flows that do not go through the app — a factory jig, or a device with its own screen.

Persistent storage

Your own key/value store in NVS, separate from the credentials above.

esp_err_t hyperwisor_nvs_get_str(const char *key, char *out_buf, size_t buf_len);
esp_err_t hyperwisor_nvs_set_str(const char *key, const char *value);
esp_err_t hyperwisor_nvs_get_i32(const char *key, int32_t *out_value);
esp_err_t hyperwisor_nvs_set_i32(const char *key, int32_t value);
esp_err_t hyperwisor_nvs_commit(void);

hyperwisor_nvs_set_i32("setpoint", 22);
hyperwisor_nvs_commit();          /* writes are buffered until you commit */

int32_t setpoint = 22;
hyperwisor_nvs_get_i32("setpoint", &setpoint);

Time

esp_err_t hyperwisor_ntp_init(const char *timezone);
esp_err_t hyperwisor_ntp_set_timezone(const char *timezone);
esp_err_t hyperwisor_ntp_get_time    (char *out_buf, size_t buf_len);
esp_err_t hyperwisor_ntp_get_date    (char *out_buf, size_t buf_len);
esp_err_t hyperwisor_ntp_get_datetime(char *out_buf, size_t buf_len);

hyperwisor_ntp_init("IST-5:30");

char now[32];
hyperwisor_ntp_get_datetime(now, sizeof(now));

Wi-Fi

bool      hyperwisor_wifi_is_connected(void);
esp_err_t hyperwisor_wifi_get_ip(char *out_buf);
esp_err_t hyperwisor_wifi_connect(const char *ssid, const char *pass);
esp_err_t hyperwisor_wifi_start_ap(const char *ssid, const char *pass);
esp_err_t hyperwisor_wifi_stop_ap(void);
esp_err_t hyperwisor_wifi_start_provisioning_server(void);
esp_err_t hyperwisor_wifi_stop_provisioning_server(void);
void      hyperwisor_wifi_register_cb(hyperwisor_wifi_cb_t cb);

The callback fires on HYPERWISOR_WIFI_EVT_CONNECTED, _DISCONNECTED, _AP_START, _AP_STOP and _GOT_IP.

GPIO

Needs HYPERWISOR_ENABLE_GPIO.

void      hyperwisor_gpio_set_allowlist(const int *gpios, int count);
esp_err_t hyperwisor_gpio_set_pin_mode(int pin, const char *mode);
esp_err_t hyperwisor_gpio_digital_write(int pin, const char *level);
bool      hyperwisor_gpio_digital_read(int pin);
esp_err_t hyperwisor_gpio_save_state(int pin, int state);
int       hyperwisor_gpio_load_state(int pin);
void      hyperwisor_gpio_restore_all_states(void);

static const int allowed[] = { 4, 5, 18 };
hyperwisor_gpio_set_allowlist(allowed, 3);

The allowlist is required. Without one, cloud GPIO commands are refused — deliberately, so a command from the internet can never reach a pin driving something you did not intend.

save_state / restore_all_states persist output levels across a reboot.

OTA

Needs HYPERWISOR_ENABLE_OTA. See OTA updates for the partition table.

esp_err_t hyperwisor_ota_perform(const char *url);
void      hyperwisor_ota_get_version(char *out_buf, size_t buf_len);
int       hyperwisor_ota_get_progress(void);     /* -1 idle, else 0..100 */
bool      hyperwisor_ota_is_in_progress(void);
bool      hyperwisor_ota_confirm_good_boot(void);

if (hyperwisor_ota_is_in_progress()) {
    show_progress(hyperwisor_ota_get_progress());   /* do not reboot here */
}

Board port

void hyperwisor_set_port(const hyperwisor_port_t *port);
const hyperwisor_port_t *hyperwisor_get_port(void);

A struct of function pointers describing your board — GPIO allowlist, display backlight, device name. The library never knows how your hardware works; it calls what you provide. Register it before hyperwisor_init().

hyperwisor_set_port(&board_port_s3);
hyperwisor_init();

Feature headers

The umbrella header pulls these in — their signatures are the source of truth.

Header	Provides
`hyperwisor_core.h`	Lifecycle, state, credentials, identity
`hyperwisor_cmd.h`	Handlers, `emit`, the `find_*` envelope helpers
`hyperwisor_widget.h`	`update_widget_*`, dialogs, data logger (`ENABLE_WIDGET`)
`hyperwisor_wifi.h`	Station, access point, provisioning server
`hyperwisor_ws.h`	Realtime transport, `hyperwisor_ws_is_connected`
`hyperwisor_hsc.h`	On-chip identity, signing, key registration
`hyperwisor_http.h`	HTTP helpers and the database API (`ENABLE_HTTP`)
`hyperwisor_nvs.h`	Persistent storage helpers
`hyperwisor_ntp.h`	Time sync (`ENABLE_NTP`)
`hyperwisor_port.h`	Board port struct
`hyperwisor_ota.h`	OTA (`ENABLE_OTA`)
`hyperwisor_gpio.h`	Cloud GPIO (`ENABLE_GPIO`)

Examples

A real project walkthrough.

OTA updates

Enable over-the-air firmware.

Overview

Arduino

ESP-IDF — API Reference

Lifecycle

Device state

Connection state

Receiving commands

Responding and emitting

Updating widgets

Specialised widgets

Telemetry and status

Dialogs

Identity and security

Credentials

Database

Users

SMS

Onboarding from the device

Persistent storage

Time

Wi-Fi

GPIO

OTA

Board port

Feature headers

Examples

OTA updates