API Reference

Below you find the complete public API that is exposed through the single header file meshnow.h.

Functions

esp_err_t meshnow_init(meshnow_config_t *config)

Initialize MeshNOW.

Attention: This API shall be called after Wi-Fi, NVS, and ESP-Netif have been initialized.
Attention: Be sure to not perform any calls to Wi-Fi before de-initializing again, unless you know what you are doing.

Parameters:

config – [in] MeshNOW configuration.

Returns:

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid config
ESP_ERR_INVALID_STATE: MeshNOW is already initialized, or Wi-Fi, NVS, or ESP-Netif is not initialized
ESP_ERR_NO_MEM: Out of memory
Others: Fail

esp_err_t meshnow_deinit()

De-initialize MeshNOW.

Attention: This API shall be called after stopping the mesh.

Returns:

ESP_OK: Success
ESP_ERR_INVALID_STATE: MeshNOW is not initialized or not stopped
Others: Fail

esp_err_t meshnow_start()

Starts the mesh.

Root: if configured, will connect to the router. Note: other nodes may not connect while the root is connecting to the router due to channel mismatch.
Others: will connect to the next best parent node within range that is already connected to the mesh.

Attention: This API shall be called after initializing the mesh.

Returns:

ESP_OK: Success
ESP_ERR_INVALID_STATE: MeshNOW is not initialized or already started
ESP_ERR_NO_MEM: Out of memory
Others: Fail

esp_err_t meshnow_stop()

Stops the mesh.

Root: will disconnect from the router.
Others: will disconnect from its parent.

Each node also disconnects all children.

Attention: This API shall be called after starting the mesh.

Note

This API is blocking to ensure all tasks can clean up properly. It may take a few seconds to return. The calling task is put to sleep during this time as to not trigger the watchdog.

Returns:

ESP_OK: Success
ESP_ERR_INVALID_STATE: MeshNOW is not initialized or not started
Others: Fail

esp_err_t meshnow_send(uint8_t *dest, uint8_t *buffer, size_t len)

Send a custom data packet to any node in the mesh.

Parameters:

dest – [in] the address of the final destination of the packet
- if MESHNOW_BROADCAST_ADDRESS, the message will be broadcasted to all nodes in the mesh
- if MESHNOW_ROOT_ADDRESS, the message will be sent to the root node
buffer – [in] pointer to the data to send
len – [in] length of the data to send; cannot exceed MESHNOW_MAX_CUSTOM_MESSAGE_SIZE

Returns:

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: MeshNOW is not initialized or not started, or the node is disconnected from the mesh
ESP_ERR_NO_MEM: Out of memory
Others: Fail

esp_err_t meshnow_register_data_cb(meshnow_data_cb_t cb, meshnow_data_cb_handle_t *handle)

Register a callback for custom data packets.

Parameters:

cb – [in] the callback to register
handle – [out] handle for the callback

Returns:

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: MeshNOW is not initialized
ESP_ERR_NO_MEM: Out of memory

esp_err_t meshnow_unregister_data_cb(meshnow_data_cb_handle_t handle)

Unregister a callback for custom data packets.

Parameters:

handle – [in] handle for the callback

Returns:

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: MeshNOW is not initialized

Structures

struct meshnow_router_config_t

Configuration options for the root when connecting to a router.

Public Members

bool should_connect: If true, the root node will try to connect to a router.

wifi_sta_config_t *sta_config: ESP Wi-Fi station configuration.

struct meshnow_config_t

MeshNOW configuration.

Public Members

bool root: If true, this device is the root node of the mesh.

meshnow_router_config_t router_config: Router configuration for when root is true.

struct meshnow_event_child_connected_t

Child connected information.

Public Members

uint8_t child_mac[MESHNOW_ADDRESS_LENGTH]: MAC address of the connected child.

struct meshnow_event_child_disconnected_t

Child disconnected information.

Public Members

uint8_t child_mac[MESHNOW_ADDRESS_LENGTH]: MAC address of the disconnected child.

struct meshnow_event_parent_connected_t

Parent connected information.

Public Members

uint8_t parent_mac[MESHNOW_ADDRESS_LENGTH]: MAC address of the parent to which this node connected.

struct meshnow_event_parent_disconnected_t

Parent disconnected information.

Public Members

uint8_t parent_mac[MESHNOW_ADDRESS_LENGTH]: MAC address of the parent from which this node disconnected.

Macros

MESHNOW_MAX_CUSTOM_MESSAGE_SIZE: Maximum size (in bytes) of a custom message.

MESHNOW_ADDRESS_LENGTH: Length of a MAC address.

Variables

esp_event_base_t MESHNOW_EVENT: Event base for MeshNOW events.

const uint8_t MESHNOW_BROADCAST_ADDRESS[MESHNOW_ADDRESS_LENGTH] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF}: Broadcast address.

const uint8_t MESHNOW_ROOT_ADDRESS[MESHNOW_ADDRESS_LENGTH] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00}: Root address.

Type Definitions

typedef void (*meshnow_data_cb_t)(uint8_t *src, uint8_t *buffer, size_t len)

Callback for custom data packets.

Attention: Do not perform any long-running or blocking operations in this callback, as it would halt the mesh.

Note

The buffer is only valid for the duration of the callback. If you need to store the data, make a copy.

Param src:: [in] the address of the node that sent the packet
Param buffer:: [in] pointer to the data
Param len:: [in] length of the data

typedef void *meshnow_data_cb_handle_t: Handle for a registered data callback.

Enumerations

enum meshnow_event_t

MeshNOW event types.

Values:

enumerator MESHNOW_EVENT_CHILD_CONNECTED: A child has connected to this node.

enumerator MESHNOW_EVENT_CHILD_DISCONNECTED: A child has disconnected from this node.

enumerator MESHNOW_EVENT_PARENT_CONNECTED: This node has connected to a parent.

enumerator MESHNOW_EVENT_PARENT_DISCONNECTED: This node has disconnected from a parent.