Skip to content

USP_Architecture.md

Latest commit

 

History

History
275 lines (222 loc) · 13.8 KB

USP_Architecture.md

File metadata and controls

275 lines (222 loc) · 13.8 KB

Architecture

The objective of the Unified Software Platform (USP) Architecture is to allow

  • the use of multiple protocols supported by the radio,
  • easy integration of new MCU and related boards,
  • easy integration of new Radio and related boards,
  • easy use of the SW in a modern SW development environment.

USP Architecture

The main SW components:

  • Radio Access Controller (RAC)
    • allows a unified access to radios
    • manages the time scheduling of requests from the application, the protocols, and other services,
    • brings with the drivers of the different radios.
  • Protocols
    • provides a database of existing protocols and services compliant with Radio Access Controller: LBM
    • can be extended with other protocols based on provided documentation and SW glue.
  • MCU HAL, Radio HAL& BSP tools to allow porting on multiple HW boards.
  • Sample applications including Multi-Protocol capabilities demonstrators

The first selected SW Platforms is Zephyr RTOS. The USP components are integrated into Zephyr SW Platform as libraries & source code in an external git repository (zephyr module) with the exposition of a set of MCU HAL & Radio HAL & BSP tools being ported externally.

USP Zephyr Architecture

The Main Examples, Protocols, and RAC lib SW components are platform-agnostic and independent from any SW Platform porting (RTOS, baremetal). Porting to a new SW Platform (RTOS, baremetal) primarly involves adapting the MCU HAL & Radio HAL & PCB configuration layers.

Repositories & file structure : Only 2 git repositories are provided by Semtech (black boxes). The two other are Zephyr git dependancy and the user application git repository.

%%{init: {'theme': 'default'}}%%

flowchart LR
    subgraph sgapp[User Application]
        direction LR
        application ~~~ note_app[
            The user  write its application in a dedicated project directory
            The user may want to extend MCU & Radio configuration files for new boards
        ]:::note_user
    end
    subgraph sgsmtczephyr["USP for Zephyr"]
        style sgsmtczephyr stroke:#333,stroke-width:4px
        subgraph Radio Shields
            rac_boards(boards) --> boards_shields(semtech_lr11xxmb1xxs,
                                           semtech_wio_lr20xx,
                                           semtech_sx126xmb2xxs)
            boards_shields ~~~ note_boards[
                Configuration of supported Radio shield boards
                The user should not modify those files
            ]:::note
            rac_boards --> boards_mcu(MCU boards)
        end
        subgraph MCU HAL
            smtc_modem_hal(modules/smtc_modem_hal) ~~~ note_mcu[
                MCU HAL implementation **for Zephyr**
                The user should not modify those files
            ]:::note
        end
        subgraph Samples
            smtc_samples("samples/usp/[lbm|rac|sdk]") ~~~ note_samples[
                Samples **for Zephyr**
                LBM, RAC, SDK
            ]:::note
        end
        subgraph Radio HAL & BSP
            drivers(drivers/usp) --> allboards(lr11xx, lr20xx, sx126x)
            allboards ~~~ note_radioboards[
                Radio HAL & BSP implementation **for Zephyr**
                The user should not modify those files
            ]:::note
        end
        smtc_zephyr[usp_zephyr] --> rac_boards
        smtc_zephyr --> drivers
        smtc_zephyr --> smtc_modem_hal
        smtc_zephyr --> smtc_samples
    end
    subgraph sglibs["USP"]
        style sglibs stroke:#333,stroke-width:4px
        lib(modules/lib/usp) --> rac(rac)
        lib(modules/lib/usp) --> protocols(protocols/lbm_lib)
        lib(modules/lib/usp) --> samples(examples)
        note[
            Location for USP SW Components, Protocols, Samples
            The user should not modify those files
        ]:::note
        protocols ~~~note
    end
    subgraph sgzephyr[Zephyr RTOS]
        zephyr --> boards
        boards ~~~ note_zephyr[
            Location for all default Zephyr files
            The user should not modify those files
        ]:::note
    end


    zephyr_workspace(zephyr_workspace) --> zephyr(zephyr)
    zephyr_workspace --> application
    zephyr_workspace --> smtc_zephyr
    zephyr_workspace --> lib

classDef note fill:#fff5cc,stroke:#d4c690
classDef note_user fill:#ffe4b2, stroke:#e67300, stroke-width:2px;
Loading

Directory Tree Format of the workspace of the user :

zephyr_workspace/
├── zephyr/
│   └── boards/
│       └── (default Zephyr files - do not modify)
├── application/
│   └── (user project - dedicated directory)
├── usp_zephyr/
│   ├── boards/
│   │   ├── semtech_lr11xxmb1xxs/
│   │   ├── semtech_wio_lr20xx/
│   │   ├── semtech_sx126xmb2xxs/
│   │   └── (MCU boards)/
│   ├── drivers/
│   │   └── usp/
│   │       ├── lr11xx/
│   │       ├── lr20xx/
│   │       └── sx126x/
│   └── modules/
│       └── lora_basics_modem/
│           └── smtc_modem_hal/
└── modules/
    └── lib/
        └── usp/
            ├── rac/
            ├── protocols/
            │   └── lbm_lib/
            └── examples/

Organization notes:

- zephyr/ : Default Zephyr RTOS files (do not modify) - **git module automatically fetched from zephyr**
- application/ : User project (modifiable) - **user directory**
- usp_zephyr/ : SW Platform for Zephyr (do not modify) - **SEMTECH main git repository : The only entry point for users**
  ├── boards/ : Configuration of supported radio shield boards
  ├── drivers/ : Radio HAL & BSP implementation for Zephyr
  └── modules/ : MCU HAL implementation for Zephyr
- modules/lib/usp/ : LoRa Multi-Protocol SW Components (do not modify) - **SEMTECH git repository**

Everything is automatically managed using the west.yml manifest.

LoRa Basics Modem

LoRa Basic Modem proposes a full implementation of the TS001-LoRaWAN L2 1.0.4 and Regional Parameters RP2-1.0.3 specifications.

LoRa Basic Modem embeds an implementation of all LoRaWAN packages dedicated to Firmware Update Over The Air (FUOTA):

LoRa Basic Modem embeds an implementation of the Relay LoRaWAN® Specification TS011-1.0.1

  • Relay Tx (relayed end-device)
  • Relay Rx
          +--------------------+       +------------------+
          | Wake On Radio      |       |     LoRaWAN      |
          | protocol + LoRaWAN |       | Class A, B, or C |
          +--------------------+       +------------------+
                    \                        /
                     \                      /
                      \                    /
         Relay Tx      v                  v
      ( End-Device ) <----> (Relay Rx) <----> (Gateway) <----> (Network Server)
              ^                                 ^
               \                               /
                -------------------------------

LoRa Basic Modem embeds an implementation of the LoRaWAN certification process

LoRa Basic Modem offers:

  • Geolocation services in combination with LoRa Edge chips

LoRa Basics Modem library

LoRa Basics Modem library code can be found in folder protocols/lbm_lib . Please refer to README.mdLOCAL ONLINE to get all information related to LoRa Basics Modem library

Radio Access Controller (RAC) API

Dynamic Behaviour, Priorities, ASAP & Scheduled transactions

lorawan vs ranging when ranging is low priority

lorawan vs ranging when ranging is low priority

  1. uplink LoRaWAN : TX
  2. Ranging is started
  3. When collision is expected, one ranging round is canceled to allow LoRaWAN RX1 & RX2
  4. Ranging go on when possible

lorawan vs ranging when ranging is very high priority

lorawan vs ranging when ranging is very high priority

  1. uplink LoRaWAN : TX
  2. Ranging is started
  3. When collision is expected, LoRaWAN RX1 & RX2 are canceled to allow ranging to continue

Multi-protocol management

USP/RAC is managing the time scheduling of Modulation Transactions.

Principles

  • If a scheduled transaction is scheduled but conflicts with another one of higher priority, it is aborted
  • If a scheduled transaction is scheduled but conflicts with another request of lower or equal priority not yet finished, the request is aborted at the scheduled date.
  • If a ASAP transaction conflicts with another transaction, it is postponed. After a while (defined delay), the ASAP transaction is promoted to a scheduled one and fired as soon as a window is found.
  • In other cases, the transactions are scheduled at programmed timestamp in sequence.

In case a transaction is aborted:

  • smtc_usp_submit_radio_transaction() returns SMTC_USP_SUCCESS.
  • callback_pre_radio_transaction() is not triggered
  • callback_post_radio_transaction() is triggered with RP_STATUS_TASK_ABORTED rp_status_t at the timestamp when the selected transaction has successfully completed just after Its successful Handle Event

Normal Case with scheduled or ASAP Modulation Transactions

c1a77dce62744963397db428b3e47caf.png

Case with Modulation Actions of different priorities and time conflicts:

2534e7bf5fad613ab97253c49a8b0c85.png Notes:

  • In Red, the scheduled transaction that failed because of time conflict
  • In case the transaction failed,
    • the callback_pre_radio_transaction() Start Event is not called,
    • the callback_post_radio_transaction() Result Event is called after the successful transaction called its callback_post_radio_transaction() Result Event

Cases with mixed ASAP & scheduled Modulation Actions and time conflicts

ASAP transaction is programmed but cannot be fired before the end of a scheduled transaction of any priority: 737a6a0d9a3ad377a98881a8d3998c8a.png

In case the ASAP transaction is postponed for too long time, after 120 seconds, It is promoted as a scheduled transaction in order to have more change to be fired: 18a5ac8fde1cb6367c50a5dcee8d00ed.png

In case ASAP transaction priority is lower than scheduled priority, It is cancelled: 38796166515420220b0f07926334d83e.png Notes:

  • In Red, the scheduled transaction that failed because of time conflict

In case ASAP transaction priority is higher than scheduled priority, It is postponed during maximum 120 seconds and then promoted as scheduled. The lowest scheduled transaction is then canceled.

low_prio_schedule_canceld_by_high_prio_asap.png

Notes:

  • In Red, the scheduled transaction that failed because of time conflict

Zephyr Integration

The USP implementation provides flexible thread management options to accommodate different application requirements and system architectures. For detailed information about thread management, see Thread Management Documentation.

Quick Threading Overview

The implementation supports multiple threading models:

  • Single Thread Mode (CONFIG_USP_MAIN_THREAD=n): Application directly manages USP/RAC
  • Multi-Thread Mode (CONFIG_USP_MAIN_THREAD=y):
    • Cooperative: Threads with negative priorities, no protection needed
    • Preemptive + Mutexes: Higher priority USP/RAC thread with mutex protection

Each mode offers different trade-offs between simplicity, performance, and real-time responsiveness. The application API remains consistent across all modes through the SMTC_SW_PLATFORM macro abstraction.