espnow_protocol.h

#ifndef ESPNOW_PROTOCOL_H
#define ESPNOW_PROTOCOL_H

#include <cstdint>
#include <cstring>
#include <string>

// ESP-NOW message size limit is 250 bytes
#define ESPNOW_MAX_DATA_LEN 250
#define ESPNOW_UUID_LEN 37
#define ESPNOW_NAME_LEN 32
#define ESPNOW_INBOX_LEN 64
#define ESPNOW_TEXT_LEN 150

namespace espnow {

// Message types
enum MessageType : uint8_t {
    kMessageTypePairingRequest = 0x01,
    kMessageTypePairingResponse = 0x02,
    kMessageTypeTextMessage = 0x03,
    kMessageTypeMetadataUpdate = 0x04,
    kMessageTypeHeartbeat = 0x05,
    kMessageTypeUnpair = 0x06
};

// Base message header (all messages start with this)
struct MessageHeader {
    uint8_t version;        // Protocol version (currently 1)
    uint8_t type;          // MessageType
    uint16_t payload_size; // Size of the payload following this header
    uint32_t timestamp;    // Timestamp in milliseconds
    uint8_t sender_mac[6]; // Sender MAC address
} __attribute__((packed));

// Pairing Request Message
// Sent when device wants to pair after sustained proximity
struct PairingRequestPayload {
    char device_uuid[ESPNOW_UUID_LEN];      // Device UUID
    char device_name[ESPNOW_NAME_LEN];      // Device name (e.g., "PlaiPin-abc123")
    char agentmail_inbox[ESPNOW_INBOX_LEN]; // AgentMail inbox ID
    int8_t rssi;                             // Current RSSI value
    uint8_t reserved[2];                     // Reserved for future use
} __attribute__((packed));

// Pairing Response Message
// Sent in response to pairing request
struct PairingResponsePayload {
    char device_uuid[ESPNOW_UUID_LEN];
    char device_name[ESPNOW_NAME_LEN];
    char agentmail_inbox[ESPNOW_INBOX_LEN];
    uint8_t accepted;     // 1 = accepted, 0 = rejected
    uint8_t reserved[2];  // Reserved for future use
} __attribute__((packed));

// Text Message
// Plain text message to be processed by LLM
struct TextMessagePayload {
    char sender_uuid[ESPNOW_UUID_LEN];
    char sender_name[ESPNOW_NAME_LEN];
    char message_text[ESPNOW_TEXT_LEN];
    uint8_t reserved[2];
} __attribute__((packed));

// Metadata Update Message
// Update device information for already paired devices
struct MetadataUpdatePayload {
    char device_uuid[ESPNOW_UUID_LEN];
    char device_name[ESPNOW_NAME_LEN];
    char agentmail_inbox[ESPNOW_INBOX_LEN];
    uint8_t reserved[2];
} __attribute__((packed));

// Heartbeat Message
// Periodic message to maintain connection
struct HeartbeatPayload {
    uint32_t uptime_seconds;
    int8_t rssi;
    uint8_t battery_level;  // 0-100
    uint8_t reserved[2];
} __attribute__((packed));

// Unpair Message
// Request to remove pairing
struct UnpairPayload {
    char device_uuid[ESPNOW_UUID_LEN];
    uint8_t reason;  // Optional reason code
    uint8_t reserved[2];
} __attribute__((packed));

// Complete message structure
struct Message {
    MessageHeader header;
    union {
        PairingRequestPayload pairing_request;
        PairingResponsePayload pairing_response;
        TextMessagePayload text_message;
        MetadataUpdatePayload metadata_update;
        HeartbeatPayload heartbeat;
        UnpairPayload unpair;
        uint8_t raw[ESPNOW_MAX_DATA_LEN - sizeof(MessageHeader)];
    } payload;
} __attribute__((packed));

// Helper class for message serialization/deserialization
class MessageBuilder {
public:
    // Create pairing request message
    static bool BuildPairingRequest(
        Message& msg,
        const uint8_t* sender_mac,
        const std::string& device_uuid,
        const std::string& device_name,
        const std::string& agentmail_inbox,
        int8_t rssi);

    // Create pairing response message
    static bool BuildPairingResponse(
        Message& msg,
        const uint8_t* sender_mac,
        const std::string& device_uuid,
        const std::string& device_name,
        const std::string& agentmail_inbox,
        bool accepted);

    // Create text message
    static bool BuildTextMessage(
        Message& msg,
        const uint8_t* sender_mac,
        const std::string& sender_uuid,
        const std::string& sender_name,
        const std::string& text);

    // Create metadata update message
    static bool BuildMetadataUpdate(
        Message& msg,
        const uint8_t* sender_mac,
        const std::string& device_uuid,
        const std::string& device_name,
        const std::string& agentmail_inbox);

    // Create heartbeat message
    static bool BuildHeartbeat(
        Message& msg,
        const uint8_t* sender_mac,
        uint32_t uptime_seconds,
        int8_t rssi,
        uint8_t battery_level);

    // Create unpair message
    static bool BuildUnpair(
        Message& msg,
        const uint8_t* sender_mac,
        const std::string& device_uuid,
        uint8_t reason);

    // Validate message integrity
    static bool ValidateMessage(const Message& msg, size_t recv_len);

    // Get message type as string (for logging)
    static const char* MessageTypeToString(MessageType type);

private:
    // Helper to initialize header
    static void InitHeader(MessageHeader& header, MessageType type, const uint8_t* sender_mac);
};

} // namespace espnow

#endif // ESPNOW_PROTOCOL_H