# lora-net/loramac-node architecture

> Architecture diagram of the GitHub repository lora-net/loramac-node, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lora-net/loramac-node
- Repository: https://github.com/lora-net/loramac-node

## Overview

##### Project type and purpose
- This is a firmware stack for LoRaWAN end-devices (“LoRaMac-Node”), providing Class A/B/C support, radio drivers (SX1272/76, SX1261/2, LR1110), secure-element abstractions, board support packages, and example applications (fuota-test-01, periodic-uplink-lpp, ping-pong, rx-sensi, tx-cw).
- It’s a layered embedded system, built with CMake, targeting ARM-Cortex MCUs (SAMR34, STM32L0/L1/L4, SAML21, etc.).

##### File structure
- Top-level: cmake/ (build scripts), src/apps/ (projects), src/boards/ (board support packages with CMSIS + HAL + BSP), src/mac/ (LoRaWAN MAC layer), src/radio/ (transceiver drivers), src/peripherals/ (sensors & secure-element abstractions), src/system/ (hardware abstraction: SPI, I²C, UART, timers, delays, NVM).
- Patterns: clear separation of concerns—application layer, protocol stack (MAC), hardware abstraction, board-specific code, and vendor CMSIS + HAL.
- README covers architecture (Class A/B/C, radio, secure-elements), build process, platforms, subsystems.

##### Detailed capture of essential elements
- Do not just show “Application → Hardware”; break out the LoRaWAN stack into Handler, MAC, Region modules, Crypto, Serializer.
- SPI/GPIO/I²C interactions in the hardware path.
- NVM Manager (src/system/nvmm.c) for persistent LoRaWAN frame counters, keys.
- External RF link between “RF Front-End” and “LoRaWAN Network Server”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        ApplicationExamples["Application Examples"]:::app
    end

    %% Handler Layer
    subgraph "Handler Layer"
        direction TB
        LmHandler["LmHandler"]:::handler
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        direction TB
        LoRaWANMAC["LoRaWAN MAC"]:::protocol
        subgraph "Region Modules"
            direction TB
            Regions["Region Modules"]:::protocol
        end
    end

    %% Secure-Element Abstraction
    subgraph "Secure-Element Abstraction"
        direction TB
        ATECC608A["ATECC608A SE"]:::hw
        LR1110SE["LR1110 SE"]:::hw
        SoftSE["Software SE"]:::hw
    end

    %% Radio Drivers
    subgraph "Radio Drivers"
        direction TB
        SX1272["SX1272 Driver"]:::hw
        SX1276["SX1276 Driver"]:::hw
        SX126x["SX126x Driver"]:::hw
        LR1110Radio["LR1110 Radio"]:::hw
    end

    %% Board Support Package
    subgraph "Board Support Package (CMSIS+HAL+BSP)"
        direction TB
        BSP["Board Support Package"]:::hw
    end

    %% System HAL APIs
    subgraph "System HAL APIs"
        direction TB
        SystemHAL["Core System HAL"]:::system
    end

    %% Build System
    subgraph "Build System"
        direction TB
        BuildSystem["CMake Build System"]:::build
    end

    %% External Network
    ExternalNetwork["External LoRaWAN Network (RF)"]:::external

    %% Connections
    ApplicationExamples -->|"uses API"| LmHandler
    LmHandler -->|"invokes"| LoRaWANMAC
    LoRaWANMAC -->|"calls crypto"| ATECC608A
    LoRaWANMAC -->|"calls crypto"| LR1110SE
    LoRaWANMAC -->|"calls crypto"| SoftSE
    LoRaWANMAC -->|"sends frames"| SX1272
    LoRaWANMAC -->|"sends frames"| SX1276
    LoRaWANMAC -->|"sends frames"| SX126x
    LoRaWANMAC -->|"sends frames"| LR1110Radio
    SX1272 -->|"SPI/GPIO"| BSP
    SX1276 -->|"SPI/GPIO"| BSP
    SX126x -->|"SPI/GPIO"| BSP
    LR1110Radio -->|"SPI/GPIO"| BSP
    BSP -->|"calls"| SystemHAL
    SystemHAL -->|"drivers to"| ExternalNetwork
    BuildSystem -->|"configures compile-time select"| ApplicationExamples
    BuildSystem -->|"configures compile-time select"| LmHandler
    BuildSystem -->|"configures compile-time select"| LoRaWANMAC
    BuildSystem -->|"configures compile-time select"| ATECC608A
    BuildSystem -->|"configures compile-time select"| LR1110SE
    BuildSystem -->|"configures compile-time select"| SoftSE
    BuildSystem -->|"configures compile-time select"| SX1272
    BuildSystem -->|"configures compile-time select"| SX1276
    BuildSystem -->|"configures compile-time select"| SX126x
    BuildSystem -->|"configures compile-time select"| LR1110Radio
    BuildSystem -->|"configures compile-time select"| BSP

    %% Click Events
    click ApplicationExamples "https://github.com/lora-net/loramac-node/tree/master/src/apps"
    click LmHandler "https://github.com/lora-net/loramac-node/blob/master/src/apps/LoRaMac/common/LmHandler/LmHandler.c"
    click LoRaWANMAC "https://github.com/lora-net/loramac-node/tree/master/src/mac"
    click Regions "https://github.com/lora-net/loramac-node/tree/master/src/mac/region"
    click ATECC608A "https://github.com/lora-net/loramac-node/blob/master/src/peripherals/atecc608a-tnglora-se/atecc608a-tnglora-se.c"
    click LR1110SE "https://github.com/lora-net/loramac-node/blob/master/src/peripherals/lr1110-se/lr1110-se.c"
    click SoftSE "https://github.com/lora-net/loramac-node/blob/master/src/peripherals/soft-se/soft-se.c"
    click SX1272 "https://github.com/lora-net/loramac-node/blob/master/src/radio/sx1272/sx1272.c"
    click SX1276 "https://github.com/lora-net/loramac-node/blob/master/src/radio/sx1276/sx1276.c"
    click SX126x "https://github.com/lora-net/loramac-node/blob/master/src/radio/sx126x/sx126x.c"
    click LR1110Radio "https://github.com/lora-net/loramac-node/blob/master/src/radio/lr1110/radio.c"
    click BSP "https://github.com/lora-net/loramac-node/tree/master/src/boards/B-L072Z-LRWAN1"
    click SystemHAL "https://github.com/lora-net/loramac-node/tree/master/src/system"
    click BuildSystem "https://github.com/lora-net/loramac-node/blob/master/CMakeLists.txt"

    %% Styles
    classDef app fill:#e0f7e9,stroke:#333,stroke-width:1px
    classDef handler fill:#d1f0ff,stroke:#333,stroke-width:1px
    classDef protocol fill:#d0e0ff,stroke:#333,stroke-width:1px
    classDef hw fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef system fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef build fill:#f3d1ff,stroke:#333,stroke-width:1px
    classDef external fill:#fff4c2,stroke:#333,stroke-width:1px
```
