ARRIBADA Horizon ARTIC R2 User manual

Arribada Horizon
Arribada Horizon ARTIC R2 Developer’s Kit
User Manual & Quickstart Guide
Version 1.0.2| April 2020
HORIZON-DEV-ARTIC-R2
https://arribada.org | [email protected]

Arribada Horizon ARTIC R2 Developer’s Kit | User Manual
Page 2 of 42
1 Introduction
2 Prerequisites
2.1 Hardware
2.2 Software
3 Hardware Preparation
3.1.1 Horizon board rev 3.0 & ARTIC R2 board rev 1.0
3.1.2 SARA-U270 cellular module rev 1.0
3.2 Application programming via secure bootloader
4 User interface
4.1 Push buttons
4.2 LED indicators
5 Provisioning and deployment guide
5.1 AWS user account setup
5.1.1 Create admin group
5.1.2 Create IoT consumer group
5.1.3 Create user accounts
5.2 Configure user security credentials
5.3 Installation of IoT configuration into AWS account
5.4 Provisioning of device certificate and device key into AWS
5.5 Provisioning of per device certificate and keys into tracker
5.6 JSON configuration file preparation
5.7 Check tracker board status
5.8 Flash memory erase
5.9 Erase existing configuration
5.10 Program the GPS almanac
5.11 Program the GPS module general configuration settings
5.12 Program the satellite (ARTIC) firmware
5.13 Collect the satellite orbital information for the configuration file
5.14 Program the JSON configuration file
5.15 Create an empty log file
5.16 Test modes
5.16.1 Maximizing GPS TTFF performance
5.16.2 Checking IOT cellular connectivity
5.16.3 Sending a satellite test message
6 Post-provisioning guide
6.1 Test modes
6.2 GPS
6.3 IOT connectivity and data management
6.4 Extracting data using AWS tools
6.4.1 Obtain a list of registered devices
6.4.2 Obtain the current device shadow status record
6.4.3 Obtain a list of implemented data sets
6.4.4 Download data sets
6.5 AWS firmware update
6.6 AWS configuration update
6.7 Obtaining the log file after a tracker board is recovered
7 Appendices
7.1 Advanced combining of commands
7.2 Bluetooth connectivity
7.2.1 Tracker configuration settings
7.2.2 Device addressing
7.2.3 Host PC preparation for scanning and connectivity
7.2.4 Scanning for tracker devices
7.2.5 Provisioning using bluetooth
7.2.6 Link performance
7.2.6.1 Log file download
7.2.6.2 GPS device programming over bluetooth
7.3 Bluetooth ble_auto automation tool
7.3.1 Example output
7.4 JSON logging format
7.5 GPS Trigger Modes
7.5.1 SWITCH_TRIGGERED
7.5.2 SCHEDULED
7.5.3 HYBRID
7.6 JSON configuration format
7.7 Tool command-line arguments
7.7.1 aws_config
7.7.2 tracker_config
7.7.3 cellular_config

Page 3 of 42
7.7.4 gps_almanac
7.7.5 gps_ascii_config
7.8 AWS data set file formats
7.8.1 Device status data set
7.8.2 GPS location data set
7.8.3 Battery data set
7.9 AWS device shadow JSON record format
1. Introduction
This document provides a brief overview of how to setup, install and provision an Horizon tracker device.
These instructions are to be used with:
v1 nRF52840 bootloader
v1 nRF52840 application firmware
v5 configuration file format version
v2.0.0 python tools
These instructions should not be assumed to be correct for versions other than those state above.
2. Prerequisites
2.1. Hardware
1 x Horizon board rev 3.0
(Optional) 1 x SARA-U270 cellular module rev 1.0
(Optional) 1 x ARTIC R2 satellite module rev 1.0
1 x PC running Ubuntu Linux (recommend Ubuntu 20.04 LTS) & 1 x Micro A USB cable
1 x J-Link JTAG programmer or equivalent (required for programming nRF52840 device)
2.2. Software
The following release packages should be downloaded and installed by cloning the following git repository: https://github.com/arribada
Python tools software package | arribada_tools-2.0.0.zip
nRF52840 bootloader file | https://github.com/arribada/horizon-v9-firmware/blob/master/horizon_bootloader_18a6102.hex
nRF52840 firmware image DFU file | https://github.com/arribada/horizon-v9-firmware
3. Hardware Preparation
3.0.0.1. Horizon board rev 3.0
With the board(s) held in the following orientation:
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual
Ubuntu 20.04 LTS is the recommended Linux operating system to use.
Run the following commands to install necessary software and check the version numbers are correct:
$ sudo apt-get update
$ sudo apt-get install -y git python3 python3.7 python3-pip libglib2.0-dev libyaml-dev usbutils python3-dev
$ sudo pip3 install python-dateutil==2.8.0
$ git clone https://github.com/arribada/horizon.git
$ cd horizon
$ sudo python3 setup.py install

Page 4 of 42
Attach aSalt Water Switch via a cable to the Salt Water Switch picoblade connector (top edge connector)
Attach the USB micro B cable between a Linux PC and the micro USB connector (left edge, lower connector)
Attach a Lithium-ion or Lithium polymer battery to the JST connector (left edge, upper connector)
3.0.0.1. Connecting Horizon modules
There are two compatible modules currently available. A SARA-U270 Cellular module and an ARTIC RS
Argos Satellite module. Both modules are connected to the GPS board via the picoblade connector.
Attach the antenna via a cable to the U.FL antenna connector (left edge connector)
Attach the Horizon board to the module via the picoblade connector (edge)
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual
ARTIC R2 Developer's Kit Contents:
1 x Horizon board
1 x ARTIC R2 module (daughterboard)
1 x Picoblade cable assembly
1 x MicroUSB cable
The main Horizon board accepts either an ARTIC R2 module, or a Cellular SARA-U270 module.
Use the included Picoblade cable (Developer's Kit) assembly to connect a module to the Horizon board.
4.2V min to 5.4V max input supply voltage (single use primary cells).
3.4 to 4.2V max input supply voltage (lithium rechargeable cell).
Connectors / preparation;

Page 5 of 42
On the cellular module, attach the battery via a JST header and cable to the module and insert a SIM card
into the sim card holder. Ensure that you have an active data plan and APN in preparation for configuration.
Firmware programming
First time secure bootloader programming must be done with a JTAG compatible device. Developer Kit's are shipped pre-programmed.
Programming is only necessary to bring up new boards, or to upgrade or downgrade devices. As the tool nrjprog is used a SEGGER J-
link is required.
To program the board, once the J-Link debug probe has been connected to the target board as show above, then run the following commands
from the arribada_nrf52840_tracker root directory:
$ make -C ports/nrf52840/bootloader erase
$ make -C ports/nrf52840/bootloader flash_softdevice
$ make -C ports/nrf52840/bootloader flash
To confirm the board is correctly programmed power it and check that the LED indicator is cycling between red, green and blue
3.0.1. Application programming via secure bootloader
$ pip install nrfutil
$ sudo nrfutil dfu usb-serial -pkg PACKAGE.zip -p /dev/ttyACM0
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual
Probe cable selection
The following debug probe and connector are compatible with the Developer Kit.
1 x TC2030-IDC-NL
1 x ARM20-CTX 20-Pin to TC2030-IDC Adapter for Cortex
The J-Link debug probe should be pushed on to the 6-pin debug header as
indicated in the white box to the right.

Page 6 of 42
4. User interface
4.1. Push buttons
The following switches and push buttons are provided:
DFU mode push button
Hard reset push button
The DFU button operatesas follows:
Tracker state Operation Action
Power cycle or hard reset Hold DFU button down while resetting / power cycling Enter secure boot DFU mode
Operational Hold DFU button for 1 second and release GPS test
Hold DFU button for 3 seconds and release Cellular test
Hold DFU button for 5 seconds and release Satellite test
Upon pressing the RESET button, with the USB cable connected to a PC, the status LED shall indicate the provisioning state accordingly as
outlined in . LED indicators
Refer to the section for more information on the test modes.Test modes
4.2. LED indicators
The Horizon board is fitted with a single RGB status LED. The LED is used to indicate the system state during and immediately after start-up.
LED State Description Notes
Flashing Red Fatal device communication error during boot-up
Refer to UART debug output trace for more information
Solid Red Missing configuration file or log file ie provisioning incomplete
Green Configuration file checks passed LED will stay on for 5 seconds
Flashing White GPS test fix
Solid White GPS test fix locked and fixed for minimum required time period. LED will stay on for 5 seconds
Flashing Yellow Test cellular data connection in progress
Solid Yellow Test cellular data connection made and IoT message success LED will stay on for 5 seconds
Flashing Blue Test message to satellite sending in progress
Solid Blue Test satellite message sent LED will stay on for 5 seconds
Off Operational
Red - Green - Blue
Alternating Secure bootloader DFU mode
5. Provisioning and deployment guide
It is recommended the provisioning steps be carried out in the order described in this guide.
By default the configuration tools will talk to the first enumerated USB tracker device on the bus. It is possible to override this using the
USB_INDEX environment variable e.g., USB_INDEX=1 will talk to the 2nd enumerated device on the bus, etc. If USB_INDEX is not set
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 7 of 42
1.
2.
3.
4.
5.
6.
1.
2.
3.
4.
5.
6.
1.
2.
3.
4.
5.
6.
7.
8.
9.
5.1. Cellular AWS user account setup
The first-time AWS account configuration is required to be done only once. The main purpose is to create an user group and anAdmin IoTCons
user group with appropriate levels of access privileges. The Admin user group shall be assigned full administrator privileges whereas theumer
IoTConsumer user group shall be assigned basic read-only priveleges that permits the downloading of data files form the IoT service.
The steps in this guide assume you have already created an AWS account with a root user (which is normally linked to a designated e-mail
address) and you have access to the AWS console at .https://console.aws.amazon.com
5.1.1. Create admin group
Follow the steps below:
Open the IAM management console at https://console.aws.amazon.com/iam
Select from the menu on the left hand sideGroups
Click the button at the top of the screenCreate New Group
When prompted for a group name enter and then click the button at the bottomAdmin Next Step
On the screen, enter the keyword "admin" into the filter and select the checkbox next to the policy. Attach Policy AdministratorAccess
Click the button at the bottomNext Step
Review the settings you have just entered on the next screen and then click the button at the bottom.Create Group
5.1.2. Create IoT consumer group
We will repeat the same process as before with some slight alterations:
Open the IAM management console at https://console.aws.amazon.com/iam
Select from the menu on the left hand sideGroups
Click the button at the top of the screenCreate New Group
When prompted for a group name enter and then click the button at the bottomIoTConsumer Next Step
On the screen, enter the keyword "iotanalytics" into the filter and select the checkbox next to theAttach Policy AWSIoTAnalyticsRead
policy. Click the button at the bottomOnlyAccess Next Step
Review the settings you have just entered on the next screen and then click the button at the bottom.Create Group
5.1.3. Create user accounts
For each user account you wish to create, execute the steps below:
Open the IAM management console at https://console.aws.amazon.com/iam
Select from the menu on the left hand sideUsers
Click the button at the top of the screenAdd User
Assign a unique user name for the user and enter this into the boxUser name
Select the check box against only for the then click the button at the bottomProgrammatic access Access type Next: Permissions
Select either the or group by clicking on the appropriate check box on the left then click the button atAdmin IoTConsumer Next: Tags
the bottom
Select the group you wish the user to be a member based on their role
Skip this screen by pressing the button at the bottomNext: Review
Review the settings and then click the button at the bottomCreate user
On the next page click the button to download the autogenerated access key ID and Access secret keyDownload .csv
This information is downloaded to the file and is required for login access when using the AWS command-lineaccessKeys.csv
tools
5.2. Configure user security credentials
Execute the following commands from the command line:
then USB_INDEX=0 is assumed.
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 8 of 42
$ aws configure
AWS Access Key ID []: <enter your AWS Access Key ID here>
AWS Secret Access Key []: <enter your AWS Secret Access Key here>
Default region name []: <enter region name eg us-west-2>
Default output format [None]: <leave blank>
Note that the above process merely creates a file called . This is a shared credentials file that is used by all the AWS~/.aws/credentials
command-line tools to authenticate remote user access.
5.3. Installation of IoT configuration into AWS account
The following steps may only be carried out by a user that is a member of the group and need only be carried out once:Admin
$ cd arribada_tools-x.y.z
$ cd certificates
# Replace UNIQUENAME below with a unique name identifier. This is
required as all AWS instances must have a unique identifier
$ aws_config --install --namespace UNIQUENAME
2019-03-28 15:32:47,748 aws_config INFO Generating root CA certificate for
arribada...
2019-03-28 15:32:47,886 aws_config INFO Installing arribada onto AWS...
2019-03-28 15:32:47,886 aws INFO register_root_ca
2019-03-28 15:32:47,906 credentials INFO Found credentials in shared
credentials file: ~/.aws/credentials
2019-03-28 15:32:49,324 aws INFO create_iot_policy
2019-03-28 15:32:50,237 aws INFO create_iot_thing_group
2019-03-28 15:32:51,141 aws INFO create_s3
2019-03-28 15:32:53,290 aws INFO deploy_sam_packages
2019-03-28 15:33:01 Building resource
'ArribadaPushShadowIoTAnalyticsFunction'
2019-03-28 15:33:01 Running PythonPipBuilder:ResolveDependencies
2019-03-28 15:33:06 Running PythonPipBuilder:CopySource
Build Succeeded
Built Artifacts : .aws-sam/build
Built Template : .aws-sam/build/template.yaml
The above steps rely upon the AWS CLI tool being installed. Please make sure all dependency software is installed as outlined in the P
section.lastic Tracker Quick Start Guide#Prerequisites
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 9 of 42
Commands you can use next
=========================
[*] Invoke Function: sam local invoke
[*] Package: sam package --s3-bucket <yourbucket>
Uploading to 43382c729305e71a5c4fa118fe669aa5 1036 / 1036.0 (100.00%)
Successfully packaged artifacts and wrote output template to file
/tmp/tmp.yaml.
Execute the following command to deploy the packaged template
aws cloudformation deploy --template-file /tmp/tmp.yaml --stack-name <YOUR
STACK NAME>
Waiting for changeset to be created..
Waiting for stack create/update to complete
Successfully created/updated stack - PushShadowIOT
2019-03-28 15:34:01 Building resource
'ArribadaPushLoggingIoTAnalyticsFunction'
2019-03-28 15:34:01 Running PythonPipBuilder:ResolveDependencies
2019-03-28 15:34:03 Running PythonPipBuilder:CopySource
Build Succeeded
Built Artifacts : .aws-sam/build
Built Template : .aws-sam/build/template.yaml
Commands you can use next
=========================
[*] Invoke Function: sam local invoke
[*] Package: sam package --s3-bucket <yourbucket>
Uploading to 9609bf1b3f7d1e52c6b7de5b40d4eeb7 3933 / 3933.0 (100.00%)
Successfully packaged artifacts and wrote output template to file
/tmp/tmp.yaml.
Execute the following command to deploy the packaged template
aws cloudformation deploy --template-file /tmp/tmp.yaml --stack-name <YOUR
STACK NAME>
Waiting for changeset to be created..
Waiting for stack create/update to complete
Successfully created/updated stack - PushLoggingIOT
2019-03-28 15:34:53,832 aws INFO create_iot_pipelines
2019-03-28 15:35:14,954 aws INFO create_iot_rules
2019-03-28 15:35:21,723 aws_config INFO Saving certificate and keys for
arribada...
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 10 of 42
2019-03-28 15:35:21,725 aws_config INFO Saving unique certificate ID
7917f42e527c1ff22ef8a47d7749f78f154fe8831acab3eed73bba16e483b755 from AWS
for arribada...
Upon completion, the following files should be visible in the certificates directory:
$ ls -la
total 32
drwxrwxr-x 2 liamw liamw 4096 Mar 28 11:35 .
drwxrwxr-x 11 liamw liamw 4096 Mar 28 08:47 ..
-rw-rw-r-- 1 liamw liamw 1103 Mar 28 11:35 arribada.cert
-rw-rw-r-- 1 liamw liamw 64 Mar 28 11:35 arribada.cid
-rw-rw-r-- 1 liamw liamw 1704 Mar 28 11:35 arribada.key
-rw-rw-r-- 1 liamw liamw 451 Mar 28 11:35 arribada.pubkey
-rw-rw-r-- 1 liamw liamw 744 Mar 28 08:47 README
-rw-rw-r-- 1 liamw liamw 1758 Mar 28 08:47
VeriSign-Class-3-Public-Primary-Certification-Authority-G5.pem
5.4. Provisioning of device certificate and device key into AWS
The following steps may only be carried out by a user that is a member of the group and should be carried out for each tracker board:Admin
Before executing the above steps please ensure that the AWS tool is installed and on your as described in the sam PATH Plastic
sectionTracker Quick Start Guide#Prerequisites
The file is an automatically generated file. It is the root CA certificate that has now been installed for your AWSarribada.cert
account and is used as the root CA for generating all subsequent device certificates and keys by . This CA certificate isaws_config
used by the AWS server to authenticate that any uploaded device certificates stem from a trusted root.
The file is supplied as part of theVeriSign-Class-3-Public-Primary-Certification-Authority-G5.pem
arribada-tools-x.y.z package. It is the primary CA used by all Amazon AWS services and can be used to authenticate the AWS servers.
These files should not be deleted. If you accidentally delete these files, you will not be able to provision any tracker devices without first
doing an and then repeat the above step.--uninstall --install
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 11 of 42
$ aws_config --register_thing yourThingName
2019-03-28 15:26:31,265 aws_config INFO Creating certificate and keys for
yourThingName
2019-03-28 15:26:31,312 aws_config INFO Registering yourThingName into AWS
2019-03-28 15:26:31,591 credentials INFO Found credentials in shared
credentials file: ~/.aws/credentials
2019-03-28 15:26:34,962 aws_config INFO Saving certificate and key files
for yourThingName
2019-03-28 15:26:34,963 aws_config INFO Creating default device shadow
yourThingName
{
"metadata": {
"desired": {
"device_status": {
"last_log_file_read_pos": {
"timestamp": 1553786796
}
}
}
},
"state": {
"desired": {
"device_status": {
"last_log_file_read_pos": 0
}
}
},
"timestamp": 1553786796,
"version": 1
}
Note that should be unique for each tracker board being registered. Upon completion, the following new files should be visible inyourThingName
the certificates directory:
$ ls -la yourThingName.*
-rw-rw-r-- 1 liamw liamw 1135 Mar 28 15:26 yourThingName.cert
-rw-rw-r-- 1 liamw liamw 1704 Mar 28 15:26 yourThingName.key
-rw-rw-r-- 1 liamw liamw 451 Mar 28 15:26 yourThingName.pubkey
The file is an automatically generated file. It is the device certificate that has now been installed into youryourThingName.cert
AWS account against the new thing called . Associated with this device certificate is the device's private key calledyourThingName you
. Both these files must now be registered into the plastic tracker's cellular modem as outlined in the followingrThingName.key
section.
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 12 of 42
5.5. Provisioning of per device certificate and keys into tracker
The following steps should be carried out for each tracker board:
$ sudo cellular_config --root_ca
VeriSign-Class-3-Public-Primary-Certification-Authority-G5.pem --cert
yourThingName.cert --key yourThingName.key
<Add example output here>
5.6. JSON configuration file preparation
A file should be created for each tracker board that has been registered into AWS. Each file should be largely identicalyourThingName.json
with the exception of device-specific parameters that should be set as follows.
For the IOT configuration, the following fields are needed for the device-specific IOT cellular AWS configuration:
{
"version": 1, # Recommended to be set to 1 for first file version
"iot": {
"cellular": {
"aws": {"arn": "xxxxxxxxx.iot.us-west-2.amazonaws.com"
"thingName": "yourThingName"
}
}
}
}
Note that the value for the field can be obtain by running the following command:"arn"
$ aws_config --get_iot_endpoint
2019-03-28 19:43:22,359 credentials INFO Found credentials in shared
credentials file: ~/.aws/credentials
a8fb7n41z7p2n.iot.us-west-2.amazonaws.com
The ARN is specific to each AWS account and does not change unless you switch to different AWS account's login credentials.
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 13 of 42
5.7. Check Horizon board status
To obtain system status information, enter the following command
$ sudo tracker_config --status
{ "cfg_version": 5, "fw_version": 1, "unique_device_identifier": xxxxxxx, "cellular_module_present":
true, "satellite_module_present": false }
The firmware version and configuration version must match the version requirements for the quick start guide as outlined in the introduction. If
these versions do not match, then it is advised not to proceed further.
5.8. Flash memory erase
It is recommended that flash memory is erased in its entirety if the board is being programmed for this first time. The following commands
will erase the entire flash chip and then reset the CPU:
$ sudo tracker_config --reset FLASH
$ sudo tracker_config --reset CPU
5.9. Erase existing configuration
This command will erase all existing configuration settings held in RAM before proceeding with provisioning:
$ sudo tracker_config --erase
Now confirm the currently active configuration stored in RAM is "empty":
$ sudo tracker_config --read current_config.json
$ cat current_config.json
{
"version": 0, # TBD: will this be the default version when the system is not programmed?
"logging": {
"fileSize": 0,
"fileType": "LINEAR",
"startEndSyncEnable": false
},
"rtc": {
"dateTime": "Mon Jan 1 00:23:40 2018"
}
}
The status LED shall be solid RED to indicate that the configuration is not yet valid. The provisioning process can now be carried out as normal
as outlined in the following sections.
5.10. Program the GPS almanac
The GPS almanac data file can be downloaded via HTTP from the u-blox AssistNow offline servers. Refer to the following guide for more
The uploading of a GPS almanac is not mandatory and can be skipped if this is not needed.
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 14 of 42
information on registering for this service:
https://www.u-blox.com/sites/default/files/products/documents/MultiGNSSAssistNow_QuickStart_%28UBX-14003139%29.pdf
Upon registration to the service, a token shall be issued that permits access to the HTTP server. Typing the following URL format into a web
browser should obtain a new file:mgaoffline.ubx
http://offline-live1.services.u-blox.com/GetOfflineData.ashx?token=insert_your_token_here&gnss=gps,glo&period=4
This assumes an almanac for a 4 week period with data for both the GNSS and GLONASS satellite systems.
Note that it is necessary to add your own token to the URL otherwise this will result in a error from the AssistNow offline server.Bad Request
To apply the almanac file to the tracker board, enter the following command:
$ sudo gps_almanac --file mgaoffline.ubx
5.11. Program the GPS module general configuration settings
It is recommended to use the pre-generated GPS ASCII configuration file supplied found inside the tracker_config tools folder. However, it is
possible to edit the configuration settings, for example, using the u-center tool.
To apply the GPS ASCII configuration to the Horizon board, enter the following command:
$ sudo gps_ascii_config --file ublox_gnss_configuration.dat
The GNSS settings are configured broadly as follows:
Hot start GNSS
GPS reporting once per second
Optimised for maritime tracking applications
All GNSS satellite systems enabled
Reporting of TTFF and POS messages only
5.12. Program the ARTIC R2 satellite firmware
The ARTIC firmware is packaged into 3 seperate files; . These need to be combined for use on theARTIC.XMEM ARTIC.YMEM ARTIC.PMEM
tracker board. To do so use the following line where points to the folder that contains the aforementioned files:--path
$ sudo artic_mems_to_firmware_file --path path/to/artic/firmware/ --output Artic_firmware.bin
Once this file has been generated, transfer it to the tracker board with the following command:
$ sudo tracker_config --firmware_type ARTIC --firmware Artic_firmware.bin
5.13. Collect the satellite orbital information for the configuration file
To collect the latest satellite orbital information visit the Argos website at: https://argos-system.cls.fr
After signing in you ensure that your time is set to UTC. This can be confirmed by checking the top right of the webpage as seen belowMUST
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 15 of 42
Once this is set, navigate to the "Satellite pass prediction" page, ensure "NK" and "NN" are ticked under "Satellite choice". This is becauseNOT
these two satellites do not support the Argos 3 messages that we are using.
Now click "Download satellite AOP" and save the file to disk.
To convert this data to the configuration JSON format use the following line:
$ sudo artic_bulletin_to_json --file AOP_2019_08_19_10_53_06.txt
{"bulletin": [{"secondsSinceEpoch": 1566170997, "params": [7195.621, 98.569, 322.886, -25.341,
101.3601, 0.0], "satelliteCode": "MA"}, {"secondsSinceEpoch": 1566169463, "params": [7195.651,
98.6984, 336.302, -25.34, 101.3604, 0.0], "satelliteCode": "MB"}, {"secondsSinceEpoch": 1566167445,
"params": [7195.586, 98.7004, 345.036, -25.34, 101.3591, 0.0], "satelliteCode": "MC"},
{"secondsSinceEpoch": 1566170008, "params": [7226.502, 99.181, 268.188, -25.5, 102.0106, -1.98],
"satelliteCode": "19"}, {"secondsSinceEpoch": 1566167176, "params": [7160.249, 98.5406, 112.607,
-25.154, 100.6149, 0.0], "satelliteCode": "SR"}]}
5.14. Program the JSON configuration file
The system configuration file is described using JSON. Refer to the section for more information.JSON configuration format
To apply the JSON configuration file to the tracker board, enter the following commands:
$ sudo tracker_config --write yourThingName.json --setdatetime "`date`"
This will additionally set the RTC date and time to the local time of your PC.
5.15. Create an empty log file
$ sudo tracker_config --erase_log --create_log LINEAR
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 16 of 42
Upon completion of the above steps the status LED shall turn GREEN to indicate that provisioning has been successful.
5.16. Test modes
A number of test modes can be activated prior to deployment in order to check that the hardware and overall system configuration are functioning
correctly. It is recommended to use the --test_mode option to enable these tests prior to unplugging the USB cable.
Below is an example command for enabling the GPS and cellular test modes:
$ tracker_config --test_mode GPS,CELLULAR
Note that the test modes will not become active until the USB cable is unplugged. The progress of the test modes can be tracked using the status
LED.
5.16.1. Maximizing GPS TTFF performance
In order to maximize the TTFF performance of the GPS module, it is recommended that a complete ephemeris is obtained after the first GPS fix is
made. This generally requires a certain period of time to elapse (with continual GPS lock) that is sufficient for the GPS device to obtain the
ephemeris data from all satellites in view.
This can be accomplish using GPS test mode. For example, setting the parameter to would prevent the tracker fromtestFixHoldTime 60
shutting down until a period of 60 seconds of continuous GPS lock have elapsed during GPS test mode.
In order to aid the end user, the LED indicator can be used to ascertain the status of the GPS test mode process:
LED flashing green - waiting for GPS test fix or GPS test fix lost during hold period
LED solid green - fix found, waiting for hold period to elapse
LED off - hold period elapsed with continual GPS lock
5.16.2. Checking IOT cellular connectivity
In order to ensure that the cellular connectivity is working properly, it is recommended to activate cellular test mode on start up. This will execute
a complete status and logging update cycle.
5.16.3. Sending a satellite test message
While it can not be guaranteed that satellites will be in view of the Horizon board, it is still possible to transmit a single satellite test message
using the satellite test mode. This can at least confirm that the hardware is functional.
6. Post-provisioning guide
6.1. Test modes
The test modes can also be activated using the DFU push button or via a bluetooth connection using the command after--test_mode
provisioning over USB has completed.
6.2. GPS
The tracker shall now start logging periodically in accordance with the tracker JSON configuration file settings. GPS fixes shall be stored to the
log file. The most recent GPS fix shall also be stored in RAM along with a timestamp of when the GPS fix was made.
6.3. IOT connectivity and data management
The system will attempt to make an IOT connection in accordance with the JSON configuration file settings. During each IOT connection cycle
the following information shall be provided:
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 17 of 42
Device status update
Logging data backlog
The IoT infrastructure has been configured to organise the received data into three separate data sets which aggregate data across all deployed
devices as follows:
Device status updates - provides the last know status of each device whenever it connects. This includes:
Last known GPS location and timestamp of when that GPS fix was made
Battery level when the device last connected
Log file read position
GPS location updates - provides a time series record of all GPS fixes since deployment (not just the last known location)
GPS location including GPS accuracy information
Time To First Fix (where available)
Battery charge and/or voltage updates - provides a time series record of all battery updates, not just the last known battery level
All data sets are organized into records continaining the that originated the data, a of when the data was generated and athingName timestamp
set of fields that represent the data record itself. More information about the structure of each data set can be found in the appendices section A
.WS data set file format
6.4. Extracting data using AWS tools
The tool provides a number of methods of obtaining data about the devices that have been registered into an AWS accountaws_config
instance.
6.4.1. Obtain a list of registered devices
This command may only be run by a user in the group:Admin
$ aws_config --list_things
[u'yourThingName1', u'yourThingName', u'yourThingName2']
6.4.2. Obtain the current device shadow status record
This command may only be run by a user in the group:Admin
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 18 of 42
$ aws_config --get_shadow thingName
{
"metadata": {
"desired": {
"device_status": {
"last_log_file_read_pos": {
"timestamp": 1553857919
}
}
}
},
"state": {
"delta": {
"device_status": {
"last_log_file_read_pos": 0
}
},
"desired": {
"device_status": {
"last_log_file_read_pos": 0
}
}
},
"timestamp": 1553857975,
"version": 2
}
Note that the device shadow record indicates fields that have changed under as well as the current value of all fields that been setstate.delta
under .state.desired
6.4.3. Obtain a list of implemented data sets
This command may only be run by a user in the or group:Admin IOTConsumer
$ aws_config --list_datasets
2019-03-29 11:23:34,217 credentials INFO Found credentials in shared
credentials file: ~/.aws/credentials
[u'arribada_battery_charge', u'arribada_device_status',
u'arribada_gps_location']
6.4.4. Download data sets
This command may only be run by a user in the or group:Admin IOTConsumer
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 19 of 42
$ aws_config --download_dataset arribada_gps_location
2019-03-29 11:14:48,107 aws_config INFO Retrieving data set meta data for
arribada_gps_location
2019-03-29 11:14:48,129 credentials INFO Found credentials in shared
credentials file: ~/.aws/credentials
2019-03-29 11:14:49,050 aws_config INFO Downloading data set to file
ffa31d0f-15db-4c59-9a85-c8e1a1d368b2.csv...
Each data set is configured to automatically update every in the AWS infrastructure ie there is an effective 15 minute lag on any data 15 minutes
set updates from tag devices. This is shortest time interval permitted for automatic updates. However, it is possible to manually force an
immediate update of a data set using the option, although this may still take 1-2 minutes before a new data --update_dataset datasetName
set is available to be downloaded.
Each data set is retrieved as a file containing the full history of all updates to that data set. The first line inside the file denotes the .csv .csv
field names for that data set.
Note that all data set fields are represented as strings with their values in double-quotes; this is a quirk of the AWS IoT data set functionality but
stripping of double-quotes can be easily done as part of data post-processing.
The data set file name is automatically generated by AWS infrastructure and changes whenever the data set contents change. When a data set
has not changed the file name remains the same ie the option will overwrite the previous local data set file..csv --download_dataset
6.5. AWS firmware update
This command may only be run by a user in the group:Admin
$ aws_config --firmware_update yourThingName --firmware_version
versionNumber --file DFUZipFileName
2019-03-29 11:28:03,703 aws_config INFO Using firmware file
nrf52840_xxaa.bin from DFU zip archive
2019-03-29 11:28:03,706 aws_config INFO Uploading firmware file
nrf52840_xxaa.bin to AWS...
2019-03-29 11:28:03,731 credentials INFO Found credentials in shared
credentials file: ~/.aws/credentials
2019-03-29 11:28:05,344 aws_config INFO Notifying device shadow update for
yourThingName...
{
"metadata": {
"desired": {
"device_update": {
"firmware_update": {
"url": {
"domain": {
"timestamp": 1553858886
},
"path": {
"timestamp": 1553858886
},
"port": {
"timestamp": 1553858886
}
},
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual

Page 20 of 42
"version": {
"timestamp": 1553858886
}
}
}
}
},
"state": {
"desired": {
"device_update": {
"firmware_update": {
"url": {
"domain": "arribada.s3.amazonaws.com",
"path":
"/f99f1395-dbef-4032-aebc-d01d21b55cf6?AWSAccessKeyId=AKIAIPZT2EDQFBIJHOWA&
Expires=1585394885&Signature=%2F%2Fabi%2BYo8%2FGd69yfB3L2Pk3MEGs%3D",
"port": 443
},
"version": 2
}
}
}
},
"timestamp": 1553858886,
"version": 3
Arribada Horizon ARTIC R2 Developer’s Kit | User Manual