Sigfox wide-area, low power devices and Ubidots are a simple to integrate IoT solution from device to application. Track cars, buses, containers, trashcan, or even your golf-bag. Keep track of cattle or take your Sigfox device to go and explore the great outdoors.
In this tutorial we will be using UbiFunctions, a feature tool of Ubidots IoT application development platform.
Requirements
1. Setting up the Suntech ST730
The Suntech ST730 is a portable device equipped with Sigfox technology, the GNSS location, Wi-Fi, and a set of sensors — making it a nice option for out-of-the-box asset tracking. This module lets users manage data when needed, preventing excess energy consumption with efficient time-outs.
This guide will explain some of the possible configurations that the Suntech ST730 has, such as the highly resolution GPS location.
Note: Ubidots is committed to helping you connect your ST730 to our IoT and cloud application platform the easiest way possible. With more guides arriving all the time, see UbiFunctions for more data analytics functions to pair or enhance your applications.
Suntech ST730 GPS Set-up:
The Sigfox module is able to transmit a maximum of 12 bytes. The format of the information sent is:
The explanation of some available modes that the device has for data transmission can be found below. Each one will be take into account when performing the UbiFunction that decode these data and POST it to Ubidots.
GPS Location
This data type is composed by:
3 bytes for latitude in degrees.
3 bytes for longitude in degrees.
Both latitude and longitude are coded using the IEEE- Standard 754 floating point format. If a GPS reading doesn't follow this format, no data reading will be sent. Here's an example of a GPS reading properly done:
Example: 01c1b6c8c23c55
0x01 – data type
0xC1B6C8 –
latitude = -22.847710xC23C55 –
longitude = -47.083084
2. High resolution GPS location
Data format for GPS in this tutorial is:
4 bytes for latitude
4 bytes for longitude
Example: 02c1b6c81cc23c5514
0x02 – data type
0xC1B6C81C –
latitude = -22.847710xC23C5514 –
longitude = -47.083084
3. Temperature
In this case there are two possible options to calculate the value of the temperature in Celsius. If the value is less than 127, the temperature would be calculated as the following way:
Temperature = value / 2
Otherwise, If the value is greater than 127 the expression would be
Temperature = (256-value) / 2
Example: 0328
0x03 – data type
0x28 –
Temperature = 0x28 / 2 = 20
4. Battery voltage
This data is coded with a 0.1 volts resolution. So in order to obtain the value in V, the expression would be:
Voltage = value / 0.1
Example: 0422
0x04 – data type
0x22 –
voltage = 34 / 0.1 = 340 V
5. Battery level
This data is the charge of the battery in percentage
Example: 053C
0x05 – data type
0x3C –
Battery level = 60 %
6. Accelerometer
In order to obtain the values sampled by the accelerometer 3D sensor. Each axis takes 2 bytes and the resolution is 3.9mg
acceleration_x = x value * 3.91
acceleration_y = y value * 3.91
acceleration_z = z value * 3.91
Example: 08FFF9FF4700C7
0x08 – data type
FFF9 –
acceleration_x = -7 * 3.91 = - 27 mgFF47 –
acceleration_y = -185 * 3.91 = - 723 mg00C7 –
acceleration_z = 199 * 3.91 = 778 mg
7. Speed
This data type reports the speed value in km/h
Example: 0925
0x09 – data type
0x25 –
speed = 37 km/h
See the SuntechST730 User Manual for additional instructions or troubleshooting to your hardware's setup.
Once you have setup the module to send data with one of the options shown above, you will now be able to configure the UbiFunction.
2. UbiFunction Setup
After understanding the Suntech ST730 payload structure, in order to processed this data before sending to Ubidots, we have to use the UbiFunctions feature, which allows to transform and analyze the data provided by the device.
This feature will enable you to create a custom HTTP GET or HTTP POST request. UbiFunction accepts NodeJS8 and Python3 as illustrated below
For creating a Function go 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 add-on for $29/month in the billing section of your account.
2. Click the blue plus icon in the upper-right corner to create a function:
3. Assign a name to the Function e.g. "suntech-ubidots", to identify it in the Sigfox backend later, the POST as the HTTP method from the scrollbar and select the Python3 as a runtime.
4. Click on "Make it live" to generate an API endpoint URL containing the name of your function. The URL should look like this:
5. Now, just copy and paste the code below into the UbiFunction Editor. When pasted, assign your Ubidots TOKEN where indicated:
import requests
import struct
import json
#Constants
TOKEN = "" #Assign your Ubidots TOKEN
BASE_URL = "https://industrial.api.ubidots.com"
def data_type(data:str):
#obtain the data type
key = struct.unpack("B", bytearray.fromhex(data[0:2]))
return key
def gps_location(data:str):
#convert the string to hex and take the big endian '>'
#f:float
data = data[:8] + '00' + data[8:] + '00'
latitude = struct.unpack(">f",bytearray.fromhex(data[2:10]))[0]
longitude = struct.unpack(">f",bytearray.fromhex(data[10:18]))[0]
payload = {
"position":{
"value":1,
"context":{
"lat": latitude,
"lng": longitude
}
}
}
return payload
def gps_high_resolution(data:str):
latitude = struct.unpack(">f",bytearray.fromhex(data[2:10]))[0]
longitude = struct.unpack(">f",bytearray.fromhex(data[10:18]))[0]
payload = {
"position":{
"value":1,
"context":{
"lat": latitude,
"lng": longitude
}
}
}
return payload
def temperature(data:str):
rawTemperature = struct.unpack(">B",bytearray.fromhex(data[2:4]))
if rawTemperature[0]< 127:
temperature = rawTemperature[0]/2
else:
temperature = (256-rawTemperature[0])/2
payload = {
"temperature": temperature
}
return payload
def battery_voltage(data:str):
rawBattery = struct.unpack(">B",bytearray.fromhex(data[2:4]))
battery = rawBattery[0]/0.1
payload = {
"Battery": battery
}
return payload
def battery_level(data:str):
battery = struct.unpack(">B",bytearray.fromhex(data[2:4]))
payload = {
"Battery": battery
}
return payload
def accelerometer(data:str):
rawAcelaration_x = struct.unpack(">h",bytearray.fromhex(data[2:6]))
rawAcelaration_y = struct.unpack(">h",bytearray.fromhex(data[6:10]))
rawAcelaration_z = struct.unpack(">h",bytearray.fromhex(data[10:14]))
acelaration_x = rawAcelaration_x[0] * 3.91
acelaration_y = rawAcelaration_y[0] * 3.91
acelaration_z = rawAcelaration_z[0] * 3.91
payload = {
"acelaration_x": acelaration_x,
"acelaration_y": acelaration_y,
"acelaration_z": acelaration_z,
}
return payload
def speed(data:str):
speed = struct.unpack(">B",bytearray.fromhex(data[2:4]))
payload = {
"Speed": speed
}
return payload
def tracking(data:str):
latitude = struct.unpack(">f",bytearray.fromhex(data[4:12]))[0]
longitude = struct.unpack(">f",bytearray.fromhex(data[12:20]))[0]
rawBattery = struct.unpack(">B",bytearray.fromhex(data[22:24]))
battery = rawBattery[0]*0.5
payload = {
"Battery":{
"value":battery,
"context":{
"lat": latitude,
"lng": longitude
}
}
}
return payload
map_functions = {
1: gps_location,
2: gps_high_resolution,
3: temperature,
4: battery_voltage,
5: battery_level,
8: accelerometer,
9: speed,
32: tracking
}
def send_to_ubidots(payload:str,device:str):
url = "{}/api/v1.6/devices/{}".format(BASE_URL, device)
headers = {"X-Auth-Token": TOKEN, "Content-Type": "application/json"}
req=requests.post(url,json=payload,headers=headers)
return req
def main(args):
print(args)
#jsonData=json.loads(args)
print(args['data'])
key = data_type(args['data'])
function = map_functions.get(key[0], None)
if function is None:
return {"Status": "Mode not available in this function"}
payload= function(args['data'])
req=send_to_ubidots(payload,args['device'])
# Prints the request result
print("[INFO] Request result:")
print(req.text)
return {"status": "Ok", "result": req.json()}
For running a function test, please paste this code in the editor that popups:
{"device": "12345", "data": "02c1b6c81cc23c5514"}
3. Sigfox Callback Configuration
Click here for an introduction and documents to configure a call in the Sigfox backend with your Suntech device. For this, you will need to use the parameters listed below.
Type:
DATA-UPLINKChannel:
URLCustom payload config: Leave it in blank
Url pattern:
https://parse.ubidots.com/prv/iotexpo/suntech-ubidots(this is the URL generated by the Ubidots parser in the step above)Use HTTP method:
POSTHeader:
X-Auth-Token-{Assign_your_ubidots_token}Content Type:
application/jsonBody:
{
"device": "{device}",
"data":"{data}"
}When the callback is executed properly, your Sigfox backend will look similar to this:
2. Press "OK" to save all the changes and visualize your new device in Ubidots.
With this, your Sigfox callback is ready and the UbiFunction is properly transforming data received to Ubidots cloud. Now it is time to develop your application with Ubidots code-free IoT application tools.
Go to the Device section and see a newly created device with the ID of Suntech Device as name:
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 functions and looks great is costly in both time and money, so we 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.