Sigfox wide-area, low power devices with Ubidots IoT Application Development platfrom makes for a simple to integrate IoT solution all the way from hardware to the end-user's experience. Built applications in Ubidots to track and monitor assets (cars, busses, trash cans, or even your golf-bag) across long ranges. 

By completing this tutorial, following each step closely, you will be able to communicate data from the Sigox backend to Ubidots when the data can be put to work as a solution. This integration will require the UbiFunctions addon, a feature tool of Ubidots IoT Application Development platform that allows users to great a custom API or endpoint for their application.

Requirements

Step-by-Step

  1. Understanding Sigfox Messages
  2. UbiFunctions configuration
    – Sample Code Breakdown and Explanation
  3. Setting up the Sigfox callback to Ubidots
  4. Checking data integration
  5. Summary

1. Understanding Sigfox Messages

If you are not already familiar with Sigfox and the Sigfox Backend, we recommend you check this Sigfox Technology Overview before proceeding much further with this guide.

Let's begin by looking at the messages structure of a Sigfox device. As you might already know, the Sigfox network allows to send (uplink) to 12 bytes per message with a maximum number of 140 messages per day.

At this point, it's important to clarify that Sigfox devices transmit data in different payload structures depending on device manufacturer. It is recommended to review the datasheet of the device provider to decoded the payload structure to be posted to to Ubidots.

For a test, let's assume that your Sigfox Device is going to send the data using the following payload structure below to send sample data to Ubidots:

  • Sample data from Sigfox Device: 4fc1b6c81cc23c5514

Where are the bytes? And, how do we understand the payload?

  • 0x4F  - Temperature - Bytes #0 (1 byte) 
  • 0xC1B6C81C - Latitude - Bytes #1 - #4 (4 bytes)
  • 0xC23C5514 - Longitude  - Bytes #5 - #9 (4 bytes)

Total of bytes = 9

If you already don't see it, let me highlight that the device is sending temperature and coordinates data to Ubidots in the first 9 bytes. This data is interpreted, understood, and securely decoded by the Sigfox backend.
 
Now assuming that the data above is received in the Sigfox Backend, it's time to setup a Callback. The Sigfox Callback is one feature that when used properly can relay data to Ubidots Cloud using an HTTP Request.

For this guide, we are going to send basic parameters such as the device id and the data received in bytes to Ubidots. Then, using the UbiFunctions tool to parse and decode the payload structure into an Ubidots friendly dataset.  Now based on this, the body of the callback should have the following structure: 

{
  "device_id": "{device}",
  "data":"{data}"
}

Now, with a basic understanding of a Sigfox payload, let's now look at how to configure the UbiFunction to decode the payload coming from Sigfox, plus how to setup the callback in Sigfox's backend to ensure data securely reaches your Ubidots account. 

2. UbiFunctions Configuration

IMPORTANT NOTE: This guide assumes that your Sigfox Device is able to transmit data to the Sigfox Backend.

Note: an UbiFunction is a Node.js cloud function executed when a GET or POST request is made in the Function's URL, as illustrated below. 

1. Create an UbiFunction by going to your Ubidots account –> Data –> Functions. 

NOTE:  If you cannot see the "Functions" module in your account's menu, you will need to enable the $29/month add-on in the billing section of your account

2. Click the blue "+" icon in the upper-right corner to create a new function: 

3. By default, every UbiFunction is populated with a sample code without any configuration. Now you need to configure the function in order to make it work best for your needs. 

The default configurations for the function are as shown below:

To begin, assign the name desired for your UbiFunction. We recommend using the format "Brand-Reference", i.e. "Sigfox-Suntech", "Sigfox-Oyster" or "Sigfox-Thinxtra". For example purposes, we are going to assign "Sigfox-Device" as the name. 

Then, select POST as HTTP Method and NodeJS 8 as Runtime. With these parameters included, your resulting Function setup is as follows:

4. Now is time to deploy the UbiFunction in order to generate the API endpoint URL which is going to be used to transmit the data from the Sigfox Backend to Ubidots. 

To deploy the UbiFunction click on "Make it live":

Now the resulting URL endpoint will look a little something like this:

IMPORTANT NOTE: This resulting URL Endpoint is important because this is the endpoint that you will direct your Sigfox callback to send all of its data to. 

As you might have noticed the resulting URL endpoint generated by the UbiFunction is: 

https://parse.ubidots.com/prv/ubidots-tutorials/sigfox-device

Where, ubidots-tutorial is the username of the account where the UbiFunction is created and sigfox-device is the name assigned to the UbiFuction.

Save the API endpoint URL to be used and assigned later in the Sigfox Callback configuration. 

5.  Erase the default code located in the UbiFunction editor, then copy and paste the below sample code replacing the default code. After pasting, be sure to assign your Ubidots TOKEN where indicated:

var request = require('request-promise');

/* Assign your Ubidots TOKEN */
var token = "BBFF-Rfcgaxns6HlVb155WA0RhSY85*****";

/**************************************************
 *                MAIN FUNCTION                   *
 **************************************************/
async function main(params) {  
    /* Save device ID of the Sigfox Device */
    var device_id = params.device_id;
    /* Save data received from Sigfox */
    var buf = new Buffer(params.data, 'hex')
    /* Parse the incoming data */
    var temp = buf.readInt8(0);    
    var lat = buf.readFloatBE(1);
    var lng = buf.readFloatBE(5);
   
    /* Uncomment lines below to debug the values decoded */
    /*
    console.log(temp);
    console.log(lat);
    console.log(lng);
    */
   
    /* Build body to be POST at Ubidots */
    var payload = {"temperature": temp, "position": {"value":"1", "context":{"lat": lat, "lng":lng}}};
   
    /* Make POST request to Ubidots */
    var post_response = await ubidotsPost(token, device_id, payload);
    /* Pass Ubidots' API response to the functions' response */
    return post_response;
}

/**************************************************
 *              POST Request to Ubidots           *
 **************************************************/
sync function ubidotsPost(token, device_label, data) {
    var options = {
        method: 'POST',
        url: 'https://industrial.api.ubidots.com/api/v1.6/devices/' + device_label + '?force=true',
        body: data,
        json: true,
        headers: {
            'Content-Type': 'application/json',
            'X-Auth-Token': token
        }
    };
    return request.post(options);
}

– Sample Code Breakdown and Explanation

1. The main function is in charge of receiving data from the Sigfox Backend. As you may have noted, below the argument of the main function is the params; this argument will contain the body of the callback configured in the Sigfox Backend.

async function main(params) {
    // Receive and Parse data to be Posted at Ubidots
}

REMINDER: The sample body of the callback is going to be the one below: 

{
  "device_id": "{device}",
  "data":"{data}"
}

Now inside the main function of the sample code provided we need to manage the data received. This part of the code is going to be different depending on the hardware manufacturer and the data structure payload of said manufacturer. 

2. Now, assuming our sample data (Temp and Coordinates) is in the Sigfox Backend, we will now look at how to decode the payload into an Ubidots acceptable format, using the UbiFunctions engine to transform/parse the data.  

2.1. The below portion of the sample code, takes the parameters received from the Sigfox Callback and assigns them as temporary variables in the UbiFunctions engine.  

    /* Save device ID of the Sigfox Device */
    var device_id = params.device_id;
    /* Save data received from Sigfox */
    var buf = new Buffer(params.data, 'hex')

Here we can see that the key device_id received in the params object is being assigned to a variable called device_id. Also, how the key data is being assigned to a variable called buf which creates a new buffer with the proper encoding format hex.

The variable device_id is an unique identifier (Sigfox Device ID) per device, assigned by the Sigfox backend, and based on the underlying piece of hardware sending the sensor data. 

Note: Because the Sigfox ID is unique, multiple devices can be deployed using the same UbiFunction. Because the device ID from Sigfox will be assigned as device label in Ubidots, anytime data is updated using the same Sigfox ID, the corresponding device in Ubidots will automatically be updated. If a new Sigfox Device ID is identified, a new device in Ubidots will automatically be created.

2.2. Then, In the parse function of the sample code, the variable buf have to be parsed to get the variable values desired. For this, you need to split the bytes received based on the datasheet from the device's manufacturer.

In this case, remember that the structure used in this tutorial is:

  • 0x4F   - Temperature - Bytes #0 (1 byte) 
  • 0xC1B6C81C  - Latitude - Bytes #1 - #4 (4 bytes)
  • 0xC23C5514 - Longitude  - Bytes #5 - #9 (4 bytes)

Accordingly, the bytes are to be split in the following portion of the sample code. Remember that depending on your hardware, this is where your code will reflect the data you wish to POST in the payload to Ubidots.

    /* Parse the incoming data */
    var temp = buf.readInt8(0);    
    var lat = buf.readFloatBE(1);
    var lng = buf.readFloatBE(5); 

As you can see above, the variables temp, lat, and long are decoding and saving the values received by the Sigfox device. In this case, the values are being saved to the following variables:

  • The variable called "temp" is saving Bytes #0 (1 byte) 
  • The variable called "lat" is saving Bytes #1 - #4 (4 byte) 
  • The variable called "lng" is saving Bytes #5- #9 (4 byte) 

2.3. [OPTIONAL] If is desire, you can uncomment the following portion of code in order to debug and verify the values which are being parsed.  

    /*
    console.log(temp);
    console.log(lat);
    console.log(lng);
    */

2.4. With the values already decoded by UbiFunctions, it's time to build the body of the HTTP Request to be POST in your Ubidots Account. 

The data format supported and understood by Ubidots is JSON. Accordingly, you need to assign each value saved (temp, lat, and lng) to a respective variable label in Ubidots. These variables labels will be the identifying markers to update the variables of your Ubidots account.  

Please note that based on the Sigfox hardware used in your Application, you must modify the following portion of the sample code to fit the variable label and value needing to be sent:

    /* Build body to be POST at Ubidots */
    var payload = {
        "temperature": temp,
        "position": {
            "value":"1",
            "context":{
                "lat": lat,
                "lng": lng
            }
       }
    };

As you might have noted above, the body contains a variable called temperature with a value of "temp", plus a variable called position with the respective coordinates (latitude and longitude) assigned as default values. 

For additional details on how to handle values, context, or timestamps keys please refer to the Ubidots REST API Reference.

2.5. Now, with all the parameters needed, It is time to call the POST request function inside the main function of the sample code provided. As you can see in the following portion of code, the method ubidotsPost(x, x , x)
is being called.  

    /* Make POST request to Ubidots */
    var post_response = await ubidotsPost(token, device_id, payload);

Where the argument of the method are:

  •  Token: Your Ubidots Account TOKEN 
  • Device ID: The Sigfox Device ID received which is being saved in the variable called device_id 
  • Payload: The JSON body built with the data already decoded by the UbiFunction.

You can simply find the ubidotsPost() method after the main function:

sync function ubidotsPost(token, device_label, data) {to
    var options = {
        method: 'POST',
        url: 'https://industrial.api.ubidots.com/api/v1.6/devices/' + device_label + '?force=true',
        body: data,
        json: true,
        headers: {
            'Content-Type': 'application/json',
            'X-Auth-Token': token
        }
    };
    return request.post(options);
}

2.6. To finish let's talk about the last portion of code provided in the main function. This portion of code will return the status of the request:

    return post_response;

At this point, if everything is properly configured you will get the following 201  successful response:  

{
    "position":[{"status_code":201}],
    "temperature":[{"status_code":201}]
}

If you get a different status code, refer to its meaning with following the Ubidots Documentation.

3. Now that you have a better idea what the code provided is doing. It's time to save the changes made, and deploy it. To do so, just press the "Make it live." 

With the changes already saved, let's setup the Sigfox Callback to start receiving the data at Ubidots Cloud.  

3. Setting up the Sigfox callback to Ubidots

The management of the data between Sigfox and Ubidots requires a "Callback". 

The Sigfox hardware will read sensors and send the values (message) to a Sigfox Base Station to be forward to the Sigfox Backend. At this point, your data is already in the cloud (on the internet), so now it's time to make this message valuable using an IoT Application Enablement platform like Ubidots using Sigfox Callback.  

Sigfox Callbacks use HTTP requests to transmit data bi-directionally with any cloud service. In this case, we are going to show how to configure the Sigfox Callback to transmit data to Ubidots by using an UbiFunctions.

1. To begin, access to the Sigfox Backend where the hardware is transmitting data.

2. Go to the Device section and select the Device Type of the registered device:

3. Next, verify your device information and select "CALLBACKS" from the menu on the left-hand side of the page, as shown below:

Sigfox callbacks allow you to report data to an external system like Ubidots. To setup a callback to Ubidots API, use the following parameters:

  • Type: DATA   - UPLINK   
  • Channel: URL
  • Custom payload config: Leave it in  blank
  • Url pattern:  This is the URL generated by the UbiFunction in the steps above
https://parse.ubidots.com/prv/ubidots-tutorials/sigfox-device
  • Use HTTP method: POST 
  • Header:  Leave it in  blank 
  • Content Type: application/json    
  • Body:
{
  "device_id": "{device}",
  "data":"{data}"
}

After configuring the callback, it should look like this:

Once you've verified the callback, press "OK". 

Now your callback is ready and enabled to post the data received from the hardware to Ubidots. At this point, the data is going to be decoded based on the code already configured in the UbiFunctions engine (previous step), then post the data to your Ubidots account.

IMPORTANT DEPLOYMENT NOTE:  Ubidots and Sigfox communicate via either URL or Batch URL (used for large deployments). This tutorial explains the standard URL channel. If you have a large scale sensor network, please contact sales@ubidots.com to receive additional information for Batch URL integrations.

4. Checking data integration 

With the UbiFunction and Sigfox Callback configured, after the hardware updates a new value, you will see a new device is created automatically in your Ubidots account. If the device already exists, data will update everytime the Sigfox Backend receives a new input. 

  1. Go to the Device section of your Ubidots account and confirm the new device(s) were created. Please note that the devices created have been assigned the names of each pieces of hardware's respective Sigfox Device ID.

[TIP] - Don't like the Sigfox Device ID as your device's name in your Ubidots display? Don't worry! You can change the name to a more friendly one, but the device label will be stay as the Sigfox Device ID to never get confused which device is which. Reference to Ubidots Help Center for more on Device Labels and Device Name changes in Ubidots.

2. Check if the variables contained each device are correct, temperature and position

Coordinates:

3. [OPTIONAL] If desired or needed, you are able to see the logs for each time the function is triggered. To find the logs, simply press the "envelop" icon located in the control bar of the function you're looking to track. 

As you can see below, the logs provide both the time of execution and output values received from the Function

IMPORTANT NOTE: If you desire to returns device messages when at least one callback has failed, reference to the Sigfox API to know how to implement such a function.

5. Summary  

With this, your Sigfox Callback is ready and the UbiFunction is properly transforming data received to Ubidots. Now it is time to develop your application with Ubidots IoT application development and deployment tools.

Ubidots is an Internet of Things (IoT) Application Development Platform that empowers system integrators and innovators to launch control, monitoring, and automation applications that turn sensor data into actionable insights. Hiring an engineering team to merge the physical world with a digital world and create an IoT application that both function and look great is costly in both time and money, so Ubidots did it for you. Ubidots exists as an efficient and economical resource to develop private cloud-based IoT applications and integrate data-driven solutions into enterprises and research to drive-decisions and improve our working economy.

Other users also found useful:

Did this answer your question?