Sigfox is an inexpensive, reliable, low-power solution to connect sensors and actuators with a dedicated radio-based network committed to integrating devices into IoT. By following the steps provided in this tutorial you will be able to retrieve, decode and display Sigfox data on your Ubidot's account without having to worry about programming API requests. Focus on decoding your data and leave the rest up to Ubidots by using this plugin.
Requirements
An active Ubidots account.
An active Sigfox account.
Table of contents
1. Sigfox plugin Installation on your Ubidots account
Step 1: Sign in to your Ubidots account, then go to devices -> plugins
Step 2: Click on Create Data Plugin
Step 3: Install the plugin, look for the Sigfox plugin as seen below, and click on it
you will see a description of the plugin and its current versión, then click on continue.
Step 4: Configure the plugin by entering the Device Type label you want to assign, then select the account's token you wish to use from the dropdown list.
NOTE: A Device Type will be created using a Type label, your Sigfox device will be created under that type.
Step 5: Enter a name and description for your plugin, then click on continue.
Step 6: Go to Decoder. Notice that you will be provided with an endpoint URL used to encode the decoding function, you must enter that URL later on Sigfox callback settings.
2. Program your decoding function.
You will be given a development environment where you can program and decode Sigfox data using Python 3.7 and return a Ubidots compatible JSON.
This programming environment is divided into 2 sections
Test Payload: There you enter a sample payload that simulates the incoming Sigfox data in JSON format, by clicking on "Test run", the decoding function will be executed using the test Payload as input. The output will be shown on the console.
Code Editor: There you enter your Python function's body where indicated, once you're happy with the code click on "SAVE&MAKE LIVE" button to save it.
3. Decoding example
It's important to clarify that Sigfox devices transmit data in different payload structures depending on the device manufacturer. It is suggested to review the datasheet provided by the maker to understand the coded payload, its structure, and how it should be decoded prior to being posted to Ubidots. For testing purposes, let's assume that your Sigfox callback is set up to send the data using the following JSON structure to Ubidots:
{
"device_id": "adff55d1",
"data": "4fc1b6c81cc23c5514"
}
Sample data from Sigfox Device: 4fc1b6c81cc23c5514
How do we make sense of this big-endian encoded payload?
Well, this is how bytes are distributed:
0x4F- Temperature - Byte #0 (1 byte)0xC1B6C81C- Latitude - Bytes (1 - 4) (4 bytes)0xC23C5514- Longitude - Bytes (5 - 8) (4 bytes)
Bytes in Total: 9
3.1 Program the decoding function body as follows.
Here's the whole decode_data() function if you wish to copy and paste it:
def decode_data(hex_array):
payload = {}
temp = int(hex_array[0])
lat = round(struct.unpack('>f', hex_array[1:5])[0],2)
ln = round(struct.unpack('>f', hex_array[5:10])[0],2)
payload['temperature'] = {'value': temp, 'context':{'lat':lat, 'lng':ln}}
return payload
Save the code by clicking on the "SAVE&MAKE LIVE" button.
3.2 Test the payload
Enter the JSON test payload within the curly braces and click on "TEST RUN".
As a result, the output seen on the console should return a 201 HTTP code, indicating that data was decoded and represented successfully as a dot inside your Ubidots account.
3.3 Check the uploaded Data on Ubidots
On your account go to devices->Types then to your Type in this case, "sigfox-devices" and finally to the device: "ad:ff:55:d1", there you will see the variable created.
Click on the "temperature" variable to check the decoded Sigfox data.
4. Setting up Sigfox Callback to Ubidots
Data transfer between Sigfox and Ubidots requires a "Callback". Sigfox hardware will read sensors and send collected data (messages) to a Sigfox base station to be forwarded to their backend. At this point, your data is already in the cloud (on the internet). Now, It's time to make this message valuable using an IoT platform like Ubidots by deploying a Sigfox Callback.
Sigfox Callbacks use HTTP requests to transmit data bi-directionally with any cloud service. In this case, we are going to configure the Sigfox Callback to forward data to Ubidots by following these steps:
Step 1: Sign in to Sigfox and go to "Device" as indicated below.
Step 2: Select any device from your device list, for this example, we will use one called "Oyster_Tracker".
Step 3: Click on "CALLBACKS" on the left side menu
Step 4: Create a "New" Callback as you can see below on the right-top corner of the image below.
Step 5: Select "Custom callback".
Sigfox callbacks allow you to transfer data to an external system like Ubidots.
Step 6: Set up a callback to Ubidots API, using the following parameters:
Type: DATA - UPLINK
Channel: URL
Custom payload config: Leave it in blank
Url pattern: There goes the URL generated by the plugin, see section 1, step 6
Use HTTP method: POST
Header: Leave it in blank
Content-Type: application/json
Body:
{
"device_id": "{device}",
"data":"{data}"
}Once configured the callback should look like this.
IMPORTANT NOTE: To avoid authentication issues between the Sigfox callback and Ubidots, make sure to check the “SEND SNI” option.
Once you've verified the callback, press "OK".
At this point, the data is going to be decoded based on the code already configured in your decoding function, then it will post the decoded data to your Ubidots account.
IMPORTANT DEPLOYMENT NOTE: Ubidots and Sigfox communicate via either URL or Batch URL (used for large deployments). This article covers 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.