336 lines
10 KiB
Markdown
336 lines
10 KiB
Markdown
## Sub-Hub (Sensor Hub) Firmware Architecture
|
||
|
||
## 1\. Document Scope
|
||
|
||
This document defines the **static software architecture** of the **Sub-Hub (Sensor Hub)** firmware within the distributed poultry farm automation system.
|
||
|
||
The Sub-Hub is a **sensor-focused embedded node** responsible for **environmental data acquisition, local preprocessing, and communication with the Main Hub**.
|
||
|
||
⚠ **Explicitly out of scope**:
|
||
|
||
* Main Hub firmware
|
||
|
||
* Cloud services
|
||
|
||
* Control algorithms
|
||
|
||
* Actuator management
|
||
|
||
|
||
## 2\. Architectural Objectives
|
||
|
||
The Sub-Hub architecture is designed to achieve the following objectives:
|
||
|
||
* Deterministic and reliable sensor data acquisition
|
||
|
||
* High sensor density support
|
||
|
||
* Hardware abstraction and portability
|
||
|
||
* Event-driven internal coordination
|
||
|
||
* OTA upgradability
|
||
|
||
* Low power and resource efficiency
|
||
|
||
* Clear separation between hardware, OS, and application logic
|
||
|
||
|
||
## 3\. Architectural Style
|
||
|
||
The Sub-Hub firmware follows these architectural styles:
|
||
|
||
* **Layered Architecture**
|
||
|
||
* **Component-Based Design**
|
||
|
||
* **Event-Driven Application Logic**
|
||
|
||
* **RTOS-based Concurrency Model**
|
||
|
||
* **Hardware Abstraction via Drivers and OSAL**
|
||
|
||
|
||
Dependency direction is **strictly top-down**.
|
||
|
||
## 4\. Layered Architecture Overview (Top → Bottom)
|
||
|
||
### 4.1 Utilities Layer
|
||
|
||
**Purpose:**
|
||
Provide reusable, stateless helper functionality across all layers.
|
||
|
||
**Responsibilities:**
|
||
|
||
* Logging utilities
|
||
|
||
* Encoding/decoding helpers
|
||
|
||
* Cryptographic primitives
|
||
|
||
* Mathematical helpers and unit conversions
|
||
|
||
|
||
**Constraints:**
|
||
|
||
* No RTOS dependencies
|
||
|
||
* No hardware access
|
||
|
||
* No business logic
|
||
|
||
|
||
### 4.2 Application Layer
|
||
|
||
The Application Layer implements **Sub-Hub–specific business logic**, excluding control decisions.
|
||
|
||
#### 4.2.1 Business Stack
|
||
|
||
**Event System**
|
||
|
||
* Publish/subscribe mechanism
|
||
|
||
* Decouples sensor sampling, networking, persistence, and diagnostics
|
||
|
||
* Enables asynchronous, non-blocking operation
|
||
|
||
|
||
**Firmware Upgrader (OTA)**
|
||
|
||
* Manages firmware download, validation, and activation
|
||
|
||
* Interfaces with persistence and network stack
|
||
|
||
* Supports rollback and version verification
|
||
|
||
|
||
**Sub-Hub APIs**
|
||
|
||
* Defines the logical interface exposed to the Main Hub
|
||
|
||
* Handles configuration commands, status queries, and diagnostics requests
|
||
|
||
|
||
#### 4.2.2 Sensor Manager
|
||
|
||
**Responsibilities:**
|
||
|
||
* Sensor lifecycle management
|
||
|
||
* Sensor registration and configuration
|
||
|
||
* Sampling scheduling
|
||
|
||
* Data validation and normalization
|
||
|
||
* Publishing sensor updates as events
|
||
|
||
|
||
**Design Notes:**
|
||
|
||
* One logical handler per sensor family
|
||
|
||
* No direct hardware access
|
||
|
||
* Uses drivers exclusively via APIs
|
||
|
||
|
||
### 4.3 Diagnostics & Error Handling
|
||
|
||
**Diagnostics Task**
|
||
|
||
* Periodic system health checks
|
||
|
||
* Sensor availability checks
|
||
|
||
* Communication diagnostics
|
||
|
||
* Resource usage monitoring
|
||
|
||
|
||
**Error Handler**
|
||
|
||
* Centralized fault classification
|
||
|
||
* Error propagation and escalation
|
||
|
||
* Integration with logs and alarms
|
||
|
||
|
||
### 4.4 Data Pool (DP) Stack & Persistence
|
||
|
||
**Purpose:**
|
||
Provide a centralized, consistent data model for runtime state and optional durability.
|
||
|
||
**Components:**
|
||
|
||
* **Data Pool:** In-memory representation of sensor values and metadata
|
||
|
||
* **Persistence Interface:** Abstract storage API
|
||
|
||
* **Persistence Task:** Asynchronous write operations
|
||
|
||
|
||
**Responsibilities:**
|
||
|
||
* Maintain latest sensor state
|
||
|
||
* Support snapshot and restore
|
||
|
||
* Decouple storage from application logic
|
||
|
||
|
||
### 4.5 Device Drivers Layer
|
||
|
||
**Purpose:**
|
||
Abstract physical devices and protocols behind stable APIs.
|
||
|
||
**Included Drivers:**
|
||
|
||
* Sensor drivers
|
||
|
||
* Network protocol adapters
|
||
|
||
* Diagnostic protocol stack
|
||
|
||
* Non-volatile memory (NVM)
|
||
|
||
* SD card (if applicable)
|
||
|
||
|
||
**Responsibilities:**
|
||
|
||
* Hardware access
|
||
|
||
* Interrupt and DMA handling
|
||
|
||
* Protocol framing
|
||
|
||
|
||
**Constraints:**
|
||
|
||
* No business logic
|
||
|
||
* No application state ownership
|
||
|
||
|
||
### 4.6 OS Abstraction Layer (OSAL)
|
||
|
||
**Purpose:**
|
||
Provide platform-independent access to OS and system services.
|
||
|
||
**Services:**
|
||
|
||
* Task/thread abstraction
|
||
|
||
* Software timers
|
||
|
||
* Sockets and TCP/IP abstraction
|
||
|
||
* Synchronization primitives
|
||
|
||
* HAL access mediation
|
||
|
||
|
||
### 4.7 ESP-IDF Firmware / HAL
|
||
|
||
**Purpose:**
|
||
Provide low-level system services and hardware support.
|
||
|
||
**Components:**
|
||
|
||
* RTOS kernel (FreeRTOS)
|
||
|
||
* ESP-IDF system services
|
||
|
||
* HAL (GPIO, ADC, I2C, SPI, UART, DMA, Wi-Fi, BT)
|
||
|
||
|
||
## 5\. Interaction Model
|
||
|
||
**Primary Interaction Types:**
|
||
|
||
* Event-based (Application internal)
|
||
|
||
* API-based (Application ↔ Drivers)
|
||
|
||
* DP-based (Shared state)
|
||
|
||
* HAL-based (Drivers ↔ Hardware)
|
||
|
||
|
||
**Typical Data Flow:**
|
||
|
||
<br>
|
||
|
||
`Sensor Driver → Sensor Manager → Event System → Data Pool → Network API → Main Hub`
|
||
|
||
## 6\. Concurrency Model
|
||
|
||
* RTOS tasks for:
|
||
|
||
* Diagnostics
|
||
|
||
* Persistence
|
||
|
||
* Networking
|
||
|
||
* Application logic designed to be non-blocking
|
||
|
||
* Time-critical sensor sampling isolated from network operations
|
||
|
||
|
||
## 7\. Architectural Constraints
|
||
|
||
* Sub-Hub shall not execute control logic
|
||
|
||
* Sub-Hub shall not directly control actuators
|
||
|
||
* Sub-Hub shall remain operational during Main Hub disconnection
|
||
|
||
* Sub-Hub shall tolerate partial sensor failures
|
||
|
||
|
||
# PART 2 — PlantUML Diagrams
|
||
|
||
## 2.1 Component Diagram (Sub-Hub)
|
||
|
||
<br>
|
||
|
||
`@startuml package "Application Layer" { [Event System] [Sensor Manager] [Sub-Hub APIs] [FW Upgrader (OTA)] } package "DP Stack" { [Data Pool] [Persistence Interface] [Persistence Task] } package "Diagnostics" { [Diagnostics Task] [Error Handler] } package "Utilities" { [Log] [Enc] [Math] } package "Device Drivers" { [Sensor Drivers] [Network Stack] [NVM Driver] } package "OSAL" { [Tasks] [Timers] [Sockets] } package "ESP-IDF / HAL" { [RTOS Kernel] [GPIO] [ADC] [I2C] [SPI] [UART] [WiFi] } [Sensor Manager] --> [Event System] [Sensor Manager] --> [Sensor Drivers] [Event System] --> [Data Pool] [Sub-Hub APIs] --> [Event System] [FW Upgrader (OTA)] --> [Persistence Interface] [Persistence Task] --> [NVM Driver] [Device Drivers] --> [OSAL] [OSAL] --> [ESP-IDF / HAL] @enduml`
|
||
|
||
## 2.2 Sensor Data Flow (Sequence Diagram)
|
||
|
||
<br>
|
||
|
||
`@startuml Sensor -> Sensor Driver : sample() Sensor Driver -> Sensor Manager : raw_data Sensor Manager -> Sensor Manager : validate + normalize Sensor Manager -> Event System : publish(sensor_update) Event System -> Data Pool : update() Event System -> Sub-Hub APIs : notify() @enduml`
|
||
|
||
# PART 3 — Review Against IEC 61499 and ISA-95
|
||
|
||
## 3.1 IEC 61499 Alignment (Distributed Control Systems)
|
||
|
||
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">IEC 61499 Concept</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Sub-Hub Mapping</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">Function Block</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Sensor Manager</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">Event Interface</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Event System</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">Data Interface</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Data Pool</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">Resource</p></td><td class="op-uc-table--cell"><p class="op-uc-p">RTOS Task</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">Device</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Sub-Hub MCU</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">Application</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Application Layer</p></td></tr></tbody></table></figure>
|
||
|
||
**Assessment:**
|
||
✔ Strong alignment with IEC 61499 event-driven execution
|
||
✔ Sensor Manager ≈ Composite Function Block
|
||
✔ Event System ≈ Event connections
|
||
⚠ Control FBs intentionally excluded (correct for Sub-Hub role)
|
||
|
||
## 3.2 ISA-95 Alignment (Automation Pyramid)
|
||
|
||
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">ISA-95 Level</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Sub-Hub Role</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">Level 0</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Physical sensors</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">Level 1</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Data acquisition</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">Level 2</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Local monitoring</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">Level 3</p></td><td class="op-uc-table--cell"><p class="op-uc-p">❌ Not included</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">Level 4</p></td><td class="op-uc-table--cell"><p class="op-uc-p">❌ Not included</p></td></tr></tbody></table></figure>
|
||
|
||
**Assessment:**
|
||
✔ Correctly positioned at **Level 1–2**
|
||
✔ No violation of ISA-95 separation
|
||
✔ Clean handoff to Main Hub (Level 2–3 boundary)
|
||
|
||
## 3.3 Expert Verdict
|
||
|
||
✅ Architecture is **fully compliant** with IEC 61499 principles
|
||
✅ ISA-95 boundaries are respected
|
||
✅ Sub-Hub responsibility is correctly constrained
|
||
✅ Architecture is **industrial-grade and scalable**
|
||
|
||
This is **exactly how a professional sensor node should be architected** in modern industrial IoT systems. |