Support

Getting started guide

Things Connected is in BETA phase at the moment, we plan to fully launch the network after BETA tests later in 2017. Digital Catapult will select a small number of users to join the BETA trial. If you already have a LoRaWAN™ based project, you can apply to join the BETA trial.

Once you have registered and been accepted onto the Bet trial, you will have access to the dashboard. From there you can connect your devices to application servers, application enablement platform or the sandbox.

Digital Catapult set up Things Connected to support the growth of the Internet of Things (IoT). The network is free to use but only for non-commercial, prototyping services. If you want to deploy a commercial service, you will need to use an alternative provider.

Check the signal strength where you are going to place your LoRaWAN™ devices.

To have a higher likelihood of indoor coverage you need to be in a strong or medium strength area.

If you are in a weak signal area, we suggest checking communications outdoors first, before using your device indoors.

NB: The size of your device's antenna and other factors, such as obstacles in the environment may affect the ability of your device to communicate with Things Connected Network.

Once you are registered and have access to the dashboard, follow these steps to connect your device and application:

    Connect your device by:

  • entering a nickname
  • application session key
  • network session key
  • device EUI
  • Select where you would like send the packets from the device (application):

  • your own application
  • application enablement platform
  • the sandbox
  • We recommend that you route your device to the sandbox first. If your own application is ready, please select "A new application" and input the URL of your application server.

    Hard code the keys onto your device and application, to do this please refer to the device manufacturer's instructions. After doing this, your device is ready to connect to the Things Connected network. Which will then forward packets to your application.

    Test the connection: Start your device to trigger a packet, check to see if the network and application has received it. You can check that the network has received the packet by clicking on the gear icon for the corresponding device and then selecting the Gateway Packets tab.

Tutorials

If you have a functioning device, but don't have an application to point the traffic to, then you can use our sandbox application to check whether the message and its’ contents are formatted correctly.

The sandbox application displays the packets that are arriving on the network, which would be forwarded on to your real application when you have it ready. You will see the packets shown in a list and can also view the raw JSON that includes attributes such as; the gateway address, the arrival time, the received signal strength and the payload itself.

To use the sandbox you need to do the following:

  • Create a new device by clicking on the "create new" button under "devices".
  • Create a new device as normal. You need to give your device a nickname. You can choose to allow Things Connected to generate the Application Session Key and Network Session Key or, click on the "edit" button to enter your own values. Then click on the "next" button.
  • When you set-up the route click on the sandbox button.
  • You will then be shown the device keys that you can load onto your device. Click "done".
  • Programme your device with the Keys and Device address

Now all traffic sent from the device and received by the network will be sent to the sandbox.

  • To view the messages received by the sandbox, click on the gear icon for the corresponding device
  • Then click on the sandbox packets tab.
  • You will see a list of the received messages.
  • You can view the raw JSON by clicking on the eye icon for the corresponding message.
  • You will be able to view the JSON that is received by the sandbox which is in the same format that would be sent to you real server

Once you are happy that your device is functioning correctly, and you have developed your real application server, you can then re-point your device to your actual server.

The RN2483 LoRa Mote is a LoRaWAN™ Class A end-device based on the RN2483 LoRa modem from Microchip. It is a standalone battery-powered node. The Mote provides a convenient platform to quickly demonstrate the long-range capabilities of the modem, as well as to verify inter-operability when connecting to LoRaWAN™ compliant gateways and infrastructure.

The Mote includes light and temperature sensors to generate data, which are transmitted either on a fixed schedule or initiated by a button-press. An LCD display provides feedback on connection status, sensor values and downlink data or acknowledgements. A standard USB interface is provided for connection to a host computer, providing a bridge to the UART interface of the RN2483 modem. As with all Microchip RN family of products, this enables rapid setup and control of the on-board LoRaWAN™ protocol stack using the high level ASCII command set.

You can buy a Microchip MOTE from here.

Once you have un-boxed your MOTE device the next step is to connect it to your computer. For this example we will be using a PC running the simple terminal programme called Termite. You can download Termite from here. You will also need a USB to micro USB cable to connect your MOTE device to your PC.

  • Connect your mote device to you PC using the USB cable.
  • Your computer will detect the device and install the necessary drivers to communicate with it. Wait until this process has finished before continuing.
  • Launch the Termite programme. WE have used version 3.1. You should see a window what looks like this:
  • Click on the "Settings" button at the top Termite window. You will see a set of Serial port setting options.
  • Configure the options as described below:

    Port configuration
  • Port: [set this to the USB port that the MOTE is connected to]
  • Baud rate: [set this to: 57600]
  • Data bits: [set this to: 8]
  • Stop bits: [set this to: 1]
  • Parity: [set this to: none]
  • Flow control: [set this to: none]
  • Forward: [set this to: none]
  • Transmitted text
  • Select the "Append CR-LF" option
  • Tick the tickbox for "Local echo"
  • Options
  • Tick the tickbox for "Quit on Excape"
  • Tick the tickbox for "Autocomplete edit line"
Click on the "ok" button to save your changes

Click on the button at the top to connect.

Press the enter key a few times on your computer. If all has gone well then you should see "invalid_param" in the terminal window. If this is the case then the Termite is communicating with the MOTE device.

The next step is to generate some Keys and a Device Address to be loaded on the MOTE. Login to your Things Connected dashboard here.

Click on create a new device, enter a nick name and point the device to the sandbox. For help with this, see the "Step-by-step connect ABC device to sandbox" example.

.

Make a note of the Device address, Application Session Key and Network Session key since we will need to programme them onto the MOTE.

In this example we will be using the following values. When you come to set up your MOTE device you will need to generate your own.

Device address: E60C0906
Network session key: 0A1918868391AE88AECDB0EB143C3F2A
Application session key: A3C28476B0C37F2430ADBEBB1921C2A9

Via the Termite terminal enter the following commands:

  • sys factoryRESET to reset the MOTE device to its factory defaults. The MOTE will respond with the build version and date.
  • mac set devaddr E60C0906 to set the device address. The MOTE will respond with "ok".
  • mac set nwkskey 0A1918868391AE88AECDB0EB143C3F2A to set the Network Session Key. The MOTE will respond with "ok".
  • mac set appskey A3C28476B0C37F2430ADBEBB1921C2A9 to set the Application Session Key. The MOTE will respond with "ok".
  • mac save to save the settings. The MOTE will respond with "ok".
  • mac join abp to join the LoRA network. The MOTE will respond with "ok" and "accepted".

N.B. Please note that this does NOT mean that the device has actually joined the network but rather that the MORE device has accepted the command. If for example you are out of coverage then you will still see "ok" and "accepted" in the terminal but the network will not see your transmitted messages.

We are now going to send the message "Hello World!" which we will encode as ASCII characters in HEX format 48656c6c6f20576f726c6421.

  • mac tx uncnf 1 48656c6c6f20576f726c6421 to send the message over port 1. The MOTE will respond with "ok".

Assuming that all has gone well the message will have been sent by the MOTE and received by the Things Connected network. You can check this by going to the Dashboard - Devices section, clicking on the gear icon for the corresponding device and then select the Gateway Packets tab. You should see your message in the payload column.

Congratulations

The SODAQ ExpLoRer board is powered by an Atmel SAMD21 MCU, featuring a 32-bit ARM Cortex® M0 core, Arduino compatible, and is equipped with a Microchip RN2483 LoRa module.

You can buy a SODAQ ExpLoRer from here.


Prerequisites

1. Register to Things Connected testbed.

2. Create a new device. For help with this see the “Step-by-step connect ABC device to sandbox” example.


Setup

1. Download and install the latest Arduino IDE.

2. To use the board in the Arduino IDE, you need to load a custom board file for the SODAQ SAMD boards (http://downloads.sodaq.net/package_sodaq_index.json):

File → Preferences

3. Install the latest version of the SODAQ SAMD boards:

Tools → Boards → Boards Manager…

4. Install the latest version of the Arduino library for the Microchip RN2483:

Sketch → Include Library → Manage Libraries

5. Install the serial driver

OSX

  • No driver installation is necessary on OSX.

  • Windows (tested on 7)

  • Connect the SODAQ ExpLoRer board to your computer with a USB cable. Open Control Panel → Hardware and Sound → Device Manager. You should see the “SODAQ” board under “Other devices”. Double click on “SODAQ” and choose “Update Driver”.

  • Select “Browse my computer for Driver software” option and navigate to the folder with the Arduino IDE you installed earlier. Locate and select the “Drivers” folder. Press “OK” and “Next" to proceed.

  • In the Device Manager you should now see a port named “Arduino Zero” under “Ports”.


    Build your first sketch

    6. We will now build a program that sends out the string ‘Hello World!‘ every 10 seconds. Download the “Sodaq_demo.ino” sketch from here. The sketch needs to be inside a sketch folder named “Sodaq_demo”.

    7. Add your own device address and keys to your sketch.

    8. Upload and run the sketch.

    Select “SODAQ ExpLoRer” from the list of boards (Tools → Board → SODAQ ExpLoRer)

    Select the port which your device is connected to from the list of ports:

  • OSX: Tools → Port → /dev/cu.usbmodemxxxx (Arduino/Genuino Zero (Native USB Port)).

  • Windows: Tools → Port → COMx (SODAQ ExpLoRer).

  • Click on the Upload button.

    Note: after uploading the sketch, it could be needed to disconnect and reconnect the board to the USB port in order for the sketch to start.


    9. To view the messages received by the sandbox, see the “Step-by-step connect ABC device to sandbox” example. In the sandbox, the payload is base 64 encoded. ‘Hello World!‘ will appear as SGVsbG8gV29ybGQhAA== which can be decoded here.

    The Pycom LoPy is a triple bearer (LoRa, WiFi, BLE) development platform based on the Espressif ESP32 SoC. It is equipped with a Semtech SX1272 LoRa module and programmable with MicroPython and the Pymakr IDE.

    You can buy the Pycom LoPy and the expansion board from here.

    Note: This tutorial is based on the Pycom quickstart guide that you can find here.

    LoPy module and expansion board


    Prerequisites

    1. Register to Things Connected testbed.

    2. Create a new device. For help with this see the “Step-by-step connect ABC device to sandbox” example.


    Setup

    1. Insert the LoPy module in the expansion board as shown in the following picture (the reset button on the LoPy module should point in the same direction as the USB connector on the expansion board).

    2. Connect the expansion board to your computer with a USB cable. In a few seconds, the LED should start blinking every 4 seconds. This means that everything is fine! If you cannot see the blinking, check the boards position and the USB connection.

    3. Upgrade the firmware.

    4. Download Pymakr from here, install it, and configure it for the first time.


    Build your first project

    5. We will now build a program that sends out the string ‘Hello World!’ every 10 seconds and also waits for messages sent from the server. In Pymakr, go to Project → New. Choose a name for the project (e.g., “hello-world”) and a directory, and select “Python Project” as Project Type.

    6. Every Pymakr project should have at least two files: boot.py and main.py.

  • File → New
    Copy the following code in the editor, click on “Save” and name the file boot (py extension is set by default).
  • Download the LoPy_demo.py script from here.
  • File → New
    Copy the script in the editor and, add your own device address and keys to your script, click on “Save” and name the file main (py extension is set by default).
  • 8. Upload and run the sketch.

  • Click on the “Sync project” button in the Pymakr IDE and wait until the process terminates successfully.
    Note: When synchronizing, make sure the device is connected. Your computer should be connected to the WiFi network named after your board (e.g., lopy-wlan-xxxx).
  • Click on the “Reset” button on the LoPy module to start the script.
  • 9. To view the messages received by the sandbox, see the “Step-by-step connect ABC device to sandbox” example. In the sandbox, the payload is base 64 encoded. ‘Hello World!‘ will appear as SGVsbG8gV29ybGQhAA== which can be decoded here.

    10. To view debug statements on the node side you can use your preferred serial terminal (screen, PuTTY, picocom). As an example, let us use screen as a serial terminal on Mac OS X. Once you have determined which device you want connect to (e.g., run the command ls /dev/tty.*), launch screen (set a baud rate of 115200 bps and replace “xxxxxxxx” with the your device’s serial number):

    This guide will take you through setting up a LoRaWAN™ application server to communicate with devices connected to the Things Connected test bed. To receive PUSH notifications the application server should implement the methods defined in the Everynet Core API.


    Prerequisites


    1. Access to Things Connected testbed

    2. Register a device

    3. Have a machine/server (with a public IP address) to run Node.js on


    Setup


    4. Download and install Node.js

    5. Create a new Node.js project and install the modules needed by the application server:


    cd $HOME

    mkdir app

    cd app

    npm init


    Just press return to accept the default answer to any question asked.


    sudo npm install jayson atob cors connect body-parser btoa


    Implement the application server


    6. Create the main script and open it in your favourite editor:


    vim index.js


    7. Require the modules needed:


    const jayson = require('jayson');

    const atob = require('atob');

    const cors = require('cors');

    const jsonParser = require('body-parser').json;

    const btoa = require('btoa');

    const fs = require('fs');

    const connect = require('connect');

    const app = connect();


    8. Define a log file where to store messages received from the Everynet Network.


    var date = new Date().toISOString().replace(/T/, '_').replace(/-/g, '').replace(/:/g, '').replace( /\..+/, '');

    var filepath = './log_data_' + date;


    9. Create the server, implement the uplink and downlink methods according to the Everynet Core API, start the server on port 9090:


    var server = jayson.server({

    uplink: function(args, callback) {

    /* Print out the uplink message received from the Everynet Network on the console and

    * append it to the log file.

    */

    console.log("Received uplink: " + JSON.stringify(args, null, 4) + "\n");

    fs.appendFile(filepath, "Received uplink: " + JSON.stringify(args, null, 4) + "\n");

    /* Get the payload (base64 encoded), which includes actual data sent by the device,

    * convert it to ASCII format, print it out on the console and append it to the log file.

    * We assume the device is sending a string.

    */

    var buffer = new Buffer(args.payload, 'base64');

    console.log("Payload: " + buffer.toString('ascii') + "\n");

    fs.appendFile(filepath, "Payload: " + buffer.toString('ascii') + "\n");


    callback(null, "200");

    },

    downlink: function(args, callback) {


    /* Print out the downlink message received from the Everynet Network on the console and

    * send back an ACK, which will then be sent to the device.

    */

    console.log("Received downlink: " + JSON.stringify(args, null, 4));

    var reply = {

    payload: btoa("ACK")

    };

    callback(null, reply);

    }

    });


    app.use(cors({methods: ['POST', 'GET']}));

    app.use(jsonParser());

    app.use(server.middleware());

    app.listen(9090);


    10. Run the server:


    node index.js


    Now assume our device is sending a 6-byte payload having the following format:


    In the uplink method, we need to parse the payload as in the following:


    uplink: function(args, callback) {

    /* Print out the uplink message received from the Everynet Network on the console and

    * append it to the log file.

    */

    console.log("Received uplink: " + JSON.stringify(args, null, 4) + "\n");

    fs.appendFile(filepath, "Received uplink: " + JSON.stringify(args, null, 4) + "\n");

    /* Get the payload (base64 encoded), which includes actual data sent by the device,

    * convert it to hex format.

    */

    var buffer = new Buffer(args.payload, 'base64');

    var hex = buffer.toString(‘hex’);

    /* Parse the payload, print it on the console, and append it to the log file */

    var temp = parseInt(hex[2].concat(hex[3]), 16);

    if (temp > 0x7F)

    temp = temp - 1 - 0xFF; // Signed, in two’s complement

    var u_count = parseInt(hex[4].concat(hex[5]), 16);

    var d_count = parseInt(hex[6].concat(hex[7]), 16);

    var voltage = parseInt(hex[8].concat(hex[9]).concat(hex[10]).concat(hex[11]), 16);

    var payload = {Temperature: temp, Uplink_counter: u_count, Downlink_counter: d_count, Battery_voltage: voltage};

    console.log("Payload: " + JSON.stringify(payload, null, 4));

    fs.appendFile(filepath, "Payload: " + JSON.stringify(payload, null, 4) + "\n");


    callback(null, "200");

    },

    Troubleshooting

    If you believe that your device is sending data packets but your end server is not receiving them then there are a few steps that you can take to check what is going wrong.

    One of the first things to check is whether your device is in the coverage area of the Things Connected Network. You can check that here. The coverage map is a prediction of the coverage based on the topology of the area and also assumes that all Gateways are on line. From time to time Gateways may be taken off line so you should also check the Gateways that serve your area are operational. You can check this by going to the Dashboard and clicking on the “Gateway Status” menu option or click here.

    The status page will like this. You can see which gateways are operational “Green” or offline “Red”.

    If you are in coverage and your serving Gateways are operational then the next thing to consider is the antenna on your device. As with all radio technologies the design and size of your antenna will greatly affect the ability to transmit and receive signals.

    If you are certain that you are in coverage, have a suitable antenna and your device is transmitting then the next thing to check is that you have configured your keys correctly. To view the keys for you device click on the gear icon for the given device. This will open a dropdown where you will be able to view the keys. Carefully check that they have been copied to your device correctly.

    If you are certain that they are correct the next thing to do would be to point the traffic to our sandbox. Click here for more details on how to connect a device to the sandbox and how to view packets.

    If, after you have tried all of the steps above, you still can't see any packets then please either post a question on the forum or get in contact with us and we will try to help.

    LoRaWAN tech overview

    Low power networks (LPWANs) such as LoRaWAN™ are able to support services that require infrequent up-link of messages with smaller payloads of a few kilobytes.

    Most LPWAN technologies also allow downlink message transmissions. Depending upon the application needs, LPWAN devices can last up to 10 years on batteries – this significantly increases the range of deployment scenarios and enables new business cases that were previously too costly because of the need of human intervention, e.g. the replacement of batteries.

    LPWANs offers deep indoor penetration due to very high link budgets, extending potential use cases even to cellars and underground environments.

    An important consideration of LPWANs is that battery lifetime decreases with the number of messages and the size of the payload since the device is on air for more of the time. So if your product and service requires a constant stream of data the LPWAN might not be the most suitable network type.

    You need to first understand whether LPWAN or more specifically LoRa is an appropriate communication option. It is possible to swap out your current communication module with a LoRa one, but this will typically require some re-engineering and design of your device software and hardware interfacing.

    Please refer to Lora Alliance and LoRa specification.

    LoRa stands for Long Range Radio. It is the wireless technology targeted towards Internet of Things (IoT) devices, machine-to-machine (M2M) applications and sensor networks.

    The technology and standards have been designed to address some of the key shortcomings of existing radio technologies such as WiFi, Bluetooth and 3G, with particular attention being paid to long range, good in building penetration, low power consumption and low cost of devices and gateways.

    A summary of some of the key technical attributes:
    Range 2-5 Km in dense urban and 15 Km in suburban areas.
    Frequency band ISM band 868 MHz in the UK & Europe and 915 MHz in other regions.
    Standard IEEE 802.15.4g.
    Modulation Spread spectrum modulation type is used which uses wide-band linear FM pulses. The frequency increase or frequency decrease over certain period is used to encode data information to be transmitted. It gives 30dB improvement over FSK.
    Capacity A single LoRa gateway can handle the traffic from thousands of nodes.
    Battery Ignoring the power consumed by peripheral hardware such as sensors, actuators and microcontrollers, the LoRa transmitter can run from a 3000mAH for several years.
    LoRa Physical layer Takes care of frequency, power, modulation,signalling between nodes and gateway.
    Data rate LoRa is designed to support of speeds of upto a few 10s of Kbits per second.
    Device or Node An object with an embedded low-power communication device capable of collecting or generating data and then transmitting it to a LoRa gateway.
    Gateway Antennas and associated receive and transmit hardware that receive broadcasts from nodes forward the data packets into the network. As LoRa is by directional gateways can also send the data back to the Nodes.
    Network The infrastructure that can route messages (data) from Nodes to the right Application, and then back.
    Application A piece of software running on a server that can receive messages (data) sent by Nodes, process it and then do something with it.
    Uplink Message A message from a Device to an Application.
    Downlink Message A message from an Application to a Device.

    Yes it is

    Class A devices support bi-directional communication between a device and a gateway. Uplink messages (from the device to the server) can be sent at any time (randomly). The device then opens two receive windows at specified times (1s and 2s) after an uplink transmission. If the server does not respond within these windows then it will have to wait for the next uplink message before being able to send data down to the device. So while the protocol does support bi-directional communication for class A devices, it is the device that controls when data can actually be sent. Therefore some thought must go into the design of the HW, firmware and application to cater for this. As such a class A device is probably not suitable for an application that would requite on demand actuation such as a garage door opener.

    Class B devices extend Class A by adding scheduled receive windows for downlink messages from the server. Using time-synchronized beacons transmitted by the gateway, the devices periodically open receive windows.

    Class C devices extend Class A by keeping the receive windows open unless they are transmitting. This allows for low-latency communication as a result will have a higher overall power consumption. In the case of our garage door opening application this would not be an issue since the power needed for the mechanism far outrights the power consumption of the device.

    LoRaWAN™ has been designed to include a certain amount of security, authentication and encryption.

    The Network Session key is used to ensure security at network level - from device to the network. The key is 128 bits in length represented by a 32-character hexadecimal string.

    The Application Session key is used to ensure end-to-end security at application level – from device to the users end application server. The key is 128 bits in length represented by a 32-character hexadecimal string.

    This security is built into the LoRa standard. A developer is of course free to further encrypt the data payload should they have the requirement to do so.