> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperwisor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ESP-IDF — API Reference

> The C API exposed through the umbrella header.

Include the umbrella header to access the full API:

```c theme={null}
#include "hyperwisor.h"
```

## Lifecycle

```c theme={null}
void hyperwisor_init(void);    /* initialize subsystems */
void hyperwisor_start(void);   /* spawn the core task: Wi-Fi, NTP, realtime, commands */
```

## Credentials

```c theme={null}
bool hyperwisor_has_credentials(void);
void hyperwisor_set_credentials(const char *ssid, const char *password,
                                const char *device_id, const char *user_id);
```

Credentials persist in NVS, so set them only on first boot or when overriding.

## Custom commands

Register a handler for a named command. The handler receives the sender ID and
the command payload as `cJSON`. Reply with `hyperwisor_send_response`:

```c theme={null}
static void cmd_blink(const char *from, cJSON *payload)
{
    gpio_set_level(GPIO_NUM_2, 1);

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

void app_main(void)
{
    hyperwisor_init();
    hyperwisor_register_cmd_handler("BLINK", cmd_blink);
    hyperwisor_start();
}
```

## Feature modules

The umbrella header pulls in feature headers. Their exact function signatures
live in the headers themselves — treat those as 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_cmd.h`    | Command registration + responses                              |
| `hyperwisor_nvs.h`    | Persistent storage helpers                                    |
| `hyperwisor_widget.h` | Push values to dashboard widgets (`HYPERWISOR_ENABLE_WIDGET`) |
| `hyperwisor_ntp.h`    | Time sync (`HYPERWISOR_ENABLE_NTP`)                           |
| `hyperwisor_http.h`   | `hyperwisor_http_get/post` helpers (`HYPERWISOR_ENABLE_HTTP`) |
| `hyperwisor_port.h`   | Board port struct                                             |
| `hyperwisor_ota.h`    | OTA (`HYPERWISOR_ENABLE_OTA`)                                 |
| `hyperwisor_gpio.h`   | Cloud GPIO (`HYPERWISOR_ENABLE_GPIO`)                         |

<Card title="Next: OTA updates" icon="cloud-arrow-up" href="/firmware/esp-idf/ota">
  Enable over-the-air firmware updates.
</Card>