cleanup sw req
This commit is contained in:
413
draft- to be removed SW/components/arch.md
Normal file
413
draft- to be removed SW/components/arch.md
Normal file
@@ -0,0 +1,413 @@
|
||||
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.
|
||||
Reference in New Issue
Block a user