F439_CPP_TX-RX_LoRa_Project
Loading...
Searching...
No Matches
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.

Firmware Layering

The firmware is organized into the following layers:

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

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

Application Layer

Module:

radioApp

Responsibilities:

  • implements the application behavior of the weather station
  • generates messages that are transmitted over the radio
  • consumes parsed messages received from the protocol layer
  • coordinates radio usage

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

This separation ensures that application code remains independent of the specific wire format used on the radio.

Protocol Layer

Module:

radioLink

Responsibilities:

  • wire format definition
  • message framing
  • payload encapsulation
  • replay protection
  • counter validation
  • cryptographic operations
  • parsing received packets

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 maintained even when parts of the protocol evolve.

The RadioLink layer is designed to be transport-agnostic.

Although the current system uses LoRa via the SX1262 modem, the protocol layer itself does not depend on that transport. Future transports such as USB or Ethernet could reuse the same framing logic.

Radio Driver Layer

Module:

SX1262 driver

Responsibilities:

  • SPI communication with the radio modem
  • radio configuration
  • packet transmission
  • packet reception
  • interrupt and status handling

This layer exposes a hardware-oriented interface for interacting with the radio modem while hiding the details of the SX1262 command set.

The driver does not implement protocol logic and is unaware of RadioLink framing structures.

Persistence Layer

Module:

MB85RS64B SPI FRAM

Responsibilities:

  • persistent storage of replay protection state
  • minimal-wear storage of protocol counters

The firmware uses a minimal write strategy to protect non-volatile memory from excessive wear.

The FRAM device supports multi-byte sequential writes which are used by the firmware through the FRAM_WriteBytes() interface.

Replay protection state is written only when required by the epoch-per-boot replay protection model.

Replay Protection Model

The firmware implements replay protection using a design referred to as the epoch-per-boot model.

TX Node

  • generates a new epoch value on boot
  • persists the epoch to FRAM once per boot
  • increments message counters during operation

RX Node

  • validates counters for received frames
  • maintains last-seen counters in RAM

This design minimizes persistent writes while still providing effective replay protection.

Runtime Role Selection

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

The role is determined at runtime using the STM32 unique device ID (UID). The UID is read during startup and used to determine whether the device behaves as a transmitter or receiver.

Compile-time role switching using preprocessor directives is intentionally avoided.

This approach ensures:

  • a single firmware image
  • simplified deployment
  • consistent protocol behavior across nodes

Hardware Abstraction Layer

The lowest layer of the firmware consists of the STM32 HAL components generated by STM32CubeIDE.

These files provide:

  • peripheral initialization
  • interrupt handling
  • SPI and GPIO drivers
  • system clock configuration

The HAL layer is intentionally excluded from most documentation pages because it is generated code rather than project-specific logic.

Layer Interaction Summary

The firmware layers interact as follows:

radioApp ↓ radioLink ↓ SX1262 Driver ↓ STM32 HAL

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

This layered design ensures that protocol logic, radio hardware control, and application behavior remain cleanly separated and easier to maintain.