Universal Tracker

Universal Tracker

This tutorial will explain the steps required to connect your SODAQ boards to AllThingsTalk.

You will need:

  • SODAQ LoRa or NB-IoT/LTE-M (with sim) board with GSM antenna attached
  • USB to micro-USB data cable.

Create an account on your Dashboard and LoRa provider if you have not done so. We recommend AllThingsTalk and T-Mobile IoT Portal for this:

https://maker.allthingstalk.com/

https://portal.iot.t-mobile.nl/order/starter/account/register

Follow the website’s instructions to complete registration. Verify your email for activation; you may have to check your email’s spam folder.

Setup

Firstly, you must have the latest Arduino IDE installed, and have added the SODAQ SAMD board files to your board manager: follow these steps in order to do so if you haven’t already.

Download the source code for the Universal Tracker from GitHub. Within the folder, open the Sodaq_Universal_Tracker.ino file with the Arduino IDE.

Ensure your SIM card is properly inserted on the SODAQ board, and the GSM antenna is attached. Then plug in the micro-USB cable into the board, and connect it to your PC.

In the Arduino IDE, check under the “Tools” tab if the board and the connected port are correct.

Upload the code to your board CTRL+U (CMD+U on Mac).

Open the Serial Monitor by clicking the magnifying glass in the top right of the IDE.

Boot-up Menu

Upon power-up or reset, the Universal Tracker will provide access to the Boot Menu for the first 30 seconds of inactivity.

Ensure that the dropdown menus on the bottom of the Serial Monitor read “Both NL & CR” and “115200 baud”  to enable Serial writing and reading at the correct data rate. If the Serial Monitor does not show the menu, select the text bar at the top of the Serial Monitor and press ENTER. This text bar is also used to send commands. This will refresh the Serial Monitor

The menu shows a list of commands and values that can be used to configure the Universal Tracker to your preferences. These are described in the readme on the GitHub page.

When writing settings on the Serial Monitor, do it without spaces. For example: “ntype=2“.

When configuring the settings through the Boot Menu, a few important settings arise:

  • “ntype” should have a value of (if multiple are possible, enter the preferred mode):
    • 2, for boards with the SARA N2xxx chip.
    • 3, for boards with the SARA R4xxx chip in NB-IoT mode.
    • 4, for boards capable of LTE-M mode
    • 5, for boards capable of 2G or 3G.
  • “apn”, “cdp”, “opr”, “bnd”, “ip”, “prt” as shown in the chart below.
  • “att” should be set to the token value on the sticker applied to your board. This is not a requirement for T-Mobile.

Update the All Things Talk Token with the Token or deviceId on your sticker. If you don’t have this Token, send an email to info@sodaq.com.

Cellular settings is as such:

OperatorT-MobileVodafone NB-IoTVodefone LTE-MMonogoto LTE-MKPN LTE-M
attnot usedYour TokenYour TokenYour TokenYour Token
apncdp.iot.t-mobile.nlnb.inetd.gdsplive.vodafone.comdata.monointernet.m2m
cdp172.27.131.100not usednot usednot usednot used
opr20416204042040420404 or 2040820408
bnd820not usednot usednot used
ip172.27.131.10040.68.172.18740.68.172.18740.68.172.18740.68.172.187
prt156838891889188918891

After the setup, you must retrieve the device IMEI-number for device registration to AllThingsTalk and your LoRa provider by sending the “SI” command in the Serial Monitor (not case-sensitive).

The module will take some time to retrieve this code, and prints it to the Serial Monitor. The Boot Menu will refresh and the IMEI can be found on top of the Commands List.

Copy or write down your IMEI, you will need it later.

Lastly, before exiting the Serial Monitor, send the “ok” command to save the values permanently in the board. If this is not done, you will have to redo the process.

T-Mobile

If you haven’t registered at T-Mobile’s IoT website yet, do so now: click here

Log in to iot.t-mobile.nl, then go to STARTERKIT and click Register Device. Enter your device’s IMEI-number and select UDP for the protocol, then hit Register to register your device.

Ensure that your device shows up in the Devices screen, otherwise refresh the page.

If the device registration page tells you that the IMEI is already registered, you may need to contact SODAQ.

Almost done! We now need to ensure that T-Mobile allows the data to be retrieved by AllThingsTalk: go to the Your Application Server tab and enter the following link to the Callback URL:

https://api.allthingstalk.io/proxy/network/tmobilenl

Then hit save. If T-Mobile says it is invalid, wait a few seconds and try again. You will know it succeeded if it automatically added a request header called X-TMNL-DUMMY-TIMEADDED.

All done with the T-Mobile interface!

AllThingsTalk

Head to https://maker.allthingstalk.com/ Go to the Playground.

On the Device tab, click on New Device. Select to add “Your own NB-IoT device”. Select Sim Card provider from the list, and enter the device name of your choice, and the IMEI number. You may leave the IMSI and SIM numbers empty.

Decoding

The payload is parsed with the ABCL decoder, some changes to the payload interpreter must be made: To do this, go to settings in the top right of the page, then click on Payload formats

Tick the box “Use ABCL data … “ and copy the following into the text box, and press save.

T-Mobile

{
  "sense": [
    {
      "asset": "timestamp",
      "value": {
        "byte": 16,
        "bytelength": 4,
        "signed": false,
        "byteorder": "little",
        "type": "integer"
      }
    },
    {
      "asset": "v",
      "value": {
        "byte": 20,
        "bytelength": 1,
        "signed": false,
        "calculation": "val / 100 + 3",
        "type": "integer"
      }
    },
    {
      "asset": "t",
      "value": {
        "byte": 21,
        "bytelength": 1,
        "signed": true,
        "type": "integer"
      }
    },
    {
      "asset": "g",
      "value": {
        "latitude": {
          "byte": 22,
          "bytelength": 4,
          "signed": false,
          "byteorder": "little",
          "calculation": "val / 10000000",
          "type": "integer"
        },
        "longitude": {
          "byte": 26,
          "bytelength": 4,
          "signed": false,
          "byteorder": "little",
          "calculation": "val / 10000000",
          "type": "integer"
        },
        "altitude": {
          "byte": 30,
          "bytelength": 2,
          "signed": false,
          "byteorder": "little",
          "type": "integer"
        }
      }
    },
    {
      "asset": "speed",
      "value": {
        "byte": 32,
        "bytelength": 2,
        "signed": false,
        "byteorder": "little",
        "type": "integer"
      }
    },
    {
      "asset": "sat",
      "value": {
        "byte": 35,
        "bytelength": 1,
        "signed": false,
        "type": "integer"
      }
    },
    {
      "asset": "ttf",
      "value": {
        "byte": 36,
        "bytelength": 1,
        "signed": false,
        "type": "integer"
      }
    }
  ]
}

All other operators:

{
  "sense": [
    {
      "asset": "timestamp",
      "value": {
        "byte": 0,
        "bytelength": 4,
        "signed": false,
        "byteorder": "little",
        "type": "integer"
      }
    },
    {
      "asset": "v",
      "value": {
        "byte": 4,
        "bytelength": 1,
        "signed": false,
        "calculation": "val / 100 + 3",
        "type": "integer"
      }
    },
    {
      "asset": "t",
      "value": {
        "byte": 5,
        "bytelength": 1,
        "signed": true,
        "type": "integer"
      }
    },
    {
      "asset": "g",
      "value": {
        "latitude": {
          "byte": 6,
          "bytelength": 4,
          "signed": false,
          "byteorder": "little",
          "calculation": "val / 10000000",
          "type": "integer"
        },
        "longitude": {
          "byte": 10,
          "bytelength": 4,
          "signed": false,
          "byteorder": "little",
          "calculation": "val / 10000000",
          "type": "integer"
        },
        "altitude": {
          "byte": 14,
          "bytelength": 2,
          "signed": false,
          "byteorder": "little",
          "type": "integer"
        }
      }
    },
    {
      "asset": "speed",
      "value": {
        "byte": 16,
        "bytelength": 2,
        "signed": false,
        "byteorder": "little",
        "type": "integer"
      }
    },
    {
      "asset": "sat",
      "value": {
        "byte": 19,
        "bytelength": 1,
        "signed": false,
        "type": "integer"
      }
    },
       {
       "asset": "ttf",
       "value": {
         "byte": 20,
         "bytelength": 1,
         "signed": false,
         "type": "integer"
       }
     }
  ]
}

Now, you can create your assets. Choose some or all of the following data to add to the list of assets. Since we have defined the asset names in the payload format section, the names in the table below must be added as they are written. Otherwise, the assets are not assigned data!

This image has an empty alt attribute; its file name is image-1.png
Asset nameDescriptionProfile type
timestampTimestampInteger
vBattery voltageInteger
tTemperatureInteger
gGlobal positionObject *
speedSpeedInteger
satSatellites observedInteger
ttfTime to First FixInteger

* For “g”, under “Advanced”, the following must be added. This can also be added afterward by selecting the asset.

{
    "type": "object",
    "properties": {
        "latitude": {
            "type": "number"
        },
        "longitude": {
            "type": "number"
        },
        "altitude": {
            "type": "number"
        }
    }
}

After creating an asset, it can be selected. To change the screen name for easier identification, the Title can be changed to your needs. For any changes you wish to make to the asset: do not forget to click the check mark to save your changes!

Final check:

With the T-Mobile IoT page and AllThingsTalk page open, wait for data to appear (the T-Mobile page requires you to click “refresh table”). If using another operator than T-Mobile, ignore the T-Mobile page.

AllThingsTalk should look like this, after it receives data:

If this is not the case, open the “DEBUG” tab to check if AllThingsTalk has parsed the received data. If the brackets behind “parsed” are empty, it has not parsed the data received. This means one of two scenarios:

  • The “name” given to the device is not the asset ID as specified in the ABCL code. Check the asset name and asset ID in settings -> payload format. If this does not match, delete the asset and recreate it with the correct “name”.
  • The ABCL is not specified. Go to settings -> payload format and enter the code as described earlier in this tutorial.

When AllThingsTalk does not show a message being received, check the T-Mobile page, which should show something like this:

If T-Mobile does not receive data after some time, check if the settings on the SODAQ Universal Tracker are correct. Do not forget to hit “refresh table”.