Showing localization data on Qubitro

Qubitro

8 min readMay 13, 2022

In this post, you will learn how to send localization data from a LoRaWAN device and show it on a map panel in Qubitro.

This project requires some hardware and the configuration of two IoT platforms. Let´s start.

What you need for this project

To implement this project, you will need the following:

Board WisBlock Base RAK5005.
WisBlock Core RAK4630.
WisBlock Accelerometer Sensor RAK1904
WisBlock GPS Sensor RAK1910
USB Cable
Access to a LoRaWAN network, or your own LoRaWAN gateway.
The Arduino IDE https://www.arduino.cc/en/Main/Software
Some Arduino libraries — we will see them later.

Also, you will need to have an account in The Things Networks and Qubitro.

Connecting and programming the hardware

Let´s start with the hardware.

First, you have to connect all the pieces carefully, as shown in the following picture.

Pay attention to using the correct slots, and take care of not forcing any connection. After connecting a component, use the tiny screws to keep it secure.

Once all the hardware is in place, you can connect the board to your computer using the USB cable. The drivers used to communicate with the board are generally recognized and installed by the operating system. I’ve tried with Windows 10 professional, and it works without issues.

Preparing the Arduino IDE

We are going to use the Arduino IDE for programming the hardware.

If you don’t yet have the Board Support Packages — BSP — you will need to download and install them in your Arduino environment. You can see a complete tutorial on this link — https://github.com/RAKWireless/RAKwireless-Arduino-BSP-Index.

Once you have the BSP installed, you will be able to access the RAK boards definitions and the examples from the Arduino IDE.

The next step consists of selecting the right board. In this case, we will select WisBlock RAK4631, as you can see in the following figure.

Finally, you will have to install a couple of libraries:

SparkFun LIS3DH Arduino library. This library implements the communication with the LIS3DH accelerometer.
SX126x-Arduino library. This library is used to communicate with the SX1262 LoRa transceiver.

OK, now you are ready to start programming the board.

The Code

The code for this project is available in the Github account of RAK Wireless. You can get it from https://github.com/RAKWireless/WisBlock/blob/master/examples/RAK4630/solutions/GPS_Tracker/GPS_Tracker.ino

Let’s inspect the main parts of this code.

First, you have the declaration of all the libraries used in the code.

Then, the parameters used in the LoRaWAN configuration appear.

bool doOTAA = true;   // OTAA is used by default. 
#define SCHED_MAX_EVENT_DATA_SIZE APP_TIMER_SCHED_EVENT_DATA_SIZE /**< Maximum size of scheduler events. */
#define SCHED_QUEUE_SIZE 60            /**< Maximum number of events in the scheduler queue. */
#define LORAWAN_DATERATE DR_5           /*LoRaMac datarates definition, from DR_0 to DR_5*/
#define LORAWAN_TX_POWER TX_POWER_15          /*LoRaMac tx power definition, from TX_POWER_0 to TX_POWER_15*/
#define JOINREQ_NBTRIALS 3            /**< Number of trials for the join request. */
DeviceClass_t gCurrentClass = CLASS_A;         /* class definition*/
LoRaMacRegion_t gCurrentRegion = LORAMAC_REGION_AU915;    /* Region:AU915*/
lmh_confirm gCurrentConfirm = LMH_UNCONFIRMED_MSG;      /* confirm/unconfirm packet definition*/
uint8_t gAppPort = LORAWAN_APP_PORT;         /* data port*/

Notice that there are some important parameters. You will have to set some of them according to your localization and needs.

First, the doOTTA lets you specify the type of activation. You should use OTAA whenever you can. If you put this to false, the node will use ABP.

To specify the data rate, the transmit power, and the region, take into consideration the region. For instance, in Argentina, these parameters are DR_5, 15 dBm, and AU915, respectively. You can see the values for your area in this document — for LoRaWAN 1.03 — https://lora-alliance.org/wp-content/uploads/2020/11/lorawan_regional_parameters_v1.0.3reva_0.pdf

The next step is setting the LoRaWAN keys. Again, depending on the activation mechanism you choose, you have two options: OTTA keys and ABP keys.

//OTAA keys !!!! KEYS ARE MSB !!!!
uint8_t nodeDeviceEUI[8] = {0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x33, 0x33};
uint8_t nodeAppEUI[8] = {0xB8, 0x27, 0xEB, 0xFF, 0xFE, 0x39, 0x00, 0x00};
uint8_t nodeAppKey[16] = {0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88};// ABP keys
uint32_t nodeDevAddr = 0x260116F8;
uint8_t nodeNwsKey[16] = {0x7E, 0xAC, 0xE2, 0x55, 0xB8, 0xA5, 0xE2, 0x69, 0x91, 0x51, 0x96, 0x06, 0x47, 0x56, 0x9D, 0x23};
uint8_t nodeAppsKey[16] = {0xFB, 0xAC, 0xB6, 0x47, 0xF3, 0x58, 0x45, 0xC7, 0x50, 0x7D, 0xBF, 0x16, 0x8B, 0xA8, 0xC1, 0x7C};

In this tutorial, we will not explore the whole code. However, you should take a look at it for a better understanding.

The code below gets the GPS data and encodes it to send it in a LoRaWAN frame. Inspecting this code, you can build your decoder in your network server. Also, you can add data from other sensors adding more data buffers.

unsigned long age;  
      gps.f_get_position(&flat, &flon, &age);
      flat == TinyGPS::GPS_INVALID_F_ANGLE ? 0.0 : flat;
      ilat = flat * 100000;
      flon == TinyGPS::GPS_INVALID_F_ANGLE ? 0.0 : flon;
      ilon = flon * 100000;
      memset(m_lora_app_data.buffer, 0, LORAWAN_APP_DATA_BUFF_SIZE);
      m_lora_app_data.port = gAppPort;
      m_lora_app_data.buffer[0] = 0x09;
      //lat data
      m_lora_app_data.buffer[1] = (ilat & 0xFF000000) >> 24;
      m_lora_app_data.buffer[2] = (ilat & 0x00FF0000) >> 16;
      m_lora_app_data.buffer[3] = (ilat & 0x0000FF00) >> 8;
      m_lora_app_data.buffer[4] =  ilat & 0x000000FF;
      if(direction_S_N == 0)
      {
        m_lora_app_data.buffer[5] = 'S';    
      }
      else
      {
        m_lora_app_data.buffer[5] = 'N';    
      }
      //lon data
      m_lora_app_data.buffer[6] = (ilon & 0xFF000000) >> 24;
      m_lora_app_data.buffer[7] = (ilon & 0x00FF0000) >> 16;
      m_lora_app_data.buffer[8] = (ilon & 0x0000FF00) >> 8;
      m_lora_app_data.buffer[9] =  ilon & 0x000000FF;
      if(direction_E_W == 0)
      {
        m_lora_app_data.buffer[10] = 'E';
      }
      else
      {
        m_lora_app_data.buffer[10] = 'W';
      }
      m_lora_app_data.buffsize = 11;
      send_lora_frame();

Now let´s see how to register your device in the TTN network server.

The Things Network configuration

To register a device in TTN you have to have a gateway previously registered in the platform. You can either use public LoRaWAN infrastructure as long as they use TTN services.

For registering the device in the network server of TTN, you will have to ingress the following parameters:

AppEUI: This parameter is an ID that is used during the activation of the device.
DevEUI: This is a unique ID to identify the device.
AppKey: This is the key used to generate the NwkSKey and AppSKey during OTAA.
End device ID: It is a readable name that you can give to your device.

You have to go to Applications > Devices in the TTN console to ingress these parameters. Then press on + Add new device and fill the fields shown in the next picture.

Once you have entered the keys and the region parameters, your device should be registered in a few seconds.

The next javascript code implements the decoder for the payload.

function Decoder(bytes, port) 
{
  var longitude_int, latitude_int;
  var decoded = {};
  
  if (port === 2)
  {
    if(bytes[0]==9) // check if the header byte is 9.
    {
      latitude_int = (bytes[1] << 24) | (bytes[2] << 16) | (bytes[3] << 8) | (bytes[4]);
      decoded.latitude = latitude_int / 100000;
      decoded.direction_S_N = String.fromCharCode(bytes[5]);
      longitude_int = (bytes[6] << 24) | (bytes[7] << 16) | (bytes[8] << 8) | (bytes[9]);
      decoded.longitude = longitude_int / 100000;
      decoded.direction_E_W = String.fromCharCode(bytes[10]);
      return decoded;
    }
  }
}

Just copy this code into your uplink decoder section, as you can see in the next picture.

Now that you have successfully registered your device, let’s see how to send data to Qubitro.

Connecting to Qubitro

Webhooks. There, create a new one using the Qubitro integration.”]]],[1,”p”,[[0,[],0,”This will lead you to the following page.”]]]]}’>

If you still don’t have a Qubitro account, go to this link and create one. It’s easy, it’s cool, and it’s free.

Once you have an account, you can create one project for free. Then click on the + New Project button, give it a name, put some description, and you are done.

Then go back to the TTN console, go to applications, select your application, and go to Integrations > Webhooks. There, create a new one using the Qubitro integration.

This will lead you to the following page.

Enter the name of your webhook in the Webhook ID field. You can use any name for identifying the webhook.

Then, go to the project’s settings page in the Qubitro platform and copy the project ID, as you can see in the next picture.

Paste this Project ID string to the Project ID field in the TTN console.

Finally, go to the Credentials page in the Qubitro platform and copy the Webhook signing key.

Then, return to TTN, paste this key in the Webhook Signing Key and click on Create Qubitro webhook. This will expand the webhook page, and you will be able to select the messages you want to send to Qubitro. See the following picture.

Click on Save changes, and you are done. You have connected your LoRaWAN application to the Qubitro project. Every uplink sent by any devices in this application will be forwarded to Qubitro. So, it´s not necessary to add each device separately. Every time a new device sends an uplink, you will see it in the Qubitro platform.

Now that you have data from your device, you can display it by creating a dashboard. Go to the Monitoring page and click on the New widget button. You will see a page like the one shown below.

There you can give a name to your widget, select the project, the device, and the widget type — in this case, Map. Finally, click on continue for moving to the next screen.