USP for Zephyr integrates Semtech’s Unified Software Platform USP into the Zephyr RTOS, which leverage fourth-generation LoRa® technology and providing ready-to-use advanced multi-protocol support.
This out-of-tree Zephyr module supports flexible integration (see Zephyr topologies):
- Standalone - for evaluation, direct use of provided samples (manifest repository),
- Integrated in Custom Applications - importation into applications's manifest (application as manifest),
- Integrated in Downstream Distributions - integration into Zephyr-based distributions (experimental with Nordic Connect SDK, distribution's manifest)
For an in-depth explanation of system components, interactions, and design principles, refer to USP Architecture.
Current Version is v1.0.0:
Install Zephyr 4.2 following : https://docs.zephyrproject.org/latest/develop/getting_started/index.html.
If using a natively-supported MCU Board, you may test it with blinky sample.
Note: Advanced users may install only the dependancy tools & SDK.
Notes regarding SDK & Toolchains :
- The Zephyr SDK contains toolchains for each of Zephyr’s supported architectures (i.e arm, x86, ...). That does include a compiler, assembler, linker and other programs required to build and debug Zephyr applications.
- Only the SDK files of the targeted MCU may be installed
- Zephyr RTOS Version Support:
- Samples are Validated1 with Zephyr RTOS v4.2 & Zephyr SDK v0.17.0.
- Samples are Buildable1 with Zephyr RTOS v3.7.0 LTS & Zephyr SDK v0.16.9. (see Supported Boards & Shields for limitations)
- Follow steps here to install/update the Zephyr SDK on your specific platform. This needs to be done only once.
- Ensure your SDK is compliant with the used version of Zephyr RTOS : https://github.com/zephyrproject-rtos/sdk-ng/wiki/Zephyr-Version-Compatibility
- To use other Toolchains than the one provided by default with the Zephyr SDK, please refer to https://docs.zephyrproject.org/latest/develop/toolchains/index.html (Please be aware that the current delivery was not validated with other toolchains than the one from the default Zephyr SDK)
1
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 onperiodical_uplinksample only with low validation
Standalone Workspace (Simplest for Evaluation)
Install USP Zephyr in a different directory than your default upstream zephyr installation:
# Create and initialize workspace
mkdir zephyr_workspace
cd zephyr_workspace
git clone https://github.com/Lora-net/usp_zephyr.git
west init -l usp_zephyr
west updateYou can check that the module is correctly recognized by Zephyr:
west list usp_zephyrNotes:
- USP Zephyr is used as the manifest repository.
- The Zephyr installation & USP Zephyr Setup was tested for both Linux & Windows Development OS.
Integration in Custom application
Example of Integration in a Custom Application with T2 Star topology (could be extended to T3):
mkdir application_zephyr_workspace & cd application_zephyr_workspace
mkdir application # or git clone https://xxxxx applicationEdit there your application/west.yml manifest file choosing the revision of ups_zephyr & ups :
manifest:
projects:
- name: usp_zephyr
path: usp_zephyr
url: https://github.com/Lora-net/usp_zephyr.git
revision: develop
import: true
self:
path: application
manifest:
projects:
- name: zephyr
url: https://github.com/zephyrproject-rtos/zephyr
revision: v4.2.0
import: true
- name: usp_zephyr
path: usp_zephyr
url: https://github.com/Lora-net/usp_zephyr.git
revision: v1.0.0
- name: usp
path: modules/lib/usp
url: https://github.com/Lora-net/usp.git
revision: v1.0.0
submodules: true
self:
path: application
and do :
west init -l application
west updateWork in your source files in application_zephyr_workspace/application
application/my_project
├── boards
├── CMakeLists.txt
├── prj.conf
├── README.rst
└── srcAnd compile & flash as usual :
west build --board xiao_nrf54l15/nrf54l15/cpuapp --shield semtech_wio_lr2021 application/xxx
west flashIntegration in NCS workspace (experimental)
WARNING : This integration is experimental as the official validated integration is for Zephyr RTOS v4.2
Can be used for T2/T3 topology.
Edit nrf/west.yml (or your manifest):
manifest:
projects:
- name: usp_zephyr
path: modules/usp_zephyr
url: https://github.com/Lora-net/usp_zephyr.git
revision: feature/usp_zephyr
import: trueUpdate workspace:
west updateCheck that the module is correctly detected by Zephyr:
west list usp_zephyrInstall pyOCD:
pip install pyocdWARNING DISABLE SYSBUILD
- At compilation, use the
--no-sysbuildparameter :
west build --pristine --board <board> --shield <shield> --no-sysbuild
Using the Semtech LoRa Plus Xiao EVK (Xiao-nRF54L15 + LR2021-Wio) on periodical_uplink sample :
cd zephyr_workspace
west build --pristine --board xiao_nrf54l15/nrf54l15/cpuapp --shield semtech_wio_lr2021 usp_zephyr/samples/usp/lbm/periodical_uplink
west flashAll samples are located in samples/usp directory, you can use any supported board/shield as define in next section to build and flash other samples :
west build --pristine --board <board> --shield <shield>For more details on Samples, refer to Samples Documentation
Seed Studio [XIAO nRF54L15] and [XIAO ESP32S3]
-
Supported Zephyr: Validated1 on 4.2
-
Build board option
Type Status1 Image Command Xiao nRF54l15 Validated 
--board xiao_nrf54l15/nrf54l15/cpuappXiao ESP32S32 Might work
(only tested with
--shield semtech_wio_lr2021)
--board xiao_esp32s3/esp32s3/procpu -
Build shield option
1
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 onperiodical_uplinksample only with low validation2 XIAO ESP32 Binary Blobs Espressif HAL requires RF binary blobs in order work. Run the command below to retrieve those files before west build.
west blobs fetch hal_espressif3 WIO-LR2021 CN version
⚠️ For WIO-LR2021 China (CN) versions the PA table configurationtx-power-cfg-lfdefined inusp_zephyr/boards/shields/semtech_wio_lr20xx/semtech_wio_lr20xx_common.dtsineed to be adjusted as defined in LR2021 Datasheet page 134 to (CN - 490Mhz) band for optimal performances. Look for the 2470MHzprefilled tables in thesemtech_wio_lr20xx_common.dtsifile. -
Flashing
The Xiao-nRF54 doesn't embeds a J-Link interface, it is instead interfaced with a CMSIS-DAP interface. We recommend using
pyocd, version >= 0.38.0 for both flashing and debugging. By default,pyocdshould be included when installing Zephyr requirements, it will be intalled inside the venv. Usepyocd --versionto check the installed version. Usepip install pyocdif it is not already installed. On Debian-based systems, you may need to install additional udev rules to be able to connect to the board. You might want to follow the instructions here to install PyOCD known USB devices. Additionaly, you will have to manually install99-xiao-nrf54l15.rulesfile found inusp_zephyr/boards/seeed/xiao_nrf54l15/supportusing the same procedure.In case you want to flash with native pyocd command, you can run:
pyocd flash -t nrf54l ./build_xiao/zephyr/zephyr.hex # Replace build_xiao with your build folder nameIf you encounter an error saying the the board is locked, run
pyocd erase -c --target nrf54l
STMicro [NUCLEO-L476RG] and [NUCLEO-U575ZI-Q]
-
Supported Zephyr: Validated1 on 4.2 (buildable1 on v3.7.0 LTS)
-
MCU board build option
Type Status1 Image Command Nucleo-L476RG Validated 
--board nucleo_l476rg/stm32l476xxNucleo-U575ZI-Q Buildable 
--board nucleo_u575zi_q/stm32u575xx -
RF shield build option
Type Status1 Image Command Wio-LR2021 LoRa Plus Expansion Board3 Validated for Nucleo-L476RG 
--shield semtech_mbed_wio_interface --shield semtech_wio_lr2021or--shield semtech_mbed_wio_interface --shield semtech_loraplus_expansion_board --shield semtech_wio_lr2021LR11xx (multi-option) Buildable 
--shield semtech_lr1110mb1xxsor
--shield semtech_lr1120mb1xxsor--shield semtech_lr1121mb1xxsSX126x Buildabled 
e.g. --shield semtech_sx1261mb2bas(cf. boards/shields/semtech_sx126xmb2xxs)1
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 onperiodical_uplinksample only with low validation3 WIO-LR2021 CN version
⚠️ For WIO-LR2021 China (CN) versions the PA table configurationtx-power-cfg-lfdefined inusp_zephyr/boards/shields/semtech_wio_lr20xx/semtech_wio_lr20xx_common.dtsineed to be adjusted as defined in LR2021 Datasheet page 134 to (CN - 490Mhz) band for optimal performances. Look for the 2470MHzprefilled tables in thesemtech_wio_lr20xx_common.dtsifile. -
Flashing
STM32 chips use ST-Link as interface, and are programmed using STM32CubeProgrammer tool. You might want to download and install STM32CubeProg from ST website. Then, Zephyr should be able to locate the installation folder and use the tool.
Nordic [nRF54L15 DK] and [nRF52840 DK]
-
Supported Zephyr:
- nRF52840 DK: Buildable3 on 4.2 & v3.7.0 LTS)
- nRF54l15 DK: Buildable3 on 4.2
-
MCU board build option
Type Status1 Image Command nRF52840 DK Buildable 
--board nrf52840dk/nrf52840nRF54l15 DK Buildable 
--board nrf54l15dk/nrf54l15/cpuapp -
RF shield build option for nRF54l15 DK
Type Status1 Image Command[2 Wio-LR2021
LoRa Plus Expansion Board3Buildable 
--shield semtech_nrf54l15dk_mbed_interface --shield semtech_mbed_wio_interface --shield semtech_wio_lr2021LR11xx
(multi-option)Buildable 
--shield semtech_nrf54l15dk_mbed_interface --shield semtech_lr1110mb1xxsor--shield semtech_nrf54l15dk_mbed_interface --shield semtech_lr1120mb1xxsor--shield semtech_nrf54l15dk_mbed_interface --shield semtech_lr1121mb1xxsSX126x Buildable 
e.g. --shield semtech_nrf54l15dk_mbed_interface --shield semtech_sx1261mb2bas(cf. boards/shields/semtech_sx126xmb2xxs)
-
RF shield build option for nRF52840 DK
Type Status1 Image Command2 Wio-LR2021
LoRa Plus Expansion Board3Buildable 
--shield semtech_mbed_wio_interface --shield semtech_wio_lr2021LR11xx
(multi-option)Buildable 
--shield semtech_lr1110mb1xxs--shield semtech_lr1120mb1xxs--shield semtech_lr1121mb1xxsSX126x Buildable 
e.g. --shield semtech_sx1261mb2bas(cf. boards/shields/semtech_sx126xmb2xxs)
1
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 onperiodical_uplinksample only with low validation2 nRF54L15 DK interface
⚠️ The nRF54L15-DK does not provide an Arduino-compatible header like the other Nordic DK boards. Because of this, a separate interface/adapter board is required to connect Semtech shields. The --shield semtech_mbed_wio_interface option must be added so that the correct pin mapping is applied when building the project. The mandatory pins are:nRF54L15-DK Pin Arduino connector Pin LRXXxx shield pin function P0.00 A0 LR_NRESET P1.06 D7 NSS P1.11 D3 BUSY P1.12 D5 DIO9 P2.06 D13 SPI_SCK P2.08 D11 SPI_MOSI P2.09 D12 SPI_MISO The mandatory pin for geoloc example on shield embedding a LNA is:
nRF54L15-DK Pin Arduino connector Pin LRXXxx shield pin function P1.13 A3 LNA_CTRL_MCU Other pins:
nRF54L15-DK Pin Arduino connector Pin LRXXxx shield pin function P0.01 A5 LED_RX P0.02 A4 LED_TX P0.03 D14 I2C_SDA P0.04 D15 I2C_SCL 3 WIO-LR2021 CN version
⚠️ For WIO-LR2021 China (CN) versions the PA table configurationtx-power-cfg-lfdefined inusp_zephyr/boards/shields/semtech_wio_lr20xx/semtech_wio_lr20xx_common.dtsineed to be adjusted as defined in LR2021 Datasheet page 134 to (CN - 490Mhz) band for optimal performances. Look for the 2470MHzprefilled tables in thesemtech_wio_lr20xx_common.dtsifile. -
Flashing For Nordic DKs, you will need:
- the Nordic
nrfutiltool (alongside with itsdevicemodule) installed and available in your PATH. Also, please note thatnrfjprogtool by Nordic is deprecated and doesn't include support for latest Nordic CPUs such as nRF54 series, so it is recommended to always usenrfutil. Please visit here for a guide on how to installnrfutiland itsdevicemodule. - SEGGER J-Link drivers, available on Segger website. Download and install the driver corresponding to your system.
- the Nordic
Thanks to the Zephyr ecosystem, the USP module can be ported to almost any MCU platform, enabling deployment across 850+ supported hardware targets, please follow the USP porting guide for more information.
USP architecture
For an in-depth explanation of system components, interactions, and design principles, refer to USP Architecture.
USP Integration in VS Code
Files provided to support VS Code integration are :
usp_zephyr_workspace.code-workspace- Build & flash :
.vscode/tasks.json(to be update to local user host configuration) - Debug :
.vscode/launch.json(to be update to local user host configuration)
Open the VS Code Workspace file (File->Open Workspace from file) : usp_zephyr/usp_zephyr_workspace.code-workspace to load USP integration in VS Code.
The configuration is for both Windows & Linux. Python virtual environment location and zephyr sdk path can be set in settings.json
CTRL-SHIFT-P will allow you to run tasks :
- West Build
- West Interactive Build
- West Flash
F5 will allow you to run & debug.
Default configuration is for
- Radios
- LoRa Plus dev kit + xiao nRF54l15,
- Wio LR2021,
- with Cortex-Debug extension from marus25.
For other MCU and radio boards, modify tasks.json & launch.json.
This section presents how to debug the sample from within VSCode environment using Cortex-Debug extension. As the name implies, this extension is designed for debugging Cortex-based MCUs.
We will use as example the nRF52840-DK Development Kit board embedding the nRF52840 MCU.
This section shows the configuration for debugging with zephyr SDK GDB tool using
- Xiao nRF54 with pyOCD
- STM32L476RG with openocd
- nRF52840 DK with JLink
- nRF54l15 DK with JLink
The installation steps of openocd, jlink is not covered by this documentation. Please refer to those tools installation guide.
Edit the launch.json configuration file:
- Change the
gdbPathin settings.json to point to zephyr SDK debugger.arm-zephyr-eaby-gdbexecutable is typically located in the Zephyr SDK folder. - You may have to update
executableif you changed the location of build directory. Typically, zephyr.elf is generated in abuild/zephyrfolder. - You can comment/uncomment
preLaunchTaskfield if you want to automatically build your project before debugging it.
The first solution is to open a Terminal and use the compilation command lines described above.
Alternately, you may tune the provided tasks.json file to
- your west environment
- your MCU & radio boards
- your application : path & compilation flags
Below is an excerpt from the tasks.json file for the "West Build" task :
{
"version": "2.0.0",
"tasks": [
{
"label": "West Build",
"type": "shell",
"group": {
"kind": "build",
"isDefault": true
},
"options": {
"cwd": "${workspaceFolder:Zephyr Workspace}",
},
"linux": {
"command": "${workspaceFolder:Zephyr Workspace}/../zephyrproject/.venv/bin/west",
"args": [
"build",
"--pristine",
"auto",
"--board",
"xiao_nrf54l15/nrf54l15/cpuapp",
"--shield",
"semtech_wio_lr2021",
"${workspaceFolder:LoRa MultiProtocol SW Platform for Zephyr}/samples/usp/sdk/ranging_demo",
"--",
"-DCMAKE_EXPORT_COMPILE_COMMANDS=ON", "-DEXTRA_CFLAGS=\"-DRANGING_DEVICE_MODE=RANGING_DEVICE_MODE_SUBORDINATE\"",
],
},
"windows": {
"command": "${workspaceFolder:Zephyr Workspace}\\..\\zephyrproject\\.venv\\Scripts\\west.exe",
"args": [
"build",
"--pristine",
"auto",
"--board",
"xiao_nrf54l15/nrf54l15/cpuapp",
"--shield",
"semtech_wio_lr2021",
"${workspaceFolder:LoRa MultiProtocol SW Platform for Zephyr}\\samples\\usp\\sdk\\ranging_demo",
"--",
"-DCMAKE_EXPORT_COMPILE_COMMANDS=ON", "-DEXTRA_CFLAGS=\"-DRANGING_DEVICE_MODE=RANGING_DEVICE_MODE_SUBORDINATE\"",
],
},
"osx": {
"command": "${workspaceFolder:Zephyr Workspace}/../zephyrproject/.venv/bin/west",
"args": [
"build",
"--pristine",
"auto",
"--board",
"xiao_nrf54l15/nrf54l15/cpuapp",
"--shield",
"semtech_wio_lr2021",
"${workspaceFolder:LoRa MultiProtocol SW Platform for Zephyr}/samples/usp/sdk/ranging_demo",
"--",
"-DCMAKE_EXPORT_COMPILE_COMMANDS=ON", "-DEXTRA_CFLAGS=\"-DRANGING_DEVICE_MODE=RANGING_DEVICE_MODE_SUBORDINATE\"",
],
},
"problemMatcher": []
},
The user has to update
- the installation path of west in settings.json
${workspaceFolder:LoRa MultiProtocol SW Platform for Zephyr}/samples/usp/sdk/ranging_demowith the application path ,-DEXTRA_CFLAGS=\"-DRANGING_DEVICE_MODE=RANGING_DEVICE_MODE_SUBORDINATE\"with the compilation flags
The user may want to update
- the default MCU board
xiao_nrf54l15/nrf54l15/cpuapp - the default radio board
semtech_wio_lr2021
Logging & Debugging
-
Output Messages
The samples uses Zephyr's
loggingapi to oputput logging messages. Then, depending on the board, these messages are sent to the user, typically via a UART link. On all boards officialy supported by Semtech, the logs are sent simply via UART to a debugger IC present on the board, that exposes (at least) one CDC interface (Virtual Serial/COM Port) on its USB interface. Some boards may expose more than one port to the host computer, and only one will be used. Any serial terminal software can be used to read data. On Unix systems,gtktermis recommended as it handles ANSI color formatting used by LBM in its output messages. On Windows,TeraTermcan be used.
Default config is 115200 baud, 8 data bits, 1 stop bit, no parity, no flow control.
The ANSI color formatting can be disabled in the sample prj.conf via theCONFIG_LOG_BACKEND_SHOW_COLORKconfig option. -
Debugging
LoRa Plus© EVK
The nRF54L15
- supports up to 4 hardware breakpoints.
- uses the Serial Wire Debug (SWD) interface for debugging and programming.
The XIAO nRF54L15
- contains a SAMD11 with CMSIS-DAP interface, allowing flashing (even drag'n'drop), debugging, logging, over the USB port.
- is compatible with usual debugging tools, such as J-Link from SEGGER, OpenOCD, pyOCD.
The LoRa Plus© EVK
- exposes a SWD Programming Interface (through pogo pins underneasth the XIAO nRF54L15) for usual debugging & advanced debugging like RTT / SWO, update of CMSIS-DAP,
- allow to use compatible advanced SWD debugging probes.
- depending on your EVK, the XIAO wiring to the SWD connector may not be available.
Porting USP to a new MCU board or RF shield
This chapter explains how to port USP Zephyr module
- on other MCU
- on other RF radio PCB (Shield)
Porting Legacy LoRa Basics Modem (LBM) to USP
- This chapter explains how to port existing LoRa Basics Modem application to USP Zephyr.
Power Consumption
Zephyr RTOS implements a way of handling the power states of the used devices (called "Power Management" (PM) actions). Basically, it offers a simple way for the RTOS to "tell" connected devices to enter sleep mode when Zephyr does so. However, as it's done without any driver intervention, the timing when the devices enter/exit sleep mode can't be precisely controlled, leading to a possible increase of power consumption.
As so, Semtech radio drivers don't use Zephyr system for handling sleep mode, and are entered sleep as soon as possible to optimize power consumption.
It is important to note that the Zephyr PM actions are correctly handled by the internal MCU peripherals, allowing the samples to reach the following current consumption values when in sleep:
| Board | Current (uA) |
|---|---|
| Xiao-nRF54L15 | ~301 |
| nRF52840-DK | ~505/~252 |
| nRF54L15-DK | ~18.13 |
| NUCLEO-L476RG | ~5 |
To reach low power, use prj_lowpower.conf when building, disabling logs:
west build --pristine --board xiao_nrf54l15/nrf54l15/cpuapp --shield semtech_wio_lr2021 usp_zephyr/samples/usp/lbm/periodical_uplink -- -DCONF_FILE="prj_lowpower.conf"Notes :
- Be aware of differencies when using
CONFIG_PM_DEVICE_RUNTIMEorCONFIG_PM_DEVICE_SYSTEM_MANAGEDin your prj.conf file.
1 It is impossible to measure only the 3.3V used to power the nRF54L15 on the Xiao-nRF54L15 board, as Seeed didn’t provide for that in the design. Instead, we have to measure the whole current supplied to the board via the VBAT pads. This does include the LR2021 IC, the DC/DC buck converter and a few more active components. For the measurement, the VBAT voltage was 3.7V (Li-Ion nominal voltage).
2 Measured @VDD = 3V. Due du a documented nRF52840 anomaly, this chip draws more current when SPI3 is used, and SPI3 is the default one routed on the board’s Arduino header. Using SPI0 instead of SPI3 will lead to ~25uA.
3 Measured @VDD = 3.3V. The nRF54L15 can go down to ~3µA, but as we have to use SPI0 peripheral as cross power-domain, it draws a few more µA.
Troubleshooting
This section presents frequentely-encountered errors and how to fix them.
| Description | Cause | Workaround |
|---|---|---|
| Nothing outputs to the serial console when plugged. |
|
Open another serial port or change serial port configuration. Check if board/shield is properly plugged and in the right orientation. Try another radio shield. |
| I can't see LoRa messages on my NS console. |
|
Check if the programmed region corresponds to your geographic location. Check the antenna connection. Check if you have a gateway in range, or host a gateway. Check the user credentials (devEUI, joinEUI, appKey). |
When using RAC or LBM API, you can encounter "Modem Panic Messages". This documentation is available for more details on how to deal with those issues.
