documentation
LoRa Basics™ Modem User Manual v3.4 documentation
LoRa Basics Modem Architecture¶
LoRa Basics™ Modem (LBM) employs a modular design in which microcontroller and transceiver interaction is carried out through the use of abstraction layers (see figure 2.1).
LoRa Basics™ Modem Software Stack¶
This modular design is implemented as a set of components that interact through corresponding interfaces. From a high level perspective, an end-device application that uses LBM is formed by 3 main components:
Hardware Abstraction Layer.
Modem Core.
Application Programming Interface.
Hardware Abstraction Layer¶
In LBM, hardware interaction is done through a Hardware Abstraction Layer. As a result, LBM can be ported to a new platform by implementing the functions defined in the Hardware Abstraction layer. Although LBM is designed to be platform independent, a minimum set of features is required from the Host MCU:
Software MCU reset.
A timer with 1ms resolution.
SPI controller.
A random number generator.
Non-volatile storage for maintaining modem state.
A dedicated (non-shared) GPIO MCU interrupt for the transceiver is recommended.
LBM has only been tested on 32-bit microcontrollers. As described in the next chapter, LBM is highly customizable and, as a result, Flash and RAM requirements will depend on the features included in the application. Worst-case stack usage is currently unknown however, to provide a rough guideline, the LBM Porting Guide lists RAM and Flash requirements for an example STM32L476 implementation.
Communication between LBM and the transceiver is done by means of an SPI bus and two signalling lines:
SPI bus. LBM issues commands to, and reads responses from, the transceiver via the Host MCU SPI bus.
Busy line. This line signals whether the transceiver is busy or ready to receive commands from the modem. It is high while the transceiver is busy and goes low when the transceiver is ready to receive commands.
DIOx line. This line signals to the LBM that the transceiver has asynchronous event data pending.
To maintain platform independence, access to the above hardware peripherals is abstracted by means of an MCU Hardware Abstraction Layer (HAL). This Hardware Abstraction Layer is defined in the header file smtc_modem_hal\smtc_modem_hal.h and in the radio drivers. To port LBM to a given Host MCU, the functions listed in the HAL must be implemented. An example HAL implementation using the STM32L476 MCU as the target controller can be found in the LBM SDK (SWSD001).
Please refer to the LBM Porting Guide for further details.
Modem Core¶
The Modem Core component encapsulates the functionality of the LBM. This section describes some of the modules that constitute the Modem Core.
Modem Services¶
The Modem Services component provides support for LoRa Cloud™ services:
Large File Upload.
Reliable Octet Stream Encoding.
Clock synchronization.
Almanac Update.
Please refer to the LoRa Cloud documentation for further details of the above services.
Device Management¶
When using the LoRa Cloud services, an end device must generate periodic uplinks, which in turn must be submitted to LoRa Cloud by the Application Server. The payload of these end device uplinks must be formatted according to the LoRa Cloud requirements. When necessary, LoRa Cloud will also send downlinks to the device with information requests or with actions that must be performed by the device. Device management uplink formatting and scheduling, as well as device management downlink processing, is carried out by the LBM Device Management component.
Modem Supervisor¶
LBM requires concurrent execution of multiple tasks to respond to user requests and process asynchronous events. The Modem Supervisor schedules task execution (without real-time constraints) and manages the interaction between user requests and internal services.
Modem Crypto¶
LoRa Basics Modem includes a software-implemented Cryptographic Engine.
Radio Abstraction Layer¶
The Radio Abstraction Layer provides a generic interface for transceiver interaction. This interface is implemented in each of the transceiver-specific drivers. As a result, to use a specific transceiver, solution developers simply need to include the driver for the selected transceiver in their code.
Application Programming Interface¶
LBM provides an Application Programming Interface (API) for application development. The files that define the LBM API are located in the smtc_modem_api folder.
Event-Driven Software Interface¶
LBM uses an event-driven scheme to interact with the application. In this scheme, the result of many of the commands is an asynchronous event that must be handled by a callback provided by the application. The use of an event-driven scheme for application interaction allows the development of power-optimized applications.
Test API¶
The LBM API includes a set of test functions which are used to implement test functionality for regulatory conformance, certification, and functional testing. With the exception of the smtc_modem_test_start command, test commands are only available if test mode is active. Test mode can only be activated if the device has not yet joined a network and is not joining a network. Once test mode is active all other modem commands are disabled.
The test functions are defined in the smtc_modem_api\smtc_modem_test_api.h file.
LR11xx Extension¶
LR1110, LR1120 & LR1121 Transceivers are pre-provisioned during production with two identifiers:
A globally unique ChipEUI number that identifies the device.
A SemtechJoinEUI number that is re-used in a set of Semtech devices.
In addition to the above identifiers, LR1110, LR1120 & LR1121 Transceivers are also pre-provisioned with a unique Device Key, DKEY. With these numbers a Device PIN number, which is required to claim the device in the LoRa Cloud Join services, is calculated.
The LR11xx Extension of the LBM provides access to the LR1110, LR1120 & LR1121 provisioning functions. Please refer to the following for further details:
LR1110 Transceiver User Manual.
LR1120 Transceiver User Manual.
LR1121 Transceiver User Manual.
LoRa Cloud Join Server documentation.