documentation
LoRa Edge Tracker Ref Design - User Guide documentation (v2)
Firmware¶
Two pieces of software are delivered with the LoRa Edge™ Tracker Reference Design:
LoRa Basics™ Modem Firmware + Application code running on the LoRa Edge Tracker Reference Design
LoRa Edge Config (mobile application)
This section describes the LoRa Edge Tracker Reference Design firmware.
The firmware source code can be found in the LoRa GitHub repository:
https://github.com/Lora-net/SWSD004
The repository contains the SDK source code as well as a Keil® project and a GCC makefile. For additional details, see the Software Development Kit.
The SWSD004 SDK contains the following applications, which you can use to explore the capabilities of the LoRa Edge Tracker Reference Design:
Tracker application: Detailed in the rest of this section.
Simple Wi-Fi example: This example illustrates the Wi-Fi scan & send procedure:
configuration of the LoRa Basics Modem library
execution of Wi-Fi scan & send feature using the Wi-Fi geolocation middleware
Geolocation GNSS example application: This example illustrates the GNSS scan & send procedure:
configuration of the LoRa Basics Modem library
execution of GNSS scan & send feature using the GNSS geolocation middleware
Full almanac update example: This example executes a full almanac update using the LR1110 API.
Tracker Application Capabilities¶
The Tracker application is highly configurable.
The following capabilities are embedded in the application:
LoRaWAN connectivity in both the EU868 and US915 regions
Wi-Fi passive scanning
GNSS scanning
Motion detection
BLE connectivity:
Firmware Updates Over-the-Air (FUOTA)
LoRa Edge Tracker Reference Design Tracker Application
LR1110 Firmware
Almanac update
Application configuration
Internal log reading (if activated)
Semtech LoRa Cloud Modem & Geolocation Service:
Differential Almanac update
GNSS position assistance update
Bootloader Mode and Nominal Operation¶
When the Tracker application is launched for the first time, it starts in Bootloader mode. If an application is installed, it takes the following actions:
Depending on the configuration set by the LoRa Edge Config app, the Tracker may connect to a LoRaWAN-compatible network server using the Semtech LoRa Cloud join server’s key derivation algorithm (if selected by the smartphone application).
When motion is detected, the Tracker:
Sends a Wi-Fi scan / NAV message every X seconds or minutes, as defined by the user. The Wi-Fi/GNSS scan strategy is defined as follows:
Perform a GNSS Scan in mobile mode.
If the scan detected enough satellites:
Send the results on LoRaWAN port 194.
If the GNSS scan result is not good enough or not valid, conduct a Wi-Fi scan.
If Wi-Fi scan detected enough access points, send the results on LoRaWAN port 196.
If the scan results are not sufficient/valid:
Send the sensor’s value on LoRaWAN port 193.
Starts a passive Wi-Fi scan / NAV message that is sent one more time, once motion is no longer detected.
Performs and sends a GNSS scan with static mode when in static mode (every X minutes/hours, as defined by the user).
When the Hall Effect sensor detects the presence of a magnet, the Tracker resets itself and enters BLE mode.
BLE Mode¶
Communication in BLE mode includes:
Configuring the parameters of the Tracker
Updating the almanac
Updating the LR1110 firmware
Updating the Tracker application firmware
Reading the internal logs
Tracker Scan Strategy¶
You can change the scan strategy by changing the scan priority parameter. Two scan strategies are available:
GNSS scan priority: The Tracker performs a GNSS scan. If the GNSS scan results are good enough, the Wi-Fi scan is not performed and only the GNSS result is sent.
No scan priority: Both GNSS and Wi-Fi scans are performed, even if the GNSS scan alone is good enough. Both results are sent.
Airplane Mode¶
The Tracker is shipped in Airplane mode. To switch from Airplane mode to the default operating mode, configure the Tracker device accordingly, using the LoRa Edge Config app over a BLE connection.
LED Indicators¶
There is a bi-color LED on the Tracker board:
The yellow color of the LED is called the RX LED and the red color of the LED is the TX LED.
The RX LED blinks when the Tracker is receiving a radio message (downlink).
The TX LED blinks when the Tracker is transmitting a radio message (uplink).
The application uses the LED to display the following events:
Application startup: the TX LED and RX LED blink twice with a period of 100ms ( 50ms Led ON / 50ms Led OFF ).
BLE radio connection mode advertising: the TX LED blink while the tracker in is adverstising mode every 200ms ( 100ms Led ON / 100ms Led OFF ).
BLE radio activity: the TX LED is solid while the tracker is in connected mode.
Join process: the TX LED and RX LED blink on for 25ms in a 3000ms period ( 25ms LED ON / 2975ms LED OFF ) while the tracker is joining.
Hall Effect sensor interrupt: the RX LED is turned on. The RX LED is turned off when the interrupt is acknowledged.
Geolocation and sensor frames sent: the TX LED blinks once ( 100ms LED ON ).
Downlink frame received: the RX LED blinks once ( 100ms LED ON ).
Battery depleted: the TX LED and RX LED blink five times with a period of 500ms ( 250ms LED ON / 250ms LED OFF ).
State Machine¶

Figure 35: Tracker Application Flow
Software Development Kit¶
The Tracker’s software development kit (SDK) contains several layers, as illustrated in Figure 36.

Figure 36: LoRa Edge Tracker Reference Design Firmware SDK Layers
The complete firmware is composed of:
A bootloader that manages application firmware updates over-the-air
An application
The geolocation middleware that belongs to a software layer that simplifies the integration of GNSS and Wi-Fi scan & send operations in a user application.
The firmware (bootloader + application) is programmed into the M4 core of the STM32WB.
Semtech uses the STM32WBXX_HAL, provided by STMicroelectronics. Semtech provides an abstraction, called SMTC_HAL, which aims to be a HAL common to all Semtech firmware.
To get more information about the firmware and middleware please refer to the tracker application description.
Payload Format Specification¶
The payloads use a dedicated port per type of payload.
Type |
Description |
Port |
---|---|---|
NAV Message |
NAV message scanned |
194 |
Data from Wi-Fi scan |
Data from Wi-Fi scan |
196 |
Data from sensors |
Data collected from sensors |
193 |
Tracker date |
Tracker current date |
151 |
Tracker settings |
Complete settings of Tracker |
151 |
The Tracker date and Tracker settings payloads shall be in a “Tag” or “Type” / Length / Value (TLV) format. Commonly used as a data communication protocol, TLV is an encoding scheme used for information elements in a communication protocol.
The Tag and Length are fixed in size (one byte), and the size of the Value field is variable. These fields are used as follows:
Tag: A binary code, often simply alphanumeric, which indicates the kind of field that this part of the message represents
Length: The size of the value field (typically in bytes)
Value: Variable-sized series of bytes which contains data for this part of the message
Tag and Length are a fixed size of one byte. This means that there are 256 Opcodes with a possible length of 256 bytes. This is sufficient to cover all possible commands.
Tag |
Length |
Value |
---|---|---|
0 |
1 |
2 to … value of Length |
Command |
Tag |
Len |
Value |
Comment |
---|---|---|---|---|
NAV Message |
NA |
variable |
NAV |
|
Data from Wi-Fi scan |
NA |
variable |
[MAC (6 bytes)] x nb_detected_ap |
Values > 1 byte are in big endian MAC in big endian |
Data from sensors |
NA |
6 bytes |
[temperature (2 bytes)] [Tracker charge (2 bytes)] [voltage (2 bytes)] |
Values > 1 byte are in big endian |
Tracker date |
0x46 |
4 |
Tracker current date |
Values > 1 byte are in big endian |
Tracker settings |
0x4C |
Variable |
TLV inside with Tracker settings |
Values > 1 byte are in big endian |
Configurable Device Parameters¶
This section describes the Tracker parameters accessible over BLE and LoRaWAN.
The communication is in a TLV format, as is used for the payload. The supported configurable parameters by the LoRa Edge Config application and LoRaWAN are:
Command |
Tag |
Len |
BLE |
LoRaWAN |
Value |
Comment |
---|---|---|---|---|---|---|
|
0x01 |
0 |
X |
X |
Return len 3 (Major/Minor/SubMinor) |
|
|
0x02 |
8 |
X |
X |
MSB First |
|
|
0x03 |
0 |
X |
X |
Return len 8 |
|
|
0x04 |
8 |
X |
X |
MSB First |
|
|
0x05 |
0 |
X |
X |
Return len 8 |
|
|
0x06 |
16 |
X |
X |
MSB First |
|
|
0x07 |
0 |
X |
X |
Return len 16 |
|
|
0x0A |
1 |
X |
X |
0 = GPS only; 1 = BEIDOU only; 2 = GPS & BEIDOU |
|
|
0x0B |
0 |
X |
X |
Return len 1 |
|
|
0x0C |
8 |
X |
X |
Return len 8 4 bytes (0-3) for Latitude; 4 bytes (4-7) for Longitude |
|
|
0x0D |
0 |
X |
X |
||
|
0x24 |
1 |
X |
X |
Return len 1 0 = Disable 1 = Enable |
|
|
0x25 |
0 |
X |
X |
||
|
0x26 |
2 |
X |
X |
Return len 2 10 to 1800 |
|
|
0x27 |
0 |
X |
X |
||
|
0x28 |
2 |
X |
X |
Return len 2 10 to 1440 |
|
|
0x29 |
0 |
X |
X |
||
|
0x2A |
0 |
X |
X |
Return len 0 |
|
|
0x2B |
0 |
X |
X |
Return len 0 |
|
|
0x2C |
12 |
X |
Return len 12 Block ID [2 bytes] almanac fragment [10 bytes] |
||
|
0x2D |
4 |
X |
X |
Return len 4 Date in second |
|
|
0x31 |
146 |
X |
Block ID [2 bytes] modem image fragment [144 bytes] |
||
|
0x32 |
0 |
X |
X |
Return len 4 |
|
|
0x33 |
0 |
X |
X |
Return len 2 |
|
|
0x34 |
0 |
X |
X |
Return len 3 (Major/Minor/SubMinor) |
|
|
0x36 |
0 |
X |
X |
1 = EU868 / 3 = US915 |
|
|
0x37 |
1 |
X |
0 = Disable / 1 = Enable |
||
|
0x38 |
0 |
X |
X |
0 = Disable / 1 = Enable |
|
|
0x39 |
0 |
X |
X |
Return len 4 |
MSB First |
|
0x3A |
1 |
X |
X |
0 = Disable / 1 = Enable |
|
|
0x3B |
0 |
X |
X |
0 = Disable / 1 = Enable |
|
|
0x3C |
1 |
X |
X |
0 = GNSS Priority; 1 = Wi-Fi Priority 2 = No Priority |
|
|
0x3D |
0 |
X |
X |
0 = GNSS Priority; 1 = Wi-Fi Priority 2 = No Priority |
|
|
0x40 |
0 |
X |
X |
Return voltage in mV on 2 bytes |
|
|
0x41 |
1 |
X |
X |
0 = Disable / 1 = Enable |
|
|
0x42 |
0 |
X |
X |
||
|
0x43 |
146 |
X |
See chapter 5.2.8 |
||
|
0x44 |
0 |
X |
X |
Return len 8 |
MSB first |
|
0x49 |
0 |
X |
X |
Remaining space in %, return len 1 bytes |
|
|
0x4A |
0 |
X |
X |
Value in mAh, return len 4 bytes |
MSB first |
|
0x4B |
0 |
X |
X |
||
|
0x4C |
0 |
X |
X |
||
|
0x54 |
0 |
X |
X |
||
|
0x55 |
0 |
X |
X |
||
|
0xFF |
0 |
X |
X |
The Tracker will answer with this opcode when the received command isn’t supported |
Get Tracker Date Over LoRaWAN¶
Command |
Tag |
Len |
---|---|---|
Tracker date |
0x46 |
0 |
The downlink payload (in hex) is: 4600
Change a Setting Over LoRaWAN¶
Command |
Tag |
Len |
Value |
Comment |
---|---|---|---|---|
0 |
1 |
2 n |
||
Tracker settings |
0x4C |
Variable |
[nb_TLV][TLV settings] |
Values > 1 byte are in big endian |
Examples :
Change scan_interval to 15s :
[tag : 4C][len : 05][ [nb_params : 1 ] [tag : 26][len : 02] [value : 000F] ]
The downlink payload (in hex) is the following: 4C05012602000F
Get all settings and HW version :
[tag : 4C][len : 05][ [nb_params : 2 ] [tag : 4C][len : 00] [tag : 01][len : 00] ]
The downlink payload (in hex) is the following: 4C05024C000100
Parse the Internal Log¶
This section describes how to parse each scan read from the internal flash memory of the MCU. To get more information about how to parse the internal log, refer to the tracker_restore_internal_log.
Here is the structure of each logged scan in the flash memory:
0 : 1 |
2 |
3: 4 |
17 : 17+n |
18+n : 22+n |
---|---|---|---|---|
Scan_len |
nb_elem |
Scan_number |
TLVs (GNSS and or Wi-Fi) |
Next_scan_address |
The first scan is always located at the beginning of the user flash_addr_start address. This address is computed during flash initialization, if an internal log context doesn’t exist. Each scan structure contains the flash address of the next scan structure.
The only variable element is the TLV part, which can contain the GNSS and/or Wi-Fi scan results. It is also possible for this element to be empty.
0 |
1 |
2 5 |
6 |
7 |
8 |
9 |
10 : 2+Len |
---|---|---|---|---|---|---|---|
Tag |
Len |
Scan_timestamp (sec) |
token |
number of sattelites |
last scan of the group |
profile |
NAV Messages |
The GNSS_SCAN has two possible tags:
0x01: TAG_GNSS_PCB_ANTENNA
0x02: TAG_GNSS_PATCH_ANTENNA
0 |
1 |
2 5 |
6 : 6+6 |
6+6+1 |
… |
n+7*m : |
6+Len |
||
---|---|---|---|---|---|---|---|---|---|
Tag |
Len |
Scan_timestamp (sec) |
MAC_Address |
RSSI |
… |
MAC_Address |
RSSI |
Whereas MAC_Address is always six bytes, RSSI is always one byte.
The Wi-Fi_SCAN has one possible tag:
0x03: TAG_WIFI_ANTENNA
How to Flash the MCU Core of the STM32WB55 Dedicated to BLE¶
The Tracker has a BLE stack programmed into the M0+ core. However, if for some reason the stack needs to be reprogrammed or updated, here are the steps to follow:
Install STM32CubeProgrammer.
Copy and paste the .bin file(s) into the STM32CubeProgrammer bin folder:
.bin from
https://github.com/Lora-net/SWSD004/apps/demonstrations/tracker_application/middleware/ble/stack_binary
toC:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin
folder.Switch the STM32WB55 to bootloader mode.
Maintain the BOOT0 pin high while the Tracker is resetting.
Connect STM32WB55 USE lines to a computer/laptop.
Open a Command Prompt window.
Navigate to the STM32CubeProgrammer bin folder:
cd C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin
Delete the existing firmware:
STM32_Programmer_CLI.exe -c port=usb1 –fwdelete
Read and upgrade the FUS version:
STM32_Programmer_CLI.exe -c port=usb1 -r32 0x20030030 1

Figure 37: Check FUS Version
Install the stack firmware using the following three commands, depending on the FUS version.
If the FUS version is:
0x20030030: 00050300: FUSv0.5.3, perform commands 1, 2, and 3 (see below).
0x20030030: 01000100 or 01000200: FUSv1.0.x, perform commands 2 and 3.
0x20030030: 01010000: FUSv1.1.0, perform command 3.
Stack firmware commands:
STM32_Programmer_CLI.exe -c port=usb1 –fwupgrade stm32wb5x_FUS_fw_for_fus_0_5_3.bin 0x080EC000 firstinstall=0
STM32_Programmer_CLI.exe -c port=usb1 -fwupgrade stm32wb5x_FUS_fw.bin 0x080EC000 firstinstall=0
STM32_Programmer_CLI.exe -c port=usb1 -fwupgrade stm32wb5x_BLE_Stack_full_fw.bin 0x080CB000 firstinstall=1

Figure 38: Flash BLE Stack Firmware
LoRa Edge Tracker Ref Design - User Guide documentation (v2)
Looking for the previous version? Find it here: