ESP-IDF

Include the umbrella header to access the full API:

#include "hyperwisor.h"

All functions take a target_id (where a message is routed — your dashboard/user) and, for widgets, a widget_id. Read target_id from an incoming command’s from, or from your stored configuration.

Lifecycle

void hyperwisor_init(void);    /* initialize subsystems */
void hyperwisor_start(void);   /* spawn the core task: Wi-Fi, NTP, realtime, commands */

void app_main(void)
{
    hyperwisor_init();
    if (!hyperwisor_has_credentials())
        hyperwisor_set_credentials("MySSID", "MyPass", "my-device-id", "my-user-id");
    hyperwisor_start();
}

Credentials

bool hyperwisor_has_credentials(void);
void hyperwisor_set_credentials(const char *ssid, const char *password,
                                const char *device_id, const char *user_id);

Persisted in NVS — set only on first boot or to override.

Connection state

bool hyperwisor_ws_is_connected(void);

if (hyperwisor_ws_is_connected()) {
    // safe to push widget updates
}

Receiving commands

void hyperwisor_register_cmd_handler(const char *name,
                                     void (*handler)(const char *from, cJSON *payload));

static void handle_relay(const char *from, cJSON *payload)
{
    cJSON *params = /* navigate payload → command → action → params */;
    bool on = cJSON_IsTrue(cJSON_GetObjectItem(params, "value"));
    gpio_set_level(RELAY_GPIO, on);

    cJSON *resp = cJSON_CreateObject();
    cJSON_AddStringToObject(resp, "status", "ok");
    hyperwisor_send_response(from, resp);   // reply to the sender
    cJSON_Delete(resp);
}

void app_main(void)
{
    hyperwisor_init();
    hyperwisor_register_cmd_handler("relay_control", handle_relay);
    hyperwisor_start();
}

Responding & emitting

esp_err_t hyperwisor_send_response(const char *from, cJSON *reply);
esp_err_t hyperwisor_emit(const char *target_id, const char *command,
                          const char *action, cJSON *params);

send_response replies to a command’s sender; emit sends a command/action/params message to any target.

cJSON *p = cJSON_CreateObject();
cJSON_AddNumberToObject(p, "value", 42);
hyperwisor_emit(target_id, "get_status", "response", p);
cJSON_Delete(p);

Updating widgets

Push a value to a dashboard widget by its widget ID (enable 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);

// Push a sensor reading to a Gauge (widget ID "w_temp")
hyperwisor_update_widget_float(target_id, "w_temp", 27.4f);

// Push text to a Label
hyperwisor_update_widget_string(target_id, "w_status", "OK");

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

Dialogs

Show a dialog on the user’s dashboard.

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

Board port (optional)

Provide a hyperwisor_port_t of function pointers for a specific board’s GPIO whitelist, display backlight, or sensors, and register it before init:

hyperwisor_set_port(&board_port_s3);
hyperwisor_init();

Feature modules

The umbrella header pulls in feature headers — their signatures are the source of truth:

Header	Provides
`hyperwisor_core.h`	Init/start lifecycle
`hyperwisor_wifi.h`	Wi-Fi connect / provisioning
`hyperwisor_ws.h`	Realtime transport + `hyperwisor_ws_is_connected`
`hyperwisor_cmd.h`	`register_cmd_handler`, `send_response`, `emit`
`hyperwisor_widget.h`	`update_widget_*` and dialogs (`HYPERWISOR_ENABLE_WIDGET`)
`hyperwisor_nvs.h`	Persistent storage helpers
`hyperwisor_ntp.h`	Time sync (`HYPERWISOR_ENABLE_NTP`)
`hyperwisor_http.h`	`hyperwisor_http_get/post` (`HYPERWISOR_ENABLE_HTTP`)
`hyperwisor_port.h`	Board port struct
`hyperwisor_ota.h`	OTA (`HYPERWISOR_ENABLE_OTA`)
`hyperwisor_gpio.h`	Cloud GPIO (`HYPERWISOR_ENABLE_GPIO`)

Examples

A real project walkthrough.

OTA updates

Enable over-the-air firmware.

Overview

Arduino

ESP-IDF — API Reference

Lifecycle

Credentials

Connection state

Receiving commands

Responding & emitting

Updating widgets

Dialogs

Board port (optional)

Feature modules

Examples

OTA updates

​Lifecycle

​Credentials

​Connection state

​Receiving commands

​Responding & emitting

​Updating widgets

​Dialogs

​Board port (optional)

​Feature modules

Examples

OTA updates

Lifecycle

Credentials

Connection state

Receiving commands

Responding & emitting

Updating widgets

Dialogs

Board port (optional)

Feature modules