The Things Network is a global, community driven LoRaWAN network, that is free to use and has a great web interface. It is ideal for trialling the Oyster LoRaWAN, using either your own gateways, or community gateways in your area. Every gateway connected to TTN routes traffic from both your own devices and public devices, so the network coverage can be expected to expand rapidly as IoT projects begin rolling out. Both the Oyster and TTN support all 800 and 900 MHz regions. However the Indian 865 MHz region is still experimental on TTN, and is not covered here.


1. Sign up for a TTN account

Browse to The Things Network front page, and click 'Sign Up' button in the top right. Follow the prompts, and complete the email verification step.


2. Open the TTN console

The console is where you configure you gateway, create an application, register your devices, and set up forwarding to Telematics Guru. It is usually accessed at https://console.thethingsnetwork.org. However Australian customers should use https://console.thethings.meshed.com.au.


3. Add your gateway

Browse to the Gateways screen in the console, and click 'register gateway'. Most gateways will be using the Semtech packet forwarder protocol, which forwards packets on UDP port 1700. So unless you have installed TTN specific software on your gateway, you should select 'I'm using the legacy packet forwarder', and type your gateway's 16 digit EUI / MAC address into the top field:


Pick the appropriate frequency plan, and a nearby router. For example, Europe and ttn-router-eu, United States and ttn-router-us-west, or Australia and meshed-router. After registering your gateway, you must configure the packet forwarder on your gateway to send to the router that you chose. Please see your gateway documentation for the correct procedure.


The server addresses visible in the Router drop-down are for TTN specific gateway software. If you are using the normal Semtech packet forwarder on port 1700, you should point your gateway to one of the following addresses instead:

  • router.au.thethings.network (Australia, 915 MHz)
  • router.as1.thethings.network (Southeast Asia, 920-923 MHz - 'AS923' low)
  • router.as2.thethings.network (Southeast Asia, 923-925 MHz - 'AS923' high)
  • router.eu.thethings.network (Europe, 868 MHz)
  • router.us.thethings.network (America, 902-928 MHz)
  • router.kr.thethings.network (Korea, 920-923 MHz)


If you need more help with gateway setup, please see the TTN documentation here. Some gateways require special tweaks to their configuration files. If you are having difficulty with the setup, try searching the forums here for a solution.


Once your gateway is set up and turned on, you should be able to see any LoRaWAN traffic it sends or receives in the Data page for your gateway. It will however remain encrypted on this page.


4. Add an application

Applications are groups of devices that speak the same protocol, and whose data must be forwarded to the same destination. An application is identified by its AppEUI, which must be known to each of the participating devices. The Oyster LoRaWAN has a configurable AppEUI, but the default value is 70B3D57050000000. Here we will create a single application that will contain all of your Oysters, and forward their data to Telematics Guru. If you like, you can create several separate applications to further group your devices. On TTN, they are allowed to share the same AppEUI.


Click Applications in the top right of the console, then click add application. Fill in a name and description, and choose a handler that is physically close to the router your gateway is using. In this example, we use the meshed-handler, which is appropriate for Australia:


When you create the application, TTN will generate a new AppEUI for it. To avoid programming this AppEUI into each Oyster individually, you can reconfigure your application to use the default AppEUI. Select your application, and navigate to the Settings tab. Add the default AppEUI (70B3D57050000000), then remove the old one:


5. Optionally, set the payload format

Select your application, then click Payload Formats. Supplying a decoder on this page will improve the output on the Data page, which makes debugging and monitoring much easier.


Change the text of the example decoder to:

function Decoder(bytes, port)
{
  // Decode an uplink message from a buffer
  // (array) of bytes to an object of fields.
  var decoded = {};

  if (port === 1)
  {
    decoded.type = "position";
    
    decoded.latitudeDeg = bytes[0] + bytes[1] * 256 + bytes[2] * 65536 + bytes[3] * 16777216;
    if (decoded.latitudeDeg >= 0x80000000)
      decoded.latitudeDeg -= 0x100000000;
    decoded.latitudeDeg /= 1e7;
      
    decoded.longitudeDeg = bytes[4] + bytes[5] * 256 + bytes[6] * 65536 + bytes[7] * 16777216;
    if (decoded.longitudeDeg >= 0x80000000)
      decoded.longitudeDeg -= 0x100000000;
    decoded.longitudeDeg /= 1e7;
      
    decoded.inTrip = ((bytes[8] & 0x1) !== 0) ? true : false;
    decoded.fixFailed = ((bytes[8] & 0x2) !== 0) ? true : false;
    decoded.headingDeg = (bytes[8] >> 2) * 5.625;
    
    decoded.speedKmph = bytes[9];
    decoded.batV = bytes[10] * 0.025;
  }
  else if (port === 2)
  {
    decoded.type = "downlink ack";
    
    decoded.sequence = (bytes[0] & 0x7F);
    decoded.accepted = ((bytes[0] & 0x80) !== 0) ? true : false;
    decoded.fwMaj = bytes[1];
    decoded.fwMin = bytes[2];
  }
  else if (port === 3)
  {
    decoded.type = "stats";
   
    decoded.initialBatV    = (((bytes[0] & 0xF) !== 0) ? (4.0 + (bytes[0] & 0xF) * 0.100) : null);
    decoded.txCount        =  32 * ((bytes[0] >> 4) + (bytes[1]  & 0x7F) *  16);
    decoded.tripCount      =  32 * ((bytes[1] >> 7) + (bytes[2]  & 0xFF) *   2
                                                    + (bytes[3]  & 0x0F) * 512);
    decoded.gpsSuccesses   =  32 * ((bytes[3] >> 4) + (bytes[4]  & 0x3F) *  16);
    decoded.gpsFails       =  32 * ((bytes[4] >> 6) + (bytes[5]  & 0x3F) *   4);
    decoded.aveGpsFixS     =   1 * ((bytes[5] >> 6) + (bytes[6]  & 0x7F) *   4);
    decoded.aveGpsFailS    =   1 * ((bytes[6] >> 7) + (bytes[7]  & 0xFF) *   2);
    decoded.aveGpsFreshenS =   1 * ((bytes[7] >> 8) + (bytes[8]  & 0xFF) *   1);
    decoded.wakeupsPerTrip =   1 * ((bytes[8] >> 8) + (bytes[9]  & 0x7F) *   1);
    decoded.uptimeWeeks    =   1 * ((bytes[9] >> 7) + (bytes[10] & 0xFF) *   2);
  }

  return decoded;
}


Once your application is set up, you should be able to see any LoRaWAN traffic it handles in the Data page for your application. Unlike the gateway's Data page, the application data page will show the decrypted and decoded data.


6. Add an HTTP Integration to Telematics Guru

Select your application, the click Integrations, and add integration. Select HTTP Integration:


If HTTP Integration is not on the list, you may be using the wrong console URL. Australian customers using the Meshed handler for their application should use https://console.thethings.meshed.com.au instead of https://console.thethingsnetwork.org. On the HTTP Integration setup page, fill in the Telematics Guru details shown below. You will need to contact info@digitalmatter.com to obtain an authorization header for your existing Telematics Guru account. The URL shown is 

http://<device-region>.telematics.guru:8083/ttn/oyster


The device region in the URL is important to target the correct regional instance of Telematics Guru. Refer to this article for an explanation of the regions and the device specific URLs. A short summary is:

Region
Device URL
Global (old)http://telematics.guru:8083/ttn/oyster
APAC01http://device-apac01.telematics.guru:8083/ttn/oyster
APAC02http://device-apac02.telematics.guru:8083/ttn/oyster
APAC03http://device-apac03.telematics.guru:8083/ttn/oyster
EMEA01http://device-emea01.telematics.guru:8083/ttn/oyster
EMEA02http://device-emea02.telematics.guru:8083/ttn/oyster
EMEA03http://device-emea03.telematics.guru:8083/ttn/oyster
AMER01http://device-amer01.telematics.guru:8083/ttn/oyster


Based on which regional server your partner account is hosted you will need to use the related URL.


The Authorization Field should be set using a special username and password obtained from Telematics Guru. TG support will provide these details. The username and password should be combined in the format username:password, and then base64 encoded. For example: abcdef1234567890:fedcba0987654321abcdef1234567890 (username:password) base64 encodes to YWJjZGVmMTIzNDU2Nzg5MDpmZWRjYmEwOTg3NjU0MzIxYWJjZGVmMTIzNDU2Nzg5MA== and should be use in the authorization field as:

Basic YWJjZGVmMTIzNDU2Nzg5MDpmZWRjYmEwOTg3NjU0MzIxYWJjZGVmMTIzNDU2Nzg5MA==


The Custom Header Name and Value fields should be left blank.


Once the integration is set up, your application will forward all of its decrypted data to Telematics Guru. If you create an asset in Telematics Guru that corresponds to one of your Oysters, it will be updated with the Oyster's position. Telematics Guru also allows you to send configuration messages to your Oyster, so that you can reconfigure it without using a configuration cable.


7. Add devices to your application

Select your application, then click Devices, and register device. Choose a name, and enter the DevEUI and AppKey printed on the Oyster's box. Unlike the DevEUI, the AppKey is not printed on the Oyster itself, as it must remain secret. You can however read or change the AppKey and AppEUI using a configuration cable. The default AppEUI is 70B3D57050000000.



Once a device is added to your application, it should be able to join the TTN network when turned on, and its data should be visible in the application's Data page. It can take the Oyster a few minutes to send its first message when turned on, particularly if it has weak GPS signal. Please make sure the Oyster has a good view of the sky when testing, and expect to wait roughly 2 minutes for the first message.


If you see data in the gateway's Data page, but don't see any in the application's Data page, it means the data is being received by TTN, but can't be recognized or decrypted. Please recheck your AppEUIs, AppKeys, and DevEUIs.


If you see Join requests on the application's Data page, but the device never manages to finish the Join procedure and start sending real data, you may have a gateway or network problem. Possible causes include:

  • Excessive ping time between the TTN servers and your gateway. You need a good ping, or the replies from the network arrive too late to transmit. Anything above 250 ms may cause problems.
  • A mis-configured or faulty gateway. If your gateway is unable to transmit, it won't be able to service Join requests. One possible culprit is the transmit power lookup table that is commonly configurable. If the network asks for a transmit power that is not in the configured table, the gateway will often refuse to transmit. See you gateway manufacturer for help debugging this and similar issues, or try searching the TTN forums here.
  • If your region is America or Australia, be sure the Oyster's channel mask is configured to the correct value (using a configuration cable). TTN's channel mask is 02000000000000FF00. If the device is using a different channel mask, the network may still occasionally receive a packet, but most communication will fail.


If you don't see anything in the Data page for your gateway, please recheck your gateway configuration, and make sure that your Oyster has been set up with the correct region and channel mask, as mentioned above. Also try refreshing the browser page, as the Data page may become unresponsive if left open for too long. Please note that the Data page only shows transmissions that arrive after the page is opened. It will never show historical data.


8. Create an asset on Telematics Guru
Log in to your Telematics Guru account, navigate to the Assets page, and click Create New Asset:


Now choose a name, select the correct Device Type, enter the DevEUI in the Device Serial field, and click Save:


If all of the previous steps have been followed correctly, new data points should start populating the Telemetry and IO Telemetry pages as soon as the Oyster gets its first GPS fix. The Oyster's location should also start updating on the live tracking page.