LoRa Device Tutorial

When setting up a LoRa client device, you need to do five main steps:

1. Setup the firmware on the specific device and get the LoRa DevID (specific to device, see below)
2. Create a description for the device in OpenChirp (described in Device Tutorial)
3. Add the LoraWAN service in OpenChirp and input the DevID
4. Add a TimeSeries datastore service
5. Add a decoder service (Byte Translator or Easybits)

It is worth noting that for commonly used devices, this can all be captured in a Device Template. Then the only values that need to be updated are the DevID, AppEUI and AppKey in the LoRaWan Service.

Step 1: Load firmware onto your device

The most important aspect of the firmware on your device will be retrieving its DevID and setting an appropriate AppEUI and AppKey. The DevID is used to tell the network to look for your device. The AppEUI and AppKey are used for the network to correctly authenticate to your device. In OpenChirp you can set your own AppEUI and AppKey when linking in your device. The DevID comes from the device itself.

A typical AppEUI is a 16 digit hex number like a4bb2648d72729c1 and typical AppKey is a 24 digit random hex string like 205ec39077cfe73560ed6678. Both can be shared across all of your devices, but the DevID is unique for each device.

To pseudorandomly generate hex string, run the following in python:

import random, string

rand_str = lambda n: ''.join([random.choice(string.hexdigits[:-6]) for i in xrange(n)])

print("Application EUI: %s Application Key: %s" % (rand_str(16), rand_str(24)))

Though the firmware is specific to your device, here are some common devices with examples that work with OpenChirp:

• PyCom LoPy
• LoRaBUG
• MultiTech Mdot

Step 2: Create a device in OpenChirp

Creating a LoRa client device is the same as creating any other OpenChirp device. Please follow the Device Tutorial.

Step 3: Adding the LoraWAN service

Once you have a device in hand with its DevID and you have created an OpenChirp Device with a known end point, you need to add the LoRaWAN service.

Go to your device and click on the "Services" tab at the top. Enter the parameters as shown below:

Once your device has joined the network, you can refresh your browser and see the updated status as shown below:

Step 4: Adding a Timeseries Datastore

At this point, you can also add the TimeSeries Datastore service (no parameters required) and see if your base64 encoded messages are appearing in rawrx in the Transducer tab. A timeseries data store must be added to automatically populate the transducer when data arrives.

At this point, if you see base64 data, you have successfully linked your device!

Step 5: Adding a packet decoder

In order to covert the base64 data into actual values, you can use one of the various packet decoders provided within OpenChirp. The key is mapping the raw byte values in the stream sent over the air from your device into actual Transducer elements. These can then be easily viewed and utilized by other services or applications. We have two main options:

1. Byte Translator
2. Easybits

Byte Translator simply translates the elements in a binary array into decimal values and maps them to a transducer name. So for example, if you send the following three values:

uint8_t array[4];
uint8_t light;
uint16_t temp;
uint8_t humidity;

in C you might send them in an array like this:

array[0]=light;
array[1]= temp >> 8;
array[2]= temp & 0xFF;
array[3] = humidity;
status=lora_send(array,sizeof(array));

If you add the ByteTranslator Service, you can decode this with the following:

Easybits uses Google ProtoBufs to transmit data. This is slightly more involved but has the advantage of being able to cope with fragmentation and automatically applying compression. More advanced applications or those requiring packets longer than a few bytes should consider using it.

You can also transmit downstream data by creating a rawtx transducer. This expects base64 encoded data similar to what arrives in rawrx. This data will be transmitted to your node as a standard byte array. You can either write directly to rawtx or link it in a similar manner to transducers the way we did for the upstream data.