AllWize loves The Things Network
Whether you are an IoT professional, lover (like us) or maker we are confident you have heard of The Things Network (TTN). The Things Network is an initiative born in 2015 in Amsterdam to provide the hardware, software and tools to help build local communities around LoRaWAN.
LoRaWAN, just like Wize, allows the users to build their own infrastructure, no need to have a contract with a provider. Back in 2015 that was somewhat expensive for most people so TTN pushed to have cheaper hardware, built Open Source network tools and helped local people gather and build something together. We love that!
You might ask what does this have to do with Wize. Aren’t LoRa and Wize two different radio protocols/modulations? Indeed. But a good thing about TTN is that you can easily create projects that cover the whole stack: from the device to the gateway to the network server to the application server to your own end-user application, and only one step in this stack uses Lora: from the device to the gateway. The rest of the solution is (almost) agnostic to the radio technology you use…
So why don’t we use Wize instead for that and benefit from Wize unique features? Sure we can. There are some issues in the way but we can sort them out. For instance: since the decoding is done in the application server we have to build and send a LoRaWAN frame from the node. So what we will do is to encapsulate a LoRaWAN frame inside a Wize frame in the node, open it up in our Wize gateway and send the original LoRaWAN message up to the network server, pretending we are a LoRaWAN gateway…
Tricky? Maybe, but we have been working on a way to ease things for you. Keep reading!
What do I need?
You will need the basic AllWize infrastructure: a node and a (single channel) gateway. You can use an AllWize K2 or an AllWize K1 shield on top of an Arduino Leonardo for the node. Plus any sensors you want to use, of course.
As a gateway you can use an AllWize G1. The G1 is nothing but a K1 on top of an ESP8266-based board like a Wemos D1 R2 and it does the Wize to WiFi bridge.
You will also need a WiFi access point to provide internet access to the gateway so it can reach the TTN LoRaWAN Network Server.
And finally you need a free account at the TTN console. We will be able to see our faked LoRaWAN gateway and also the messages from the devices. More on this below.
Wize & LoRaWAN
LoRaWAN is built on top of LoRa, a radio modulation. That is, a way to send digital data over electromagnetic waves. And a very clever way by the way. But LoRa only defines the physical part of the transmission. LoRaWAN defines the rest of layers on top of the physical layer, including the network layer and the application layer.
Wize on the other side defines both the radio modulation (technically EN13757-4) and the network and application layers. But what we care about here is the application layer, that is: how do we encode the message.
The LoRaWAN frame format looks like this:
Some interesting bits here:
The Message Integrity Code (MIC) is created using information that’s specific for each message and encrypting it using AES128 and the Network Session Key. This 4-bytes number is used by the Network Server to tell if a message belongs to the network.
The Device Address is unique for each device.
The Frame Counter holds an incrementing counter with each message
The Frame Port is used to help the final application identify the contents of the payload
And finally, the Frame Payload holds the original application payload encrypted using the Application Session Key
Let’s see now the Wize Application Frame format:
Even though the schema looks different, the contents are very similar, we have a A-field which is the device address, the L6-Cpt is the counter, the L6-App is equivalent to LoRaWAN’s Frame Port and finally the payload goes into the L7-Ciph (encrypted or not). So we can easily encapsulate a LoRaWAN message inside a Wize message without too much redundant data.
This looks too techie and complex. The good thing is that we created a wrapper around our AllWize library that does exactly that:
Creates a LoRaWAN frame from your data
Encapsulates it into a Wize message removing dupplicate data to keep the physical payload as short as possible
Sends it using Wize
And then, in the gateway, rebuilds the original LoRaWAN message, ready to be transmitted to the LoRaWAN Network Server
The wrapper class is included with the main class and it’s called “AllWize_LoRaWAN”. Let’s see how to use it.
Examples
First, you can find full examples of both a node and a gateway in the library examples, look for “allwize > lorawan > lorawan_gateway” and “allwize > lorawan > lorawan_node”. Here we are going to cover the important bits of code.
The Things Network Console
This is when you need to have an account at the The Things Network Console. We will first create a new application (name it however you want) and a new device inside the application. You can name the device as you wish and let the console create random EUI (the device identifier) for you.
The only requirement we have is that the device activation method must be ABP (Activation By Personalisation). This is because our solution only supports uplinks at the moment and the other activation method (Over the Air Activation or OTAA) requires a negotiation between the node and the backend, thus a downlink… You can change that in the device settings tab.
The Node
Check the full AllWize LoRaWAN Node code.
We will use the AllWize LoRaWAN wrapper both in the node and the gateway, so instead of the usual include we will have:
Here we are using an AllWize K2 board, hence the SerialWize object. See how to add support the AllWize K2 inside the Arduino IDE. The node initialization looks just like a normal Wize node:
Nothing different here, just remember to use the same channel and data rate in the nodes and the gateway.
Now, here it comes the LoRaWAN specific part. If you have programmed a LoRaWAN node before this code will look familiar:
First we define the device address (DEVADDR) and the Network and Application Session Keys (NWKSKEY and APPSKEY). We get those from the device we just created using the TTN console (just click on the “<>” sign and then copy the contents).
Finally we call the joinABP method to store the values and do some inside configuration. This method belongs to the AllWize_LoRaWAN class, of course.
Now we are ready to send a message. And this couldn’t be simpler:
This will simply send a byte (42, the answer to everything). Of course you will want to do something more complex like sending sensor data. We recommend you to take a look at two different payload encoding libraries: CayenneLPP and MBUSPayload. You can find examples on how to use them in the AllWize library slave examples.
The great thing about Cayenne is that TTN has a built-in decoder for it. This is how you would use it, first including the library:
And then building the payload and sending it:
Great, we are half way there. Let’s move to the gateway.
Wize 2 TTN bridge
The Wize to TTN gateway code is a little more involved but we moved all the configuration to an external file. You will first have to rename the “configuration.sample.h” file to “configuration.h” and then edit it to suit your configuration. Basically change the WiFi credentials and the forwarder configuration (leave the forwarder server and port untouched if you are going to use TTN Europe server).
Again, remember to use the same channel and data rate than in the node.
The most important feature of the gateway code is that it “speaks” Semtech’s Legacy Protocol. This is one of the “official” ways to send data to a LoRaWAN Network Server. That is how we will send the info to TTN, pretending we are a LoRaWAN gateway.
To build the code you will have to have support for the ESP8266 platform inside the Arduino IDE. Here you have a good tutorial about it. At the time being the library does not support the last version of the ESP8266 Core, just keep it in version 2.5.0.
Now select the Wemos D1 R2 board, build and flash it. If you open the serial monitor now at 115200bps and you see something like this, then it’s working!
It’s working and it’s sending messages, but, where are they?
Claim your gateway
Now we have to claim our gateway. That is: telling TTN that this gateway is ours. The gateway ID is the EUI in the message above (600194FFFF79602D in this case). We will go back to the TTN console and create a new gateway. In the creating form we will chose “I’m using the legacy packet forwarder” and enter the ID before:
Once the gateway is registered you will start seeing the messages in the “Traffic” tab.
As you can see the TTN Network Server is tricked to show it as a “FSK Wize” message, but this is only makeup, the application really doesn’t know or care about that.
Also, if you visit your device page now and click on the “Data” tab you will see the data there, decoded and ready for you.
And now what?
The Things Network only provides the routing service: help you get your data where you want. You can enable several integrations with third party tools from the console itself and it also has an MQTT API for data so you can easily get your data anywhere you want.
But that’s another story!