How to Build a GPS Tracker with Notecard and Datacake

Yay. Everybody, let's build this interface for the Notecard.

In this tutorial, we will show you how to connect your Blues Wireless Notecard to the Datacake platform and use the Notecard's GPS feature to set up an asset tracking solution.

In doing so, we will use the Datacake platform's Webhook integration to receive data via HTTP push from the Notecard's associated management platform, Notehub.

Prerequists

This tutorial assumes that you have a Notecard and have already registered it on Notehub.

Also, your Notecard should be prepared as a stand-alone tracker. Information on how to do this can be found in the Notecard Documentation at the following link:

https://dev.blues.io/build/notecard-guides/asset-tracking/#configure-a-standalone-tracker

Create Datacake Account

If you don't have a Datacake account yet, then register now on the Datacake platform. To do so, simply follow this link here.

https://app.datacake.de/signup

After registering, you will be automatically redirected to your first Workspace on Datacake.

A workspace is the place on Datacake where you add devices or members and set other preferences or create global dashboards.

Datacake offers the creation of additional workspaces and members as well as devices can exist in multiple workspaces at the same time. For the present tutorial, however, we will limit ourselves to a first workspace.

Create first device

Now create your first device by clicking on "Add Device" in the fleet overview.

This will open a dialog that will now ask you for the device type. Here you select the type "API" using the buttons.

Datacake Product

Now you will be asked for the desired Datacake Product to which you want to add your new device. There are two choices available here:

• New Product - Creates a new product for the device at the same time.
• Existing Product - Adds the device to an existing product.

Now select "New Product" and enter a name for the product, e.g. "Notecard Asset Tracker Product".

Now confirm the selection and entry by clicking on the "Next" button.

What is a product?

A product is the definition for one or more devices. The product defines the design of the dashboard, the fields in the database and also the payload decoder for processing the incoming data.

If you add one or more devices to the product, it will automatically get the settings for dashboard, database and decoder (downlinks as well, if available).

Serial number and device

In the next step you will be asked for the serial number that you can store for your Notecard.

Since this is important for the automatic assignment of incoming data from the device (via webhook), Datacake allows you to set your own serial number here.

You now have two options.

• you use the Notecard Device ID here, as specified on the Notehub.
• you assign your own serial number via the Notecard API.

If you are not sure how to assign an individual serial number to the Notecard, enter the serial number as it is shown in the Notehub overview.

So just copy the following serial number and paste it into the Datacake view.

Don't worry. You can change the serial number as many times as you want at a later time.

Finally, you need to assign a name for your first device. I suggest something like "Notecard Asset Tracker" here.

Last but not least confirm your entry by clicking on the "Next" button.

Plan

Before the device can be created, you still need to decide on a subscription plan. We support two free devices and since we currently only want to create one device, simply select the "Free" plan here.

Confirm your selection by clicking the "Add Device" button. The API device will now be created.

If you want to learn more about the Datacake Pricing, you can visit our Pricing Info Page:

https://datacake.co/pricing

Configuration of the device

After successful creation you will be taken back to the Fleet-Overview of the Datacake platform. Here the newly created device is listed in the table.

For further configuration, you now need to open the device view. Simply click on the entry in the list. The following view appears.

You will now see an empty dashboard, which we will build later. For now, we are interested in the basic configuration.

Now use the tab bar in the Device view to get to the configuration of the device.

This is where all the configuration for the device will now take place.

Creating database fields

First, we will now create a few database fields that will later store the data of the notecard historically.

To do this, scroll down a little in the Device view until you reach the "Fields" section.

Now click on the field "Add Field". Now you can create database fields via the setup dialog.

For the first field, enter the name "RSSI" and select the type "Float".

You will notice that the input field "Identifier" will be filled in automatically. Accept this suggestion and confirm the creation of the field with "Save". You can ignore the input fields for Unit and Form.

This identifier will be used later by the payload decoder to assign the data.

For the notecard as asset tracker we need the following fields in total:

• Name: RSSI, Type: Float
• Name: Bars, Type: Float
• Name: Voltage, Type: Float
• Name: Card Temperature, Type: Float
• Name: Orientation, Type: String
• Name: Motion, Type: Float
• Name: Tower Location, Type: Geo Location
• Name: Device Location, Type: Geo Location

Please create the fields as well, so that the Fields view will look something like the following when finished.

Webhook Forward

As mentioned above, we have created a separate product for the new API Device. On Datacake, each product gets its own Webhook URL, which we will now copy and deposit on the Notehub portal for the Notecard.

You can find this URL in the HTTP Payload Decoder Settings in the Configuration View, where the list of database fields is also displayed.

Scroll up a bit in the Configuration until you see the following section.

There please copy the following URL by clicking on the Copy button.

Now, open the Notehub portal and navigate to the "Routes" item using the sidebar.

If you have not yet saved any routes, you will see an empty view.

Now start creating a new route by clicking on the Add Route button in the upper right section of the platform.

The dialog for setting up the new route will now open.

First give the route a name, e.g. "Datacake Route". Then copy the webhook URL for the API product on Datacake and paste it into the Route URL field.

All other settings for the route can be left at their default value. Then finally confirm the creation of the route by clicking "Save".

Checking the webhook

If your notecard is already configured and sending data, then you can check the creation of the webhook for success by opening the logs for the webhook URL in the configuration view of the Datacake device.

To do this, scroll down to the "HTTP Payload Decoder" section. In the right corner of the panel you will find a button "Show logs".

After clicking it, a log section will open and here you will see all HTTP requests that have been received via the product's webhook URL.

Decoding of data

A big advantage of the Datacake Webhook integration is that it does not dictate the structure of the data.

Instead, Datacake provides a payload decoder that allows you to use small JavaScript snippets to decode the incoming data, pre-process it, and pass it on to your appropriate devices on Datacake.

To edit the payload decoder, navigate back to the configuration view of your device.

Now scroll down a bit until you reach the "HTTP Payload Decoder" area.

There you will find a code editor with syntax highlighting and other familiar IDE features. Here you can write your decoder.

We now use this decoder to decode the incoming data from Notehub via webhook accordingly and pass it to the newly created device.

For this purpose, the Notehub platform sends us the data of the respective notecard in the body of the webhook. In a first step, we convert this body into a JSON object, so that we can then pick up the user data directly via an object.

function Decoder(request) {
    var data = JSON.parse(request.body);
    // ...
}

Assignment to the Device

As mentioned before, the Datacake Webhook URL is bound to the respective Datacake product, not to the Device.

So now we also have to extract the serial number of the notecard to be able to pass it later with the notecard data to the corresponding device. The serial number serves here as index.

Let's have a closer look at the user data in the Notehub webhook:

{
    "device":"dev:864475044266285",
    "sn": "DatacakeNotecard007",
    "product": "product:en.datacake.simon:datacaketest"
}

Here we see that the notecard device ID, as well as a user serial number, is present in the payload.

Since we have set the Datacake device serial number to the notecard device ID in this example, we are currently interested in just that ID as well, and we extract it in the payload decoder on Datacake as follows:

function Decoder(request) {
    var data = JSON.parse(request.body);
    var device = data.device;
    ...
}

Pro Tip

You can see that in the Notehub payload there is also the user serial number as well as a product ID. Via the HTTP Payload Decoder of the Datacake Product you have of course also access to these variables and could use the 1) the User Serial Number as serial number for your Device, as well as 2) the Product ID as routing information in the Payload Decoder.

Extracting payload data

Now we want to extend the HTTP Payload Decoder on Datacake so that it also extracts the payload data such as Temperature, Voltage and Location (for Cell-Tower and Device). To do this, we extend the decoder as follows:

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 + ")";
    }
    // Extract additional device-usage-data
    decoded.rssi = data.rssi;
    decoded.bars = data.bars;
    decoded.temp = data.temp;
    decoded.orientation = data.orientation;
    //...
}

Return

Now all payload data from the webhook is available in a dictionary (decoded-object) and can now be routed to the corresponding Datacake device.

For this purpose, the payload decoder returns an array containing dictionaries in which the data, as well as the serial number of the respective device (to which the data is to be assigned), are present.

In our example this array looks like this:

function Decoder(request) {
    var data = JSON.parse(request.body);
    var device = data.device;
    // ...
    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
        }
    ];
}

The crucial piece here is the assignment via serial number and several places come together, including

• The serial number or device ID in the webhook of the notecard on Notehub
• The individual serial number of the device on Datacake
• The forwarding from the HTTP payload decoder to the respective device.

The crucial part here is:

function Decoder(request) {
    var data = JSON.parse(request.body);
    var device = data.device;
    // ...
    return [
        {
            device: device,
            // ..
        },
        // ...
    ]
}

As you can see, we extract the serial number or device ID of the notecard from the webhook and use it as an identifier in the array that we pass to the Datacake device.

The Datacake backend extracts the array and takes the serial number and associated data (such as Temperature, Voltage, etc.), and assigns it to the device that has the same serial number.

The complete decoder then looks like this.

Test Payload Decoder

In addition to the IDE functions for writing code, the Payload Decoder Editor also offers functions that allow you to test the code directly.

This is exactly what we will do now with the payload that is already sent from Notehub to Datacake.

To do this, please open the logs of the webhook integration and copy the payload shown there.

Now paste this payload into the body text field below the payload decoder editor.

If you now click on "Try Decoder", the code written above will be executed via a virtual incoming webhook and you will see the result in the debug output in the same window.

Payload Decoder Programming Guide

If you want to know more about decoding payload, we have a chapter in the documentation that shows and explains the available options in more detail. Please use the following link:

https://docs.datacake.de/integrations/webhook#payload-decoder-programming-guide

Debugging

If your notecard is already configured and sends data, then these should now already run through the decoder into the respective device. You can check this in several ways.

Data in Database

One way is to look at the database fields in the device configuration. Scroll down to the Fields section, which lists the database fields. There you will also see the current measured value in each row. If now data was written into the device, then you find the last measured values indicated here.

Debug Log

Another way is to open the debug log of a device. Use the tab bar in the device view to open the debug log.

Here you can see the last 100 log messages of the device. Also, errors with the assignment are indicated here, like e.g. wrong transfer values or other problems.

Why don't I see this in the Webhook-Logs?

Good question. Well, the logs of the HTTP Payload Decoder in the Configuration View currently refer to the Datacake Product (which is assigned to the Device). You can also see this by the "Product-wide" note.

These logs show the activity regarding the webhook URL of the Datacake Product, but not of the respective Device. At the current time, the Datacake Product is still merged with the Datacake Device in the front-end.

Create a Dashboard

Now that database fields, as well as payload decoders, are created, and data is flowing from the Notecard to the Device through the Notehub platform via webhook, we can proceed with creating a dashboard.

To do this, navigate to the dashboard using the tab bar.

Here you will currently see an empty dashboard.

To start editing, please click on the edit mode switch at the top right end of the tab bar.

The view of the dashboard will change as follows.

Desktop vs. Mobile

Datacake offers independent editing of layouts for desktop and mobile.

The latter layout is used when you open the portal on a smartphone or other device with a smaller screen in the browser (so it does not refer to an app).

We will now limit ourselves to designing a dashboard for the desktop layout. You can derive the mobile layout from the desktop layout later.

Map widget

Now, the first thing we'll do is create a widget to display the two location data (Cell-Tower and Device-Location). To do this, click on the " + Add Widget" button, which is located in the upper right corner next to the Edit Mode switch.

A modal will open with a gallery showing you the available widgets. Here please select the "Map" widget.

After clicking on it, the configuration window for the widget will open directly, which looks like this.

The views for the widget configuration are often identical. Here you will find a tab bar, with which you can navigate to the respective settings. Often the widget starts with the "Basics" settings. Here you set basic settings, in the case of the map widget just name for the two currently supported languages.

Selecting the fields

Now use the tab bar of the widget configuration to get to the "Device and Field" section.

Here click on "Add Device" (don't get confused, the device is already preselected), and a first option for selecting a field as a drop-down will appear.

When you open the drop-down, you will see the database fields compatible with the widget.

Tracking the positions

Since we want to build a GPS tracker with the notecard, please click on "Timeframe" now and please activate the option "Show historical data" there. From now on you can select a time range ("Timeframe") that defines the display period of the historical positions (from, to).

The widget will now show you the covered route of the notecard and you can use a slider to rewind or fast forward the route.

More options

The Map widget offers a few more options, like setting the display style, i.e. map material. Adapt that to your own needs.

More widgets

Following the format described above, you can now add more widgets to the dashboard for the visual representation of the measurements.

Importing the dashboard

Our dashboard editor offers the option of copying dashboards. For this notecard tutorial, we have already created a dashboard that uses the fields created above.

https://github.com/datacake/datacake-notecard-assettracker-tutorial/blob/main/dashboard-data.txt

To do this, copy the following string and paste it into the dashboard. To do this, click on the "More" dropdown in Edit mode and select the "Paste Dashboard" option.

A modal with a text field will open in which you can paste the dashboard string.

After that, the dashboard should look like this.

Complete Decoder

In the Github