wikiroute

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== IoTLabs: Exploring LoRaWAN ======

In this lab, you will be designing and prototyping the first IoT services based on a LoRaWAN network.

===== - Platform =====

During this lab, you will benefit from the first experimental platform implementing an end-to-end LoRaWAN solution in Lebanon. The platform consists of the following elements:

  * Devices that communicate to one or more gateways via a wireless interface using single hop LoRa and implementing the LoRaWAN protocol. These devices are physically connected to sensors that generate data. 
  * Gateways or base stations that forward frames between the devices and the network server. Gateways are connected to the network server via IP interfaces.
  * A LoRAWAN backend that implements the network server functions and provides frame control and security.
  * Applications that enable to visualize and store the sensor data obtained from the devices. 

[{{ :lora-pilot-architecture.png?direct&650 | Figure 1. Architecture of the LoRaWAN Platform}}]

{{ :img_20170124_160141.jpg?nolink&400 | Outdoor antenna of ESIB}}

<WRAP center round help 100%>
  * What is LoRaWAN? What is the difference between LoRaWAN and LoRa?
  * Illustrate the protocol stacks on the LoRaWAN platform.
  * What elements are IP enabled in the platform? What do you think about IP support in IoT? 
</WRAP>
===== - Backend =====
In a LoRaWAN network, the devices communicate with a Network Server through the gateway. The backend installed in the platform is based on an open-source LoRaWAN network-server https://www.loraserver.io. A web interface is available for configuring the applications and devices on the platform (http://212.98.XX.XX:8080).

[{{::iot-course2122.png?direct&400|| Figure 2. Loraserver web interface}}]

Start by choosing the application named ''IoTCourse2122'' and create a new device. You should provide the following information:
  * A unique device name: ''IoT-GX'' (where ''X'' is your group number)
  * The device description
  * A unique device EUI on 64 bits: click on the circular arrow to generate a random EUI.
  * A unique application key on 128 bits also obtained by random generation.
 
Make sure to choose ''lora-profile'' as a ''Device-profile'' in order to enable OTAA join method.

<WRAP left round help 100%>
  * What does the application key mean? How is it used in LoRaWAN security?
  * Compare the two device activation methods used in LoRaWAN by giving the advantages and shortcomings. 
</WRAP>
===== - Devices =====

Devices in the LoRaWAN platform are implemented on Arduino boards with Dragino shields. The combined module as well as the basic configuration steps are presented in [[exploring_lora|Exploring LoRa lab]]. 

Start by verifying the installation on your PC of the latest Arduino IDE. Unzip the Arduino {{ :mcci_lorawan_lmic_library.zip |LMIC library}} and copy it to your sketchbook library folder as detailed in [[https://www.arduino.cc/en/Guide/Libraries]]. Then, download and open the example sketch {{ :example-code-idoe-iot-lab.zip |example-code-idoe-iot-lab.ino}} with Arduino IDE.

Now you should configure your device with the same identifiers ''DEVEUI'' and ''APPKEY'' as in the backend:

<code c++>
// Change this!
// This should also be in little endian format, see below.
static const u1_t PROGMEM DEVEUI[8]= { };
void os_getDevEui (u1_t* buf) { memcpy_P(buf, DEVEUI, 8);}

// Change this!
static const u1_t PROGMEM APPKEY[16] = { };
void os_getDevKey (u1_t* buf) {  memcpy_P(buf, APPKEY, 16);}
</code>

<WRAP left round tip 100%>
Note that the device EUI should be in little endian format. Hence, the key, ''0badde1cafe2deca'' should be written as ''0xCA, 0xDE, 0xE2, 0xAF, 0x1C, 0xDE, 0xAD, 0x0B'' in the Arduino sketch.
</WRAP>

Let us analyze the radio parameters in the sketch by answering the following questions.

<WRAP left round help 100%>
  * In the setup function, which channels are activated on the device? 
  * What are the different spreading factors on each channel?
  * What is the regulation on the radio channels in LoRa?
</WRAP>

The LMIC library (see {{ :lmic-v1.5.pdf | documentation}}) defines a set of events corresponding to the protocol machine state. These events appear in the ''onEvent()'' function.

<WRAP left round help 100%>
  * What is the difference between the JOINING and the JOINED events? 
  * When is the EV_TXCOMPLETE event called?
</WRAP>

Finally let us look at the message sending on the device.

<WRAP left round help 100%>
  * What is the function for sending messages on the device? How it is called?
  * What is the period of message sending? Explain the implementation choice.
  * Is this period guaranteed according to the LoRaWAN specification?
</WRAP>

Now you are ready to compile the sketch and upload it to the LoRaWAN device. Connect the device to a USB port on your PC, choose the board type as presented in [[exploring_lora|Exploring LoRa lab]] and select the corresponding port. Compile and upload!

<WRAP center round todo 60%>
Debugging causes memory problems on Arduino One and duemilanove. Debug level should stay 0.
</WRAP>

Open the serial monitor in the Arduino IDE at 115200 baud and analyse the debug messages.

<WRAP left round help 100%>
  * Explain the obtained debug messages.
</WRAP>

Getting back to the backend, you can monitor some important information related to your device. Click on the corresponding device activation.

<WRAP left round help 100%>
  * What are the different fields that appear in the device activation corresponding to you device?
  * Explain how each field is created according to the LoRaWAN specification.
  * What are the different counters visible at the backend? Explain how they get incremented and how they are used.
</WRAP>

[currently not working] The backend also enables to capture LoRaWAN frames. Click on ''LORAWAN FRAMES'' for your device and answer the following questions accordingly.

<WRAP left round help 100%>
  * Explain the different fields in the packet header.
  * What are the parameters of the LoRa modulation? Explain.
  * What is the value of the payload?
</WRAP>

===== - Applications =====

<WRAP center round todo 60%>
If you have an android smartphone, download mqtt dashboard and try it!
Do not forget user credentials.
</WRAP>

mqtt-spy is an open source utility intended to help you with monitoring activity on MQTT topics. It has been designed to deal with high volumes of messages, as well as occasional publications. mqtt-spy is a JavaFX application, so it should work on any operating system with an appropriate version of **Java 8 installed** (if you encounter problems [[https://mqttfx.jensd.de|MQTT.fx]] can be used). A very useful tutorial is available on [[https://github.com/eclipse/paho.mqtt-spy/wiki]]. The tool can be directly downloaded from this {{ :mqtt-spy-1.0.0.jar.zip |link}}.

You can use mqtt-spy to debug the messages received from the LoRaWAN devices. After starting the application, configure a new connection to the MQTT broker by simply adding the IP address of the broker in the ''Server URI'' field. Now you can subscribe to any MQTT topic. If you want to receive all messages arriving at the backend, you can use the generic topic ''#''. You can also limit to the topic including the messages of any specific device: ''application/APPLICATION_ID/device/DEVICE_EUI/rx''. 

<WRAP left round help 100%>
  * Summarize the concepts and functionalities of the MQTT protocol.
  * What are the possible strengths and weaknesses in terms of security of MQTT?
  * What are the different types of topics used by the backend? Explain.
  * Explain the different fields in a captured MQTT message received from you device. 
</WRAP>

<WRAP left round tip 100%>
The payload (data field) received by the MQTT client is decrypted but encoded in Base64. You should decode it to get the original message (using for instance [[https://www.base64encode.org]]). 
</WRAP>

If you need to send data to your device, you should publish an encoded message in the corresponding topic ''application/APPLICATION_ID/device/DEVICE_EUI/tx'' as follows:

<code>
{
    "confirmed": false,                        // whether the payload must be sent as confirmed data down or not
    "fPort": 10,                              // FPort to use (must be > 0)
    "data": "...."                            // base64 encoded data (plaintext, will be encrypted by LoRa Server)
}
</code>

<WRAP left round tip 100%>
The payload sent by the MQTT client must be encoded in Base64.
</WRAP>

You can also download a {{ :mqtt-emoncms-eguz-script.py.zip | python script}} that automates the data retrieval from the MQTT broker .
===== - LoRaWAN Challenges =====
Implement and provide technical documentation for each of the following challenges.

==== - The End-to-End Challenge ====
I can send data from the device to the application.

<WRAP center round tip 100%>
Note that the ''String'' function can be used to cast the message you want to send in a string format.
</WRAP>

==== - The Downlink Challenge ====
I can send data from the application to the device.

==== - The Radio Challenge ====
I can tune the LoRa radio parameters.

These two commands can be helpful when used after the join event:

<code c++>
LMIC_disableChannel(N);
LMIC_setDrTxpow(DR_SF12,14);
</code>

==== - The Sensor Challenge ====
I can use different sensors to send data from the device: PIR, moisture, temperature, light, etc. 
<WRAP center round important 100%>
When connecting sensors, check the pin mapping for unused pins https://wiki.dragino.com/index.php?title=Lora_Shield
</WRAP>