LoRaWAN Workshop

From Things Calderdale Wiki
Jump to: navigation, search

Introduction

This workshop aims to introduce you to the LoRaWAN long lange, low power wireless technology, and crowdsourced data network for IoT, The Things Network.

The workshop uses the IoTUK Boost LoRaWAN Development Kit that is based around the Arrow SmartEverything LION board (Microchip SAMD21 MCU and Microchip RN2483 LoRaWAN module).

The SmartEverything LION has the Arduino form factor and compatible headers, and can be programmed via the novice friendly Arduino IDE, making it easy to prototype devices.

Getting started

If you’re not already familiar with LoRaWAN and/or The Things Network (TTN), see:

Workshop examples

The files required for the workshop are available at:

The zip file should be downloaded and expanded. This contains copies of the Arduino libraries and sketches (code) used in the workshop.

The Sketches folder should be copied to your sketchbook folder, the location of which can be found from the Arduino IDE preferences menu option.

Datasheets for the LoRaWAN module and sensors are also included in the zip file.

Software prerequisites

Arduino IDE

If you do not already have the Arduino IDE installed, you will need to download and install this.

Once the IDE is installed, some additional components will need to be installed.

SmartEverything LION board support

The SmartEverything LION uses the Microchip SAMD21 microcontroller and support for this needs to be installed.

Start the Arduino IDE and go to the menu Tools -> Board -> Boards Manager…

Search for and install support for Arduino SAMD Boards.

Arduino BoardsManager SAMD.png

Once SAMD support has been installed, search for and install support for Arrow boards.

Arduino BoardsManager ArrowBoards.png

Sensor and display libraries

It is best to install the required libraries via the Library Manager, using menu Sketch -> Include Library -> Manage Libraries…

First search for OneWire and then pick the one shown below.

Arduino OneWire installation.png

Next, search for and install DallasTemperature.

Arduino DallasTemperature installation.png

Then repeat the process for:

  • SmartEverything Lion RN2483
  • SmartEverything SE868-AS
  • Adafruit GFX Library
  • Adafruit ST7735 Library

Alternatively, the contents of library folder extracted from the zip file should be copied to your Arduino libraries folder.

Selecting the SmartEverything LION board

At this point if the Arduino IDE is open it should be restarted.

When using the SmartEverything LION board ensure that you select the correct board from the Tools -> Board menu as shown below.

Arduino ToolsBoard.jpg

Create a TTN account and application

Point your web browser at:

If you already have an account then follow the Already have an account? link to login. Once you have successfully registered, you should login and follow the link for the Console.

From the Console select Applications. Here the TTN applications that you have created are listed, or it will be empty if this is your first time here. Click the add application link and enter an application name, for example, "LoRaWAN Workshop".

The application page will list the App EUI (a unique identifier for the app) as a series of hexadecimal numbers. The ‘< >’ symbol in front of this will change the output format. Pressing it once will give a series of hex values suitable for pasting into the sketches. Pressing this again will change the format to least significant bit first and then to hex. Select msb for this workshop. Use the copy icon to take a copy of the values when needed.

TTN Add Application.jpg

Once you have your account and an application created you are ready to start using the SmartEverything LION board.

Projects

Note that when using the example sketches, the debug output, if any, can be seen using the Arduino Serial Monitor function. A lot of the examples will have code similar to:

// Waiting for the USB serial connection
while (!Serial) {
  ;
}

This will wait for the serial connection to be established before continuing. However if you are using batteries or not using the serial connection then your device will appear to hang. If the example has not already been updated then it is recommended to comment it out:

// while (!Serial) {
//   ;
// }

There is a function that will detect if the SmartEverything Lion board is running on batteries and operate appropriately. However, at the time of writing this does not appear to work 100% of the time.

Ascertain and set device parameters

Get the RN2483 module EUI

Use the example sketch getChipInformation.ino from the SmartEverything LION RN2483 library, to obtain the device EUI so that this can be registered against the TTN application you have previously created.

Once the sketch has been uploaded to your SmartEverything LION, open the serial monitor (CTRL+SHIFT+M) and you should see an output similar to below. (use 115200 baud)

GetChipInformation.png

Register the device to the TTN application

After running the sketch, you can now register the device with your application on the TTN Console.

TTN Register Device.jpg

Select the application you created and then navigate to the Devices tab. In the Devices section, click the register device link. Select OTAA (Over-the-Air Activation) and copy the EUI value from the serial monitor window as highlighted above. This value is pasted into the Device EUI box. Click the Register button and the device will be added to the system. You should now see something like:

TTN Device Params.jpg

Configuring Arduino sketches

You will need to ensure that in the workshop sketches the App EUI and App Key values are pasted in the appropriate places. Use the Copy to clipboard icon to copy the value in the appropriate format.

For example, where the application EUI is set:

#define APP_EUI "xxxxxxxxxxxxxxxx"

Using the value shown above would give:

#define APP_EUI "70B3D57EF0004C61"

And where the application key is set:

#define APP_KEY "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Using the value shown above this would give:

#define APP_KEY "C16AFE1239E1276CC00AEC701CAF106A"

Obviously you will need to use the values that are associated with the TTN application you created earlier.

Note: The Things Network currently requires devices to be registered before they can be used. There is a new feature to be released soon that will allow devices to be registered to an application upon first activation. This should enable new devices to be setup much more quickly than at present.

Basic network uplink (sending data)

Open the sendDataOTA_Console.ino sketch.

After configuring the sketch using your application EUI and key, then compiling and uploading it to the board, you should see the output in the Arduino Serial monitor window. If the LoRaWAN join fails then you should see a response denied message as shown below (at the time of writing spelling errors exist in the library examples).

ConsoleUplinkDenied.png

When the App EUI and Keys are correctly entered, you should see a successful join and transmission of example data.

ConsoleUplinkSuccessful.png

You should also see an entry in the message box on the TTN device page.

Refreshing the page and looking at the Device Info section, you should now see the device has been activated. This also shows the Network session and Application session keys that have been generated when the device joined the TTN network.

Decoding data

TTN Device Payload.jpg

The default payload display will show the hexadecimal representation of the data. To display this in a more meaningful manner you can set the Application payload format. These changes will apply to all devices using the same application. It is therefore advisable that if you have devices with different data formats, that you use separate applications for them.

Select a custom payload format and set the Decoder Javascript to that shown below. This will decode the payload into a string of characters representing the temperature reading for the next example.

function Decoder(bytes, port) {
   // Decode an uplink message from a buffer
   return {
     message: String.fromCharCode.apply(null,bytes)
   };
}

Temperature sensor

LoRaWAN Workshop TempSensor Breadboard.jpg

The sketch OTA_Temperature.ino takes readings from a DS18B20 digital temperature sensor and sends these via network uplink. The circuit should be wired as shown in the images above and below.

Note that here two 2K2 resistors in series have been used, but a single 4K7 pull-up resistor can be used instead. This connects the centre pin to the positive rail on the breadboard.

LoRaWAN Workshop TempSensor Breadboard-detail.jpg

The yellow wire is connected to D4 on the SmartEverything board. The LED is not used in this example sketch.

Using the OTA_Temperature sketch, update the Application ID and key. On the TTN console you should now see a regular temperature update. If you have updated the Payload decoder you should now see the temperature displayed correctly.

TTN Temperature Data.jpg

Downlink control

The OTA_DownlinkLED.ino example demonstrates the ability for the device to receive messages and perform an action based on the message. Using the Downlink option on the device screen, entering a value of either 01 to turn on the LED or 00 to turn off the LED on the SmartEverything board.

TTN Downlink Control.jpg

The LED will not change immediately as the LoRaWAN protocol requires the device to contact the gateway first. When a message has been sent from the device it waits for any pending downlink messages. The downlink message FPort value must be set to 1 for this example to work. The different port values enable messages for different control purposes and formats to be used.

Downlink messages

This example sketch should be configured with the App EUI and key as previously described. The display should be plugged into the SmartEverything LION board. Once the sketch has been uploaded to the board it will periodically send an incrementing count. If there are any downlink messages pending then they will be displayed.

The TTN downlink messages must be entered as a series of 2 hex digit hexadecimal numbers.

There are websites available that can generate the values from simple text strings such as https://www.branah.com/ascii-converter shown below.

ASCII Converter.jpg

The options to select include Convert white space characters and Remove 0x otherwise your message will not be converted to the correct format.

The hexadecimal value in the output box should be copied and pasted into the Payload field on the TTN console.

TTN Downlink Message.jpg

Clicking Send will queue the message for transmission. Once the message has been received, the display should show the message in both hexadecimal and ASCII formats.

LCD Downlink.jpg

GPS position uplink

The OTA_GPS_Display.ino example uses the GPS receiver to determine our position and send this in the LoRaWAN payload. A suitable application can then decode the payload and record or plot the location of the device. This can be used as a simple tracking or range testing device. When combined with the downlink and payload acknowledgements this can be an effective tool to determine your gateway coverage.

It has been found that the GPS receiver can take a long time to produce a GPS lock when used indoors. Part of the problem could be the small antenna and the positioning under the display shield. In your own products, using a larger or external antenna should give better results.

The sketch will display the location and date/time information once a lock has been established. When a location is determined, this information is packaged into the LoRaWAN payload and sent to the gateway. In order to decode this you can either create a new decoder on the TTN application or process the data elsewhere.

An example TTN decoder to decode the location data and output a JSON message is shown below:

function Decoder(bytes, port) {
  // Decode an uplink message from a buffer to determine latitude/longitude
  var latInt = (bytes[3] << 24) + (bytes[2] << 16) + (bytes[1] << 8) + bytes[0];
  var lonInt = (bytes[7] << 24) + (bytes[6] << 16) + (bytes[5] << 8) + bytes[4];
  var altInt = (bytes[9] << 8) + bytes[8];
  var lat = ieee32ToFloat(latInt);
  var lon = ieee32ToFloat(lonInt);

  var position = { latitude: lat, longitude: lon, altitude: altInt };
  return {
    message: position
  //  message: String.fromCharCode.apply(null,bytes)
  };
// Function to convert binary to floating point value
function ieee32ToFloat(intval) {
    var fval = 0.0;
    var x;//exponent
    var m;//mantissa
    var s;//sign
    s = (intval & 0x80000000)?-1:1;
    x = ((intval >> 23) & 0xFF);
    m = (intval & 0x7FFFFF);
    switch(x) {
        case 0:
            //zero, do nothing, ignore negative zero and subnormals
            break;
        case 0xFF:
            if (m) fval = NaN;
            else if (s > 0) fval = Number.POSITIVE_INFINITY;
            else fval = Number.NEGATIVE_INFINITY;
            break;
        default:
            x -= 127;
            m += 0x800000;
            fval = s * (m / 8388608.0) * Math.pow(2, x);
            break;
    }
    return fval;
} 
  
}

It currently only decodes the Lat/Lon and altitude values. The remaining payload data is defined in the payloadDataStruct within the sketch.

References

LoRa/LoRaWAN

The Things Network

Communities

Hardware

Software

Integration services

DIY Integration

Development services

Authors

Workshop materials developed by:

Thing Innovations.jpg

With minor edits by:

AB Open.jpg