The LoRa Basics Modem SDK (SWSD001) will receive no further enhancements and/or bug fixes beyond the latest version 2.1.0. Going forward, examples of how to exercise functionality of the LoRa Basics Modem (SWL2001) are bundled within the LoRa Basics Modem release v4.3.0 (and onward) development repository (http://github.com/lora-net/SWL2001/tree/v4.3.0). The examples included in the SWL2001 repository target application use-cases instead of atomic demonstrations of functionality. The SWL2001 repository now contains multiple reference implementations targeting different MCU and RTOS architectures and as such offers more example code regarding how to port LBM to new platforms.
Support requests for earlier versions should be directed to https://semtech.my.site.com/ldp/ldp_support
The LoRa Basics modem SDK contains several simple examples highlighting LoRa Basic Modem features.
The SDK is made of two different kind of projects:
- Examples, each demonstrating a specific feature of LoRa Basics Modem
- Demonstrations, more elaborated than the examples
Here is the list of the different examples available in the SDK:
| Name | Description | Documentation |
|---|---|---|
| Almanac update | Perform a partial almanac update | README |
| DM information | Configure periodic DM message reports and trigger asynchronous report | README |
| Large file upload | Transfer a file (up to 2048 byte long) to LoRa Cloud | README |
| LoRaWAN | Send data on a periodic basis | README |
| LoRaWAN asynchronous | React on an asynchronous event - a button press here - and send data | README |
| LoRaWAN Class B | Enable Class B after joining a network | README |
| LoRaWAN Multicast - Class B | Enable Class B after joining a network and configure multicast sessions | README |
| LoRaWAN Multicast - Class C | Enable Class C after joining a network and configure multicast sessions | README |
| Stream | Send data as a stream to LoRa Cloud | README |
| Time synchronization | Get time from the network server or from LoRa Cloud | README |
| TX/RX continuous | Generate a TX/RX continuous thanks to the test mode | README |
Here is the list of the different demonstrations available in the SDK:
| Name | Description | Documentation |
|---|---|---|
| Region switching | Switch between two different networks with different switching mechanisms | README |
Each example has its own set of parameters - see apps/<example>/main_<example>.h.
There is also a common configuration file where LoRaWAN parameters can be set:
- DevEUI
- JoinEUI
- AppKey
- Class
- Region
In order to help a LoRa Basics Modem Edge application code conversion to a LoRa Basics Modem application code please refer to ModemE_to_LBM.
LoRa Basics Modem is platform independent and can be used with any MCU that fulfills the requirements.
This SDK is developed on the STMicroeletronics NUCLEO-L476RG development board.
Different Semtech shields can configured at compile time:
Examples can be compiled with either:
The projects are known to compile with GCC arm-none-eabi toolchain v10.3.1.
The LoRa Basics Modem library requires the following firmware:
- LR1110 firmware version 0x0307 (available here)
- LR1120 firmware version 0x0101 (available here)
- LR1121 firmware version 0x0101 (available here)
To update the transceiver with the desired firmware version, please use the updater tool application.
Before starting to build an example, check the parameters in the common configuration file. Make sure that the LoRaWAN configuration is consistent with what is configured in your network server and in your LoRa Cloud account.
Parameters can be seen in the debug output.
Each example is delivered with a several Keil project files, available under MDK-ARM folder for each project:
| Target name | Transceivers | LoRaWAN parameters | Cryptographic operations | Notes |
|---|---|---|---|---|
| lbm_example__LR11xx_LR_cred_crypto.uvprojx | LR1110 / LR1120 / LR1121 | LR11XX-based | LR11xx cryptographic engine | |
| lbm_example__LR11xx_LR_crypto.uvprojx | LR1110 / LR1120 / LR1121 | User-defined | LR11xx cryptographic engine | |
| lbm_example__LR11xx_soft_crypto.uvprojx | LR1110 / LR1120 / LR1121 | User-defined | Software | |
| lbm_example__SX126x_soft_crypto.uvprojx | SX1261 / SX1262 / SX1268 | User-defined | Software | Not available for Almanac update |
Each project has different targets (Keil manual), each one selecting a specific shield.
The procedure to compile a project is then the following:
- Open Keil with the project file corresponding to the the project to use, the transceiver available on the shield and the cryptographic mode to use
- Select the target corresponding to the shield
- Click on compile button
Each example is delivered with a makefile, available under makefile folder. The output files of the build process are stored in the build folder with firmware binary file having the same name as the project with a .bin extension.
It is possible to choose the cryptographic mode with the CRYPTO variable:
| CRYPTO value | Cryptographic operations | LoRaWAN parameters | Comments |
|---|---|---|---|
| SOFT | Software | User-defined | Compatible with all transceivers |
| LR11XX | LR11XX cryptographic engine | User-defined | Compatible with LR1110 / LR1120 / LR1121 transceivers only |
| LR11XX_WITH_CREDENTIALS | LR11XX cryptographic engine | LR11XX-based | Compatible with LR1110 / LR1120 / LR1121 transceivers only |
The default value is LR11XX.
It is possible to choose the shield with the RADIO_BOARD variable. The possible values are listed in the corresponding README file:
The default value is LR1110MB1DIS.
For instance, to build the project lorawan on the LR1120MB1DJS platform board with the software cryptographic mode, call the following commands:
$ cd $SDK_FOLDER/apps/examples/lorawan/makefile
$ make RADIO_BOARD=LR1120MB1DJS CRYPTO=SOFTWhen re-building an example after changing a compile-time parameter that affects LoRa Basics Modem library (like CRYPTO, RADIO_BOARD or MIDDLEWARE), it is important to force re-build of the LoRa Basics Modem library.
This can be achieved by cleaning prior the re-build of the example with:
$ make clean_lbmAdditional configuration flags can be passed from command line to compiler with EXTRAFLAGS argument.
This is dedicated to define macros that can be defined like the following:
$ make EXTRAFLAGS='-D<MACRO>=<VALUE>'Where <MACRO> is the macro name to set and <VALUE> is the value to set for this macro.
Not all macro can be redefined through this way. Refer to the readme of examples for the list of macro that can be defined.
Note that when using the configuration on command line, make cannot detect a change in configuration on next build.
Therefore make clean must be invoked when building after a build where configuration was provided on command line.
The code can produce critical messages being printed on serial port when critical situations occurs. This is typically the case when setting a LoRaWAN region or LoRaWAN class fails.
The default behavior is to print the critical message and keep running.
This behavior can be changed so that the code freezes (until watchdog reset the device).
To do so, the macro ENABLE_CRITICAL_ERROR_DEADLOOP has to be defined, for instance by doing:
$ make EXTRAFLAGS='-DENABLE_CRITICAL_ERROR_DEADLOOP'After a project is built, it can be loaded onto a device.
There are multiple ways to do it:
- Drag and drop the binary file to the USB drive listed by our OS - usually shows up as
NODE_L476RG. - Load it through the Keil IDE
On the NUCLEO-L476RG development board, the firmware prints debug information to the UART that is connected via the ST-LINK to the host computer. The configuration is 921600/8-N-1:
- On Linux, this device usually shows up as
/dev/ttyACM0 - On Windows, the port can be obtained from the device manager
For instance, using stty on Linux:
$ stty -echo raw speed 921600 < /dev/ttyACM0 && cat /dev/ttyACM0
INFO: ###### ===== LoRa Basics Modem LoRaWAN Class A/C demo application ==== ######
INFO: LoRaWAN version: 01.00.04.01
INFO: LoRa Basics Modem version: 02.01.00
INFO: ###### ===== BASICS MODEM RESET EVENT ==== ######
Reset count : 95
INFO: Application parameters:
INFO: - LoRaWAN uplink Fport = 2
INFO: - DM report interval = 60
INFO: - Confirmed uplink = No
INFO: LoRaWAN parameters:
DevEUI - (8 bytes):
00 16 C0 00 00 00 00 00
JoinEUI - (8 bytes):
00 16 C0 01 FF FE 00 01
Class: A
Region: EU868
INFO: ###### ===== JOINED EVENT ==== ######The examples provided in the SDK have been tested under the following configurations:
- shields (not all shields have been used on every regions):
- LR1110MB1DJS
- LR1110MB1GJS
- LR1120MB1DJS
- LR1120MB1GJS
- SX1261MB1BAS
- SX1261MB1CAS
- SX1262MB1CAS
- SX1262MB1DAS
- SX1268MB1GAS
- LoRaWAN Network Server: The Things Network (v3.22.0)
- Application Server: the Node-Red based one provided in
apps/examples/application_server
| Regions | Validation executed | Comment |
|---|---|---|
| SMTC_MODEM_REGION_AS_923_GRP1 | ✅ | |
| SMTC_MODEM_REGION_AS_923_GRP2 | ✅ | |
| SMTC_MODEM_REGION_AS_923_GRP3 | ✅ | |
| SMTC_MODEM_REGION_AU_915 | ✅ | |
| SMTC_MODEM_REGION_CN_470 | ❌ | Validation has not been executed on this region |
| SMTC_MODEM_REGION_CN_470_RP_1_0 | ✅ | |
| SMTC_MODEM_REGION_EU_868 | ✅ | |
| SMTC_MODEM_REGION_IN_865 | ✅ | |
| SMTC_MODEM_REGION_KR_920 | ✅ | |
| SMTC_MODEM_REGION_RU_864 | ✅ | |
| SMTC_MODEM_REGION_US_915 | ✅ | |
| SMTC_MODEM_REGION_WW2G4 | ✅ | Validation has been executed on examples as only LoRaWAN class A is supported for this region: - time_sync - stream - lorawan_asynchronous - almanac_update - dm_info - lorawan ( SMTC_MODEM_CLASS_A) - large_file_upload |
