File espos_wifi.h¶

File List > espos_wifi > include > espos_wifi.h
/*
 * SPDX-FileCopyrightText: 2026 Dirk Wahrheit
 * SPDX-License-Identifier: Apache-2.0
 *
 * espos_wifi — station connection manager with an explicit status model,
 * multi-network priority list, exponential backoff, static or DHCP
 * addressing, and a SoftAP provisioning portal. Configuration lives in the
 * "wifi" namespace of espos_config; status is exposed at GET /api/v1/wifi/status
 * and pushed on the SSE stream as "wifi" events.
 *
 * The station is one transport of espos_net (espos_net.h): it reports its
 * link there, and "is the network up" is espos_net_is_up(), not this
 * component's state — a firmware with an Ethernet port or without WiFi at
 * all answers the same question the same way. The device id, the hostname
 * (net.hostname) and the mDNS responder (espos_mdns.h) are espos_net's too;
 * the wrappers below stay for one release.
 */
#pragma once

#include <stdbool.h>
#include <stddef.h>
#include "esp_err.h"
#include "espos_wifi_sm.h"

#ifdef __cplusplus
extern "C" {
#endif

esp_err_t espos_wifi_start(void);
esp_err_t espos_wifi_stop(void);

typedef struct {
    espos_wifi_sm_status_t sm;
    int8_t rssi;
    uint32_t backoff_remaining_ms;
    uint32_t connected_s;      /* seconds since GOT_IP, 0 if not connected */
    char hostname[33];
    char portal_ssid[33];
    char portal_ip[16];
} espos_wifi_status_t;

esp_err_t espos_wifi_get_status(espos_wifi_status_t *out);

esp_err_t espos_wifi_refresh_rssi(void);

esp_err_t espos_wifi_status_json(char **out_json);

/* Scan API: start is asynchronous; results are cached and a "wifi_scan"
 * SSE event fires when they are ready. */
esp_err_t espos_wifi_scan_start(void);
typedef struct {
    char ssid[33];
    uint8_t bssid[6];
    int8_t rssi;
    uint8_t channel;
    uint8_t authmode;          /* wifi_auth_mode_t value */
} espos_wifi_scan_entry_t;
esp_err_t espos_wifi_scan_json(char **out_json);

const char *espos_wifi_short_id(void);

/* Co-processor link watchdog (esp_hosted builds only; a no-op elsewhere).
 *
 * A wedged host<->co-processor transport takes the radio down while the
 * WiFi state machine still reports CONNECTED, so nothing above notices.
 * This watches the co-processor heartbeat — which travels over the same
 * RPC channel that dies — and restarts the device when it stops.
 *
 * Safe to call on every boot; returns ESP_ERR_NOT_SUPPORTED when the
 * build has no hosted co-processor. A non-OK return means wedges will
 * NOT be detected, not that WiFi is broken. */
esp_err_t espos_wifi_hosted_watchdog_start(void);

/* Always 0. Recovery is a deliberate restart, so no RAM counter can
 * survive to report it; a wedge shows up as reset_reason plus the
 * "radio link is gone" line in the log ring. Kept for API uniformity. */
uint32_t espos_wifi_hosted_recoveries(void);

#ifdef __cplusplus
}
#endif