Blues Wireless Notecard

Integration of Blue Wireless Notecard with Datacake through Notehub.

About Blues Wireless

Blues Wireless is the manufacturer of the Notecard, a Cellular NB-IoT and LTE cellular modem that is particularly easy to integrate into existing hardware or new developments.

The user addresses the Notecard via JSON commands, which are then also available on the cloud. In addition, it is particularly power-saving and comes with a SIM card and 500 megabytes of data volume.

Read more about Blues Wireless here:

Blues Wireless Notecard

Documentation on Notehub

Blues Wireless does also feature a guide on how to hook up their Notehub to Datacake. You can access this under the following link:

Datacake on Blues Wireless Developers

Requirements

Create Account

If you haven't yet signed up on Datacake, now it's time to do so. It's free for the first two devices and all you need to do is to click on the following link.

https://app.datacake.de/signup

If you already have an account, well then, please sign in.

Create a New Device

After you have signed up on Datacake you will be guided into an empty workspace. The first thing that we need to do now is to create a new device. Please click on the "Add Device" Button on top right, as shown in the following screenshot:

You will now see a modal asking you for

  • Type of Device

  • Datacake Product

Now please select "API" as the device type.

As a further step, the modal will ask you for the "Datacake Product".

  • Please select New Product from template which will bring up a list of available templates for API devices.

  • Please choose the Blues Wireless Notecard template from that list and please click on the "Next" button.

Now the window will ask you for details about the device you want to create, especially the serial number and a name.

Serial Number

Usually, a serial number is automatically being created for your device.

However, if you have your Notecard ready on the Blues Wireless Notehub, it now makes sense to copy the serial number of that Notecard and use it as the serial number for the new device.

So on your Notehub please copy the serial number of the device that you want to add to Datacake.

In the detail view, you will find an ID. Copy this ID and paste it into the serial number mask on Datacake.

Last but not least please name your first Datacake device and click on the "Next" button to continue to the next step.

Device Plan

Before we can add the device to Datacake you need to choose a device subscription plan. If you have just registered, you have the possibility to create up to 2 devices for free.

Now select the "Free Plan" and confirm your selection by clicking on the "Add 1 Device" button. The device is now automatically added to your workspace.

For more information about pricing, please visit our pricing page.

Open Device

After you have been creating the device on Datacake, the modal will close and you can see the device on the fleet list of your Datacake Workspace.

Now it's time to access the device view. To do so please click on the entry in the device list view. You will see something like the following.

This dashboard comes with the template and gives you an easy start with the platform.

Of course, there is no data on the dashboard yet, as we still need to realize a connection with the platform. In the next chapter, we will show you what steps are required in order to do that.

Add Route

In order to forward data from your Notecard to Datacake using Notehub, we need to add a so-called route to the Notehub. This is a classical HTTPS webhook.

Add Route on Notehub

On the Notehub please navigate into the route settings and start creating a new Route for Datacake by clicking on "Create Route" on top right.

This will bring you into a route type selector and here please choose the following route type.

  • "General HTTP/HTTPS Request Response"

This will bring you into the setup dialog for that route.

We now need to enter two details:

  • Name of the route (something like "Datacake Route")

  • Destination Webhook URL

The Webhook URL needs to be copied from Datacake. In the next chapter we will show you how you can do that.

Webhook URL

Now we need to specify the address that will receive the data from the output streams. This is the so-called webhook.

We get this address from Datacake. To do this, switch to the configuration view of your device on Datacake by opening the "Configuration" tab on the device view.

Scroll down a bit in the configuration view until you get to the "HTTP Payload Decoder" section.

Below the editor for the payload decoder, you will find the webhook URL, which you can copy directly to your clipboard by clicking on the "Copy" button on the right.

Now switch back into the Notehub and paste the webhook URL into the following field.

Activate your Notecard

By having a route in place the Notehub is now prepared to forward data to your Device on Datacake.

Due to the starting template, Datacake is also prepared to receive that data and store it on that particular device.

You should now go ahead an activate your Notecard so that it triggers sending of some fresh new data.

See Logs on Datacake

Once the data has been sent, switch back to Datacake. On the HTTP Payload Decoder section, you will find a button "Show logs" on the right side next to the header of the decoder panel.

Clicking this button will open a window listing all the messages coming in via the webhook URL.

This is the place where you should see incoming data from your Notecard via Notehub.

See Dashboard

Also, if the sending of data was successful, you should now also see data on the device dashboard. Simply switch into the dashboard view of your device using the navigation tab bar and have a look.

If everything worked out fine, you should see something like the following:

Further Steps

Working with Payload Decoders

We do have a guide that shows you everything you need to know about developing payload decoders on Datacake. Please make sure you have a deep look into it:

Incoming Webhooks

Understanding Payload Decoding

To understand how the decoding of payload works, lets first analyse the contents of the Webhook coming from Notehub.

{
   "event":"02ebee6c-7a8e-44e4-9f2a-4f730a1261ea",
   "session":"0b8e2abe-1d48-4688-abad-f2d42d178c45",
   "device":"dev:868050040248573",
   "product":"product:com.blues.rlauer:datacake_asset_tracker",
   "received":1647933695.622265,
   "routed":1647933701,
   "req":"note.add",
   "when":1647933671,
   "file":"_track.qo",
   "updates":1,
   "body":{
      "hdop":1,
      "humidity":36.375,
      "pressure":98362.766,
      "status":"heartbeat",
      "temperature":17.125,
      "time":1647890462,
      "voltage":4.1992188
   },
   "where_olc":"86MG3HC8+GXHG",
   "where_when":1647890462,
   "where_lat":43.0713125,
   "where_lon":-89.43251171875,
   "where_location":"Shorewood Hills, WI",
   "where_country":"US",
   "where_timezone":"America/Chicago",
   "tower_when":1647933694,
   "tower_lat":43.074087500000005,
   "tower_lon":-89.44282812499999,
   "tower_country":"US",
   "tower_location":"Shorewood Hills WI",
   "tower_timezone":"America/Chicago",
   "tower_id":"310,410,17169,77315594",
   "project":{
      "id":"app:f1496e91-7143-46b9-b469-bdc61c529cd2",
      "name":"Datacake Asset Tracker",
      "contacts":{
         
      }
   }
}

Let's take a closer look at the payload.

The Notehub sends us all the important data encapsulated in this JSON Object. We now need to write a decoder on Datacake that reads out the important data and stores it into database fields of that device.

Serial Number

Please also note that the serial number of that device, this data is belonging to, is encapsulated in the JSON.

"device":"dev:868050040248573"

The Payload Decoder

To extract the payload, Datacake uses the principle of payload decoders.

This is a small piece of JavaScript code that is executed on incoming messages, and which can be used to extract data and forward it to appropriate devices.

This forwarding takes place based on the serial number of the Datacake device, and if you recall, we replaced this serial number with the ID we found specified on the Notehub platform.

We now also find this ID in the payload that the Notehub Route forwarded to us. In order to be able to forward the data to the corresponding Datacake device, we need the following payload decoder:

function Decoder(request) {
    
    var data = JSON.parse(request.body);
    var device = data.device;
    
    var file = data.file;
    
    var decoded = {};
    
    if (file === "locations.qos") {
        
        decoded.voltage = data.body.voltage;
        decoded.motion = data.body.motion;
        decoded.seconds = data.body.seconds;
        
    } else if (file === "_session.qo") {
        
        decoded.voltage = data.voltage;
    }
    
    if (("tower_lat" in data) && ("tower_lon" in data)) {
        decoded.tower_location = "(" + data.tower_lat + "," + data.tower_lon + ")";
    }
    if (("where_lat" in data) && ("where_lon" in data)) {
        decoded.device_location = "(" + data.where_lat + "," + data.where_lon + ")";
    }
    
    decoded.rssi = data.rssi;
    decoded.bars = data.bars;
    decoded.temp = data.temp;
    decoded.orientation = data.orientation;

    return [
        {
            device: device,
            field: "TOWER_LOCATION",
            value: decoded.tower_location
        },
        {
            device: device,
            field: "DEVICE_LOCATION",
            value: decoded.device_location
        },        
        {
            device: device,
            field: "RSSI",
            value: decoded.rssi
        },
        {
            device: device,
            field: "BARS",
            value: decoded.bars
        },
        {
            device: device,
            field: "VOLTAGE",
            value: decoded.voltage
        },
        {
            device: device,
            field: "CARD_TEMPERATURE",
            value: decoded.temp
        },
        {
            device: device,
            field: "ORIENTATION",
            value: decoded.orientation
        }                
    ];
    
}

At the end of the decoder, you can see that the last step is to return an array containing the device's payload data with a serial number and an indication of a field.

This field is a unique identifier for the respective database field on the device that carries the serial number.

Database Fields

Payload decoders store the data in corresponding fields of the database of your device. You can freely define the number and types of these fields on Datacake.

A listing of all fields for the device can be found in the "Fields" section on the same configuration view of your Datacake device.

Simply scroll down until you reach the "Fields" section.

Here you will already find some fields that were automatically created by the Template you selected.

Since we created the device via a template in this example, the device already has some fields. You can now add any fields if your device has more data than we show here in this example.

If needed, you are welcome to add more fields, delete existing ones or modify them if necessary. More details about fields can be found here.

Last updated