ESP32 Wi-Fi Mesh

ESP32 Wi-Fi Mesh API. More...

Data Structures
struct	esp_wifi_mesh_event_info
	Information delivered with a mesh event. More...
struct	esp_wifi_mesh_status
	Current mesh status snapshot. More...
struct	esp_wifi_mesh_addr
	A mesh node address (a 6-byte MAC). More...

Typedefs
typedef void(*	esp_wifi_mesh_event_cb_t) (enum esp_wifi_mesh_event event, const struct esp_wifi_mesh_event_info *info)
	Application mesh event callback.

Enumerations
enum	esp_wifi_mesh_event {   ESP_WIFI_MESH_EVENT_STARTED , ESP_WIFI_MESH_EVENT_STOPPED , ESP_WIFI_MESH_EVENT_PARENT_CONNECTED , ESP_WIFI_MESH_EVENT_PARENT_DISCONNECTED ,   ESP_WIFI_MESH_EVENT_CHILD_CONNECTED , ESP_WIFI_MESH_EVENT_CHILD_DISCONNECTED , ESP_WIFI_MESH_EVENT_NO_PARENT_FOUND , ESP_WIFI_MESH_EVENT_FIND_NETWORK ,   ESP_WIFI_MESH_EVENT_ROUTING_TABLE_CHANGE , ESP_WIFI_MESH_EVENT_TODS_REACHABLE , ESP_WIFI_MESH_EVENT_TODS_UNREACHABLE }
	Wi-Fi mesh events delivered to the application callback. More...

Functions
void	esp_wifi_mesh_event_cb_register (esp_wifi_mesh_event_cb_t cb)
	Register the application mesh event callback.
int	esp_wifi_mesh_start (void)
	Start the Wi-Fi mesh stack.
int	esp_wifi_mesh_send (const uint8_t *data, size_t len)
	Send a data buffer over the mesh.
int	esp_wifi_mesh_recv (uint8_t *data, size_t *len, int timeout_ms)
	Receive a data buffer from the mesh.
void	esp_wifi_mesh_get_status (struct esp_wifi_mesh_status *status)
	Read the current mesh status.
int	esp_wifi_mesh_get_routing_table (struct esp_wifi_mesh_addr *macs, size_t max, size_t *count)
	Read the mesh routing table node addresses.
void	esp_wifi_mesh_set_tods_reachable (bool reachable)
	Announce the root external-network (toDS) reachability to the mesh.
void	esp_wifi_mesh_bind_sta_rx (void)
	Deliver root station uplink frames to the station interface.
struct net_if *	esp_wifi_mesh_netif_get (void)
	Get the Ethernet-over-mesh network interface.

Detailed Description

ESP32 Wi-Fi Mesh API.

Since

4.5

Version

0.1.0

Typedef Documentation

esp_wifi_mesh_event_cb_t

typedef void(* esp_wifi_mesh_event_cb_t) (enum esp_wifi_mesh_event event, const struct esp_wifi_mesh_event_info *info)

#include <zephyr/drivers/wifi/esp_wifi/esp_wifi_mesh.h>

Application mesh event callback.

Parameters

event	the event that occurred.
info	event details.

Enumeration Type Documentation

esp_wifi_mesh_event

enum esp_wifi_mesh_event

#include <zephyr/drivers/wifi/esp_wifi/esp_wifi_mesh.h>

Wi-Fi mesh events delivered to the application callback.

These abstract the underlying vendor mesh events into a stable Zephyr-native set so the application does not depend on vendor mesh headers.

Enumerator
ESP_WIFI_MESH_EVENT_STARTED	The mesh stack has started.
ESP_WIFI_MESH_EVENT_STOPPED	The mesh stack has stopped.
ESP_WIFI_MESH_EVENT_PARENT_CONNECTED	This node connected to a parent (see is_root in the info).
ESP_WIFI_MESH_EVENT_PARENT_DISCONNECTED	This node lost its parent.
ESP_WIFI_MESH_EVENT_CHILD_CONNECTED	A child node connected to this node.
ESP_WIFI_MESH_EVENT_CHILD_DISCONNECTED	A child node disconnected from this node.
ESP_WIFI_MESH_EVENT_NO_PARENT_FOUND	No parent was found during the last scan.
ESP_WIFI_MESH_EVENT_FIND_NETWORK	The node started looking for a network to join.
ESP_WIFI_MESH_EVENT_ROUTING_TABLE_CHANGE	The routing table changed (see routing_table_size in the info).
ESP_WIFI_MESH_EVENT_TODS_REACHABLE	The root external-network (toDS) path became reachable.
ESP_WIFI_MESH_EVENT_TODS_UNREACHABLE	The root external-network (toDS) path became unreachable.

Function Documentation

esp_wifi_mesh_bind_sta_rx()

void esp_wifi_mesh_bind_sta_rx

(

void

)

#include <zephyr/drivers/wifi/esp_wifi/esp_wifi_mesh.h>

Deliver root station uplink frames to the station interface.

The mesh stack installs its own station receive callback. On the root, the station also carries the uplink to the router, so this restores the driver receive path for that interface. Call once the node becomes the mesh root.

esp_wifi_mesh_event_cb_register()

void esp_wifi_mesh_event_cb_register

(

esp_wifi_mesh_event_cb_t

cb

)

#include <zephyr/drivers/wifi/esp_wifi/esp_wifi_mesh.h>

Register the application mesh event callback.

The callback runs on the shared Wi-Fi event task and must not block. Its stack is CONFIG_ESP32_WIFI_EVENT_TASK_STACK_SIZE; heavy work (bringing up the IP stack, DHCP, NAT) should either run on the application's own thread or the event task stack should be sized for it. Only one callback is supported; registering again replaces the previous one.

Parameters

cb	callback to invoke on mesh events, or NULL to unregister.

esp_wifi_mesh_get_routing_table()

int esp_wifi_mesh_get_routing_table	(	struct esp_wifi_mesh_addr *	macs,
		size_t	max,
		size_t *	count )

#include <zephyr/drivers/wifi/esp_wifi/esp_wifi_mesh.h>

Read the mesh routing table node addresses.

On the root the table spans the whole sub-network; on an internal node it holds the node's own sub-tree.

Parameters

macs	output array receiving the node addresses.
max	number of entries macs can hold.
count	output set to the number of entries written.

Return values

0	on success.
-EINVAL	on a NULL argument.

esp_wifi_mesh_get_status()

void esp_wifi_mesh_get_status

(

struct esp_wifi_mesh_status *

status

)

#include <zephyr/drivers/wifi/esp_wifi/esp_wifi_mesh.h>

Read the current mesh status.

Parameters

status

output filled with the current mesh state.

esp_wifi_mesh_netif_get()

struct net_if * esp_wifi_mesh_netif_get

(

void

)

#include <zephyr/drivers/wifi/esp_wifi/esp_wifi_mesh.h>

Get the Ethernet-over-mesh network interface.

The mesh netif carries Ethernet frames over the Wi-Fi mesh transport so the Zephyr network stack runs unmodified on top of the mesh. Use the returned interface to assign IP addresses and drive DHCP, NAT and routing.

Returns

the mesh network interface, or NULL before it is initialized.

esp_wifi_mesh_recv()

int esp_wifi_mesh_recv	(	uint8_t *	data,
		size_t *	len,
		int	timeout_ms )

#include <zephyr/drivers/wifi/esp_wifi/esp_wifi_mesh.h>

Receive a data buffer from the mesh.

Blocks up to timeout_ms for a mesh frame addressed to this node.

Note

Not available with CONFIG_WIFI_ESP32_MESH_IP (see esp_wifi_mesh_send()).

Parameters

data	buffer to receive into.
len	in: buffer size; out: received length.
timeout_ms	receive timeout in milliseconds.

Return values

0	on success, with len updated to the received size.
-EAGAIN	if no frame arrived before the timeout.

esp_wifi_mesh_send()

int esp_wifi_mesh_send	(	const uint8_t *	data,
		size_t	len )

#include <zephyr/drivers/wifi/esp_wifi/esp_wifi_mesh.h>

Send a data buffer over the mesh.

On a non-root node the buffer is routed up to the root. On the root it is sent to every node in the routing table. This is a convenience path for application messaging that does not use the IP-over-mesh interface.

Note

Not available with CONFIG_WIFI_ESP32_MESH_IP. The IP interface and this raw path would both drain the single mesh receive queue with no demux, so frames would split non-deterministically between the two readers. They are kept mutually exclusive until the receive path demultiplexes on the frame protocol tag.

Parameters

data	buffer to send.
len	number of bytes to send.

Return values

0	on success (or partial success on the root).
-EIO	on a mesh send error.

esp_wifi_mesh_set_tods_reachable()

void esp_wifi_mesh_set_tods_reachable

(

bool

reachable

)

#include <zephyr/drivers/wifi/esp_wifi/esp_wifi_mesh.h>

Announce the root external-network (toDS) reachability to the mesh.

Called on the root once its uplink is up (or down) so the mesh admits or stops admitting child traffic bound for the external network.

Parameters

reachable

true if the root can forward toward the external network.

esp_wifi_mesh_start()

int esp_wifi_mesh_start

(

void

)

#include <zephyr/drivers/wifi/esp_wifi/esp_wifi_mesh.h>

Start the Wi-Fi mesh stack.

Performs the full mesh bring-up: puts Wi-Fi in AP+STA mode, initializes and configures the mesh stack from the driver Kconfig options (mesh id, channel, router and softAP credentials, tree limits), disables power save, and starts the mesh.

The node role follows the WIFI_ESP32_MESH_ROLE choice: the auto role runs self-organized election (a router is required); WIFI_ESP32_MESH_FORCE_ROOT designates this node as the fixed root and stops its self-organized parent search; WIFI_ESP32_MESH_FORCE_CHILD keeps a node from becoming root.

A router is required. The tree forms around the root's association to the router, and children auto-attach through the self-organized parent search. A fully router-less mesh (no router at all) needs each child to be given an explicit parent, which this driver does not do, so a child does not attach to a fixed root without a router.

Note

Mesh is a boot-time mode with no runtime teardown. Once started it stays resident for the lifetime of the node; there is no stop or deinit entry point, and the normal station/softAP wifi_mgmt operations (connect, disconnect, ap_enable, scan) are rejected while it runs.

Return values

0	on success.
-EINVAL	if the auto role is used without a router SSID.
-EIO	on a mesh stack error.