ASF-Nabd/ASF_01_sys_sw_arch

Fork 0

Files

mahmamdouh edd3e96591 init

2026-01-19 16:19:41 +01:00

7.4 KiB

Raw Blame History

Annex B: External Interface Specifications

Document: SRS Annex B
Version: 1.0
Date: 2025-01-19

Purpose

This annex defines the external interfaces between the Sensor Hub and external entities (Main Hub, sensors, storage, HMI).

1. Main Hub Communication Interface

1.1 Protocol Stack

Application Layer (Sensor Hub APIs)
    ↓
Transport Security Layer (TLS/DTLS)
    ↓
Network Layer (Wi-Fi / Zigbee / LoRa)
    ↓
Physical Layer

1.2 Message Format

Request Message Structure:

typedef struct {
    uint8_t message_type;      // REQ_DATA, REQ_STATUS, REQ_DIAG, CMD_CONFIG, CMD_OTA
    uint16_t message_id;       // Unique request ID
    uint32_t timestamp;        // Request timestamp
    uint16_t payload_length;   // Payload length in bytes
    uint8_t payload[];         // Message-specific payload
    uint32_t checksum;         // Message integrity checksum
} main_hub_request_t;

Response Message Structure:

typedef struct {
    uint8_t message_type;      // RESP_DATA, RESP_STATUS, RESP_DIAG, ACK, NACK
    uint16_t message_id;       // Matching request ID
    uint8_t status_code;        // SUCCESS, ERROR, TIMEOUT
    uint32_t timestamp;        // Response timestamp
    uint16_t payload_length;   // Payload length in bytes
    uint8_t payload[];         // Message-specific payload
    uint32_t checksum;         // Message integrity checksum
} main_hub_response_t;

1.3 Message Types

Message Type	Direction	Purpose	Payload
`REQ_DATA`	Main Hub → Sensor Hub	Request latest sensor data	None
`RESP_DATA`	Sensor Hub → Main Hub	Sensor data response	Sensor data records
`REQ_STATUS`	Main Hub → Sensor Hub	Request system status	None
`RESP_STATUS`	Sensor Hub → Main Hub	System status response	Status information
`REQ_DIAG`	Main Hub → Sensor Hub	Request diagnostic data	Diagnostic filter
`RESP_DIAG`	Sensor Hub → Main Hub	Diagnostic data response	Diagnostic events
`CMD_CONFIG`	Main Hub → Sensor Hub	Configuration update	Configuration data
`CMD_OTA`	Main Hub → Sensor Hub	OTA update request	OTA metadata
`ACK`	Sensor Hub → Main Hub	Acknowledgment	None or status
`NACK`	Sensor Hub → Main Hub	Negative acknowledgment	Error code

1.4 Communication Requirements

Encryption: All messages SHALL be encrypted using TLS/DTLS
Authentication: All messages SHALL be authenticated
Integrity: All messages SHALL include integrity checksums
Timeout: Request timeout: 5 seconds
Retry: Maximum 3 retries with exponential backoff

2. Sensor Interfaces

2.1 Supported Protocols

Protocol	Sensor Types	Interface
I2C	Temperature, Humidity, CO2, NH3, VOC, Light	I2C bus (configurable pins)
SPI	Particulate matter sensors	SPI bus (configurable pins)
UART	Some sensor modules	UART (configurable pins)
Analog	Analog sensors	ADC channels

2.2 Sensor Detection Signal

Each sensor slot SHALL provide a dedicated GPIO pin for presence detection:

High (3.3V): Sensor present
Low (0V): Sensor absent

2.3 Sensor Data Format

typedef struct {
    uint8_t sensor_id;          // Unique sensor identifier
    uint8_t sensor_type;        // TEMP, HUM, CO2, NH3, VOC, PM, LIGHT
    float value;                // Filtered sensor value
    uint8_t unit;               // Unit code (C, RH, PPM, LUX, etc.)
    uint64_t timestamp_us;     // Timestamp in microseconds
    uint8_t validity_status;    // VALID, INVALID, DEGRADED, FAILED
    uint8_t sample_count;       // Number of samples used for filtering
} sensor_data_record_t;

3. Storage Interfaces

3.1 SD Card Interface

File System: FAT32
Mount Point: /sdcard

Directory Structure:

/sdcard/
  ├── sensor_data/
  │   └── YYYYMMDD_HHMMSS.dat
  ├── diagnostics/
  │   └── diag_log.dat
  ├── machine_constants/
  │   └── mc.dat
  └── ota/
      └── firmware.bin

File Naming Convention:

Sensor data: YYYYMMDD_HHMMSS.dat (timestamp-based)
Diagnostics: diag_log.dat (circular log)
Machine constants: mc.dat (single file)
OTA firmware: firmware.bin (temporary)

3.2 NVM (Non-Volatile Memory) Interface

Storage Areas:

Machine Constants: 4KB
System Configuration: 2KB
Diagnostic Log (circular): 8KB
OTA Metadata: 1KB

Access Method: ESP-IDF NVS (Non-Volatile Storage) API

4. HMI Interfaces

4.1 OLED Display Interface

Protocol: I2C
Address: Configurable (default: 0x3C)
Display: 128x64 pixels, monochrome

Display Content:

Main Screen: Connectivity, System State, Sensor Count, Time/Date
Menu Screens: Diagnostics, Sensors, Health

4.2 Button Interface

Buttons: 3 GPIO inputs (Up, Down, Select)

Button Behavior:

Up: Navigate menu up / Scroll up
Down: Navigate menu down / Scroll down
Select: Enter menu / Select item / Return to main screen

Debouncing: Hardware debouncing (10ms) + software debouncing (50ms)

5. Debug Interface

5.1 Physical Interface

Protocol: UART
Baud Rate: 115200
Data Bits: 8
Parity: None
Stop Bits: 1
Flow Control: None

5.2 Debug Protocol

Session Establishment:

Client sends authentication challenge
Sensor Hub responds with challenge response
Client sends session key (encrypted)
Sensor Hub validates and establishes session

Debug Commands:

READ_DIAG <filter> - Read diagnostic events
READ_STATUS - Read system status
READ_MC - Read machine constants
CLEAR_DIAG - Clear diagnostic log
REBOOT - Reboot system
TEARDOWN - Initiate controlled teardown

Security: All debug sessions SHALL be authenticated. Unauthorized access SHALL be rejected and logged as a security violation.

6. Peer Sensor Hub Communication

6.1 Protocol

Protocol: Same as Main Hub communication (Wi-Fi / Zigbee / LoRa)
Message Types: Limited to connectivity checks and time synchronization

6.2 Message Types

Message Type	Purpose
`PEER_PING`	Connectivity check
`PEER_PONG`	Connectivity response
`PEER_TIME_SYNC`	Time synchronization request
`PEER_TIME_RESP`	Time synchronization response

6.3 Requirements

Peer communication SHALL NOT interfere with Main Hub communication
Peer communication SHALL be encrypted and authenticated
Peer communication SHALL be limited to coordination functions only

7. Interface Requirements Summary

Interface	Protocol	Encryption	Authentication	Integrity
Main Hub	TLS/DTLS over Wi-Fi/Zigbee/LoRa	Yes	Yes	Yes
Sensors	I2C/SPI/UART/Analog	No	No	No (hardware-level)
SD Card	SPI (SD protocol)	Optional (SWR-SEC-006)	No	Yes (file system)
NVM	ESP-IDF NVS	Optional (SWR-SEC-005)	No	Yes (NVS)
OLED Display	I2C	No	No	No
Buttons	GPIO	No	No	No
Debug	UART	Yes	Yes	Yes
Peer Sensor Hub	Same as Main Hub	Yes	Yes	Yes

8. Traceability

SWR-IF-001: Main Hub communication interface
SWR-IF-002: Sensor interfaces
SWR-IF-003: OLED display interface
SWR-IF-004: Button input interfaces
SWR-IF-005: Storage interfaces
SWR-IF-006: Debug interface

7.4 KiB Raw Blame History