# lora-net/usp_zephyr architecture

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

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

## Overview

USP for Zephyr adapts Semtech’s LoRa software platform to Zephyr radios. The main runtime path is the USP thread: it initializes the modem HAL, signals readiness, then repeatedly runs the modem and RAC engines (and optionally FLRP) before sleeping. Radio-family board, HAL, and calibration/BSP implementations provide the hardware-facing layer; modem helpers, platform utilities, logging, LEDs, tracing, and storage support the integration. README capabilities include advanced multi-protocol support and FLRP. Several subsystem links are documented capabilities rather than verified calls in the excerpts, so they are omitted or marked unverified.

Main entry points: [`subsys/usp/zephyr_usp_thread.c`](https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/zephyr_usp_thread.c) (USP main thread), [`modules/smtc_modem_hal/smtc_modem_hal.c`](https://github.com/lora-net/usp_zephyr/blob/main/modules/smtc_modem_hal/smtc_modem_hal.c) (Modem HAL), [`drivers/usp/lr11xx/lr11xx_board.c`](https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr11xx/lr11xx_board.c) (LR11xx board), [`drivers/usp/lr20xx/lr20xx_board.c`](https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr20xx/lr20xx_board.c) (LR20xx board)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["USP runtime"]
  node_usp_thread["USP main thread"]
  node_initialization["Initialization sync"]
end

subgraph group_modem["Modem services"]
  node_modem_engine["Modem engine"]
  node_rac_engine["RAC engine"]
  node_flrp["FLRP engine"]
  node_modem_helper["Modem callbacks"]
  node_modem_hal["Modem HAL<br/>[smtc_modem_hal.c]"]
  node_hal_storage[("Modem storage")]
  node_hal_trace["Debug tracing"]
end

subgraph group_radio["Radio hardware"]
  node_lr11xx_board["LR11xx board<br/>[lr11xx_board.c]"]
  node_lr11xx_hal["LR11xx HAL<br/>[lr11xx_hal.c]"]
  node_lr11xx_bsp["LR11xx calibration"]
  node_lr20xx_board["LR20xx board<br/>[lr20xx_board.c]"]
  node_lr20xx_hal["LR20xx HAL<br/>[lr20xx_hal.c]"]
  node_lr20xx_bsp["LR20xx calibration"]
  node_sx126x_board["SX126x board<br/>[sx126x_board.c]"]
  node_sx126x_hal["SX126x HAL<br/>[sx126x_hal.c]"]
  node_sx126x_bsp["SX126x BSP<br/>[sx126x_ral_bsp.c]"]
end

subgraph group_platform["Zephyr platform"]
  node_platform_helper["Platform helpers"]
  node_led_service["LED service<br/>[smtc_hal_led.c]"]
  node_custom_log["Custom logging"]
end

node_application(("Zephyr application"))
node_zephyr["Zephyr RTOS"]

node_application -.->|"starts runtime"| node_usp_thread
node_usp_thread -->|"initializes HAL"| node_modem_hal
node_usp_thread -->|"signals ready"| node_initialization
node_usp_thread -->|"runs engine"| node_modem_engine
node_usp_thread -->|"runs engine"| node_rac_engine
node_usp_thread -->|"runs engine"| node_flrp
node_usp_thread -->|"sleeps via"| node_zephyr
node_modem_hal -.->|"radio integration"| node_lr11xx_board
node_modem_hal -.->|"radio integration"| node_lr20xx_board
node_modem_hal -.->|"radio integration"| node_sx126x_board
node_lr11xx_board -.->|"uses HAL"| node_lr11xx_hal
node_lr11xx_board -.->|"uses BSP"| node_lr11xx_bsp
node_lr20xx_board -.->|"uses HAL"| node_lr20xx_hal
node_lr20xx_board -.->|"uses calibration"| node_lr20xx_bsp
node_sx126x_board -.->|"uses HAL"| node_sx126x_hal
node_sx126x_board -.->|"uses BSP"| node_sx126x_bsp
node_platform_helper -.->|"uses services"| node_zephyr
node_led_service -.->|"drives GPIO"| node_zephyr
node_custom_log -.->|"uses logging"| node_zephyr

click node_usp_thread "https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/zephyr_usp_thread.c"
click node_initialization "https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/zephyr_usp_initialization.c"
click node_modem_helper "https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/smtc_modem_helper.c"
click node_modem_hal "https://github.com/lora-net/usp_zephyr/blob/main/modules/smtc_modem_hal/smtc_modem_hal.c"
click node_hal_storage "https://github.com/lora-net/usp_zephyr/blob/main/modules/smtc_modem_hal/smtc_modem_hal_storage.c"
click node_hal_trace "https://github.com/lora-net/usp_zephyr/blob/main/modules/smtc_modem_hal/smtc_modem_hal_dbg_trace.c"
click node_lr11xx_board "https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr11xx/lr11xx_board.c"
click node_lr11xx_hal "https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr11xx/lr11xx_hal.c"
click node_lr11xx_bsp "https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr11xx/lr11xx_ral_bsp_calibration.c"
click node_lr20xx_board "https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr20xx/lr20xx_board.c"
click node_lr20xx_hal "https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr20xx/lr20xx_hal.c"
click node_lr20xx_bsp "https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr20xx/lr20xx_ral_bsp_calibration.c"
click node_sx126x_board "https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/sx126x/sx126x_board.c"
click node_sx126x_hal "https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/sx126x/sx126x_hal.c"
click node_sx126x_bsp "https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/sx126x/sx126x_ral_bsp.c"
click node_platform_helper "https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/smtc_sw_platform_helper.c"
click node_led_service "https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/smtc_hal_led.c"
click node_custom_log "https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/smtc_zephyr_log_custom.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_usp_thread,node_initialization toneBlue
class node_modem_engine,node_rac_engine,node_flrp,node_modem_helper,node_modem_hal,node_hal_storage,node_hal_trace toneAmber
class node_lr11xx_board,node_lr11xx_hal,node_lr11xx_bsp,node_lr20xx_board,node_lr20xx_hal,node_lr20xx_bsp,node_sx126x_board,node_sx126x_hal,node_sx126x_bsp toneMint
class node_platform_helper,node_led_service,node_custom_log toneRose
class node_application,node_zephyr toneIndigo
```

## Components

### USP runtime

- [USP main thread](https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/zephyr_usp_thread.c): `subsys/usp/zephyr_usp_thread.c`
- [Initialization sync](https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/zephyr_usp_initialization.c): `subsys/usp/zephyr_usp_initialization.c`

### Modem services

- **Modem engine**
- **RAC engine**
- **FLRP engine**
- [Modem callbacks](https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/smtc_modem_helper.c): `subsys/usp/smtc_modem_helper.c`
- [Modem HAL](https://github.com/lora-net/usp_zephyr/blob/main/modules/smtc_modem_hal/smtc_modem_hal.c): `modules/smtc_modem_hal/smtc_modem_hal.c`
- [Modem storage](https://github.com/lora-net/usp_zephyr/blob/main/modules/smtc_modem_hal/smtc_modem_hal_storage.c): `modules/smtc_modem_hal/smtc_modem_hal_storage.c`
- [Debug tracing](https://github.com/lora-net/usp_zephyr/blob/main/modules/smtc_modem_hal/smtc_modem_hal_dbg_trace.c): `modules/smtc_modem_hal/smtc_modem_hal_dbg_trace.c`

### Radio hardware

- [LR11xx board](https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr11xx/lr11xx_board.c): `drivers/usp/lr11xx/lr11xx_board.c`
- [LR11xx HAL](https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr11xx/lr11xx_hal.c): `drivers/usp/lr11xx/lr11xx_hal.c`
- [LR11xx calibration](https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr11xx/lr11xx_ral_bsp_calibration.c): `drivers/usp/lr11xx/lr11xx_ral_bsp_calibration.c`
- [LR20xx board](https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr20xx/lr20xx_board.c): `drivers/usp/lr20xx/lr20xx_board.c`
- [LR20xx HAL](https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr20xx/lr20xx_hal.c): `drivers/usp/lr20xx/lr20xx_hal.c`
- [LR20xx calibration](https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/lr20xx/lr20xx_ral_bsp_calibration.c): `drivers/usp/lr20xx/lr20xx_ral_bsp_calibration.c`
- [SX126x board](https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/sx126x/sx126x_board.c): `drivers/usp/sx126x/sx126x_board.c`
- [SX126x HAL](https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/sx126x/sx126x_hal.c): `drivers/usp/sx126x/sx126x_hal.c`
- [SX126x BSP](https://github.com/lora-net/usp_zephyr/blob/main/drivers/usp/sx126x/sx126x_ral_bsp.c): `drivers/usp/sx126x/sx126x_ral_bsp.c`

### Zephyr platform

- [Platform helpers](https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/smtc_sw_platform_helper.c): `subsys/usp/smtc_sw_platform_helper.c`
- [LED service](https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/smtc_hal_led.c): `subsys/usp/smtc_hal_led.c`
- [Custom logging](https://github.com/lora-net/usp_zephyr/blob/main/subsys/usp/smtc_zephyr_log_custom.c): `subsys/usp/smtc_zephyr_log_custom.c`

### Other components

- **Zephyr application**
- **Zephyr RTOS**

## Connections

- Zephyr application → USP main thread: starts runtime (evidence: `README.md`)
- USP main thread → Modem HAL: initializes HAL (evidence: `subsys/usp/zephyr_usp_thread.c`)
- USP main thread → Initialization sync: signals ready (evidence: `subsys/usp/zephyr_usp_thread.c`)
- USP main thread → Modem engine: runs engine (evidence: `subsys/usp/zephyr_usp_thread.c`)
- USP main thread → RAC engine: runs engine (evidence: `subsys/usp/zephyr_usp_thread.c`)
- USP main thread → FLRP engine: runs engine (evidence: `subsys/usp/zephyr_usp_thread.c`)
- USP main thread → Zephyr RTOS: sleeps via (evidence: `subsys/usp/zephyr_usp_thread.c`)
- Modem HAL → LR11xx board: radio integration
- Modem HAL → LR20xx board: radio integration
- Modem HAL → SX126x board: radio integration
- LR11xx board → LR11xx HAL: uses HAL
- LR11xx board → LR11xx calibration: uses BSP
- LR20xx board → LR20xx HAL: uses HAL
- LR20xx board → LR20xx calibration: uses calibration
- SX126x board → SX126x HAL: uses HAL
- SX126x board → SX126x BSP: uses BSP
- Platform helpers → Zephyr RTOS: uses services
- LED service → Zephyr RTOS: drives GPIO
- Custom logging → Zephyr RTOS: uses logging
