documentation
HOME » DOCUMENTATION » TECHNICAL DOCUMENTS » LoRa Edge™ Tracker Reference Design User Guide v1 » Firmware

Firmware

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

  1. LoRa Edge Tracker Reference Design Firmware

  2. 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:

  1. 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).

  2. 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.

  3. Switches to BLE mode when the Hall Effect sensor detects the presence of a magnet.

  4. 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:

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

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

Set LoRaWAN JoinEui

0x04

8

X

X

  

MSB First

Get LoRaWAN JoinEui

0x05

0

X

X

Return len 8

Set LoRaWAN AppKey

0x06

16

X

X

  

MSB First

Get LoRaWAN AppKey

0x07

0

X

X

Return len 16

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

  

Set GNSS Scan mode

0x10

1

X

X

Return len 1 1 = Assisted 2 = Autonomous

  

Get GNSS Scan mode

0x11

0

X

X

  

Set GNSS search mode

0x14

1

X

X

Return len 1 0 = Default; 1 = Best effort

  

Get GNSS search mode

0x15

0

X

X

  

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

  

Set Wi-Fi Channels

0x18

8

X

X

Return len 2 Bit field on 2 bytes

  

Get Wi-Fi Channels

0x19

0

X

X

  

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

  

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

  

Set Wi-Fi retrials

0x1E

1

X

X

Return len 1 1 to 255

  

Get Wi-Fi retrials

0x1F

0

X

X

  

Set Wi-Fi Max results

0x20

1

X

X

Return len 1 1 to 32

  

Get Wi-Fi Max results

0x21

0

X

X

  

Set Wi-Fi Timeout

0x22

2

X

X

Return len 2 20 to 5000

  

Get Wi-Fi Timeout

0x23

0

X

X

  

Set use accelerometer

0x24

1

X

X

Return len 1 0 = Disable 1 = Enable

  

Get use accelerometer

0x25

0

X

X

  

Set Scan Interval

0x26

2

X

X

Return len 2 10 to 1800

  

Get Scan Interval

0x27

0

X

X

  

Set Keep alive frame interval

0x28

2

X

X

Return len 2 10 to 1440

  

Get Keep alive frame interval

0x29

0

X

X

  

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:

  1. Install STM32CubeProgrammer.

  2. 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

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

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

  1. 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.

  2. 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:

  1. STM32_Programmer_CLI.exe -c port=usb1 –fwupgrade stm32wb5x_FUS_fw_1_0_2.bin 0x080EC000 firstinstall=0

  2. STM32_Programmer_CLI.exe -c port=usb1 -fwupgrade stm32wb5x_FUS_fw.bin 0x080EC000 firstinstall=0

  3. 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

Previous
Next
« RETURN TO TECHNICAL DOCUMENTS