Arduino Tracker Application for SODAQ SARA/AFF/SFF  BLD4131-v2.13
Arduino Tracker Application for SODAQ SARA/AFF/SFF Documentation

Arduino Tracker Application for SODAQ SARA/AFF/SFF

Version: BLD4131-v2.13

This document describes SodaqTracker, an example application for SODAQ SARA/AFF/SFF boards which supports periodically sending location information.

See Thingstream Client SDK for documentation of the Thingstream Client library.

Prerequisites

Hardware

This example has been tested on the following boards:

  • SODAQ SARA AFF R410M Rev 3
  • SODAQ SARA AFF R412M Rev 3
  • SODAQ SARA SFF R412M Rev 2

Other SODAQ board variants or revisions may require minor changes.

Application description

The SodaqTracker application sends location updates as a JSON string whenever a configured event occurs. The typical payload contains location data in the form of coordinates as obtained from the GNSS receiver or information about the currently connected cellular base station which can be used to approximate a location. In addition, the payload contains sensor information, namely the current battery voltage and temperature.

The payload is sent to predefined topic device/<identity>/publish, where <identity> is shown on the Thing Details page for the device accessed from the Portal Things Page and is of the form identity:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

The following events can trigger a publish:

  • power: The device has been powered on or reset.
  • timer: The publish timer has expired. This is a repeating event for trackers configured for periodic publishing.
  • motion: The accelerometer has detected that the device is in motion.
  • config: The device has received a configuration message. This triggers a special message to be returned, consisting of the full device configuration.

Payload format

This is an example payload from the SodaqTracker application:

{
"event": { "timer": 0 },
"sensor": { "bat": { "mV": 4206 }, "temp": 22 },
"loc": { "gnss": { "lat": 37.4, "lon": -121.9, "qty": 1 } }
}

Capturing progress logs

Logs are enabled by default and are written to SerialUSB. Whenever logs are being captured by a connected host system, i.e. the USB serial port has been opened on the host, the application will avoid entering deep sleep in order to keep the USB connection alive.

Monitoring progress using the LEDs

The RGB LED will fade in and out in the following colors to indicate progress:

Color Phase
GREEN Tracker starting
YELLOW Acquiring GNSS position
CYAN Acquiring cellular location info
MAGENTA Publishing payload to Thingstream

Error codes are indicated with RED flashes

Pattern Meaning
1 x 500ms ON, 500ms off Error in tracker code
2 x 750ms ON, 250ms off Error getting GNSS location
2 x 500ms ON, 500ms off Error getting cellular location
5 x 200ms ON, 200ms off Error publishing payload

While sleeping in between tracker runs, the LED will flash briefly as follows:

  • A single flash indicates the device is in deep sleep.
  • A double flash indicates that the device is sleeping, but avoiding deep sleep due to the SerialUSB port being opened on the host.
  • BLUE indicates the tracker is idle, waiting for the next timer event to trigger publishing.
  • GREEN indicates that the accelerometer detected a motion event. The tracker will either publish immediately, or wait until config.interval.min minutes have passed since the last publish. See below for further details.

Configuration

Configuration is done over MQTT by sending QoS 1 messages to the topic device/<identity>, for example by using the "Send Test Message" menu on the Portal Things Page.

Note that in order to conserve power, the device will not remain connected to the Thingstream gateway at all times. It will poll for configuration messages whenever it publishes its location. Configuration messages should be sent to the device using QoS 1, otherwise the message may be discarded.

Configuration values are stored in flash memory. The values get overwritten with defaults when the tracker application is reflashed.

Configuration message format

Configuration messages can be sent as a JSON string, such as:

{ "config": { "loc": { "gnss": 0 }, "motion": 0, "interval": { "max": 15 } } }

For convenience, the configuration parser also accepts simplified text formats, such as:

gnss:0,motion:0,max:15

Simplified configuration format rules:

  • Quotes around the property names are optional. Both single and double quotes are allowed.
  • The use of composite JSON objects is currently optional, since all property names are unique.
  • Property names and values can be separated by either ':' or '='.
  • Properties can be separated by ',' or ';'.

A configuration message can change all properties at once or consist of an partial update, leaving other properties unchanged. The resulting full configuration is published to the predefined topic device/<identity>/publish in response to a configuration message.

Configuration properties

config.interval

This configuration object is used to specify the interval for timer events. Two intervals can be configured in this object:

  • config.interval.max: Sets the maximum time in minutes between subsequent publish attempts. This is used to specify the interval at which the application should automatically send updates.
  • config.interval.min: Sets the minimum time in minutes between subsequent publish attempts. This is used to avoid publishing too frequently. This is useful in conjunction with config.motion where accelerometer movement triggers a publish.

Example configuration for periodic publishing once every 3 hours when the device is stationary and once every 15 minutes when the device is in motion and using medium accelerometer sensitivity:

{ "config": { "interval": { "min": 15, "max": "180" }, "motion": 3 } }

config.motion

This property sets the sensitivity of the accelerometer motion detection. Valid values range from 0 (accelerometer disabled) to 5 (maximum sensitivity).

config.loc

The priority of location sources can be set using the config.loc property, where each supported location source is listed with a priority.

The SodaqTracker supports location sources gnss and cell. Future versions of the tracker may support additional location sources.

Location priorities are interpreted as follows:

  • A priority of 0 (zero) indicates that data from this location source, if available, will always be included in the payload.
  • Priorities 1 to 9 indicate the order in which location sources are queried. After processing location sources set to 0, all location sources with priority 1 will be queried and their result, if available, added to the payload. If any of the priority 1 sources yielded data, the process stops. Otherwise, the tracker repeats the process with the next priority level.
  • Location sources set to priority level -1 will be disabled.
  • Location sources not listed in the config.loc property will be treated as being set to priority level -1, i.e. disabled.

Note that the config.loc object is always interpreted as a whole. That means partial messages always overwrite the entire priority table, i.e. gnss:0 enables GNSS unconditionally and disables all other location sources.

The following example configures the tracker so that it attempts to get GNSS location and falls back to cell tower information when no GNSS fix can be acquired:

{ "config": { "loc": { "gnss": 1, "cell": 2 } } }

Default configuration

After flashing the SodaqTracker application, the default values given in nvmem.cpp will be applied. The default configuration is:

{ "config": { "interval": { "min": 5, "max": "60" }, "motion": 3 },
"loc": { "gnss": 1, "cell": 2 } }

This means the tracker will publish every 60 minutes when stationary and every 5 minutes while in motion. Default location source is GNSS, but if no GNSS fix can be obtained, cellular information is sent instead.

Building and uploading the application from the Arduino IDE

The example is provided as part of the Thingstream Arduino library in library/Thingstream.zip

Launch the Arduino IDE and use the Sketch->Include Library-> Add .ZIP Library menu option to load the Thingstream library.

All Thingstream examples should then be available on the File-> Examples menu (near the end of the list in the Examples from Custom Libraries section). It is ready to Verify and Upload in the usual manner.

Uploading the SodaqTracker sketch to the board

Uploading from the Arduino IDE can be done using the 'Upload' button, whenever the board is connected and running.

However, at the end of each data collection and communication cycle, the board is put into deep sleep to conserve battery power, unless the USB serial port has been opened on a connected host.

Whenever the device is in deep sleep, the USB serial port will disappear from the list of ports available on the host, which prevents flashing. However, by clicking the RESET button on the board twice in quick succession, the board enters bootloader mode. This is indicated by the blue LED fading in and out. In this mode, the board can be reprogrammed from the host.


Release Notes

Release History

Release v2.13: 18-Aug-2021

  • Tracker: add one-time modem configuration

Release v2.12: 29-Jun-2021

  • Tracker: improve code for obtaining cell location using COPS/CxREG

Release v2.10: 16-Jun-2021

  • Initial Tracker release