6 ‐ Quick Start Guide - arribada/CLS-Argos-Linkit-CORE GitHub Wiki

This guide is intended for users who have purchased a Linkit or Horizon board directly from CLS or Arribada and are unboxing the device for the first time. It assumes that Linkit firmware has been pre-programmed onto the device and you are seeking guidance to quickly setup and test the device on a computer running either Windows 10 or 11. Your computer will also need Bluetooth, which is commonly found on laptops but may be missing from a desktop computer. If so, a USB Bluetooth dongle is recommended as communication to a Linkit or Horizon board is solely by Bluetooth and not USB.

Step 1) Preparing to install the Pylinkit software tool

The Pylinkit software tool requires Python 3.9. Download a suitable installer for Python 3.9 and during the installation process, make sure to check the box that says "Add Python 3.9 to PATH". This makes it easier to run Python from the command line. Once installed we will install the Pylinkit software tool using the command prompt. Also download a ZIP file of the Pylinkit software tool itself and extract the folder to a local folder of your choice.

Here is an example screenshot of the Windows x86 executable installer when installing Python. Notice the tick box "Add Python 3.9 to PATH".

Step 2) Installing the Pylinkit software tool

Restart your computer if you have just installed Python 3.9 running Windows so that the PATH can be established, otherwise if you already had Python, open a command prompt as Administrator and navigate to the folder where you extracted the Pylinkit software tool. Look for the file setup.py to confirm you are in the correct sub-directory. To install the tool, run python setup.py install. Your command prompt will look something like the following:

The installation script should run and output the following successful installation message. Note - if you receive a message that Python is already running with the error message "the process cannot access the file because it is being used by another process" then it is likely that you have already installed Pylinkit previously. If so you should manually remove the .egg file from the directory indicated and re-run the command again.

If successful you will see "Finished processing dependencies for pylinkit==3.X.X"

Step 3) Communicating with your Linkit or Horizon board using Pylinkit

Now that you have installed the Pylinkit software tool we can scan for active Bluetooth devices. To place your device into Bluetooth mode, first connect a battery. A white LED will flash momentarily. Hold a magnet next to the reed switch until you see a white LED and hold the magnet in place until it starts flashing. At this point remove the magent. Your device is now booting up and will continue until you see a flashing cyan LED indicating that it is searching for a GPS fix.

To place the device into Bluetooth mode, hold the magnet on the reed switch again until you see a dark blue LED. When you see the dark blue LED remove the magnet. The dark blue LED will start to flash. The device is now in Bluetooth pairing mode and can be detected using the Pylinkit software tool.

To scan for the device run the following command from command prompt pylinkit --scan. You should see the device in the scan:

If you don't see the device, try moving it nearer and confirming that your Bluetooth dongle is working by running pylinkit --scan --debug. The --debug argument will also show you other Bluetooth devices, such as your phone, and is useful if you want to confirm that your computer is scanning normally.

To connect to the device, use the UUID of the device from the scan as below. As the UUID in the screenshot above is D0:B3:95:32:48:63 you would enter the following to connect to the device and then request to download a config file, log etc by providing arguments in the command line: pylinkit --device D0:B3:95:32:48:63

To download the default configuration file for example, use the following command, replacing the UUID with your own device's UUID. The --parmr argument means "Parameter Read".

pylinkit --device D0:B3:95:32:48:63 --parmr get_config.txt

For a full list of possible commands run: pylinkit --help

To edit the config file you just downloaded simply open it in a text editor (Notepad++ etc) and change the variables according to the guide.

Once ready to push the config file back to the device, save it, and run the following command to re-connect and push the configuration file across:

pylinkit --device D0:B3:95:32:48:63 --parmw get_config.txt

The dark blue LED will become solid and the config file will be written. Once written the dark blue LED will continue to flash again. Note - if at any time it takes several minutes between commands the device may timeout and go to sleep. If it does, simply wake it again by holding the magnet until the white LED starts to flash and then remove the magnet, replace it again and hold it until you see the dark blue LED show. Once you see the dark blue LED remove the magnet to re-activate the Bluetooth advertising mode.

Note - to start the device after making any changes hold the magnet until you see the green LED and then remove it. The green LED will flash indicating that the device is starting.

Step 4) Testing GNSS / GPS

The default GNSS acquisition time is 10 minutes between fixes after the device first achieves a fix from a cold start. We can see that the default time period in the configuration file is 530 seconds (GNSS_COLD_ACQ_TIMEOUT) meaning the device will try to aquire a fix for 530 seconds when booting for the first time (i.e. a cold start). The cyan LED indicates that the device is trying to acquire a fix, and we can also see that if it is unsuccessful after trying for 530 seconds, it will try again 60 seconds later (GNSS_COLD_START_RETRY_PERIOD = 60).

Test the device yourself by starting it (holding the magnet until you see a solid white LED followed by a flashing LED indicating that the device has started) and then remove the magnet and wait until you see a flashing cyan LED. Place the device outside to acquire a fix. You will see the LED turn green when a fix has been acquired and it will then wait for 10 minutes until it logs another fix (GNSS_DELTATIME_ACQ = 10).

Note - if you are in a poor GPS location (i.e. surrounded by buildings, trees etc) when running this test, you can disable the GNSS accuracy filters that force the device to continue to try to acquire a fix to a higher degree of accuracy (GNSS_HACCFILT_ENABLE = 1 and GNSS_HDOPFILT_ENABLE = 1). Change these to 0 and the first fix will be logged without any accuracy filtering.

Step 4) Downloading GPS logs

To download logs, run the device with the default configuration file for 1 hour to collect a series of GPS fixes (every 10 mins by default) and then connect to the device and download the GNSS log using the following command:

pylinkit --device D0:B3:95:32:48:63 --dump_sensor GNSS_logs.csv --dumpd_type gnss

A CSV file of the GNSS log will be downloaded.

To download just the system log, change the --dumpd_type to system

Step 5) Activating the Argos transmitter

To start to transmit data via the integrated Argos transmitter it's necessary to populate the ARGOS_DECID configuration field and ARGOS_HEXID field with your own Argos ID supplied by CLS.

After entering your own HEDID and DECID, change ARGOS_MODE to LEGACY and save the file. By default your device will now transmit and send a message with the last GPS location it acquired every 60 seconds. You will see a purple LED light up for a few seconds when the device is transmitting. Make the configuration changes as noted above, save your configuration file and then push it to your device using pylinkit --device D0:B3:95:32:48:63 --parmw get_config.txt. To start the device, hold the magnet until you see the green LED and then remove it. The latest configuration file will be read and processed.

Note - it is recommended to leave the device outside with a clear line of sight to the sky and to confirm when Argos satellites are passing above by using the Argos CLS dashboard's pass predication interface.