espnow_protocol.hpp

Go to the documentation of this file.

 
#pragma once
 
#include <cstdint>
#include <cstring>
#include "freertos/FreeRTOS.h"
#include "freertos/queue.h"
#include "esp_idf_pedantic_compat.hpp"
#include "esp_log.h"
 
// Include security definitions for pairing support
#include "espnow_security.hpp"
 
// ------------- ESPNOW CONFIG -------------
 
// Sync byte at start of every message
static constexpr uint8_t ESPNOW_SYNC_BYTE = 0xAA;
 
// Protocol version (must match remote controller)
static constexpr uint8_t ESPNOW_PROTOCOL_VERSION = 1;
 
// Device ID for this fatigue tester (must match remote controller device registry)
static constexpr uint8_t DEVICE_ID_FATIGUE_TESTER = 1;
 
// Max payload bytes in our custom packet
static constexpr size_t ESPNOW_MAX_PAYLOAD = 200;
 
// WiFi/ESP-NOW channel
static constexpr uint8_t WIFI_CHANNEL = 1;
 
// Remote controller (UI board) MAC address (STA interface).
// If set non-zero, the test unit can send responses immediately (without waiting
// to "learn" the sender MAC from the first inbound ESPNOW message).
//
// Update this when the remote controller prints its MAC, e.g.:
//   Remote Controller MAC (STA): B0:81:84:96:90:10
static constexpr uint8_t UI_BOARD_MAC[6] = { 0xB0, 0x81, 0x84, 0x96, 0x90, 0x10 };
 
// ------------- MESSAGE TYPES -------------
 
enum class MsgType : uint8_t {
    DeviceDiscovery = 1,
    DeviceInfo,
    ConfigRequest,     // = 3
    ConfigResponse,    // = 4
    ConfigSet,         // = 5
    ConfigAck,         // = 6
    Command,           // = 7
    CommandAck,        // = 8
    StatusUpdate,      // = 9
    Error,             // = 10
    ErrorClear,        // = 11
    TestComplete,      // = 12
    
        // Fatigue-test extensions
        BoundsResult      = 13,
    
    // Security / Pairing messages (20-29 range)
    PairingRequest  = 20,   
    PairingResponse = 21,   
    PairingConfirm  = 22,   
    PairingReject   = 23,   
    Unpair          = 24,   
};
 
enum class TestState : uint8_t {
    Idle = 0,
    Running,
    Paused,
    Completed,
    Error
};
 
enum class CommandId : uint8_t {
    Start = 1,
    Pause = 2,
    Resume = 3,
    Stop = 4,
    // Dedicated bounds-finding command (independent of starting the test).
    RunBoundsFinding = 5,
    // Set manual bounds (center distance from left stop, degrees).
    SetManualBounds = 6,
    ManualBoundsStart = 7,      
    ManualBoundsArmPlaced = 8,  
    ManualBoundsJog = 9,        
    ManualBoundsConfirm = 10,   
    ManualBoundsCancel = 11,    
    ManualBoundsReZero = 12,    
    StartWithManualBounds = 13, 
    StartWithManualRealign = 14, 
};
 
#pragma pack(push, 1)
struct BoundsResultPayload {
    uint8_t ok;        
    uint8_t bounded;   
    uint8_t cancelled; 
    uint8_t reserved;
    float   min_degrees_from_center;
    float   max_degrees_from_center;
    float   global_min_degrees;
    float   global_max_degrees;
};
#pragma pack(pop)
 
// ------------- PACKET STRUCTURES -------------
 
#pragma pack(push, 1)
struct EspNowHeader {
    uint8_t sync;       // always ESPNOW_SYNC_BYTE
    uint8_t version;    // protocol version
    uint8_t device_id;  // device type ID
    uint8_t type;       // MsgType
    uint8_t id;         // sequence ID
    uint8_t len;        // payload length (0..ESPNOW_MAX_PAYLOAD)
};
 
struct EspNowPacket {
    EspNowHeader hdr;
    uint8_t      payload[ESPNOW_MAX_PAYLOAD];
    uint16_t     crc;  // CRC over [hdr + payload[0..len-1]]
};
#pragma pack(pop)
 
#pragma pack(push, 1)
struct ConfigPayload {
    // Base fields (17 bytes) - required, always present
    uint32_t cycle_amount;                     // Target number of cycles (0 = infinite)
    float    oscillation_vmax_rpm;             // Max oscillation velocity (RPM) - directly to TMC5160 VMAX
    float    oscillation_amax_rev_s2;          // Oscillation acceleration (rev/s²) - directly to TMC5160 AMAX
    uint32_t dwell_time_ms;                    // Dwell time at endpoints (milliseconds)
    uint8_t  bounds_method;                    // 0 = stallguard, 1 = encoder
    
    // Extended fields (16 bytes) - optional, for bounds finding configuration
    float    bounds_search_velocity_rpm;       // Search speed during bounds finding (RPM)
    float    stallguard_min_velocity_rpm;      // Minimum velocity threshold for StallGuard2 (RPM)
    float    stall_detection_current_factor;   // Current reduction factor (0.0-1.0)
    float    bounds_search_accel_rev_s2;       // Acceleration during bounds finding (rev/s²)
 
    // Extended v2 field (optional)
    // StallGuard threshold (SGT). Valid range is typically [-64, 63].
    // 127 means "use test config default".
    int8_t   stallguard_sgt;
};
 
struct ConfigAckPayload {
    uint8_t ok;        // 1 = success, 0 = failure
    uint8_t err_code;  // optional error code
};
 
struct CommandPayload {
    uint8_t command_id;  // CommandId enum value
};
 
struct StatusPayload {
    uint32_t cycle_number;
    uint8_t  state;      // TestState enum value
    uint8_t  err_code;   // error code if state == Error
    // 1 = bounds may be reused (motor still energized + within validity window)
    // 0 = bounds invalid, must re-run bounds finding
    // 255 = unknown/unspecified (backward compatibility)
    uint8_t  bounds_valid;
};
 
struct ErrorPayload {
    uint8_t  err_code;
    uint32_t at_cycle;
};
#pragma pack(pop)
 
// ------------- SETTINGS STRUCTURE -------------
 
struct TestUnitSettings {
    uint32_t cycle_amount = 300;                      
    float    oscillation_vmax_rpm = 60.0f;            
    float    oscillation_amax_rev_s2 = 10.0f;         
    uint32_t dwell_time_ms = 500;                     
    bool     bounds_method_stallguard = true;         
    
    // Extended configuration for bounds finding (configurable via remote controller)
    float    bounds_search_velocity_rpm = 0.0f;       
    float    stallguard_min_velocity_rpm = 0.0f;      
    float    stall_detection_current_factor = 0.0f;   
    float    bounds_search_accel_rev_s2 = 0.0f;       
 
    int8_t   stallguard_sgt = 0;                    
};
 
struct UISettings {
    bool orientation_flipped = false;                
    // Future UI settings can be added here (e.g., brightness, contrast, etc.)
};
 
struct Settings {
    TestUnitSettings test_unit;  
    UISettings       ui;         
};
 
// ------------- EVENTS -------------
 
enum class ProtoEventType {
    // Incoming commands from UI board (test unit side)
    ConfigRequest,
    ConfigSet,
    CommandStart,
    CommandPause,
    CommandResume,
    CommandStop,
    CommandRunBoundsFinding,
    CommandSetManualBounds,
    CommandManualBoundsStart,
    CommandManualBoundsArmPlaced,
    CommandManualBoundsJog,
    CommandManualBoundsConfirm,
    CommandManualBoundsCancel,
    CommandManualBoundsReZero,
    CommandStartWithManualBounds,
    CommandStartWithManualRealign,
    // Status/response events (both sides)
    ConfigUpdated,
    ConfigApplyOk,
    ConfigApplyFail,
    Started,
    Paused,
    Resumed,
    Stopped,
    Status,
    ErrorEvent,
    TestCompleted,
    
    // Pairing events
    PairingRequest,     
    PairingComplete,    
    PairingFailed,      
    PeerUnpaired,       
};
 
struct ProtoEvent {
    ProtoEventType type;
    union {
        TestUnitSettings config;  // Config data (includes extended float fields)
        struct { uint32_t cycle; TestState state; uint8_t err_code; } status;
        struct { uint8_t err_code; uint32_t at_cycle; } error;
        struct { 
            uint8_t peer_mac[6];
            uint8_t device_type;
            char    device_name[MAX_DEVICE_NAME_LEN];
        } pairing;
        struct { float center_distance_deg; } manual_bounds;
        struct { float target_deg; } manual_jog;
        struct { float total_range_deg; float left_backoff_deg; float right_backoff_deg; } manual_confirm;
        struct { float total_range_deg; float left_backoff_deg; float right_backoff_deg; } manual_start;
    } data;
};
 
// ------------- CRC16-CCITT FUNCTION -------------
 
inline uint16_t Crc16Ccitt(const uint8_t* data, size_t len) noexcept
{
    uint16_t crc = 0xFFFF;
    for (size_t i = 0; i < len; ++i) {
        crc ^= static_cast<uint16_t>(data[i]) << 8;
        for (int j = 0; j < 8; ++j) {
            if (crc & 0x8000) {
                crc = (crc << 1) ^ 0x1021;
            } else {
                crc <<= 1;
            }
        }
    }
    return crc;
}