Skip to content

Zephyr RTOS integration of Semtech's Unified Software Platform (USP). Includes LoRa Basics Modem. Compatible with LR20xx, SX126x and LR11xx radio devices.

License

Notifications You must be signed in to change notification settings

Lora-net/usp_zephyr

Repository files navigation

USP For Zephyr

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:

Prerequisites

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)

1Validated : 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_uplink sample only with low validation

Setup

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 update

You can check that the module is correctly recognized by Zephyr:

west list usp_zephyr

Notes:

  • 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 application

Edit there your application/west.yml manifest file choosing the revision of ups_zephyr & ups :

Simple dependency description

manifest:
  projects:
    - name: usp_zephyr
      path: usp_zephyr
      url: https://github.com/Lora-net/usp_zephyr.git
      revision: develop
      import: true
  self:
    path: application
    

Advanced dependency description with selected versions

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 update

Work in your source files in application_zephyr_workspace/application

application/my_project
├── boards
├── CMakeLists.txt
├── prj.conf
├── README.rst
└── src

And compile & flash as usual :

west build --board xiao_nrf54l15/nrf54l15/cpuapp --shield semtech_wio_lr2021 application/xxx
west flash
Integration 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: true

Update workspace:

west update

Check that the module is correctly detected by Zephyr:

west list usp_zephyr

Install pyOCD:

pip install pyocd

WARNING DISABLE SYSBUILD

  • At compilation, use the --no-sysbuild parameter :
west build --pristine --board <board> --shield <shield> --no-sysbuild

Build and Run in the Standalone Workspace

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 flash

All 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

Supported Boards & Shields

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/cpuapp
    Xiao ESP32S32 Might work
    (only tested with
    --shield semtech_wio_lr2021)
    --board xiao_esp32s3/esp32s3/procpu
  • Build shield option

    Type Status1 Image Command
    Wio-LR2021 Standalone3 Validated for Xiao nRF54l15 --shield semtech_wio_lr2021
    Wio-LR2021 LoRa Plus Expansion Board3 Validated for Xiao nRF54l15 --shield semtech_loraplus_expansion_board --shield semtech_wio_lr2021

    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 on periodical_uplink sample only with low validation

    2 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_espressif
    

    3 WIO-LR2021 CN version ⚠️ For WIO-LR2021 China (CN) versions the PA table configuration tx-power-cfg-lfdefined in usp_zephyr/boards/shields/semtech_wio_lr20xx/semtech_wio_lr20xx_common.dtsi need to be adjusted as defined in LR2021 Datasheet page 134 to (CN - 490Mhz) band for optimal performances. Look for the 2 470MHz prefilled tables in the semtech_wio_lr20xx_common.dtsi file.

  • 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, pyocd should be included when installing Zephyr requirements, it will be intalled inside the venv. Use pyocd --version to check the installed version. Use pip install pyocd if 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 install 99-xiao-nrf54l15.rules file found in usp_zephyr/boards/seeed/xiao_nrf54l15/support using 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 name

    If 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/stm32l476xx
    Nucleo-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_lr2021 or --shield semtech_mbed_wio_interface --shield semtech_loraplus_expansion_board --shield semtech_wio_lr2021
    LR11xx (multi-option) Buildable --shield semtech_lr1110mb1xxs or
    --shield semtech_lr1120mb1xxs or
    --shield semtech_lr1121mb1xxs
    SX126x 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 on periodical_uplink sample only with low validation

    3 WIO-LR2021 CN version ⚠️ For WIO-LR2021 China (CN) versions the PA table configuration tx-power-cfg-lfdefined in usp_zephyr/boards/shields/semtech_wio_lr20xx/semtech_wio_lr20xx_common.dtsi need to be adjusted as defined in LR2021 Datasheet page 134 to (CN - 490Mhz) band for optimal performances. Look for the 2 470MHz prefilled tables in the semtech_wio_lr20xx_common.dtsi file.

  • 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/nrf52840
    nRF54l15 DK Buildable --board nrf54l15dk/nrf54l15/cpuapp
  • RF shield build option for nRF54l15 DK

    Type Status1 Image Command[2
    Wio-LR2021
    LoRa Plus Expansion Board3
    Buildable --shield semtech_nrf54l15dk_mbed_interface --shield semtech_mbed_wio_interface --shield semtech_wio_lr2021
    LR11xx
    (multi-option)
    Buildable --shield semtech_nrf54l15dk_mbed_interface --shield semtech_lr1110mb1xxs or --shield semtech_nrf54l15dk_mbed_interface --shield semtech_lr1120mb1xxs or --shield semtech_nrf54l15dk_mbed_interface --shield semtech_lr1121mb1xxs
    SX126x 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 Board3
    Buildable --shield semtech_mbed_wio_interface --shield semtech_wio_lr2021
    LR11xx
    (multi-option)
    Buildable --shield semtech_lr1110mb1xxs
    --shield semtech_lr1120mb1xxs
    --shield semtech_lr1121mb1xxs
    SX126x 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 on periodical_uplink sample only with low validation

    2 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 configuration tx-power-cfg-lfdefined in usp_zephyr/boards/shields/semtech_wio_lr20xx/semtech_wio_lr20xx_common.dtsi need to be adjusted as defined in LR2021 Datasheet page 134 to (CN - 490Mhz) band for optimal performances. Look for the 2 470MHz prefilled tables in the semtech_wio_lr20xx_common.dtsi file.

  • Flashing For Nordic DKs, you will need:

    • the Nordic nrfutil tool (alongside with its device module) installed and available in your PATH. Also, please note that nrfjprog tool by Nordic is deprecated and doesn't include support for latest Nordic CPUs such as nRF54 series, so it is recommended to always use nrfutil. Please visit here for a guide on how to install nrfutil and its device module.
    • SEGGER J-Link drivers, available on Segger website. Download and install the driver corresponding to your system.


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.

Guides & Advanced Topics

USP architecture

For an in-depth explanation of system components, interactions, and design principles, refer to USP Architecture.

Samples Documentation

For more details on Samples, refs to samples/usp.

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.

Debugging the samples (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 gdbPath in settings.json to point to zephyr SDK debugger. arm-zephyr-eaby-gdb executable is typically located in the Zephyr SDK folder.
  • You may have to update executable if you changed the location of build directory. Typically, zephyr.elf is generated in a build/zephyr folder.
  • You can comment/uncomment preLaunchTask field if you want to automatically build your project before debugging it.

Build in VS Code

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 logging api 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, gtkterm is recommended as it handles ANSI color formatting used by LBM in its output messages. On Windows, TeraTerm can 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 the CONFIG_LOG_BACKEND_SHOW_COLOR Kconfig 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_RUNTIME or CONFIG_PM_DEVICE_SYSTEM_MANAGED in 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.
  • The serial port opened isn't the board serial port, or the serial port configuration is wrong.
  • The board or the shield isn't properly connected.
  • The BUSY pin is held high by the radio.
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.
  • The programmed region is wrong.
  • The antenna is disconnected or faulty.
  • You are not in range of any LoRa gateway connected to your NS.
  • The entered user credentials are wrong.
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.

About

Zephyr RTOS integration of Semtech's Unified Software Platform (USP). Includes LoRa Basics Modem. Compatible with LR20xx, SX126x and LR11xx radio devices.

Resources

License

Stars

Watchers

Forks

Packages

No packages published