414 lines
9.3 KiB
Markdown
414 lines
9.3 KiB
Markdown
Excellent — this is a **very strong foundation**, and your clarification is important.
|
||
Below I will proceed **exactly in the order you requested**, and **strictly scoped to the Sub-Hub (Sensor Hub) firmware only**.
|
||
|
||
I will deliver **three clearly separated parts**, written in **formal engineering language**, suitable for ALM / ARCHITECTURE.md usage.
|
||
|
||
---
|
||
|
||
# PART 1 — Formal Architecture Document
|
||
|
||
## 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:**
|
||
|
||
```
|
||
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)
|
||
|
||
```plantuml
|
||
@startuml
|
||
@startuml
|
||
skinparam packageStyle rectangle
|
||
title Sub-Hub Component Diagram
|
||
|
||
package "Application Layer" {
|
||
component "Event System" as ES
|
||
component "Sensor Manager" as SM
|
||
component "Sub-Hub APIs" as API
|
||
component "FW Upgrader (OTA)" as OTA
|
||
}
|
||
|
||
package "DP Stack" {
|
||
component "Data Pool" as DP
|
||
component "Persistence Interface" as PI
|
||
component "Persistence Task" as PT
|
||
}
|
||
|
||
package "Diagnostics" {
|
||
component "Diagnostics Task" as DT
|
||
component "Error Handler" as EH
|
||
}
|
||
|
||
package "Utilities" {
|
||
component "Log" as LOG
|
||
component "Enc" as ENC
|
||
component "Math" as MATH
|
||
}
|
||
|
||
package "Device Drivers" {
|
||
component "Sensor Drivers" as SD
|
||
component "Network Stack" as NET
|
||
component "NVM Driver" as NVM
|
||
}
|
||
|
||
package "OSAL" {
|
||
component "Tasks/Timers/Sockets" as OSALC
|
||
}
|
||
|
||
package "ESP-IDF / HAL" {
|
||
component "RTOS Kernel" as K
|
||
component "GPIO/ADC/I2C/SPI/UART/WiFi" as HAL
|
||
}
|
||
|
||
SM --> ES : publish(sensor_update)
|
||
SM --> SD : sample()/config()
|
||
ES --> DP : update(state)
|
||
API --> ES : command()/subscribe()
|
||
OTA --> PI : store(fw)/read()
|
||
PT --> NVM : write()/read()
|
||
SD --> OSALC : irq / DMA
|
||
OSALC --> HAL : system calls
|
||
ES ..> DT : emits diagnostics events
|
||
LOG ..> ES : log()
|
||
@enduml
|
||
```
|
||
|
||
---
|
||
|
||
## 2.2 Sensor Data Flow (Sequence Diagram)
|
||
|
||
```plantuml
|
||
@startuml
|
||
@startuml
|
||
title Sensor Data Flow
|
||
participant Sensor
|
||
participant "Sensor Driver" as SD
|
||
participant "Sensor Manager" as SM
|
||
participant "Event System" as ES
|
||
participant "Data Pool" as DP
|
||
participant "Sub-Hub APIs" as API
|
||
participant "Persistence Task" as PT
|
||
|
||
Sensor -> SD : sample()
|
||
SD -> SM : raw_data
|
||
SM -> SM : validate(); normalize()
|
||
SM -> ES : publish(sensor_update)
|
||
ES -> DP : update(sensor:value)
|
||
ES -> API : notify(subscribers)
|
||
ES -> PT : async_persist(sensor:value)
|
||
PT -> NVM : write()
|
||
API --> ES : read(state) // response flow
|
||
@enduml
|
||
```
|
||
|
||
---
|
||
|
||
# PART 3 — Review Against IEC 61499 and ISA-95
|
||
|
||
---
|
||
|
||
## 3.1 IEC 61499 Alignment (Distributed Control Systems)
|
||
|
||
| IEC 61499 Concept | Sub-Hub Mapping |
|
||
| ----------------- | ----------------- |
|
||
| Function Block | Sensor Manager |
|
||
| Event Interface | Event System |
|
||
| Data Interface | Data Pool |
|
||
| Resource | RTOS Task |
|
||
| Device | Sub-Hub MCU |
|
||
| Application | Application Layer |
|
||
|
||
**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)
|
||
|
||
| ISA-95 Level | Sub-Hub Role |
|
||
| ------------ | ---------------- |
|
||
| Level 0 | Physical sensors |
|
||
| Level 1 | Data acquisition |
|
||
| Level 2 | Local monitoring |
|
||
| Level 3 | ❌ Not included |
|
||
| Level 4 | ❌ Not included |
|
||
|
||
**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.
|
||
|
||
---
|
||
|
||
## What we should do next (recommended)
|
||
|
||
1. Define **Sub-Hub state machine**
|
||
2. Define **communication ICD (Sub-Hub ↔ Main Hub)**
|
||
3. Define **sensor abstraction model**
|
||
4. Define **fault classification table**
|
||
5. Prepare **Main Hub architecture** (next logical step)
|
||
|
||
If you want, next I can:
|
||
|
||
* Turn this into **ISO/IEC/IEEE 42010 compliant architecture views**
|
||
* Write **formal architectural constraints & quality attributes**
|
||
* Prepare **Main Hub architecture using the same rigor**
|
||
* Align Sub-Hub ↔ Main Hub communication with **IEC 61850 / MQTT Sparkplug concepts**
|
||
|
||
Just tell me the next step.
|