LoRa Edge Tracker Ref Design - User Guide documentation (v2)

Firmware

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

  1. LoRa Basics Modem Firmware + Application code running on the LoRa Edge Tracker Reference Design

  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/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:

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

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

  3. Performs and sends a GNSS scan with static mode when in static mode (every X minutes/hours, as defined by the user).

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

_images/TrackerAppFlow.png

Figure 35: Tracker Application Flow

Software Development Kit

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

_images/SDKLayers.png

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.

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

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

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

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

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:

  1. Install STM32CubeProgrammer.

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

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

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

_images/CheckFUSVersion.png

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:

  1. STM32_Programmer_CLI.exe -c port=usb1 –fwupgrade stm32wb5x_FUS_fw_for_fus_0_5_3.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

_images/FlashBLEStack.png

Figure 38: Flash BLE Stack Firmware