File espos_net.h¶

FileList > espos_net > include > espos_net.h

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

Classes¶

Type	Name
struct	espos_net_status_t

Public Types¶

Type	Name
typedef void(*	espos_net_cb_t Called on every default-route change: up, down, or moved to another interface or address (the last is reported to ESPOS_EVENT as NETWORK_DOWN followed by NETWORK_UP, so the "one DOWN per UP" rule holds).
enum	espos_net_if_t

Public Functions¶

Type	Name
uint32_t	espos_net_backoff_ms (uint32_t round, uint32_t cap_ms, uint32_t rnd) Reconnect backoff for round `round` : 1 s · 2^round, capped at cap_ms, ±25 % jitter from`rnd` , never below 250 ms.
esp_err_t	espos_net_get_status (espos_net_status_t * out) Snapshot of the current status (thread-safe copy; never calls a driver).
const char *	espos_net_if_str (espos_net_if_t iface) Name of an interface as the REST document spells it: "none", "wifi_sta", "eth", "thread".
bool	espos_net_is_up (void) True while a default route exists.
esp_err_t	espos_net_register_if (espos_net_if_t iface, void * esp_netif) A transport hands over the esp_netif it drives (esp_netif_t , opaque here so this header carries no IDF type).*
void	espos_net_report (espos_net_if_t iface, bool up, const char * ip, const char * netmask, const char * gateway, int8_t rssi) A transport reports its link: `up` with the dotted addresses (gateway may be "" or NULL) and, for WiFi, the RSSI; or`up == false` and the rest ignored.
const char *	espos_net_short_id (void) Device-unique short id, "1a2b": the last two bytes of the base MAC read from eFuse, so it is the same whether the device speaks WiFi, Ethernet or Thread, and the same on the ESP32-P4 whose radio is a co-processor.
esp_err_t	espos_net_start (void) Bring the network seam up: base MAC and short id, hostname (net.hostname, moved once from a 0.7 wifi.hostname), the /net endpoints, the "net" SSE event and the mDNS responder.
esp_err_t	espos_net_status_json (char ** out_json) The status as the JSON document of docs/rest-api.md (malloc'ed; caller frees).
esp_err_t	espos_net_subscribe (espos_net_cb_t cb, void * arg)
esp_err_t	espos_net_unsubscribe (espos_net_cb_t cb, void * arg)

Macros¶

Type	Name
define	ESPOS_NET_HOSTNAME_MAX `33 /\* 32 characters, the DHCP/mDNS label limit \*/`
define	ESPOS_NET_IP6_MAX `40 /\* textual IPv6 \*/`
define	ESPOS_NET_IP_MAX `16 /\* dotted IPv4 \*/`
define	ESPOS_NET_SHORT_ID_MAX `5 /\* "1a2b" \*/`

Public Types Documentation¶

typedef espos_net_cb_t¶

Called on every default-route change: up, down, or moved to another interface or address (the last is reported to ESPOS_EVENT as NETWORK_DOWN followed by NETWORK_UP, so the "one DOWN per UP" rule holds).

typedef void(* espos_net_cb_t) (const espos_net_status_t *st, void *arg);

Runs on the task of the transport that reported the change — for WiFi the default event loop task — with no espos_net lock held; st is valid for the call only. Copy it out and return; never block. arg is handed back untouched. Small fixed table: ESP_ERR_NO_MEM when full; the same (cb, arg) pair registered twice is called once. Callable before espos_net_start().

enum espos_net_if_t¶

enum espos_net_if_t {
    ESPOS_NET_IF_NONE = 0,
    ESPOS_NET_IF_WIFI_STA = 1,
    ESPOS_NET_IF_ETH = 2,
    ESPOS_NET_IF_THREAD = 3,
    ESPOS_NET_IF_MAX = 4
};

Public Functions Documentation¶

function espos_net_backoff_ms¶

Reconnect backoff for round round : 1 s · 2^round, capped at cap_ms, ±25 % jitter fromrnd , never below 250 ms.

uint32_t espos_net_backoff_ms (
    uint32_t round,
    uint32_t cap_ms,
    uint32_t rnd
)

The same curve every espOS retry loop uses (WiFi rounds, the SignalK stream, HTTP retries), moved here from espos_wifi so a loop needs no radio to back off. Pure function.

function espos_net_get_status¶

Snapshot of the current status (thread-safe copy; never calls a driver).

esp_err_t espos_net_get_status (
    espos_net_status_t * out
)

ESP_ERR_INVALID_STATE before espos_net_start().

function espos_net_if_str¶

Name of an interface as the REST document spells it: "none", "wifi_sta", "eth", "thread".

const char * espos_net_if_str (
    espos_net_if_t iface
)

function espos_net_is_up¶

True while a default route exists.

bool espos_net_is_up (
    void
)

False before espos_net_start().

function espos_net_register_if¶

A transport hands over the esp_netif it drives (esp_netif_t *, opaque here so this header carries no IDF type).

esp_err_t espos_net_register_if (
    espos_net_if_t iface,
    void * esp_netif
)

espos_net sets the hostname on it and reads its link-local IPv6 address for the status. Callable before or after espos_net_start(); ESP_ERR_INVALID_ARG for NONE or an out-of-range iface. The host build has no netif: pass NULL, nothing is applied.

function espos_net_report¶

A transport reports its link: up with the dotted addresses (gateway may be "" or NULL) and, for WiFi, the RSSI; orup == false and the rest ignored.

void espos_net_report (
    espos_net_if_t iface,
    bool up,
    const char * ip,
    const char * netmask,
    const char * gateway,
    int8_t rssi
)

Report on every change — got an address, lost it, refreshed the RSSI. Identical reports are cheap no-ops. espos_net decides whether the default route changed and, if so, posts NETWORK_UP / NETWORK_DOWN and runs the subscribers on the caller's task before returning. Thread-safe; ignored before espos_net_start().

function espos_net_short_id¶

Device-unique short id, "1a2b": the last two bytes of the base MAC read from eFuse, so it is the same whether the device speaks WiFi, Ethernet or Thread, and the same on the ESP32-P4 whose radio is a co-processor.

const char * espos_net_short_id (
    void
)

Default names (hostname espos-<id>, portal SSID espOS-<id>, the SignalK source label) all derive from it. On the linux target a fixed "1a2b". "" before espos_net_start().

function espos_net_start¶

Bring the network seam up: base MAC and short id, hostname (net.hostname, moved once from a 0.7 wifi.hostname), the /net endpoints, the "net" SSE event and the mDNS responder.

esp_err_t espos_net_start (
    void
)

Requires espos_init() (config) and espos_httpd_start(); ESP_ERR_INVALID_STATE with one log line otherwise. Idempotent. Transports start after this — espos_wifi_start() refuses to run before it — so the hostname is set on every interface they create.

function espos_net_status_json¶

The status as the JSON document of docs/rest-api.md (malloc'ed; caller frees).

esp_err_t espos_net_status_json (
    char ** out_json
)

function espos_net_subscribe¶

esp_err_t espos_net_subscribe (
    espos_net_cb_t cb,
    void * arg
)

function espos_net_unsubscribe¶

esp_err_t espos_net_unsubscribe (
    espos_net_cb_t cb,
    void * arg
)

Macro Definition Documentation¶

define ESPOS_NET_HOSTNAME_MAX¶

#define ESPOS_NET_HOSTNAME_MAX `33 /* 32 characters, the DHCP/mDNS label limit */`

define ESPOS_NET_IP6_MAX¶

#define ESPOS_NET_IP6_MAX `40 /* textual IPv6 */`

define ESPOS_NET_IP_MAX¶

#define ESPOS_NET_IP_MAX `16 /* dotted IPv4 */`

define ESPOS_NET_SHORT_ID_MAX¶

#define ESPOS_NET_SHORT_ID_MAX `5  /* "1a2b" */`

The documentation for this class was generated from the following file espos_net/include/espos_net.h