Home
(work in progress)
MoRa is a repository including software, hardware configuration and documentation related to the expermenting activities about LoRa/LoRaWAN technology carried out in Modena by Davide Gariselli and Alberto Trentadue.
Repository's resources can be used to implement demos and/or kick-starters for further projects using LoRaWAN as digital communication infrastructure for the Internet of Things (IoT).
Very short introduction to LoRa and LoRaWAN.
MoRa development is aimed to deliver one of the possible implementations of a communication infrastructure for the IoT using LoRaWAN as network and LoRa as last hop communication technique.
The Things Network (TTN) project is an authoritative example of LoRaWAN infrastructure implemented world-wide in Open Source and MoRa holds it as reference for many fundamental aspects.
However, we decided to implement (for now) an infrastructure independently from TTN in order be able to study in detail and experiment in first person some LoRaWAN network low-level aspects and issues that are mainly already solved and thus hidden by TTN's software components. Nevertheless, We foresee that MoRa should integrate with TTN in the next future to actively contribute to TTN's objectives fulfillment which we consider very important and worthy for its motivation, its practices and the effects they have in the IoT development for communities.
Ours is a minimalist but complete LoRaWAN network implementation and therefore it follows its standard architecture.
Our implementation includes a node, a gateway and Network Server having both LoRa Server and "Application Server" functions.
As first test gateway we have chosen to follow the design realized by the "The Things Network" work group in Zurich (Switzerland) - the ZH-TTN. They have published the complete project on their Github wiki.
Our Gateway #1 components are:
- Raspberry Pi3 as host controller.
- The IMST IC880a LoRa concentrator - IC880a IMST web site. The IC880a concentrator is the cheapest solution of its service capability, having 8 LoRa channels managed at same time, thus suitable for on-the field, multiple application employment. There are indeed several cheaper solutions as LoRaWAN gateways, e.g. working on single channel of operation.
- The connection backplane between Raspberry and IC880a, developed by one of the TTN-ZH team members, Gonzalo Casas, and available on Tindie
- 868MHz antenna - any antenna will be ok provided that it is designed for the 868MHZ ISM band. The antenna needs a adaptation cable to be connected to the micro-FL connector on the IC880a card.
- An electrical outdoor IP67 box to include all the listed devices. We chose to take a fairly bigger SCAME box in order to possibly allocate more hardware in a possible on-the field deployment.
The integration and installation guide is fully on the TTN-ZH wiki, so please follow that carefully. We have assigned to the Raspberry Pi a fixed IP address to the ETH interface (IP cable), in order to be sure that we can connect the card at any time for maintenance, without having to search for its IP address. Even if there is possibility to connect the RPi3 using its WiFi interface, it is not recommended because it may generate unwanted radio frequency interference so close to the IC880a LoRa radio.
When using the connection backplane, be careful to connect the Raspberry pins in the correct alignment: that's because when mounting it, the connector on the Raspberry is hidden under the backplane and not easily visible.
It is recommended to create a specific user on the Raspberry to run the gateway software.
We created a login named "lora" and having possibility to use the "sudo" command (i.e. configured in the /etc/sudoers file):
$ sudo visudo
Add the line lora ALL=(ALL) NOPASSWD: ALL
For the software installation it is needed to have the Raspberry Pi3 connected to the Internet. Just connect the ETH interface to an Internet router. You can also use the on-board WiFi interface, but remember to deactivate it before actual LoRa operation.
Make sure you have an updated Raspbian installation
$ sudo apt-get update
$ sudo apt-get upgrade
It is neccessary to activate the SPI functionaity in the Raspberry Pi using the raspi-config utility.
It is also recommended to activate the locales for english (GB) and italian (IT) localization by:
$ sudo dpkg-reconfigure locales
$ sudo dpkg-reconfigure tzdata
You will need the git software to compile the Packet Forwarder software.
$ sudo apt-get install git
For the subsequent software installation it is recommended to follow from chapter 2 of the "IC880a Quick Start Guide" PDF file. It can be found on the Internet, for example here.
The needed software, including the Packet Forwarder, is available from the LoRa Net Github Project. It will be downloaded and compiled using git:
As the "lora" user, do the following steps:
$ mkdir -p ~/LoRa/lora_gateway
$ cd ~/LoRa/lora_gateway
$ git clone https://github.com/Lora-net/lora_gateway.git
Configure the build file libloragw/library.cfg like this:
DEBUG_AUX= 0
DEBUG_SPI= 0
DEBUG_REG= 0
DEBUG_HAL= 1
DEBUG_GPS= 0
Now it is possible to compile and build the software. Within the ~/LoRa/lora_gateway directory:
$ make
This will make the Packet Forwarder ready.
For normal operation, it is recommended to configure the Raspberry Pi3 to run automatically the Packet Forwarder at startup.
As Network Server we are currently using a small PC. For testing purposes server hardware is not critical. The PC is (obviously 😉) running Linux. Common distros are OK, such as latest versions of Ubuntu, Mint or Debian.
The Network Server plays the roles of LoRa Server, Application Server and IoT Dashboard all in one. For the LoRaWAN network controller we have chosen the Open Source Loraserver.io suite.
This software set includes an additional component, the LoRa Gateway Bridge, as a separate daemon. This component is a middle layer between the LoRa Server and the gateways available geographically and is introduced so that the Loraserver component may communicate using a common MQTT broker internally and still exposing a standard UDP interface towards the gateways.
For the Loraserver.io software components installation we followed 100% the installation guides available on the LoraServer.io website:
Therefore we will not repeat them here.
The Network Server installation requires the installation of a MQTT Broker. The widely used Mosquitto broker is suitable for the purpose. It can be installed in the Network Server as a common linux software package:
$ apt-get install mosquitto
$ apt-get install mosquitto-clients
The Mosquitto MQTT Broker is by default configured to listen on the 1883 TCP port.
This port is then set inside the the Application Server configuration file /etc/lora-app-server/lora-app-server.toml:
[application_server]
...
[application_server.integration.mqtt]
...
server="tcp://localhost:1883"
The Application Server exposes an HTTPS web interface to manage the configuration of the IoT applications integrated in the system. This interface is configured inside the Application Server configuration file /etc/lora-app-server/lora-app-server.toml:
[application_server]
...
[application_server.external_api]
...
bind="0.0.0.0:8002"
Therefore, the web interface of the Application server will be accessed by a browser at the address:
https://<network_server_ip>:8002/
Here the server Admin can login to manage the overal configuration.
Loraserver configuration follows a data model which organizes items needed to implement an end-2-end application over a LoRaWAN network Below there is a summary of the model entities and they relation, to serve as a guide for the Loraserver configuration:
- Organizations: an Organization represents an entity that owns key items of a LoRa infrastructure: Applications, Gateways and Users. It also owns configuration templates for Applications, called Service Profiles, and for Devices, called Device Profiles.
- Applications: an Application belongs to one Organization and is associated to one of the possible Service Profiles.
- Gateways: each Gateway belongs to one Organization and is identified by the MAC, which is the string obtained by its interface MAC Address
- Users: each User belongs to one Organization and is enabled to access the Application Server data. It may have Admin privileges
- Devices: a Device represents a remote node connected to the network via LoRa. It is associated to one of the possible Device Profiles. Each Device belongs to an Application. Each device is uniquely identified by the DevEUI. The DevEUI must be unique in a Network and in general is assigned by the LoRa Network manager. When the device registers itself into a LoRa Network (using the Over-the-Air Activation (OTAA) mode), it must specify the AppKey, a kind of "passkey" to get connected to the right Application. The AppKey is configured for each device.
It is important to remember that DevEUI and AppKey must be properly configured on the remote note in order to make the OTAA registration successul.
It is necessary to tell the Packet Forwarder on all deployed LoRa gateways which is the Network Server IP address. This IP address must be reachable from the gateways and vice-versa, so usually they are in the same address sub-net.
This is done on the Raspberry gateway host, by configuring the server_address settings inside the "gateway_conf" section of the global_conf.json file in the ~/LoRa/lora_gateway/bin directory
"gateway_conf": {
"server_address": "192.168.1.14",
"serv_port_up": 1700,
"serv_port_down": 1700,
"servers": [ {
"server_address": "192.168.1.14",
"serv_port_up": 1700,
"serv_port_down": 1700,
"serv_enabled": true
} ]
}
As IoT dashboard we are using the Open Source platform Thingsboard. Thingsboard allows for both local in-premise installation or as cloud based usage through the Amazon WS infrastructure. Of course we have chosen the hardest route 😉, and we have installed the local package on the Network Server. Thingsboard has a detailed installation guide on its website, therefore it is recommended to follow that.
As first demo for end-2-end test purpose we have implemented a IoT classic about simple applications, that is a LoRaWAN connected temperature & humidity sensor.
In this application a DHT22 temperature & humidity sensor is read by an Arduino Mini board and its values are send over the LoRa link to an Application Server passing through the LoRa Gateway, the Gateway Bridge and the LoRa Server. These reading are then re-routed to Thingsboard and displayed into graphs in a dashboard.
The sensor node implementation is described above.
LoRa communication is fully oriented to the minimal usage of energy by the remote sensors. Besides the inherent low power required to establish the radio link with the gateway, every possible care must be taken to reduce power consumption at the remote node. Data transmission is one of the most power consuming operation performed by the remote node, therefore it is important to reduce transmit time to the very minimum possible.
In our Arduino code, we have reduced the amound transmitted data to only 3 bytes:
- One byte for the temperature
- One byte for the relative humidity
- A terminating '\0' character
These bytes are copied into a 3-character string and this string is then passed to the LMIC routine to be sent at the appropriate time slot over the LoRa link.
The 3-character string is received as LoRa packet by the gateway and then encapsulated into a JSON document to be relayed to the Network Server (via the Gateway Bridge). The JSON document includes a number of other fields including, among others, the gateway identifier, location and operational status and the link signal strength perceived from the node.
The Gateway Bridge on the Network Server encapsulates in turn the JSON document into an MQTT message directed to the LoRa server. The MQTT topic used to relay the JSON document to the LoRa Server has the form gateway/<gateway_mac>/rx
The LoRa Server receives the document and based on the application and device identifiers (AppEUI and DevEUI), forwards the message to the appropriate Application Server (consider that there may be more than one Application Servers in a deployment)
An important operation is to extract the application data from the JSON document and translate it into usable format (remember that the application data is stil a 3-character string included in the JSON). For this reason the LoRa Server configuration includes the possibility to configure a Decoder for each application deployed. The Decoder is a piece of JavaScript code that takes the JSON document as input and replace the raw data string sent by the remote node in meaningful fields within the JSNO document. In our example the Decoder defined for our demo is:
// Decode decodes an array of bytes into an object.
// - fPort contains the LoRaWAN fPort number
// - bytes is an array of bytes, e.g. [225, 230, 255, 0]
// The function must return an object, e.g. {"temperature": 22.5}
function Decode(fPort, bytes) {
var myObject = {};
var humid = Number(bytes[0]).toString();
var tmp = Number(bytes[1]).toString();
myObject.temp = tmp;
myObject.hum = humid;
return myObject;
}
This piece of code has the effect to modify the JSON so that two additional fields "temp" and "hum" are added in the JSON data object, derived by reading the 2 bytes transmitted by the remote node.