Full API reference for the Mesh-NOW library. All functions are declared in mesh_now.h.

Initialization

mesh_now_init

Initialize the ESP-NOW mesh networking subsystem. Registers callbacks, adds the broadcast peer, and starts the beacon and retransmit tasks.

esp_err_t mesh_now_init(void);

Returns: ESP_OK on success, appropriate esp_err_t on failure.

Side effects:

• Initializes ESP-NOW
• Registers send and receive callbacks
• Adds the broadcast peer (FF:FF:FF:FF:FF:FF)
• Creates beacon_task pinned to core 0
• Creates retransmit_task pinned to core 0

mesh_now_deinit

Deinitialize the mesh. Stops tasks, removes peers, unregisters callbacks.

esp_err_t mesh_now_deinit(void);

Returns: ESP_OK on success.

Side effects:

• Deletes beacon and retransmit tasks
• Removes the broadcast peer
• Unregisters ESP-NOW callbacks
• Clears the peer table

Sending

mesh_now_send_broadcast

Send a chat message to all nodes in range.

esp_err_t mesh_now_send_broadcast(const char *message);

Returns: ESP_OK on success.

Message type: MSG_TYPE_CHAT
ACK: No
Relay: Yes

mesh_now_send_message

Alias for mesh_now_send_broadcast.

esp_err_t mesh_now_send_message(const char *message);

mesh_now_send_direct

Send a message to a specific peer. Acknowledged and retransmitted up to 3 times when the ACK does not arrive.

esp_err_t mesh_now_send_direct(const uint8_t *target_mac, const char *message);

Returns: ESP_OK on success, ESP_ERR_INVALID_ARG if parameters are NULL.

Message type: MSG_TYPE_DIRECT
ACK: Yes
Relay: Yes (route, or flood if no route is known)

mesh_now_send_group

Send a message to all nodes in a specific group.

esp_err_t mesh_now_send_group(uint8_t group_id, const char *message);

Returns: ESP_OK on success.

Message type: MSG_TYPE_GROUP
ACK: No
Relay: Yes

mesh_now_send_presence

Broadcast a presence/status announcement.

esp_err_t mesh_now_send_presence(const char *status);

Returns: ESP_OK on success.

Message type: MSG_TYPE_PRESENCE
ACK: No
Relay: Yes

mesh_now_send_typing

Send a typing indicator to a specific peer.

esp_err_t mesh_now_send_typing(const uint8_t *target_mac, bool typing);

Returns: ESP_OK on success, ESP_ERR_INVALID_ARG if target_mac is NULL.

Message type: MSG_TYPE_TYPING
ACK: No
Relay: Conditional (forwarded toward target like direct traffic)

Peer Management

mesh_now_add_peer

Add a peer to the mesh. Called automatically when receiving beacons and messages. Ignores the local MAC address.

void mesh_now_add_peer(const uint8_t *mac);

mesh_now_remove_peer

Remove a peer from the mesh.

void mesh_now_remove_peer(const uint8_t *mac);

mesh_now_get_peer_count

Get the number of active, non-expired peers.

int mesh_now_get_peer_count(void);

Returns: Current active peer count. Expired peers are compacted out of the table, so this reflects only peers tracked as online.

mesh_now_get_peers

Get a pointer to the peer table.

mesh_peer_t* mesh_now_get_peers(void);

Returns: Pointer to the internal mesh_peer_t array (max MAX_PEERS entries).

mesh_now_snapshot_peers

Thread-safe copy of the peer table. Best used when the caller does not own the internal mutex (e.g. a UI thread serializing peers over a stream).

int mesh_now_snapshot_peers(mesh_peer_t *out, size_t max_out);

Returns: Number of entries written, at most max_out. Entries are a point-in-time copy taken under the mutex.

Routing

mesh_now_get_route

Copy the route to a virtual peer into out, if one exists.

bool mesh_now_get_route(const uint8_t *dest_mac, mesh_route_t *out);

Returns: true if a route to dest_mac exists and was copied.

mesh_now_get_route_count

Number of active route entries (routes to virtual peers).

int mesh_now_get_route_count(void);

mesh_now_snapshot_routes

Thread-safe copy of the route table.

int mesh_now_snapshot_routes(mesh_route_t *out, size_t max_out);

Returns: Number of entries written, at most max_out.

mesh_now_pin_route

Pin a fixed route to dest_mac via proxy_mac. Bypasses discovery and never expires.

esp_err_t mesh_now_pin_route(const uint8_t *dest_mac, const uint8_t *proxy_mac);

Returns: ESP_OK on success, ESP_ERR_INVALID_ARG if a parameter is NULL.

mesh_now_unpin_route

Remove a previously pinned route. Fails if none exists for dest_mac.

esp_err_t mesh_now_unpin_route(const uint8_t *dest_mac);

mesh_now_set_route_failure_callback

Install the handler fired when a route to a destination cannot be found.

void mesh_now_set_route_failure_callback(mesh_now_route_failure_callback_t cb);

Node Naming

mesh_now_set_name

Set the local node name (truncated to MESH_NOW_NODE_NAME_MAX = 16 chars). Announced in beacons.

esp_err_t mesh_now_set_name(const char *name);

Returns: ESP_OK on success, ESP_ERR_INVALID_ARG if name is NULL.

mesh_now_get_name

Return the current local node name (empty until mesh_now_set_name()).

const char *mesh_now_get_name(void);

mesh_now_announce_name

Push the current name out immediately with an extra beacon instead of waiting for the next interval.

esp_err_t mesh_now_announce_name(void);

Configuration

mesh_now_set_receive_callback

Set the callback function for received messages.

void mesh_now_set_receive_callback(mesh_now_receive_callback_t callback);

If no callback is set, messages are queued in the internal message queue (see Message Queue).

mesh_now_set_group

Set the local node’s group membership.

esp_err_t mesh_now_set_group(uint8_t group_id);

Returns: Always ESP_OK.

mesh_now_set_encryption_key

Set the payload encryption key.

esp_err_t mesh_now_set_encryption_key(const uint8_t *key, size_t len);

Returns: ESP_OK on success, ESP_ERR_INVALID_ARG if key is NULL or len is not 16.

mesh_now_is_encrypted

True once encryption is configured (after mesh_now_set_encryption_key()).

bool mesh_now_is_encrypted(void);

mesh_now_peer_is_online

True if a peer entry was contacted within the peer expiry window.

bool mesh_now_peer_is_online(const mesh_peer_t *peer);

mesh_now_get_group_id

Current local group id (0 = not in a group).

uint8_t mesh_now_get_group_id(void);

Types

mesh_message_t

typedef struct {
    uint8_t type;
    uint8_t flags;
    uint8_t group_id;
    uint8_t hop_limit;
    uint8_t hop_count;
    uint32_t message_id;
    uint32_t reply_to;
    uint8_t sender_mac[6];
    uint8_t target_mac[6];
    uint32_t timestamp;
    char message[MAX_MESH_MESSAGE_LEN];
    char node_name[MESH_NOW_NODE_NAME_MAX + 1];
    uint8_t neighbor_count;
    uint8_t neighbor_macs[CONFIG_MESH_NOW_MAX_BEACON_NEIGHBORS][6];
    char neighbor_names[CONFIG_MESH_NOW_MAX_BEACON_NEIGHBORS][MESH_NOW_NODE_NAME_MAX + 1];
} mesh_message_t;

mesh_peer_t

typedef struct {
    uint8_t peer_addr[6];
    bool active;
    int64_t last_seen;
    char node_name[MESH_NOW_NODE_NAME_MAX + 1];
} mesh_peer_t;

mesh_now_receive_callback_t

typedef void (*mesh_now_receive_callback_t)(const mesh_message_t *message);

Constants

Next Steps