Skip to content

Latest commit

 

History

History
310 lines (203 loc) · 18.5 KB

README.md

File metadata and controls

310 lines (203 loc) · 18.5 KB






WisBlock Goes Blues

RAKWireless RAKstar Blues

While WisBlock is usually associated with LoRa and LoRaWAN, this time we are diving into the cellular data transmission using the Blues.IO Notecard. To make it more interesting, we are mixing LoRa P2P communication and cellular communication into one project.

Overview

When I got a Blues Notecard for some testing, the first thing was of course to connect it to the WisBlock modules. After some initial testing like connecting the Notecard to my cellular provider and sending some sensor data, I was hungry for more.

Browsing through the Blues website I found their very interesting product Sparrow Development Kit. What caught my interest was the fact that it combines LoRa and Cellular communication in a simple way.

Inspired by Sparrow and after browsing through the open source code of it on Github I decided to build a similar system with WisBlock sensors.


Principles of Blues Sparrow

Sparrow connects multiple sensors nodes over LoRa P2P to a "gateway" sensor node that is equipped with a Blues Notecard. The sensor nodes register themselves on the gateway and send their sensor data in assigned timeslots to the gateway. The gateway then forwards the sensor data to the Blues Notehub. From there you can send the data either to the Sparrow example web application (you have to setup this by yourself) or to another visualization platform.
This is a very interesting combination of LoRa and Cellular communication.


Principles of the WisBlock Hummingbird Concept of Proof

The WisBlock Hummingbird CoP transfers the idea of Blues Sparrow to the WisBlock world. It uses WisBlock modules for both the sensor nodes and the gateway that is connected to the Blues Notecard. The sensor nodes are sending their data over LoRa P2P to the gateway node which then forwards the data to the Blues Notehub.


Differences between Blues Sparrow and WisBlock Hummingbird

I looked into the protocol and data flow of Sparrow and (of course) found some things that I wanted to change to make it easier to integrate my existing sensors to the sensor network.

  1. Most of my WisBlock examples can be switched between LoRaWAN and LoRa P2P communication, but Sparrow uses their "Notes" format (data in JSON format) to transmit the sensor data. This would require a change in the source codes of my existing sensor applications. I prefer to keep my existing data format, which is Cayenne LPP. This allows me to basically connect any of my exising sensor devices to the Hummingbird gateway without any code changes. The only thing that has to be done is to switch the LoRa protocol from LoRaWAN to LoRa P2P and setup the same parameters as on the gateway.
  2. Sparrow requires that the sensor nodes are registering themselves on the gateway and submit their sensor data format as a template to the gateway. As I am sending data from the nodes to the gateway in Cayenne LPP format, this registration with a template is not required. Instead I implemented in the gateway firmware a parser for the data that can basically understand the data sent from any sensor that uses Cayenne LPP format.
  3. Sparrow assignes a timeslot to each sensor where they are allowed to send their sensor data. I skipped this time slot assignment, as I want to connect as well sensors that want to send a data packet on an event, e.g. a door status switched (house alarm system) or an alarm for water leaking. Instead of the timeslots, I implemented Semtech SX1262's CAD feature. CAD (channel activity detection) helps to prevent collision of data sent from different devices on the same frequency at the same time. It does check for activity on the frequency before it starts sending the data packet. This is not 100% preventing packet collision in the air, but it works quite well for me.
  4. Sparrow uses different Note definitions for the different devices, like motion.qo for motion sensors, sensors.qo for environment sensors. In this PoC I used only one Note type, the sensors.qo and the differentiation between the different sensors is done in the end.point.
  5. Blues offers an open source reference web application to visualize the data of the Sparrow sensor nodes. They have as well easy to follow guides how to deploy the reference web application in the cloud with e.g. Netlify or Vercel. But as I don't have a Sparrow system and (despite the very good documentation) I struggled to get the reference web app to life, I instead switched for the visualization to my favorite Datacake.

How to use WisBlock Hummingbird


Hummingbird Gateway

The only thing that requires some work is to setup the WisBlock system with the Blues Notecard. To connect the Blues Notecard RAKwireless has the RAK13102 WisBlock IO module. This module uses the IO slot of the RAK19007 Base Board.

Hardware Setup

The code in this repository is for the Hummingbird Gateway and supports beside of the communication to the Blues Notecard a RAK1906 environment sensor. The code can be used as well for a simple sensor node with a RAK1906 sensor without the Blues Notecard.

Setup

You have to setup your NoteCard at Blues.IO before it can be used. There are two options to setup the NoteCard.

Option one is to follow the very good Quickstart↗️ guides provided by Blues.

Option two is to setup the device with AT commands directly through the WisBlock's USB.

Option one, NoteCard Setup through the USB of the RAK13102 NoteCard

Connect the RAK13102 NoteCarriers USB to your computer (WisBlock has to be powered separate!) and use the Blues Quickstart↗️

Option two, setup through AT commands

⚠️ IMPORTANT ⚠️

If setting up the NoteCard through AT commands, these settings will always override settings that are stored in the NoteCard.
To remove settings saved from AT commands use the AT command ATC+BR to delete all settings saved from AT commands before.

Connect the WisBlock USB port to your computer and connect a serial terminal application to the COM port.

Setup the Product UID

To connect the Blues NoteCard to the NoteHub, a Product UID is required. This product UID is created when you create your project in NoteHub as shown in Set up Notehub↗️.

Get the Product UID from your NoteHub project:

Product UID

Then use the ATC+BEUI command to save the Product UID in the WisBlock:

ATC+BUID=com.my-company.my-name:my-project

Replace com.my-company.my-name:my-project with your project EUI.

The current product UID can be queried with

ATC+BUID=?

Select SIM card

There are two options for the Blues NoteCard to connect. The primary option is to use the eSIM that is already on the NoteCard. However, there are countries where the eSIM is not working yet. In this case you need to use an external SIM card in the RAK13102 WisBlock module. This can be a SIM card from you local cellular provider or a IoT data SIM card like for example a SIM card from Monogoto↗️ or from another provider. You can purchase a MonoGoto card together with the Blues NoteCard from the RAKwireless store IoT SIM card for WisNode Modules

Use the AT command ATC+BSIM to select the SIM card to be used.

The syntax is ATC+BSIM=<SIM>:<APN>
<SIM> == 0 to use the eSIM of the NoteCard only
<SIM> == 1 to use the external SIM card of the RAK13102 NoteCarrier only
<SIM> == 2 to use the external SIM card as primary and the eSIM of the NoteCard as secondary
<SIM> == 3 to use the external SIM card as secondary and the eSIM of the NoteCard as primary

If the external SIM card is selected ( is 1, 2 or 3), the next parameter is the APN that is required to connect the NoteCard <APN> e.g. internet to use with the Filipino network provider SMART.
Several carriers will have a website dedicated to manually configuring devices, while other can be discovered using APN discovery websites like apn.how↗️

The current settings can be queried with
AT+BSIM=?

Select NoteCard connection mode

The Blues NoteCard supports different connection modes. For testing purposes it might be required to have the NoteCard connected continuously to the cellular network, but in an battery powered application, the prefered connection type would be minimal, which connects to the cellular network only when data needs to be transfered.

The connection mode can be setup with the AT command AT+BMOD.

The syntax is AT+BMOD=<mode>
<mode> == 0 to use the minimal connection mode
<mode> == 1 to use the continuous connection mode

Default is to use minimal connection mode.

The current status can be queried with
AT+BMOD=?.

Delete Blues NoteCard settings

If required all stored Blues NoteCard settings can be deleted from the WisBlock Core module with the AT+BR command.

⚠️ Requires restart or power cycle of the device ⚠️

The syntax is AT+BR

Reset Blues NoteCard to factory settings

If required the Blues NoteCard can be reset to factory default.


⚠️ THIS WILL ERASE ALL SETTINGS IN THE NOTECARD ⚠️


All saved settings like Product UID, connection settings, APN, ... in the NoteCard WILL BE ERASED

The syntax is AT+BRES

Get Blues NoteCard status

Show NoteCard connection status with req:hub.status.

The syntax is AT+BLUES

Send request to the NoteCard

⚠️

This works only for simple requests without parameters, like hub.status or hub.sync ⚠️

Sends a simple request to the NoteCard and returns the response from the NoteCard

The syntax is AT+BREQ=<request>
<request> is the NoteCard request, e.g. card.version or card.location


Hummingbird Sensor

As I am using the "standard" data format of my WisBlock examples, many of my existing WisBlock example application can be used without any changes:

For other (older) example codes, it is required to add the LoRa P2P send functionality and/or extend the CayenneLPP data packet with the device identifier. I use the DevEUI of the device as unique device identifier, as every WisBlock Core has the unique DevEUI printed on its label.
In my examples, I use the CayenneLPP library from ElectronicCats with my own class extension. When using this library, the data packet is generated in WisCayenne g_solution_data(255);. The unique device identifier (the DevEUI) is added at the start of the existing data packet using this few lines of code:


⚠️ Using WisBlock-API-V2: ⚠️

// Add the device DevEUI as a device ID to the packet
g_solution_data.addDevID(LPP_CHANNEL_DEVID, &g_lorawan_settings.node_device_eui[4]);

before sending the packet with

send_p2p_packet(g_solution_data.getBuffer(), g_solution_data.getSize());

⚠️ Using RUI3: ⚠️

uint8_t packet_buffer[g_solution_data.getSize() + 8];
if (!api.lorawan.deui.get(packet_buffer, 8))
{
	MYLOG("UPLINK", "Could not get DevEUI");
}

memcpy(&packet_buffer[8], g_solution_data.getBuffer(), g_solution_data.getSize());

for (int idx = 0; idx < g_solution_data.getSize() + 8; idx++)
{
	Serial.printf("%02X", packet_buffer[idx]);
}
Serial.println("");

before sending the packet with

api.lorawan.psend(g_solution_data.getSize() + 8, packet_buffer);

Hummingbird in Action


Hummingbird Gateway

After doing the hardware setup, flashing the firmware and following Blues Quickstart guides to setup my Notehub and the Notecard, my existing sensors are able to send data to the Hummingbird Gateway.

Here is an example log output with the result of the CayenneLPP data parsing then the packet sent from the gateway over the Notecard:

Gateway Log


Blues Notehub

The notes send to the Blues Notehub can be seen in the Events listing of the Nothub

Notehub Events Log


To forward the messages to Datacake, a Route has to be defined in the Notehub. There are many easy to follow tutorials available in the Blues documentation, in this case I used of course the Datacake Tutorial to setup the routing.

Once the route has been setup, the Notefiles used in this route have to been selected. As all sensor nodes data are sent as sensor.qo, this Note has to be enabled.

⚠️ INFO ⚠️

Different to the tutorial steps, I did not use the Transform Data option !!!!

Notehub Route Setup


Now the routing events are shown in the Routes log view:

Notehub Routed Log


When opening one of these events, the sensor data can be seen in the Body view:

Notehub Routed Data


Datacake

To visualize the data in Datacake a matching device has to be defined, as it is described in the Datacake Tutorial.

⚠️ INFO ⚠️

As Hummingbird is sending sensor data from different sensor nodes to one end-point, a different payload decoder is required !!!!

I wrote a payload decoder that separates the incoming sensor data depending on the sensor node ID into different fields. This is required to distinguish between the data of the sensor nodes. The Datacake decoder for this task is the file Decoder.js in this repository.
The content of this file has to be copied into the HTTP Payload Decoder of Datacake:

Payload Decoder


Then the matching fields for the sensor data have to been created. The easiest way to do this is to wait for incoming data from the sensors. If no matching field is existing, the data will be shown in the Suggested Fields list in the configuration:

Suggested Fields

The sensor data can be easily assigned to fields using the Create Field button.


Once all the sensor data is assigned to fields, we can start with the visualization of the data.

Create Fields

As you can see, there are multiple fields for battery, temperature, humidity, ..., but each field has a leading device ID!

Datacake has two options, the first one is the Device Dashboard, but as we expect a lot of data from different devices, it would be quite crowded and difficult to distinguish between the different devices. To make it easier to view the data per devices, I instead created a device independent Dashboard that allows me to create tabs to separate the data from the different sensors. Such Dashboards can be created with Add Dashboard on the left side of the Datacake panel:

Create Dashboard


After creating the Dashboard I clicked on the button on the right side to enable editing, then on Edit Dashboard Meta.

Enable editing Dashboard

In the opening window I added a tab for each of my Hummingbird sensor devices:

Add tabs

This allows me to sort the data from the different sensor nodes into these tabs.


I will not go into details how to create visualization widgets in Datacake, this step is handled in other tutorials already.


The final result for the two sensors and the sensor gateway that are sending sensor data looks like this:

Sensor Device 1 is a particulate matter sensor

PM Sensor

Sensor Device 2 is a barometric pressure sensor

Barometer Sensor

Sensor Device 3 is the Hummingbird gateway that I enquipped with an environment sensor

Sensor Gateway



LoRa® is a registered trademark or service mark of Semtech Corporation or its affiliates.

LoRaWAN® is a licensed mark.