e12_protocol.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023 e12.io
 * All rights reserved.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
#ifndef H_E12_SPEC
#define H_E12_SPEC
 
#include <stdint.h>
 
#define E12_MAX_PKT_SIZE 128
 
#define E12_MAX_DATA_PAYLOAD (E12_MAX_PKT_SIZE - sizeof(e12_onwire_head_t) - 8)
 
enum class e12_cmd_t : uint8_t {
  NONE = 0,
  CMD_PING,
  CMD_AUTH,
  CMD_INFO,
  CMD_PROFILE,
  CMD_PIN_CTL,
  CMD_CONFIG,
  CMD_STATE,
  CMD_STATUS,
  CMD_LOG,
  CMD_TIME,
  CMD_SCHEDULE_WAKEUP,
  CMD_NODE_SLEEP,
  CMD_NODE_AWAKE,
  CMD_OTA,
  CMD_VMCU_OTA,
  CMD_SET_NODE_PROPERTIES,
  CMD_DEBUG_BLINK
};
 
enum class e12_release_t : uint8_t {
  STABLE = 0,
  CANARY,
  DEV
};
 
enum class ctl_op_t : uint8_t {
  READ = 0,
  WRITE
};
 
enum class e12_err_t : int8_t {
  ERR_NONE = 0,
  ERR_RETRY_LATER = -1,
};
 
enum class e12_evt_status_t : uint8_t {
  STATUS_DONE = 0,
  STATUS_NEW,
  STATUS_IN_PROCESSING,
  STATUS_IN_WAITING
};
 
enum class e12_node_op_status_t : uint8_t {
  STATUS_NONE = 0,
  STATUS_ACTIVE,
  STATUS_SLEEP,
  STATUS_OTA,
  STATUS_VMCU_OTA
};
 
enum class mcu_arch_t : uint8_t { ARCH_NONE = 0, ARCH_ATMEGA328, ARCH_SAMD21 };
 
enum class mcu_flashing_protocol_t : uint8_t {
  PROTOCOL_NONE = 0,
  PROTOCOL_STK500,
  PROTOCOL_BOSSA
};
 
#define E12_MAX_LOG_BUFFERS 1
#define MAX_S_LOG_DATA 16
typedef struct __attribute__((packed, aligned(4))) e12_log_evt {
  uint8_t type;
  uint8_t status;
  uint8_t src;
  uint8_t src_index;
  uint32_t ts;
  uint32_t count;
  union {
    uint32_t state;
    struct {
      uint8_t s : 1;
      uint8_t f : 1;
      uint8_t i : 1;
      uint8_t : 0;
      uint8_t in_use : 1;
      uint8_t : 0;
      uint8_t resv1;
      uint8_t resv2;
    };
  };
  union {
    char s_data[MAX_S_LOG_DATA];
    struct {
      float f_data;
      int32_t i_data;
      uint32_t resv3;
      uint32_t resv4;
    };
  };
} e12_log_evt_t;
 
typedef struct __attribute__((packed, aligned(4))) e12_wakeup_data {
  uint32_t ms;
} e12_wakeup_data_t;
 
typedef struct __attribute__((packed, aligned(4))) e12_debug_blink {
  uint32_t on_ms;
  uint32_t off_ms;
  uint32_t count;
} e12_debug_blink_t;
 
typedef struct __attribute__((packed, aligned(4))) e12_node_properties {
  union {
    uint32_t flags;
    struct {
      uint8_t REBOOT : 1;
      uint8_t FACTORY_RESET : 1;
      uint8_t DISABLE_SLEEP : 1;
      uint8_t REFRESH_CONFIG : 1;
      uint8_t ACTIVATE_WIFI : 1;
      uint8_t ACTIVATE_LTE : 1;
      uint8_t ACTIVATE_LORA : 1;
      uint8_t ACTIVATE_WIFI_CAPTIVE_PORTAL : 1;
      uint8_t ENCRYPT : 1;
      uint8_t TRANSMIT : 1;
      uint8_t LOGMASK : 1;
    };
  };
  union {
    uint64_t data;
    struct {
      uint32_t data1;
      uint32_t data2;
    };
  };
} e12_node_properties_t;
 
#define MAX_SSID_LEN 32
#define MAX_PWD_LEN 32
typedef struct __attribute__((packed, aligned(4))) e12_auth_data {
  struct {
    uint8_t AUTH_WIFI : 1;
    uint8_t AUTH_LTE_AP : 1;
  };
  union {
    struct {
      char ssid[MAX_SSID_LEN];
      char pwd[MAX_PWD_LEN];
    } wifi;
  };
} e12_auth_data_t;
 
typedef struct __attribute__((packed, aligned(4))) e12_node_state {
  struct {
    uint8_t AUTH_OK : 1;
    uint8_t CONFIGURED : 1;
    uint8_t CONNECTED : 1;
  };
  e12_node_op_status_t op_status;
  uint16_t next_connection_in_sec;
  union {
    uint32_t data;
    struct {
      uint32_t node_wake_up_ms;  // if e12_node is in sleep mode
    };
  };
} e12_node_state_t;
 
#define MAX_LOG_SIZE (sizeof(e12_log_evt_t))
 
typedef struct __attribute__((packed, aligned(4))) e12_header {
  uint8_t seq;
  uint8_t len;
  struct {
    uint8_t RESP_EXPECTED : 1;
    uint8_t IS_RESPONSE : 1;
    uint8_t : 0;
  };
  e12_cmd_t cmd;
} e12_header_t;
 
#define E12_MAGIC_MARKER_LEN 2
#define E12_MAGIC_MARKER_1 (0xEC)
#define E12_MAGIC_MARKER_2 (0xEC ^ 0xCE)
typedef union __attribute__((packed, aligned(4))) e12_onwire_head {
  uint32_t head;
  struct {
    uint8_t magic[E12_MAGIC_MARKER_LEN];
    uint8_t len;
    uint8_t checksum;
  };
} e12_onwire_head_t;
 
#define E12_MAX_CMD_DATA_PAYLOAD (E12_MAX_DATA_PAYLOAD - sizeof(e12_header_t))
#define E12_MAX_FIRMWARE_VERSION_LEN 32
 
typedef struct __attribute__((packed, aligned(4))) {
  e12_header_t head;
  union {
    uint32_t data;
    struct {
      uint8_t type : 1;      
      uint8_t op : 1;        
      uint8_t response : 1;  
      uint8_t : 0;
      uint8_t pin;     
      uint16_t value;  
    };
  };
} e12_ctl_msg_t;
 
// it is expected that the head.len is set to include the 
// size of e12_header_t + size of the specific msg payload
// so typically e.g msg_err.head.len = sizeof(msg_err);
typedef union __attribute__((packed, aligned(4))) e12_packet {
  uint8_t buf[E12_MAX_DATA_PAYLOAD];
  struct {
    e12_header_t head;
    char data[E12_MAX_CMD_DATA_PAYLOAD];
  } msg;
  struct {
    e12_header_t head;
    uint32_t err;  // 0 = OK, 1 = ERR
  } msg_err;
  struct {
    e12_header_t head;
    uint32_t ms;
  } msg_wakeup;
  struct {
    e12_header_t head;
    uint32_t ms;
  } msg_sleep;
  struct {
    e12_header_t head;
    e12_debug_blink_t data;
  } msg_debug_blink;
  struct {
    e12_header_t head;
    e12_node_properties_t props;
  } msg_node_props;
  struct {
    e12_header_t head;
    e12_auth_data_t data;
  } msg_auth_credentials;
  struct {
    e12_header_t head;
    uint32_t ms;
  } msg_time;
  struct {
    e12_header_t head;
    uint32_t release_type;
    uint32_t size;
    char version[E12_MAX_FIRMWARE_VERSION_LEN];
  } msg_ota;
  struct {
    e12_header_t head;
    uint32_t version;
    mcu_arch_t arch;
    mcu_flashing_protocol_t protocol;
    bool flashing_enabled;
  } msg_info;
  struct {
    e12_header_t head;
    union {
      uint32_t all;
      struct {
        uint16_t digital;  
        uint16_t analog;   
      };
    } pins;
    union {
      uint32_t all;
      struct {
        uint16_t digital;  
        uint16_t analog;   
      };
    } mask;
  } msg_dev_profile;
  e12_ctl_msg_t msg_ctl;
  struct {
    e12_header_t head;
  } msg_vmcu_ota;
} e12_packet_t;
 
typedef union __attribute__((packed, aligned(4))) e12_onwire {
  uint8_t buf[E12_MAX_PKT_SIZE];
  struct {
    e12_onwire_head_t head;
    e12_packet_t data;
    uint8_t resp_pending : 1;
    uint8_t : 0;
    uint8_t recv_len;
    uint8_t resv;
    uint8_t resv1;
    uint32_t ts;
  };
} e12_onwire_t;
 
typedef struct __attribute__((packed, aligned(4))) e12_data {
  uint8_t IS_JSON : 1;
  uint8_t STORE : 1;
  uint8_t FETCH : 1;
  uint8_t : 0;
  uint32_t ts_ms;
  uint8_t data[E12_MAX_CMD_DATA_PAYLOAD - 5];
} e12_data_t;
 
typedef struct __attribute__((packed, aligned(4))) e12_device {
  e12_data_t state;
  e12_data_t config;
  e12_log_evt_t log;
} e12_device_t;
 
typedef struct __attribute__((packed, aligned(4))) {
  ctl_op_t op;
  uint8_t pin;
  int16_t value;
} ctl_log_t;
 
class e12 {
 private:
  uint32_t _vid;              
  uint32_t _pid;              
  uint32_t _version;          
  uint32_t _pin_mask;         
  uint32_t _pin_io_mask;      
  e12_node_state_t _status;   
  uint32_t _mcu_fwr_version;  
  mcu_arch_t _arch;
  mcu_flashing_protocol_t _protocol;
  bool _mcu_flashing_enabled;
 
  e12_onwire_t _encode_buf;  
  e12_onwire_t _decode_buf;  
  e12_device_t* _dev_ptr;    
 
 protected:
  uint32_t _timeout;  
  uint8_t _seq;       
 
  e12_onwire_t* get_encode_buffer() { return &_encode_buf; }
 
  e12_onwire_t* get_decode_buffer() { return &_decode_buf; }
 
  void flush_buffer(e12_onwire_t* buf);
  
  e12_node_op_status_t get_node_status();
  
  e12_node_op_status_t set_node_status(e12_node_op_status_t status,
                                       uint32_t data);
 
  bool on_ctl(ctl_op_t op, uint8_t pin, uint32_t val);
 
 public:
  e12(uint32_t vid, uint32_t pid);
 
  ~e12();
 
  // Packet handling
 
  e12_packet_t* e12_get_packet();
 
  e12_onwire_t* encode(e12_packet_t* data);
 
  e12_packet_t* decode(e12_onwire_t* pkt, uint8_t data);
 
  // Device management
 
  void set_e12_device(e12_device_t* p) { _dev_ptr = p; }
 
  void set_product_info(uint32_t vid, uint32_t pid) {
    _vid = vid;
    _pid = pid;
  }
 
  void set_fwr_details(uint32_t fwr_version, mcu_arch_t arch,
                       mcu_flashing_protocol_t protocol, bool enabled) {
    _mcu_fwr_version = fwr_version;
    _arch = arch;
    _protocol = protocol;
    _mcu_flashing_enabled = enabled;
  }
 
  uint32_t get_fwr_version() { return _mcu_fwr_version; }
 
  uint32_t get_pin_mask();
  uint32_t get_pin_io_mask();
 
  int publish_info();
 
  int publish_profile();
 
  bool set_pin_in(uint8_t pin_number, bool is_analog = false);
 
  bool set_pin_out(uint8_t pin_number, bool is_analog = false);
 
  void set_node_properties(e12_node_properties_t* props);
 
  void set_timeout(uint32_t ms) { _timeout = ms; }
 
  bool is_configured() { return _status.CONFIGURED; }
 
  void set_configured(bool status) { _status.CONFIGURED = status; }
 
  uint32_t get_version() { return _version; }
 
  void set_version(uint32_t v) { _version = v; }
 
  void set_pin_mask(uint32_t pin_mask, uint32_t io_mask) {
    _pin_mask = pin_mask;
    _pin_io_mask = io_mask;
  }
 
  // Communication
 
  virtual e12_packet_t* get_request(e12_cmd_t cmd, bool response = true,
                                    void* data = 0);
 
  virtual e12_packet_t* get_response(e12_packet_t* p);
 
  bool get_message(e12_packet_t* data);
 
  static uint8_t get_checksum(const char* data, uint8_t len);
 
  virtual int on_receive(e12_packet_t* p);
 
  virtual int wakeup_e12_node() { return 0; }
 
  // Utility
 
  virtual int print_buffer(e12_onwire_t* buf) { return 0; }
 
  virtual int on_ctl_read(uint8_t pin);
 
  virtual bool on_ctl_write(uint8_t pin, uint32_t val);
 
  // Pure virtual functions to be implemented by derived classes
 
  virtual int begin(void* bus, uint8_t e12_addr = 0) = 0;
  virtual uint32_t get_time_ms() = 0;
  virtual e12_log_evt_t* get_log_evt() = 0;
  virtual int send(e12_packet_t* buf, bool retry = true) = 0;
  virtual e12_packet_t* read() = 0;
  virtual int sleep(uint32_t ms, void* data) = 0;
  virtual int log(uint8_t type, uint8_t status, uint32_t ts, void* data) = 0;
  virtual int on_wakeup() = 0;
  virtual int set_node_auth_credentials(e12_auth_data_t* auth) = 0;
  virtual int on_config(const char* s, int len) = 0;
  virtual int on_get_state(char* s, int len, void* ctx) = 0;
  virtual int on_restore_state(const char* s, int len) = 0;
};
 
#endif