Every Mesh-NOW message is serialized to MessagePack and sent as a binary ESP-NOW frame.

Wire Format

Messages use a binary envelope: a 32-byte header followed by a MessagePack-encoded payload. The full binary layout is in Wire Format. The canonical protocol specification is mesh_now.ksy at the repository root.

Internal Structure

The library works with this structure internally:

typedef struct {
    uint8_t type;              // Message type (0-9)
    uint8_t flags;             // Bitfield: REQUIRES_ACK, ENCRYPTED, HAS_NODE_NAME
    uint8_t group_id;          // Group identifier (0-255)
    uint8_t hop_limit;         // Max hops for this frame
    uint8_t hop_count;         // Hops taken so far
    uint32_t message_id;       // Unique message identifier
    uint32_t reply_to;         // Message id being acknowledged (ACK frames only)
    uint8_t sender_mac[6];     // Sender MAC address
    uint8_t target_mac[6];     // Target MAC (direct messages)
    uint32_t timestamp;        // Network time in ms
    char message[MAX_MESH_MESSAGE_LEN];      // Payload (null-terminated)
    char node_name[MESH_NOW_NODE_NAME_MAX + 1];  // Node name (beacons/RREQ/RREP)
    uint8_t neighbor_count;    // Zone announce: count of advertised one-hop peers
    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;

Field Reference

Message Types

Flags

Sending Functions

// Broadcast to all peers
esp_err_t mesh_now_send_broadcast(const char *message);

// Alias for broadcast
esp_err_t mesh_now_send_message(const char *message);

// Direct to a specific peer (with ACK + retransmit)
esp_err_t mesh_now_send_direct(const uint8_t *target_mac, const char *message);

// Group-scoped broadcast
esp_err_t mesh_now_send_group(uint8_t group_id, const char *message);

// Presence announcement
esp_err_t mesh_now_send_presence(const char *status);

// Typing indicator to a specific peer
esp_err_t mesh_now_send_typing(const uint8_t *target_mac, bool typing);

Node Naming

Nodes can set a human-readable name that is broadcast in beacons:

mesh_now_set_name("Sensor-01");

When a beacon with MSG_FLAG_HAS_NODE_NAME arrives, the name is stored in the peer table and shows up in mesh_peer_t.node_name.

Next Steps