Firmware Architecture Overview

This page describes the high-level firmware architecture of the Nucleo-F439 LoRa TX/RX weather station system.

The firmware is intentionally organized into layered subsystems so that radio transport, protocol framing, application behavior, and hardware interfaces remain cleanly separated.

The architecture emphasizes:

• strict layering
• transport independence
• minimal persistent state
• clear subsystem ownership

This document serves as the primary architectural reference for the firmware.

Architecture Navigation

Use the links below to jump directly into the subsystem-level documentation for each layer:

• Firmware Architecture module index
• Radio Application Layer
• RadioLink Protocol Layer
• SX1262 Driver Layer
• Persistence Layer
• Hardware Abstraction Layer

Architecture Flow

The documentation is intended to be read top-down:

• Project Main Page
• Firmware Architecture Overview
• subsystem groups listed above
• file-level and API-level documentation within each subsystem

Conceptual interaction flow:

Project Main Page
    -> Firmware Architecture Overview
        -> Subsystem Groups
            -> Files / APIs
 
radioApp
    -> radioLink
        -> SX1262 driver
            -> STM32 HAL / board support
 
radioLink
    -> Persistence Layer (FRAM)

Layer Interaction Diagram

The diagram below shows the intended steady-state interaction between the major firmware layers. The persistence path is shown as a side-path because replay-related FRAM access is coordinated by the RadioLink protocol layer rather than by the application layer directly.

End-to-End Frame Lifecycle

The diagram below ties together the application layer, the RadioLink TX path, the on-air Wire v3 frame, and the corresponding RX-side processing path.

It is intended as the top-level lifecycle view for a frame moving through the system from application intent on one node to accepted payload delivery on the peer node.

Firmware Layering

The firmware is organized into the following layers:

• Radio Application Layer
• RadioLink Protocol Layer
• SX1262 Driver Layer
• Persistence Layer
• Hardware Abstraction Layer

Each layer has a clearly defined responsibility and interacts only with the layers immediately above or below it.

Application Layer

Module:

radioApp

Responsibilities:

• implements application behavior for the weather-station nodes
• generates outbound messages for transmission
• consumes decoded inbound messages from the protocol layer
• coordinates radio usage at the application level

The application layer does not construct wire frames directly. Instead it submits payloads to the RadioLink protocol layer which handles framing, counters, and replay protection.

Protocol Layer

Module:

radioLink

Responsibilities:

• wire format definition
• frame construction and parsing
• cryptographic protection
• replay protection
• counter validation
• persistence coordination for replay state

RadioLink defines the protocol structures used on the wire.

The core structures representing the wire protocol are:

• radio_hdr_t
• radio_msg_t

These structures represent the logical model of a transmitted message and are intentionally preserved because they express the Wire v1+ framing model.

RadioLink is intentionally transport-agnostic. The current transport is LoRa through the SX1262 modem, but the framing layer is designed so that future transports could reuse the same message model.

Radio Driver Layer

Module:

SX1262 driver

Responsibilities:

• SPI communication with the SX1262 modem
• modem configuration
• packet transmission and reception
• IRQ and status handling

The driver exposes a hardware-oriented modem interface while remaining independent of RadioLink framing policy.

Persistence Layer

Module:

MB85RS64B SPI FRAM

Responsibilities:

• persistent storage of replay-related state
• minimal-wear storage of protocol counters and epoch state

The firmware uses a minimal-write persistence strategy. Multi-byte sequential writes are supported by the FRAM hardware and are used through FRAM_WriteBytes().

Replay Protection Model

Replay protection uses the epoch-per-boot model.

TX node behavior:

• derives the active node role at runtime
• generates or advances the epoch/session value on boot
• persists replay-related state once per boot
• advances counters during operation

RX node behavior:

• validates counters on received frames
• keeps last-seen replay state in RAM

This design minimizes persistent writes while preserving replay resistance.

Runtime Role Selection

The firmware supports both TX and RX roles using the same firmware image.

The role is determined at runtime from the STM32 unique device ID (UID). This is an intentional design choice. Compile-time role switching through preprocessor macros is not part of the architecture.

Hardware Abstraction Layer

The lowest layer is the STM32 HAL and board/platform integration logic.

This layer provides:

• peripheral initialization
• SPI and GPIO services
• interrupt integration
• board-level startup support

Most Cube-generated support files are excluded from Doxygen because they are generated infrastructure rather than project-owned architectural logic.

Layer Interaction Summary

The steady-state interaction path is:

radioApp ↓ radioLink ↓ SX1262 driver ↓ STM32 HAL / board support

Persistent replay state is accessed through the FRAM persistence layer, which is used by the RadioLink protocol implementation.

This layered design keeps application behavior, wire protocol policy, radio hardware control, and persistent state management cleanly separated.