30 KiB
30 KiB
Interface Definitions
ASF Sensor Hub (Sub-Hub) Software Interfaces
Document ID: ICD-ASF-SensorHub-SW-001
Version: 1.0
Date: 2025-02-01
Standard: ISO/IEC/IEEE 29148:2018
Scope: Software Interface Definitions for ASF Sensor Hub
1. Introduction
1.1 Purpose
This document defines all software interfaces for the ASF Sensor Hub embedded system. It provides detailed specifications for external interfaces (hardware, communication) and internal interfaces (component-to-component) to ensure consistent implementation and integration.
1.2 Scope
This document covers:
- External Interfaces: Hardware sensors, communication protocols, storage devices, user interfaces
- Internal Interfaces: Component APIs, event system, data structures
- Data Formats: Message structures, persistent data formats, configuration schemas
- Protocol Specifications: Communication protocols, state machine interfaces
1.3 Interface Categories
| Category | Description | Examples |
|---|---|---|
| Hardware Interfaces | Physical device interfaces | I2C sensors, GPIO buttons, SD card |
| Communication Interfaces | Network and peer communication | MQTT/TLS, ESP-NOW, diagnostic protocols |
| Component Interfaces | Internal software APIs | Event System, Data Pool, State Manager |
| Data Interfaces | Data structures and formats | Sensor records, diagnostic events, configuration |
| Storage Interfaces | Persistent storage access | SD card files, NVM data, configuration storage |
2. External Interfaces
2.1 Hardware Interfaces
2.1.1 Sensor Interfaces
I2C Sensor Interface
// I2C Sensor Interface Definition
typedef struct {
uint8_t device_address; // I2C device address (7-bit)
uint32_t clock_speed; // Clock speed in Hz (100kHz, 400kHz)
uint8_t register_width; // Register address width (8 or 16 bits)
bool use_repeated_start; // Use repeated start condition
} i2c_sensor_config_t;
// Standard I2C operations
esp_err_t i2c_sensor_init(uint8_t sensor_id, const i2c_sensor_config_t* config);
esp_err_t i2c_sensor_read_register(uint8_t sensor_id, uint16_t reg_addr, uint8_t* data, size_t len);
esp_err_t i2c_sensor_write_register(uint8_t sensor_id, uint16_t reg_addr, const uint8_t* data, size_t len);
esp_err_t i2c_sensor_detect_presence(uint8_t sensor_id, bool* present);
SPI Sensor Interface
// SPI Sensor Interface Definition
typedef struct {
uint32_t clock_speed; // SPI clock speed in Hz
uint8_t mode; // SPI mode (0-3)
uint8_t bit_order; // MSB_FIRST or LSB_FIRST
uint8_t cs_pin; // Chip select GPIO pin
bool cs_active_low; // CS polarity
} spi_sensor_config_t;
// Standard SPI operations
esp_err_t spi_sensor_init(uint8_t sensor_id, const spi_sensor_config_t* config);
esp_err_t spi_sensor_transfer(uint8_t sensor_id, const uint8_t* tx_data, uint8_t* rx_data, size_t len);
esp_err_t spi_sensor_detect_presence(uint8_t sensor_id, bool* present);
UART Sensor Interface
// UART Sensor Interface Definition
typedef struct {
uint32_t baud_rate; // Baud rate (9600, 19200, 38400, 115200)
uint8_t data_bits; // Data bits (7, 8)
uint8_t parity; // Parity (NONE, EVEN, ODD)
uint8_t stop_bits; // Stop bits (1, 2)
uint8_t flow_control; // Flow control (NONE, RTS_CTS)
uint16_t rx_timeout_ms; // Receive timeout in milliseconds
} uart_sensor_config_t;
// Standard UART operations
esp_err_t uart_sensor_init(uint8_t sensor_id, const uart_sensor_config_t* config);
esp_err_t uart_sensor_send_command(uint8_t sensor_id, const uint8_t* cmd, size_t cmd_len);
esp_err_t uart_sensor_read_response(uint8_t sensor_id, uint8_t* response, size_t max_len, size_t* actual_len);
esp_err_t uart_sensor_detect_presence(uint8_t sensor_id, bool* present);
Analog Sensor Interface
// ADC Sensor Interface Definition
typedef struct {
uint8_t adc_channel; // ADC channel number
uint32_t sample_rate; // Sampling rate in Hz
uint8_t resolution; // ADC resolution (12-bit for ESP32-S3)
uint32_t reference_voltage; // Reference voltage in mV
bool enable_filter; // Enable hardware filter
} adc_sensor_config_t;
// Standard ADC operations
esp_err_t adc_sensor_init(uint8_t sensor_id, const adc_sensor_config_t* config);
esp_err_t adc_sensor_read_raw(uint8_t sensor_id, uint32_t* raw_value);
esp_err_t adc_sensor_read_voltage(uint8_t sensor_id, uint32_t* voltage_mv);
esp_err_t adc_sensor_detect_presence(uint8_t sensor_id, bool* present);
2.1.2 User Interface Hardware
OLED Display Interface
// OLED Display Configuration
typedef struct {
uint8_t i2c_address; // I2C address (typically 0x3C or 0x3D)
uint16_t width; // Display width in pixels (128)
uint16_t height; // Display height in pixels (64)
bool flip_horizontal; // Flip display horizontally
bool flip_vertical; // Flip display vertically
} oled_config_t;
// OLED Display Operations
esp_err_t oled_init(const oled_config_t* config);
esp_err_t oled_clear_screen(void);
esp_err_t oled_set_cursor(uint8_t x, uint8_t y);
esp_err_t oled_write_text(const char* text, uint8_t font_size);
esp_err_t oled_draw_bitmap(uint8_t x, uint8_t y, const uint8_t* bitmap, uint8_t width, uint8_t height);
esp_err_t oled_update_display(void);
Button Interface
// Button Configuration
typedef enum {
BUTTON_UP = 0,
BUTTON_DOWN = 1,
BUTTON_SELECT = 2,
BUTTON_COUNT = 3
} button_id_t;
typedef struct {
uint8_t gpio_pin; // GPIO pin number
bool active_low; // Button active low or high
uint32_t debounce_ms; // Debounce time in milliseconds
uint32_t repeat_delay_ms; // Initial repeat delay
uint32_t repeat_rate_ms; // Repeat rate
} button_config_t;
// Button Operations
esp_err_t button_init(button_id_t button, const button_config_t* config);
esp_err_t button_register_callback(button_id_t button, void (*callback)(button_id_t, bool pressed));
bool button_is_pressed(button_id_t button);
2.1.3 Storage Interfaces
SD Card Interface
// SD Card Configuration
typedef struct {
uint8_t spi_host; // SPI host (SPI2_HOST, SPI3_HOST)
uint8_t cs_pin; // Chip select pin
uint32_t max_frequency; // Maximum SPI frequency
bool format_if_mount_failed; // Format if mount fails
} sdcard_config_t;
// SD Card Operations
esp_err_t sdcard_init(const sdcard_config_t* config);
esp_err_t sdcard_mount(const char* mount_point);
esp_err_t sdcard_unmount(void);
esp_err_t sdcard_get_info(uint64_t* total_bytes, uint64_t* free_bytes);
bool sdcard_is_mounted(void);
NVM Interface
// NVM (Non-Volatile Memory) Operations
esp_err_t nvm_init(void);
esp_err_t nvm_write_blob(const char* namespace, const char* key, const void* data, size_t length);
esp_err_t nvm_read_blob(const char* namespace, const char* key, void* data, size_t* length);
esp_err_t nvm_erase_key(const char* namespace, const char* key);
esp_err_t nvm_erase_namespace(const char* namespace);
2.2 Communication Interfaces
2.2.1 Main Hub Communication Interface
MQTT over TLS Configuration
// MQTT Configuration
typedef struct {
char broker_uri[256]; // MQTT broker URI (mqtts://...)
char client_id[64]; // Unique client identifier
char username[64]; // MQTT username (optional)
char password[64]; // MQTT password (optional)
uint16_t keepalive; // Keepalive interval in seconds
uint8_t qos_level; // QoS level (0, 1, 2)
bool clean_session; // Clean session flag
uint32_t reconnect_timeout_ms; // Reconnection timeout
} mqtt_config_t;
// TLS Configuration
typedef struct {
const char* ca_cert_pem; // CA certificate in PEM format
const char* client_cert_pem; // Client certificate in PEM format
const char* client_key_pem; // Client private key in PEM format
bool verify_peer; // Verify peer certificate
bool verify_hostname; // Verify hostname
} tls_config_t;
// MQTT Operations
esp_err_t mqtt_init(const mqtt_config_t* mqtt_config, const tls_config_t* tls_config);
esp_err_t mqtt_connect(void);
esp_err_t mqtt_disconnect(void);
esp_err_t mqtt_publish(const char* topic, const void* payload, size_t payload_len, uint8_t qos, bool retain);
esp_err_t mqtt_subscribe(const char* topic, uint8_t qos);
esp_err_t mqtt_unsubscribe(const char* topic);
bool mqtt_is_connected(void);
MQTT Topic Structure
/farm/{site_id}/{house_id}/{node_id}/data/{sensor_type} - Sensor data
/farm/{site_id}/{house_id}/{node_id}/status/heartbeat - Heartbeat messages
/farm/{site_id}/{house_id}/{node_id}/status/system - System status
/farm/{site_id}/{house_id}/{node_id}/diag/{severity} - Diagnostic events
/farm/{site_id}/{house_id}/{node_id}/cmd/{command_type} - Commands from Main Hub
/farm/{site_id}/{house_id}/{node_id}/ota/{action} - OTA update messages
CBOR Message Format
// CBOR Message Header
typedef struct {
uint16_t message_type; // Message type identifier
uint16_t version; // Message format version
uint32_t timestamp; // Unix timestamp
uint32_t sequence_number; // Message sequence number
uint16_t payload_length; // Payload length in bytes
uint16_t checksum; // Message checksum
} __attribute__((packed)) cbor_header_t;
// Sensor Data Message (CBOR encoded)
typedef struct {
cbor_header_t header;
uint8_t sensor_id;
uint8_t sensor_type;
float value;
char unit[8];
uint32_t timestamp;
uint8_t validity;
uint16_t error_count;
} __attribute__((packed)) sensor_data_msg_t;
// Diagnostic Event Message (CBOR encoded)
typedef struct {
cbor_header_t header;
uint16_t diagnostic_code;
uint8_t severity;
uint8_t component_id;
uint32_t timestamp;
char description[64];
uint32_t occurrence_count;
} __attribute__((packed)) diagnostic_msg_t;
2.2.2 Peer Communication Interface
ESP-NOW Configuration
// ESP-NOW Peer Configuration
typedef struct {
uint8_t mac_address[6]; // Peer MAC address
uint8_t channel; // Wi-Fi channel (1-14)
bool encrypt; // Enable encryption
uint8_t lmk[16]; // Local Master Key (if encryption enabled)
} espnow_peer_config_t;
// ESP-NOW Operations
esp_err_t espnow_init(void);
esp_err_t espnow_add_peer(const espnow_peer_config_t* peer_config);
esp_err_t espnow_remove_peer(const uint8_t* mac_address);
esp_err_t espnow_send_data(const uint8_t* mac_address, const void* data, size_t len);
esp_err_t espnow_register_recv_callback(void (*callback)(const uint8_t* mac_addr, const uint8_t* data, int len));
ESP-NOW Message Format
// ESP-NOW Message Types
typedef enum {
ESPNOW_MSG_PING = 0x01,
ESPNOW_MSG_PONG = 0x02,
ESPNOW_MSG_TIME_SYNC_REQ = 0x03,
ESPNOW_MSG_TIME_SYNC_RESP = 0x04,
ESPNOW_MSG_STATUS = 0x05
} espnow_msg_type_t;
// ESP-NOW Message Header
typedef struct {
uint8_t message_type; // Message type
uint8_t sequence; // Sequence number
uint16_t payload_length; // Payload length
uint32_t timestamp; // Timestamp
uint16_t checksum; // Message checksum
} __attribute__((packed)) espnow_header_t;
// Ping/Pong Message
typedef struct {
espnow_header_t header;
uint8_t sender_id[6]; // Sender MAC address
uint32_t uptime; // Sender uptime in seconds
int8_t rssi; // Signal strength
} __attribute__((packed)) espnow_ping_msg_t;
2.3 Diagnostic Interface
Diagnostic Session Protocol
// Diagnostic Command Types
typedef enum {
DIAG_CMD_GET_STATUS = 0x01,
DIAG_CMD_GET_SENSORS = 0x02,
DIAG_CMD_GET_DIAGNOSTICS = 0x03,
DIAG_CMD_CLEAR_DIAGNOSTICS = 0x04,
DIAG_CMD_GET_CONFIG = 0x05,
DIAG_CMD_SET_CONFIG = 0x06,
DIAG_CMD_REBOOT = 0x07
} diag_cmd_type_t;
// Diagnostic Command Structure
typedef struct {
uint8_t command; // Command type
uint8_t sequence; // Sequence number
uint16_t payload_length; // Payload length
uint8_t payload[]; // Variable length payload
} __attribute__((packed)) diag_command_t;
// Diagnostic Response Structure
typedef struct {
uint8_t command; // Original command
uint8_t sequence; // Sequence number
uint8_t status; // Response status (0=success)
uint16_t payload_length; // Payload length
uint8_t payload[]; // Variable length payload
} __attribute__((packed)) diag_response_t;
3. Internal Interfaces
3.1 Component Interfaces
3.1.1 Event System Interface
Event System API
// Event Types
typedef enum {
EVENT_SENSOR_DATA_UPDATE = 0x0001,
EVENT_DIAGNOSTIC_EVENT = 0x0002,
EVENT_STATE_CHANGED = 0x0003,
EVENT_OTA_REQUEST = 0x0004,
EVENT_MC_UPDATE = 0x0005,
EVENT_COMMUNICATION_STATUS = 0x0006,
EVENT_STORAGE_STATUS = 0x0007,
EVENT_BUTTON_PRESSED = 0x0008,
EVENT_TIMER_EXPIRED = 0x0009,
EVENT_SYSTEM_ERROR = 0x000A
} event_type_t;
// Event Data Structure
typedef struct {
event_type_t type; // Event type
uint32_t timestamp; // Event timestamp
uint8_t source_component; // Source component ID
uint16_t data_length; // Event data length
void* data; // Event data pointer
} event_t;
// Event Handler Function Type
typedef void (*event_handler_t)(const event_t* event);
// Event System Operations
esp_err_t event_system_init(void);
esp_err_t event_publish(event_type_t type, const void* data, size_t data_len);
esp_err_t event_subscribe(event_type_t type, event_handler_t handler);
esp_err_t event_unsubscribe(event_type_t type, event_handler_t handler);
esp_err_t event_system_process(void); // Process pending events
3.1.2 Data Pool Interface
Data Pool API
// Data Pool Entry Types
typedef enum {
DATA_TYPE_SENSOR_READING = 0x01,
DATA_TYPE_SYSTEM_STATUS = 0x02,
DATA_TYPE_COMMUNICATION_STATUS = 0x03,
DATA_TYPE_DIAGNOSTIC_SUMMARY = 0x04,
DATA_TYPE_CONFIGURATION = 0x05
} data_type_t;
// Data Pool Entry
typedef struct {
data_type_t type; // Data type
uint8_t key[16]; // Data key (sensor ID, etc.)
uint32_t timestamp; // Last update timestamp
uint16_t data_length; // Data length
void* data; // Data pointer
bool valid; // Data validity flag
} data_pool_entry_t;
// Data Pool Operations
esp_err_t data_pool_init(void);
esp_err_t data_pool_write(data_type_t type, const uint8_t* key, const void* data, size_t data_len);
esp_err_t data_pool_read(data_type_t type, const uint8_t* key, void* data, size_t* data_len);
esp_err_t data_pool_get_timestamp(data_type_t type, const uint8_t* key, uint32_t* timestamp);
esp_err_t data_pool_is_valid(data_type_t type, const uint8_t* key, bool* valid);
esp_err_t data_pool_invalidate(data_type_t type, const uint8_t* key);
3.1.3 State Manager Interface
State Manager API
// System States
typedef enum {
STATE_INIT = 0,
STATE_BOOT_FAILURE = 1,
STATE_RUNNING = 2,
STATE_WARNING = 3,
STATE_FAULT = 4,
STATE_OTA_PREP = 5,
STATE_OTA_UPDATE = 6,
STATE_MC_UPDATE = 7,
STATE_TEARDOWN = 8,
STATE_SERVICE = 9,
STATE_SD_DEGRADED = 10
} system_state_t;
// State Transition Reasons
typedef enum {
TRANSITION_REASON_STARTUP = 0,
TRANSITION_REASON_NORMAL_OPERATION = 1,
TRANSITION_REASON_ERROR_DETECTED = 2,
TRANSITION_REASON_OTA_REQUEST = 3,
TRANSITION_REASON_MC_UPDATE_REQUEST = 4,
TRANSITION_REASON_USER_REQUEST = 5,
TRANSITION_REASON_SYSTEM_SHUTDOWN = 6
} transition_reason_t;
// State Change Callback
typedef void (*state_change_callback_t)(system_state_t old_state, system_state_t new_state, transition_reason_t reason);
// State Manager Operations
esp_err_t state_manager_init(void);
system_state_t state_manager_get_current_state(void);
esp_err_t state_manager_request_transition(system_state_t target_state, transition_reason_t reason);
bool state_manager_is_transition_valid(system_state_t from_state, system_state_t to_state);
esp_err_t state_manager_register_callback(state_change_callback_t callback);
bool state_manager_is_operation_allowed(system_state_t state, const char* operation);
3.1.4 Data Persistence Interface
Data Persistence API
// Persistence Data Types
typedef enum {
PERSIST_TYPE_SENSOR_DATA = 0x01,
PERSIST_TYPE_DIAGNOSTIC_LOG = 0x02,
PERSIST_TYPE_MACHINE_CONSTANTS = 0x03,
PERSIST_TYPE_SYSTEM_CONFIG = 0x04,
PERSIST_TYPE_CALIBRATION_DATA = 0x05,
PERSIST_TYPE_FIRMWARE_IMAGE = 0x06
} persist_type_t;
// Persistence Operations
esp_err_t persistence_init(void);
esp_err_t persistence_write(persist_type_t type, const char* key, const void* data, size_t data_len);
esp_err_t persistence_read(persist_type_t type, const char* key, void* data, size_t* data_len);
esp_err_t persistence_delete(persist_type_t type, const char* key);
esp_err_t persistence_list_keys(persist_type_t type, char keys[][32], size_t* key_count);
esp_err_t persistence_flush_all(void);
esp_err_t persistence_get_storage_info(uint64_t* total_bytes, uint64_t* free_bytes, uint64_t* used_bytes);
bool persistence_is_available(void);
3.1.5 Sensor Manager Interface
Sensor Manager API
// Sensor Types
typedef enum {
SENSOR_TYPE_TEMPERATURE = 0x01,
SENSOR_TYPE_HUMIDITY = 0x02,
SENSOR_TYPE_CO2 = 0x03,
SENSOR_TYPE_NH3 = 0x04,
SENSOR_TYPE_VOC = 0x05,
SENSOR_TYPE_PM = 0x06,
SENSOR_TYPE_LIGHT = 0x07
} sensor_type_t;
// Sensor Status
typedef enum {
SENSOR_STATUS_NOT_PRESENT = 0,
SENSOR_STATUS_INITIALIZING = 1,
SENSOR_STATUS_WARMING_UP = 2,
SENSOR_STATUS_READY = 3,
SENSOR_STATUS_ERROR = 4,
SENSOR_STATUS_FAILED = 5
} sensor_status_t;
// Sensor Data Record
typedef struct {
uint8_t sensor_id; // Sensor identifier
sensor_type_t sensor_type; // Sensor type
float value; // Sensor reading
char unit[8]; // Unit of measurement
uint32_t timestamp; // Reading timestamp
sensor_status_t status; // Sensor status
uint16_t error_count; // Error count
float min_value; // Minimum valid value
float max_value; // Maximum valid value
} sensor_data_record_t;
// Sensor Manager Operations
esp_err_t sensor_manager_init(void);
esp_err_t sensor_manager_start_acquisition(void);
esp_err_t sensor_manager_stop_acquisition(void);
esp_err_t sensor_manager_get_sensor_data(uint8_t sensor_id, sensor_data_record_t* data);
esp_err_t sensor_manager_get_all_sensor_data(sensor_data_record_t* data_array, size_t* count);
sensor_status_t sensor_manager_get_sensor_status(uint8_t sensor_id);
bool sensor_manager_is_sensor_present(uint8_t sensor_id);
esp_err_t sensor_manager_calibrate_sensor(uint8_t sensor_id, float reference_value);
3.2 Data Structures
3.2.1 Machine Constants Structure
Machine Constants Data Format
// Machine Constants Structure
typedef struct {
// Header
uint32_t magic_number; // Magic number for validation (0xDEADBEEF)
uint16_t version; // Structure version
uint16_t checksum; // Data checksum
uint32_t timestamp; // Last update timestamp
// System Identity
char site_id[16]; // Farm site identifier
char house_id[16]; // House identifier
char node_id[16]; // Node identifier
uint8_t mac_address[6]; // Device MAC address
// Communication Configuration
char mqtt_broker_uri[256]; // MQTT broker URI
char mqtt_username[64]; // MQTT username
char mqtt_password[64]; // MQTT password
uint16_t mqtt_port; // MQTT port
uint16_t heartbeat_interval; // Heartbeat interval in seconds
// Sensor Configuration
struct {
bool enabled; // Sensor enabled flag
sensor_type_t type; // Sensor type
uint8_t interface_type; // Interface type (I2C, SPI, UART, ADC)
uint8_t address; // I2C address or SPI CS pin
uint32_t sample_rate; // Sampling rate in Hz
uint16_t warmup_time; // Warmup time in seconds
float calibration_offset; // Calibration offset
float calibration_scale; // Calibration scale factor
float min_valid_value; // Minimum valid reading
float max_valid_value; // Maximum valid reading
} sensors[8]; // Support up to 8 sensors
// System Configuration
uint32_t acquisition_interval; // Acquisition interval in ms
uint16_t diagnostic_retention; // Diagnostic retention in days
uint8_t log_level; // Logging level
bool debug_enabled; // Debug mode enabled
// Reserved for future use
uint8_t reserved[128];
} __attribute__((packed)) machine_constants_t;
3.2.2 Diagnostic Event Structure
Diagnostic Event Data Format
// Diagnostic Severity Levels
typedef enum {
DIAG_SEVERITY_INFO = 0,
DIAG_SEVERITY_WARNING = 1,
DIAG_SEVERITY_ERROR = 2,
DIAG_SEVERITY_FATAL = 3
} diagnostic_severity_t;
// Diagnostic Event Structure
typedef struct {
uint16_t diagnostic_code; // Diagnostic code (0xSCCC format)
diagnostic_severity_t severity; // Severity level
uint8_t component_id; // Source component identifier
uint32_t timestamp; // Event timestamp
uint32_t occurrence_count; // Number of occurrences
uint32_t first_occurrence; // First occurrence timestamp
uint32_t last_occurrence; // Last occurrence timestamp
char description[64]; // Human-readable description
uint8_t context_data[32]; // Context-specific data
} __attribute__((packed)) diagnostic_event_t;
// Diagnostic Code Definitions
#define DIAG_CODE_SENSOR_DISCONNECTED 0x1001
#define DIAG_CODE_SENSOR_OUT_OF_RANGE 0x1002
#define DIAG_CODE_SENSOR_CALIBRATION_FAIL 0x1003
#define DIAG_CODE_COMMUNICATION_TIMEOUT 0x2001
#define DIAG_CODE_COMMUNICATION_AUTH_FAIL 0x2002
#define DIAG_CODE_STORAGE_WRITE_FAIL 0x3001
#define DIAG_CODE_STORAGE_READ_FAIL 0x3002
#define DIAG_CODE_STORAGE_FULL 0x3003
#define DIAG_CODE_OTA_DOWNLOAD_FAIL 0x4001
#define DIAG_CODE_OTA_VALIDATION_FAIL 0x4002
#define DIAG_CODE_SYSTEM_MEMORY_LOW 0x5001
#define DIAG_CODE_SYSTEM_WATCHDOG_RESET 0x5002
3.2.3 System Status Structure
System Status Data Format
// System Status Structure
typedef struct {
// System Information
system_state_t current_state; // Current system state
uint32_t uptime_seconds; // System uptime in seconds
uint32_t boot_count; // Number of boots since manufacturing
uint32_t last_reset_reason; // Last reset reason
// Resource Usage
uint32_t free_heap_bytes; // Free heap memory in bytes
uint32_t min_free_heap; // Minimum free heap since boot
uint8_t cpu_usage_percent; // CPU usage percentage
uint32_t task_count; // Number of active tasks
// Communication Status
bool mqtt_connected; // MQTT connection status
int8_t wifi_rssi; // Wi-Fi signal strength in dBm
uint32_t messages_sent; // Total messages sent
uint32_t messages_received; // Total messages received
uint32_t communication_errors; // Communication error count
// Storage Status
bool sd_card_mounted; // SD card mount status
uint64_t sd_total_bytes; // SD card total capacity
uint64_t sd_free_bytes; // SD card free space
uint32_t storage_errors; // Storage error count
// Sensor Status Summary
uint8_t sensors_present; // Number of sensors present
uint8_t sensors_active; // Number of active sensors
uint8_t sensors_failed; // Number of failed sensors
uint32_t last_acquisition_time; // Last successful acquisition timestamp
// Diagnostic Summary
uint16_t info_events; // Number of INFO events
uint16_t warning_events; // Number of WARNING events
uint16_t error_events; // Number of ERROR events
uint16_t fatal_events; // Number of FATAL events
// Temperature and Performance
float cpu_temperature; // CPU temperature in Celsius
uint32_t flash_wear_level; // Flash wear level (0-100%)
// Firmware Information
char firmware_version[32]; // Firmware version string
uint32_t firmware_build_time; // Firmware build timestamp
uint8_t firmware_checksum[32]; // Firmware SHA-256 checksum
} __attribute__((packed)) system_status_t;
4. Protocol Specifications
4.1 State Machine Protocol
State Transition Protocol
// State Transition Request
typedef struct {
system_state_t target_state; // Requested target state
transition_reason_t reason; // Reason for transition
uint32_t timeout_ms; // Transition timeout
bool force_transition; // Force transition flag
uint8_t context_data[16]; // Context-specific data
} state_transition_request_t;
// State Transition Response
typedef struct {
bool accepted; // Transition accepted
system_state_t current_state; // Current state after transition
uint32_t transition_time_ms; // Time taken for transition
char error_message[64]; // Error message if rejected
} state_transition_response_t;
4.2 OTA Update Protocol
OTA Update Message Flow
// OTA Request Message
typedef struct {
uint32_t firmware_size; // Firmware size in bytes
uint8_t firmware_checksum[32]; // SHA-256 checksum
char firmware_version[32]; // Firmware version string
uint32_t chunk_size; // Chunk size for transfer
uint16_t total_chunks; // Total number of chunks
bool force_update; // Force update flag
} ota_request_msg_t;
// OTA Response Message
typedef struct {
bool accepted; // Update accepted
char reason[64]; // Reason if rejected
uint32_t estimated_time_ms; // Estimated update time
} ota_response_msg_t;
// OTA Chunk Message
typedef struct {
uint16_t chunk_number; // Chunk sequence number
uint16_t chunk_size; // Actual chunk size
uint8_t chunk_checksum[4]; // CRC32 checksum of chunk
uint8_t data[]; // Chunk data
} ota_chunk_msg_t;
// OTA Status Message
typedef struct {
uint16_t chunks_received; // Number of chunks received
uint16_t chunks_total; // Total chunks expected
uint8_t progress_percent; // Progress percentage
bool validation_complete; // Validation completed
bool ready_to_activate; // Ready for activation
} ota_status_msg_t;
5. Error Codes and Return Values
5.1 Standard Error Codes
// Standard ESP-IDF Error Codes (esp_err_t)
#define ESP_OK 0 // Success
#define ESP_FAIL -1 // Generic failure
#define ESP_ERR_NO_MEM 0x101 // Out of memory
#define ESP_ERR_INVALID_ARG 0x102 // Invalid argument
#define ESP_ERR_INVALID_STATE 0x103 // Invalid state
#define ESP_ERR_INVALID_SIZE 0x104 // Invalid size
#define ESP_ERR_NOT_FOUND 0x105 // Requested resource not found
#define ESP_ERR_NOT_SUPPORTED 0x106 // Operation not supported
#define ESP_ERR_TIMEOUT 0x107 // Operation timed out
#define ESP_ERR_INVALID_RESPONSE 0x108 // Received response was invalid
#define ESP_ERR_INVALID_CRC 0x109 // CRC or checksum was invalid
#define ESP_ERR_INVALID_VERSION 0x10A // Version was invalid
// Application-Specific Error Codes
#define APP_ERR_SENSOR_NOT_PRESENT 0x1001 // Sensor not detected
#define APP_ERR_SENSOR_INIT_FAILED 0x1002 // Sensor initialization failed
#define APP_ERR_SENSOR_READ_FAILED 0x1003 // Sensor read operation failed
#define APP_ERR_COMMUNICATION_FAILED 0x2001 // Communication failure
#define APP_ERR_AUTHENTICATION_FAILED 0x2002 // Authentication failure
#define APP_ERR_STORAGE_NOT_AVAILABLE 0x3001 // Storage not available
#define APP_ERR_STORAGE_WRITE_FAILED 0x3002 // Storage write failed
#define APP_ERR_STORAGE_READ_FAILED 0x3003 // Storage read failed
#define APP_ERR_STATE_TRANSITION_INVALID 0x4001 // Invalid state transition
#define APP_ERR_OTA_VALIDATION_FAILED 0x5001 // OTA validation failed
#define APP_ERR_SECURITY_VIOLATION 0x6001 // Security violation detected
6. Interface Validation
6.1 Interface Testing Requirements
Each interface SHALL be validated using the following methods:
| Interface Type | Validation Method | Test Coverage |
|---|---|---|
| Hardware Interfaces | Unit tests with hardware simulation | 100% of API functions |
| Communication Interfaces | Integration tests with protocol validation | Message format and error handling |
| Component Interfaces | Unit and integration tests | API contracts and data flow |
| Data Structures | Serialization/deserialization tests | All data formats and edge cases |
| Protocol Specifications | Protocol compliance tests | State machines and message flows |
6.2 Interface Compliance
All interfaces SHALL comply with:
- Data Alignment: Structures use appropriate packing and alignment
- Endianness: Network byte order for communication protocols
- Error Handling: Consistent error code usage and propagation
- Thread Safety: Interfaces used by multiple tasks are thread-safe
- Resource Management: Proper resource allocation and cleanup
Document Status: Final for Implementation Phase
Interface Count: 50+ interfaces defined
Compliance: ISO/IEC/IEEE 29148:2018
Next Phase: Component Implementation
This document serves as the definitive interface specification for the ASF Sensor Hub software implementation.