Firmware¶

Two pieces of software are delivered with LoRa Edge^™ Tracker Reference Design:

LoRa Edge Tracker Reference Design Firmware
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/lora_edge_tracker_ref_design

The repository contains the SDK source code as well as a Keil^® project and a GCC makefile.

The LoRa Edge Tracker Reference Design SDK contains the following applications, which you can use to illustrate the capabilities of the LoRa Edge Tracker Reference Design:

Tracker application: Detailed in the rest of this section.
Simple LoRaWAN^® Class A/C application 868/915MHz: This application automatically joins the LoRa Network server then sends uplinks periodically with a defined interval.
Simple Wi-Fi example: The modem executes a Wi-Fi scan periodically according to the Wi-Fi settings defined in the application.
Simple GNSS example: The user is asked to supply the UNIX date in ASCII through a terminal. When the modem receives the date, it executes a GNSS scan periodically according to the GNSS settings defined in the application.
Simple Tx Continuous app: The modem starts to send a continuous wave.
Simple BLE Standalone app: The tracker starts and stays in BLE mode.
Simple Low Power: Puts the tracker in the lowest-possible power mode.
Simple LoRaWAN Clock Synchronization Example: This application automatically joins the LoRaWAN network server. The LR1110 clock is then synchronized with the Application Layer Clock Synchronization service (ALC Sync).
UART-based Firmware Update application example: This application updates the LR1110 firmware, which is received from the UART.

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 with configurable parameters
GNSS scanning with configurable parameters
Motion detection
BLE connectivity:
- Firmware Updates Over-the-Air (FUOTA)
  - LoRa Edge Tracker Reference Design Tracker Application
  - LoRa Basics™ Modem-E
- Almanac update
- Application configuration
- Internal log reading (if activated)
Semtech LoRa Cloud Device & Application Services:
- Differential Almanac update
- GNSS position assistance update
- Streaming

Bootloader Mode¶

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 LoRa Edge Tracker Reference Design 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 LoRa Edge Tracker Reference Design:
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. Scan GNSS on the first antenna. By default this is the PCB antenna when both antennas are selected.
  2. If ( (number of detected satellites >=4) && (2nd antenna is activated) )
    1. Scan GNSS on the second antenna. The second scan is performed if both antennas are activated and the first scan returned results.
    2. Determine whether NAV messages are valid and which one is the best.
  3. If the GNSS scan is result not good enough or not valid, conduct a Wi-Fi scan.
  4. If the scan results are sufficient/valid:
    1. Send the GNSS results if one NAV is valid.
    2. If the GNSS results are not good enough or are not valid, the Wi-Fi results are sent, but only if the Wi-Fi result contains at least two access points. If no scans (Wi-Fi or GNSS) are good enough, send only the sensor value.
2. Starts a passive Wi-Fi scan / NAV message that is sent one more time, once motion is no longer detected.
Switches to BLE mode when the Hall Effect sensor detects the presence of a magnet.
Sends a “keep alive” frame when in static mode (every X minutes/hours, as defined by the user).

BLE Mode¶

Communication in BLE mode includes:

Configuring the parameters of the tracker device.
Updating the almanac.
Updating the LoRa Basics™ Modem-E firmware.
Updating the tracker application firmware.
Reading the internal logs.
Running an automatic diagnosis of the Tracker/System.

Tracker Scan Strategy¶

You can change the scan strategy by changing the scan priority parameter. Three scan strategies are available:

GNSS scan priority

Wi-Fi scan priority

No priority

GNSS Scan Priority¶

If this strategy is selected, the tracker will start with a GNSS scan, if the GNSS scan results are good enough, the Wi-Fi scan will be not performed and only the GNSS result will be sent.

If both GNSS antennas are activated (PCB and PATCH), both NAV messages will be analyzed and only the best one will be sent.

Wi-Fi Scan Priority¶

If this strategy is selected, the tracker will start with a Wi-Fi scan. If the Wi-Fi scan results are good enough (that is, if at least two access points are scanned), the GNSS scan will not be performed and only the Wi-Fi result will be sent.

No Scan Priority¶

If this strategy is selected, the tracker will perform the GNSS scan and the Wi-Fi scan. The best results will be sent.

Sensors¶

The TLV sensor that is sent differs, depending on whether or not the scan results are good enough.

If the GNSS or Wi-Fi scan is good enough:

Basic TLV sensor is sent. For more information, see `Payload Format Specification.html#Payload Format Specification`_.

If the GNSS or Wi-Fi scan isn’t good enough:

Complete TLV sensor is sent. For more information, see `Payload Format Specification.html#Payload Format Specification`_.

Shipping 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 two-color LED on the LoRa Edge Tracker Reference Design board:
- The LED turns yellow when the tracker is receiving a radio message (downlink).
- The LED turns red when the tracker is transmitting a radio message (uplink).
- The yellow component is called the RX LED and the red component is the TX LED.
The application uses the LED of the Lora Edge Tracker Reference Design to display the following events:
- Application startup: the LEDs blink twice within a 100 ms period.
- Battery depleted: the LEDs blink five times within a 500 ms period.
- Clock synchronized: the RX LED blinks four times within a 100 ms period.
- Clock unsynchronized: the TX LED blinks four times within a 100 ms period.
- BLE radio activity: the TX LED blinks continuously.
- Hall Effect sensor interrupt: the RX LED is turned on. The LED is turned off when the interrupt is acknowledged.
- Uplink frame sent: the TX LED flashes once.
- Downlink frame received: the RX LED flashes once.

State Machine¶

/uploads/lora_edge_tracker/TrackerAppFlow.png

Figure 40: Tracker Application Flow

Software Development Kit¶

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

/uploads/lora_edge_tracker/SDKLayers.png

Figure 41: LoRa Edge Tracker Reference Design Firmware SDK Layers

The complete firmware is composed of:

An application
A bootloader that manages application firmware updates over-the-air

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.

This SMTC_HAL contains the following files:

smtc_hal_adc.c
smtc_hal_gpio.c
smtc_hal_flash.c
smtc_hal_mcu.c
smtc_hal_rng.c
smtc_hal_rtc.
smtc_hal_spi.c
smtc_hal_i2c.c
smtc_hal_tmr.c
smtc_hal_tmr_list.c
smtc_bsp_uart.c
smtc_bsp_watchdog.c

The LoRa Basics Modem-E driver layer is an implementation of the drivers for the LR1110 modem in the C programming language. This layer handles Wi-Fi and GNSS scans over LoRaWAN. It does not involve any state machine or high-level API.

The GNSS, Wi-Fi, and BLE thread layers provide high-level APIs that easily run a state machine for the following tasks:

GNSS scanning, with given parameters.
Wi-Fi scanning, with given parameters.
BLE connections between the tracker and the mobile device running LoRa Edge Config.

Payload Format Specification¶

The payload 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 3: Tracker Payload TLV Format¶
Tag	Length	Value
0	1	2 to … value of Length

Table 4: Interface Command Input Payload Content¶
Tag	Description	Notes
NAV from PCB antenna	NAV message scanned on GNSS PCB antenna
NAV from Patch antenna	NAV message scanned on GNSS Patch antenna
Data from Wi-Fi scan	Data from Wi-Fi scan
Data from sensors	Data collected from accelerometer
Tracker reset counters	Different reset counters (Host and Modem)
Tracker date	Tracker current date
Tracker settings	Complete settings of tracker

Table 5: Interface Payload Format¶
Command	Tag	Len	Value	Comment
NAV from PCB antenna	0x06	variable	NAV
NAV from Patch antenna	0x07	variable	NAV
Data from Wi-Fi scan	0x0E	variable	[Version (1 byte)] Timestamp (4 bytes)] RSSI (1 byte)] [MAC (6 bytes)]	Values > 1 byte are in big endian MAC in big endian
Data from sensors	0x0D	1 or 7 depending on the version	[(Version(4 bits) << 4) \| (move history (4 bits)) (v0 & v1)] [temperature (2 bytes)(v1)] [modem charge (2 bytes)(v1)] [voltage (2 bytes)(v1)]	Values > 1 byte are in big endian
Tracker reset counters	0x0C	6	[Host Reset (2 bytes)] [Modem Reset by host (2 bytes)] [Host Reset itself (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

Example 1. GNSS Payload: 07460142E1092808C23CA944A72AE9034452B5BB61A600E0A4F28EC5300F80511D2886367D86B25A9C95F4C5186C90C09432E3D41ECA28DC53B8A99640D3249874557F1FD7873F01

[TAG][LEN][NAV]

In this case:

[07][46][0142E1092808C23CA944A72AE9034452B5BB61A600E0A4F28EC5300F80511D2886367D86B25A9C95F4C5186C90C09432E3D41ECA28DC53B8A99640D3249874557F1FD7873F01]

0x07 is the tag of the patch antenna

0x46 is the length of the NAV

Example 2. Wi-Fi Payload: 0E1A016107C512CC18D6C7AFDC18B70887C6693620B1249504FF409C

[0x0E][Len][ [Version (1byte)] [Timestamp in sec (4bytes)] [RSSI_1 (1 byte)][MAC_1 (6bytes)] [RSSI_2][MAC_2] [RSSI_3][MAC_3] ]

In this case:

[0E][1A][01][6107C512][CC18D6C7AFDC][18][B70887C66936][20][B1249504FF40][9C]

0x0E is the tag of the Wi-Fi scan

0x1A is the length of the Wi-Fi scan

0x01 is the TLV version

0x6107C512 is timestamp in seconds (MSB first)

RSSI in an int8 value

MAC is MSB first

Example 3. Full Sensor Payload: 0D07100B54001D0CB2

[0D][Len][Version | Accelerometer move history ][Temperature][Modem-E Charge][Voltage]

In this case:

[0D][07][10][0B54][001D][0CB2]

0x0D is the tag of the sensor

0x07 is the length of the sensor

0x10 is the version and the accelerometer move history, here version 1 and move history 0

The movement history for each of the last four uplinks of the tracker are represented on the 4 least significant bytes (LSB) of this bit field.

0x0B54 is Temperature (MSB first) in degrees Celsius

0x001D is Charge (MSB first) in mAh

0x0CB2 is Voltage (MSB first) in mV

Example 4. Basic Sensor Payload: 0D0101

[0D][Len][Version | Accelerometer move history]

In this case:

[0D][01][01]

0x0D is the tag of the sensor

0x01 is the length of the sensor

0x01 is the version and the accelerometer move history, here version 0 and move history 1

The movement history for each of the last four uplinks of the tracker are represented on the four LSB of this bit field.

Table 6: Version and Move History Bit Field¶
	Most Significant Bytes (MSB)				LSB
Bit	7 … 4	3	2	1	0
Content	Version	Fcnt-3	Fcnt-2	Fcnt-1	Fcnt

Each bit represents whether or not the tracker has moved:

0: LoRa Edge Tracker Reference Design has not moved
1: LoRa Edge Tracker Reference Design has moved

Examples:

Move History Bit Field: 0b 0001. This means that the tracker moved on the last uplink.
Move History Bit Field: 0b 1000. This means that the tracker moved three uplinks ago.
Move History Bit Field: 0b 0011. This means that the tracker moved one uplink ago and just now.

Configurable Device Parameters¶

This section describes the tracker parameters accessible over BLE and LoRaWAN.

The communication shall be 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 feature enable`	0x08	1	X	X	Return len 1
`Get GNSS feature enable`	0x09	0	X	X	0 = disable; 1 = enable
`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 GNSS antenna used`	0x0E	1	X	X	Return len 1 1 = Patch; 2 = PCB; 3 = both
`Get GNSS antenna used`	0x0F	0	X	X	Return len 1 1 = Patch; 2 = PCB; 3 = both
`Set GNSS Scan mode`	0x10	1	X	X	Return len 1 1 = Assisted 2 = Autonomous
`Get GNSS Scan mode`	0x11	0	X	X	Return len 1 1 = Assisted 2 = Autonomous
`Set GNSS search mode`	0x14	1	X	X	Return len 1 0 = Default; 1 = Best effort
`Get GNSS search mode`	0x15	0	X	X	Return len 1 0 = Default; 1 = Best effort
`Set Wi-Fi feature enable`	0x16	1	X	X	Return len 1 0 = Disable 1 = Enable
`Get Wi-Fi feature enable`	0x17	0	X	X	Return len 1 0 = Disable 1 = Enable
`Set Wi-Fi Channels`	0x18	8	X	X	Return len 2 Bit field on 2 bytes
`Get Wi-Fi Channels`	0x19	0	X	X	Return len 2 Bit field on 2 bytes
`Set Wi-Fi Type`	0x1A	1	X	X	Return len 1 1 = type B; 2 = Type G/N
`Get Wi-Fi Type`	0x1B	0	X	X	Return len 1 1 = type B; 2 = Type G/N
`Set Wi-Fi Scan Mode`	0x1C	1	X	X	Return len 1 1 = Mode Beacon; 2 = Mode Beacon & Packet
`Get Wi-Fi Scan Mode`	0x1D	0	X	X	Return len 1 1 = Mode Beacon; 2 = Mode Beacon & Packet
`Set Wi-Fi retrials`	0x1E	1	X	X	Return len 1 1 to 255
`Get Wi-Fi retrials`	0x1F	0	X	X	Return len 1 1 to 255
`Set Wi-Fi Max results`	0x20	1	X	X	Return len 1 1 to 32
`Get Wi-Fi Max results`	0x21	0	X	X	Return len 1 1 to 32
`Set Wi-Fi Timeout`	0x22	2	X	X	Return len 2 20 to 5000
`Get Wi-Fi Timeout`	0x23	0	X	X	Return len 2 20 to 5000
`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`	0x26	2	X	X	Return len 2 10 to 1800
`Get Scan Interval`	0x27	0	X	X	Return len 2 10 to 1800
`Set Keep alive frame interval`	0x28	2	X	X	Return len 2 10 to 1440
`Get Keep alive frame interval`	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 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
`Set ADR Profile`	0x3E	1	X	X	0 = Network controlled; 1 = Mobile long range 2 = Mobile low power; 3 = Custom
`Get ADR Profile`	0x3F	0	X	X	0 = Network controlled / 1 = Mobile long range / 2 = Mobile low power; 3 = Custom
`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 modem status`	0x45	0	X	X	Bit field containing the modem status, return len 2 bytes	MSB first
`Get modem date`	0x46	0	X	X	Date UTC in second, return len 4 bytes	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 reset counter`	0x4D	0	X	X		MSB first
`Reset reset counter`	0x4E	0	X	X
`Get nb uplink sent since last downlink`	0x50	0	X	X	return len 2 bytes	MSB first
`Get last_nb_sv_detected`	0x51	0	X	X	Return len 1 byte
`Get last_nb_wifi_detected`	0x52	0	X	X	Return len 1 byte
`Get system sanity check`	0x53	0	X	X	Return len 1 byte Bit 0 corresponds to GNSS scan 0 unsuccessful / 1 : successful Bit 1 corresponds to Wi-Fi scan 0 unsuccessful / 1 : successful Bit 2 corresponds to Applicative downlink RX 0 unsuccessful / 1 : successful

Parse the Internal Log¶

This chapter describes how to parse each scan read from the internal memory flash of the MCU.

Here is the structure of each logged scan in the memory flash:

Table 8: Commands for Diagnosis¶
0.1	2	3:4	5:8	9:10
Scan_len	nb_elem	Scan_number	Scan_timestamp (sec)	Accelerometer_x (mg)
11:12	13:14	15:16	17:17+n	18+n:22+n
Accelerometer_y (mg)	Accelerometer_z (mg)	Temperature (°C)	TLVs (GNSS and or WiFi)	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 scan and/or the Wi-Fi scan. It is also possible for this element to be empty.

Table 9: GNSS scan¶
0	1	2 : 2+Len
Tag	Len	NAV Messages

The GNSS_SCAN has two possible tags:

0x01 : TAG_GNSS_PCB_ANTENNA
0x02 : TAG_GNSS_PATCH_ANTENNA

Table 10: Wi-Fi scan¶
0	1	2 : 2+6		2+6+1	…	n+7*m :		2+Len
Tag	Len	MAC_Address		RSSI	…	MAC_Address		RSSI

Where 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 M0+ Dedicated to BLE¶

The Semtech LoRa Edge Tracker Reference Design 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.
Install the STM32WB Cube Package.

/uploads/lora_edge_tracker/InstallSTM32WBxx.png

Figure 42: Install STM32WBxx Package

Once installed, the necessary .bin file(s) are in the following folder:

C:Users...STM32CubeRepositorySTM32Cube_FW_WB_V1.8.0ProjectsSTM32WB_Copro_Wireless_BinariesSTM32WB5x

Copy and paste the .bin file(s) into the STM32CubeProgrammer bin folder:

C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin

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

/uploads/lora_edge_tracker/CheckFUSVersion.png

Figure 43: Check FUS Version

Install the stack firmware using the following 3 commands, depending on the FUS version.

If the FUS version is:

0x20030030: 00050300: FUSv0.5.3, perform commands 1, 2 and 3.
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_1_0_2.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

/uploads/lora_edge_tracker/FlashBLEStack.png

Figure 44: Flash BLE Stack Firmware