Sigfox

How to connect Sigfox Backend to Datacake IoT Platform

Introduction

In this tutorial, we will show you how to integrate your Sigfox devices into Datacake.

Sigfox

The Sigfox network is similar to the LoRaWAN network, but you don't need gateways because there is already a nationwide network in many countries around the world that you can use for your IoT devices.

If you want to learn more about Sigfox, check out the following link.

Technical Information

HTTPS Push

For the connection between the SigFox backend and the Datacake IoT platform, we use the HTTP Push function, which transmits incoming data from your sensors to Datacake via a web call.

Datacake creates a custom HTTP URL for you, which you can use for all devices of a type. You must store this URL on the Sigfox backend as a callback for your device types. In this tutorial we will show you how to set this up.

Payload Decoding

Similar to the LoRaWAN integration, Datacake provides you with so-called payload decoders, which you can use to decode the payload of your SigFox sensors and convert it into useful data (for dashboards, alerts, etc.).

Starting Template

To make starting with SigFox on Datacake as easy as possible, we offer you a SigFox Starting Template, which pre-decodes the structure of the SigFox backend.

Let's go

Registration

If you have not yet registered on the Datacake platform, you should do so now. Registration is free, no credit card is required, and the first two devices on Datacake are also free, but come with full functionality.

To register on the Datacake platform, please use the following link.

Add Device

When you first register on Datacake, you will be taken to an empty workspace. So the first thing that we need to do is to create our first device on Datacake.

Create a new device by clicking on the blue button "Add Device".

Datacake will now ask you for the device type. Here you select the "API Device" device type.

Datacake Product

Datacake will now ask you for the product. Here you can select if you want to create a new product, select an existing product or use a template.

What is a product?

Products store the definition of a device. Read more about products on Datacake here. For now, though, we can just continue with the next steps.

Starting Template

For easy integration, Datacake has a template for the Sigfox backend. To use this template, select "Existing Template" and choose the SigFox template from the list of available templates.

You will have to scroll down in the list of available templates and probably also browse the available pages to find the Sigfox template.

Now confirm the selection. Datacake will take you to the next step.

Serial Number

The routing of the data from the payload decoder of the product to the respective device will take place via the serial number of your SigFox device.

So now enter the serial number of your SigFox device as you find it on the Sigfox backend. The following screenshot may help you.

Name

You are free to choose the name of your device and can change it at any time.

Create device

Now confirm the entries via the "Add One Device" button. The device will be created for you in the background.

By creating the device, the dialog is closed, and Datacake takes you back to the device overview. In the list of available devices, you should now see your newly created device.

For further use, more steps are necessary, so please click on the device in the list. This will take you to the Device view.

The Sigfox Starting Template has also created an initial dashboard for your new device, which you can see when you open the Device view.

When we connect Datacake to the Sigfox Backend in the later step, and should your device start sending data, you will also be able to see the first data on this dashboard.

Sigfox Backend

To connect your device to Datacake, we need to link the Sigfox backend to the Datacake platform.

Forwarding URL

As mentioned earlier, forwarding between Sigfox and Datacake takes place via a webhook or HTTP forward. To do this, a URL must be specified on the Sigfox backend. This URL is associated with the product of your Datacake device, which you just created.

Now navigate to the configuration view to be able to copy this URL.

Scroll down until you reach the API section. You will see the corresponding URL in a field below the HTTP Payload Decoder.

To copy the URL, just click on the Copy button, or select the URL manually and copy it.

Setup Callback

With the URL in the clipboard, you can now switch to your Sigfox portal and switch to the callback configuration view.

In the callback configuration of your device type, two callbacks must be created for the forwarding.

Data Callback
Service Callback

On the screenshot above you can see the callbacks that need to be created. See the next steps on how to set them up correctly.

Data Callback

The data callback is used to transfer the user data of your Sigfox Device to Datacake.

Please enter the following parameters.

Type: DATA, UPLINK
Channel: URL
Use HTTP Method: GET
Send SNI: Yes
Headers: Not required
URL: Datacake URL + Addendum (see below)

URL

In the URL you just copied from Datacake, you need to add some more information. Add the following to the end of the URL:

data?id={device}&data={data}

Thus, the entire URL will be as follows:

https://api.datacake.co/integrations/api/<your-url-id>/data?id={device}&data={data}

Service Callback

With the service callback, you transfer metadata of your device from the Sigfox backend to Datacake. This is information like location (triangulated) or other useful data about the Sigfox network.

Please set the following configuration.

Type: SERVICE, DATA ADVANCED
Channel: URL
Use HTTP Method: POST.
Send SNI: Yes
Headers: Not required
URL: Datacake URL + Paht (see below)
Content Type: application/json
Body: Custom Body (see below)

URL

The following must also be added to the Datacake URL for the service callback. Add service/ to the end of the URL. This will make the URL read as follows:

https://api.datacake.co/integrations/api/<your-url-id>/service/

Body

Copy and paste the following JSON snippet into the textbox for the body:

{
    "linkQuality":"{linkQuality}",
    "location":"({fixedLat},{fixedLng})",
    "device":"{device}",
    "data":"{data}",
    "lqi":"{lqi}",
    "cloc":{computedLocation},
    "opName":"{operatorName}",
    "cc":"{countryCode}"
}

With these two callbacks created, you have now successfully connected the Sigfox backend to Datacake. You can now send data from your Sigfox device and should already be able to see it in Datacake.

Dashboard

As the Starting Template responds to the Sigfox Backend service callback, you should already be able to see the first data on the dashboard.

Debug Log

In the Device view on Datacake, you will find the Debug Log navigation element in the tab bar, which shows you a listing of the last 100 incoming messages. Here you can also see the incoming data from your Sigfox device.

Troubleshooting

If you have problems connecting the Sigfox backend to Datacake, please always feel free to use our live chat or send an email to support@datacake.de

Payload Decoder

The Starting Template comes with a simple Payload Decoder, which decodes the data structure of the Sigfox backend and passes it to the Datacake backend.

What the payload decoder does not do is decode the actual payload data of your sensor.

This payload data is transmitted as hexadecimal, as is typical for Sigfox, and must be decoded into payload data according to the structure of this data and forwarded to Datacake.

This is the task of the payload decoder and on Datacake you have various tools for converting hexadecimal payloads to real values.

Example

In the following example code snippet, you can see the decoder that is included in the Datacake Sigfox starting template. Its purpose is to already decode the typical Sigfox HTTP callback data structure, but its purpose is also to show you the basic principles on how to access the real sensor data.

function hexToBytes(hex) {
    for (var bytes = [], c = 0; c < hex.length; c += 2)
        bytes.push(parseInt(hex.substr(c, 2), 16));
    return bytes;
}

function Decoder(request) {

    if (request.path.indexOf("service") !== -1) {

        var payload = JSON.parse(request.body);

        return [
            {
                device: payload.device,
                field: "LOCATION",
                value: "(" + payload.cloc.lat + "," + payload.cloc.lng + ")"
            },
            {
                device: payload.device,
                field: "LINK_QUALITY",
                value: payload.lqi
            },
            {
                device: payload.device,
                field: "OPERATOR_NAME",
                value: payload.opName
            },
            {
                device: payload.device,
                field: "LINK_QUALITY_VALUE",
                value: payload.linkQuality
            }
        ];

    } else if (request.path.indexOf("data") !== -1) {
    
        // Here you decode the current data from your sensor 
        // and forward it to the Datacake device.

        var payload = request["GET"]; // The actual sensor data
        var device = payload.id[0]; // The Sigfox device the data is coming from
        
        // This is a helper function that converts the data string to Hex-values
        var data = hexToBytes(payload.data[0]);

        // Now convert the Hex-data into corresponding fields
        var temperature = (data[0] << 8 | data[1]) / 10.0;
        var battery = data[2] / 10.0;

        // Return fields from the decoder to store in the database
        return [
            {
                // Address the device on Datacake by using Sigfox Serial
                device: device, 
                field: "TEMPERATURE",
                value: temperature
            },
            {
                device: device,
                field: "BATTERY",
                value: battery
            }
        ];
    }
}

Last updated 1 year ago