![]() |
Arduino Tracker Application for SODAQ SARA/AFF/SFF
BLD4131-v2.13
|
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.
This example has been tested on the following boards:
Other SODAQ board variants or revisions may require minor changes.
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.This is an example payload from the SodaqTracker
application:
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.
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:
config.interval.min
minutes have passed since the last publish. See below for further details.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 messages can be sent as a JSON string, such as:
For convenience, the configuration parser also accepts simplified text formats, such as:
Simplified configuration format rules:
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.
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.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:
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:
After flashing the SodaqTracker
application, the default values given in nvmem.cpp
will be applied. The default configuration is:
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.
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 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.