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:

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:
1. 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:
  1. Perform a GNSS Scan in mobile mode.
  2. If the scan detected enough satellites:
    1. Send the results on LoRaWAN port 194.
  3. If the GNSS scan result is not good enough or not valid, conduct a Wi-Fi scan.
    1. If Wi-Fi scan detected enough access points, send the results on LoRaWAN port 196.
  4. If the scan results are not sufficient/valid:
    1. Send the sensor’s value on LoRaWAN port 193.
2. 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¶

Software Development Kit¶

The Tracker’s software development kit (SDK) contains several layers, as illustrated in Figure 36.

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.

Table 4: Interface Command Input Payload Content¶
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.

Table 5: Tracker Payload TLV Format¶
Tag	Length	Value
0	1	2 to … value of Length

Table 6: Interface Payload Format¶
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:

Table 7: Configurable Parameters¶
Command	Tag	Len	BLE	LoRaWAN	Value	Comment
`Read FW version`	0x01	0	X	X	Return len 3 (Major/Minor/SubMinor)
`Set LoRaWAN DevEUI`	0x02	8	X	X		MSB First
`Get LoRaWAN DevEUI`	0x03	0	X	X	Return len 8	MSB First
`Set LoRaWAN JoinEui`	0x04	8	X	X		MSB First
`Get LoRaWAN JoinEui`	0x05	0	X	X	Return len 8	MSB First
`Set LoRaWAN AppKey`	0x06	16	X	X		MSB First
`Get LoRaWAN AppKey`	0x07	0	X	X	Return len 16	MSB First
`Set GNSS Constellation`	0x0A	1	X	X	0 = GPS only; 1 = BEIDOU only; 2 = GPS & BEIDOU
`Get GNSS Constellation`	0x0B	0	X	X	Return len 1
`Set GNSS assistance position`	0x0C	8	X	X	Return len 8 4 bytes (0-3) for Latitude; 4 bytes (4-7) for Longitude
`Get GNSS assistance position`	0x0D	0	X	X
`Set use accelerometer`	0x24	1	X	X	Return len 1 0 = Disable 1 = Enable
`Get use accelerometer`	0x25	0	X	X	Return len 1 0 = Disable 1 = Enable
`Set Scan Interval when Tracker is mobile`	0x26	2	X	X	Return len 2 10 to 1800
`Get Scan Interval when Tracker is mobile`	0x27	0	X	X	Return len 2 10 to 1800
`Set Scan Interval when Tracker is static`	0x28	2	X	X	Return len 2 10 to 1440
`Get Scan Interval when Tracker is static`	0x29	0	X	X	Return len 2 10 to 1440
`Flush Internal log`	0x2A	0	X	X	Return len 0
`Reset board`	0x2B	0	X	X	Return len 0
`Set Almanac update`	0x2C	12	X		Return len 12 Block ID [2 bytes] almanac fragment [10 bytes]
`Get last almanac update date`	0x2D	4	X	X	Return len 4 Date in second
`Fuota Modem start`	0x31	146	X		Block ID [2 bytes] modem image fragment [144 bytes]
`Get hardware version`	0x32	0	X	X	Return len 4
`Get LoRaWAN Stack Version`	0x33	0	X	X	Return len 2
`Get LoRa Basics Modem Version`	0x34	0	X	X	Return len 3 (Major/Minor/SubMinor)
`Get Region`	0x36	0	X	X	1 = EU868 / 3 = US915
`Set Airplane mode`	0x37	1	X		0 = Disable / 1 = Enable
`Get Airplane mode`	0x38	0	X	X	0 = Disable / 1 = Enable
`Get Pin`	0x39	0	X	X	Return len 4	MSB First
`Set usage of Semtech LoRa Cloud Join Server`	0x3A	1	X	X	0 = Disable / 1 = Enable
`Get usage of Semtech LoRa Cloud Join Server`	0x3B	0	X	X	0 = Disable / 1 = Enable
`Set Scan Priority`	0x3C	1	X	X	0 = GNSS Priority; 1 = Wi-Fi Priority 2 = No Priority
`Get Scan Priority`	0x3D	0	X	X	0 = GNSS Priority; 1 = Wi-Fi Priority 2 = No Priority
`Get Board Voltage`	0x40	0	X	X	Return voltage in mV on 2 bytes
`Set Internal Log`	0x41	1	X	X	0 = Disable / 1 = Enable
`Get Internal Log`	0x42	0	X	X
`Read Internal Log`	0x43	146	X		See chapter 5.2.8
`Get Chip EUI`	0x44	0	X	X	Return len 8	MSB first
`Get Internal Log remaining space`	0x49	0	X	X	Remaining space in %, return len 1 bytes
`Get Accumulated Charge`	0x4A	0	X	X	Value in mAh, return len 4 bytes	MSB first
`Reset Accumulated Charge`	0x4B	0	X	X
`Get Tracker settings`	0x4C	0	X	X
`Get Tracker Type`	0x54	0	X	X
`Get LR1110 firmware version`	0x55	0	X	X
`NOT SUPPORTED COMMAND`	0xFF	0	X	X	The Tracker will answer with this opcode when the received command isn’t supported

Get Tracker Date Over LoRaWAN¶

Table 8: Get Tracker Date Command¶
Command	Tag	Len
Tracker date	0x46	0

The downlink payload (in hex) is: 4600

Change a Setting Over LoRaWAN¶

Table 9: Get/Set Tracker Settings¶
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:

Table 10: Internal Log Header¶
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.

Table 11: GNSS Scan¶
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

Table 12: Wi-Fi Scan¶
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 to C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin folder.
Switch the STM32WB55 to bootloader mode.
1. Maintain the BOOT0 pin high while the Tracker is resetting.
2. Connect STM32WB55 USE lines to a computer/laptop.
Open a Command Prompt window.
1. Navigate to the STM32CubeProgrammer bin folder: cd C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin
2. Delete the existing firmware: STM32_Programmer_CLI.exe -c port=usb1 –fwdelete
3. Read and upgrade the FUS version: STM32_Programmer_CLI.exe -c port=usb1 -r32 0x20030030 1

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