Unified Software Platform (USP)

USP RELEASE v1.0.0

Overview

USP provides an abstraction layer for scheduling and managing multiple radio access across available modulations (LoRa, FSK, LR-FHSS, FLRC) and protocols (LoRaWAN). The library enables applications to request radio access, configure transmissions/receptions, and schedule operations with priority management.

Current Version is v1.0.0:

• Changelog
• known limitations

Supported Software & Hardware

The USP repository includes LoRa Basics Modem 4.9.0.

The supported Semtech radios are:

• Validated¹ on LoRa Plus EVK(LoRa Plus Expansion Board + Wio-LR2021 radio)²
• buildable¹ on LR11xx shield radios
• buildable¹ on SX126x shield radios

The supported MCU boards are:

• Validated¹ on STMicro NUCLEO-STM32L476RG
• might work¹ on STMicro NUCLEO-STM32L073RZ

Notes

¹ Validated : passed the Semtech nominal validation process, Buildable : can be compiled but did not go through full Semtech validation process and can be considered experimental, might work : was compiled and tested on periodical_pulink sample only with low validation

²WIO-LR2021 CN version ⚠️ For WIO-LR2021 China (CN) versions the PA table configuration shall be adjusted as defined in LR2021 Datasheet page 134 to (CN - 490Mhz) band for optimal performances. Refer to USP Porting Guide for more details.

Software Components

| Component | Description | Documentation | |-----------|-------------|---------------| | USP/RAC Library | Radio Access Component (RAC) API for Semtech transceiver management, including also RAL & Semtec Radio Drivers | View Full API Documentation → | | LoRa Basics Modem | Integrated LoRaWAN stack (v4.9.0) | LBM User Guide → | | Semtec Radio Drivers | Legacy Drivers for supported Semtec Radios | Semtec Radio Drivers | Examples Core | Sample applications demonstrating RAC API usage that can be compiled for baremetal and are also used by USP Zephyr | USP / USP Zephyr Samples Common Guide → |

The architecture is described with more detailed in the USP Zephyr repository

Key Features

• Priority-based scheduling - Manage radio access with configurable priorities
• Multi-modulation support - LoRa, FSK, LR-FHSS, and FLRC modulations
• LoRa capabilities - Full support for transmission, reception, and ranging
• Precise timing - Schedule radio operations with accurate timing control
• Asynchronous operations - Callback support for non-blocking execution
• Seamless integration - Built on Semtech's radio planner

Getting Started

Recommended Development Software

The USP software was tested with:

• gcc 13.3 or higher
• CMake 3.28 or higher
• OpenOCD 0.12 or higher
• Ninja build tool 1.11 or higher

Available Applications

The Samples documentation is available here : USP / USP Zephyr Samples Common Guide →.<br> The following applications are available in the examples/` directory:

Ranging (RTToF)

• rttof_manager: RTToF ranging manager device
• rttof_subordinate: RTToF ranging subordinate device

Communication Examples

• ping_pong: Ping-pong communication example
• periodical_uplink: Periodical uplink transmission example
• multiprotocol: Multiprotocol example (LoRa + Ranging)

Packet Error Rate (PER) Tests

• per_tx: LoRa packet error rate - transmitter
• per_rx: LoRa packet error rate - receiver
• per_fsk_tx: FSK packet error rate - transmitter
• per_fsk_rx: FSK packet error rate - receiver
• per_flrc_tx: FLRC packet error rate - transmitter
• per_flrc_rx: FLRC packet error rate - receiver

Modulation Examples

• lrfhss_tx: LR-FHSS transmission example

Certification & Testing

• lctt_certif: LCTT certification example

Advanced Examples

• spectral_scan: Spectral scan analysis example
• tx_cw: Continuous wave transmission example
• direct_driver_access: Direct radio driver access example (Use RAL or Drivers API instead of USP/RAC API to manage radio, and fine-tune radio sleeping operations)
• geolocation: Manage geolocation of LR1110 & LR1120 radio family
• hw_modem: Drive USP based MCU through UART (only LBM is currently stable)

Build Basics

Compilation is done through the cmake command line.

Targets

In CMakeLists.txt 3 main targets are available :

• example : will compile a example binary based on -DAPP=XXX XXX being the upper case of one of the "Available Applications" above,
• the xxx example name as defined below in "Available Applications" chapter and in CMakeLists.txt (for example per_fsk_tx in the below list),
• all_examples : to compile all "Available Applications" example targets defined in CMakeLists.txt

Have a look on cmake trace to get the list of "Available Applications" targets

-- Available examples:
--   - hw_modem         : Hardware modem
--   - rttof_manager    : ranging (RTToF) manager
--   - rttof_subordinate: ranging (RTToF) subordinate
--   - ping_pong        : ping-pong communication example
--   - per_tx           : packet error rate - LoRa (transmitter)
--   - per_rx           : packet error rate - LoRa (receiver)
--   - per_fsk_tx       : packet error rate - FSK (transmitter)
--   - per_fsk_rx       : packet error rate - FSK (receiver)
--   - per_flrc_tx      : packet error rate - FLRC (transmitter)
--   - per_flrc_rx      : packet error rate - FLRC (receiver)
--   - lrfhss_tx        : LR-FHSS transmission example
--   - spectral_scan    : spectral scan analysis example
--   - periodical_uplink      : Periodical uplink transmission example
--   - multiprotocol          : Multiprotocol example
--   - porting_tests          : Porting_tests example
--   - lctt_certif            : LCTT certification example
--   - geolocation            : geolocation example
--   - tx_cw            : continuous transmission (TX CW) example
--   - direct_driver_access : direct radio driver access example
--   - cad              : CAD (Channel Activity Detection) example

For example to compile periodical_uplink both example & periodical_uplink targets can be used :

rm -Rf build/ ; cmake -L -S examples  -B build -DCMAKE_BUILD_TYPE=MinSizeRel -DBOARD=NUCLEO_L476 -DRAC_RADIO=lr2021 -G Ninja; cmake --build build --target periodical_uplink

or

rm -Rf build/ ; cmake -L -S examples  -B build -DAPP=PERIODICAL_UPLINK -DCMAKE_BUILD_TYPE=MinSizeRel -DBOARD=NUCLEO_L476 -DRAC_RADIO=lr2021 -G Ninja; cmake --build build --target example

To compile all predefined targets with predefined cmake symbols :

rm -Rf build/ ; cmake -L -S examples  -B build -DCMAKE_BUILD_TYPE=MinSizeRel -DBOARD=NUCLEO_L476 -DRAC_RADIO=lr2021 -G Ninja; cmake --build build --target all_examples

One more example with rttof example:

rm -Rf build/ ; cmake -L -S examples  -B build -DCMAKE_BUILD_TYPE=MinSizeRel -DBOARD=NUCLEO_L476 -DRAC_RADIO=lr2021 -DRANGING_DEVICE_MODE=SUBORDINATE -DCONTINUOUS_RANGING=false -G Ninja; cmake --build build --target rttof_subordinate

geolocation & hw_modem are not included in all_examples target. They shall be compiled whatever the example, hw_modem, or geolocation by specifying the -DAPP=xxx cmake symbol in order to force the GEOLOCATION cmake symbols by default :

• geolocation for lr1120:

rm -Rf build/ ; cmake -L -S examples  -B build -DAPP=GEOLOCATION -DCMAKE_BUILD_TYPE=MinSizeRel -DBOARD=NUCLEO_L476 -DRAC_RADIO=lr1120 -G Ninja; cmake --build build --target geolocation

• hw_modem for lr2021 (no geolocation)

rm -Rf build/ ; cmake -L -S examples  -B build -DAPP=HW_MODEM -DCMAKE_BUILD_TYPE=MinSizeRel -DBOARD=NUCLEO_L476 -DRAC_RADIO=lr2021 -DLBM_GEOLOCATION=OFF -G Ninja; cmake --build build --target hw_modem

selected cmake symbols can defer depending on command line, have a look on the following chapter.

cmake compilation symbols & C compilation definitions

Management of compilation symbols

• When cmake symbols are available (often activating compiler definitions), use them directly in cmake configuration command line with -D option (e.g. -DBOARD=NUCLEO_L476) :
  • cmake symbols are described in example documentation,
  • for advanced users, some cmake symbols are defined in cmake sub components like examples/CMakeLists.txt, smtc_rac_lib/CMakeLists.txt, protocols/lbm_lib/CMakeLists.txt, protocols/lbm_lib/options.cmake, protocols/lbm_lib/smtc_modem_core/CMakeLists.txt
• Some important compilation defines are not yet available through cmake symbols. In this case, with care, they can be update in cmake command line by using the CFLAGS & -UCMAKE_C_FLAGS. For example, for LoRa Basics Modem examples, you can use the following command to pass LoRaWAN keys & regions in cmake command lines:

env CFLAGS="-DMODEM_EXAMPLE_REGION=SMTC_MODEM_REGION_WW_2G4 -DUSER_LORAWAN_DEVICE_EUI='{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}' -DUSER_LORAWAN_JOIN_EUI='{0x00,0x00,0x00,0x0