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.