Sigfox

Avatar
Databoom Master
Follow

 Are you looking for Databoom device configuration? Click HERE

Sigfox Back-End

Sigfox Back-End provides a web interface for devices management and configuration, besides some APIs to automate operations. APIs are based on HTTPS REST requests, as GET and POST, the payload is in JSON format.

 

 

Activation procedure

To access the back-end it is required to contact Sigfox to get the connectivity for the modules to connect to the Sigfox network. The procedure consists of the creation of an account with a valid mail address and a password. Is therefore possible to create a group, an user, a device type and the devices. It is then required to associate each serial number and PAC with a license.

 

 

Login

Once the activation procudere has been completed, access credentials will be available.

After the fields have been filled, the main page of the Sigfox back-end is loaded, with the list of news and updates. From the side menu it is possible to view the network events and the servie map.

 

 

Device

By clicking Device in the top menu, the list of devices associated with the account is shown.

  • The initial area allows to filter and search devices;
  • The gear on the right, and the next click on "Select the columns to show/hide" allows to edit the visible columns;
  • By clicking the device type the type detail page is shown;
  • By clicking the ID the device detail page is shown.

 

 

Device - Info

All the device main info is listed in the page. From the side menu the specific areas are accessible.

 

 

Device - Location

It visualizes a map with the device location, if set. By clicking the flag marker, more details are shown as the latitude and longitude.

 

 

Device - Messages

  • The initial area allows to filter and search messages, besides to export data in CSV format;
  • From the dropdown it is possible to choose the visualization order;
  • The listed fields are:
    • Message receiving date and time;
    • Delay, in seconds;
    • Message header;
    • Package data;
    • Location;
    • Signal and reception details;
    • Transmission status according callback result or ACK request.

 

 

Device - Events

An event represents the change of a specific communication paramenter. Events are used from Sigfox to monitor a device activities and to notify administrator users of irregular device activity.

 

 

Device - Statistics

Shows graph on the transmitted info:

  • Messages;
  • Bytea;
  • Received SNR messages;
  • RSSI;
  • Temperature;
  • Vdd;
  • Frequency.

 

 

Device - Event configuration

It is possible to configure the devices alerts and to receive notifications via email when they happen. Email content is not customizable. By clicking on New the page to set the event type and the email addresses is shown.

 

 

Device Type

By clicking Device Type in the top menu, the list of the devices types is shown.

  • The initial area allows to filter and search devices types;
  • The gear on the right, and the next click on "Select the columns to show/hide" allows to edit the visible columns;
  • The click on the group opens the details page of the group the device belongs to;
  • The click on the name of the type shows its detail page;
  • The click on the row outside the links opens the dropdown menu. By clicking Edit the edit page of the type is shown.

 

 

Device Type - Edition

It is possible to access the edition page of a type of device by clicking the proper option in the device list menu or by clicking the Edit button in the deviec type page.

The edition page is splitted in three sections:

  • Device type information;
  • Downlink data;
  • Display type.

Device type information

It is possible to edit the device type name, add a description, set a keepalive time (in seconds) and define the emails where the callback are forwarded, if set for that purpose.

Downlink data block

In this section the type of used downlink data mode is defined:

  • Direct, if the Sigfox module requests an ACK at the end of transmission, the field Downlink data in hexa can be filled with the response in hexadecimal format.  Variables {time}, {tapid} e {rssi} can be used;
  • Callback, if this mode is enabled, an email is automatically sent when data arrives, while no ACKs is sent as answer. If the module tries to sent a package requiring ACK, it fails.

Display block

In this section it is possible to specify the message format. You can choose among:

  • None, no format is specified. It is used for raw data;
  • Geolocation, option reserved for GPS compatible devices;
  • String, to send plain text;
  • Test, only for testing;
  • Custom, to customize the frame format.

Some more information about frame customization:

format = field_def [“ “ field_def]* ;
field_def = field_name “:” byte_index “:” type_def ;
field_name = (alpha | digit | “-” | “_”)* ;
byte_index = [digit*] ;
type_def = bool_def | char_def | float_def | uint_def ;
bool_def = “bool:” (“0” | “1” | “2” | “3” | “4” | “5” | “6” | “7”) ;
char_def = “char:” length ;
float_def = “float:” (“32”) ;
uint_def = “uint:” (“8” | “16” | “24” | “32”) [ “:little-endian” | “:big-endian” ] ;
length = number* ;
digit = “0” | “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9”

A field is defined by its name, its location in the message, it length and its type:

  • The name (field_name) can have letters, digits and the characters '-' and '_';
  • The index (byte_index) is the offset in the message, starting from 0, after which the field is read. If omitted, the position used is the current byte for boolean fields while the next byte is used with other types. For the first field, the position omission indicates the start of message buffer.
  • Following there are the type name and parameters, that change according the type:
    • boolean: the parameter and the bit location in the byte;
    • char: the parameter is the number of bytes to gather in a string;
    • float: the parameter is the length in bit of the value. Decoding follows the IEEE 754 standard;
    • uint: the parameters are the number of bits to include in the value, and optionally the byte order for multi-bytes integers. Default order is big endian.

 

 

Device Type - Information

All the device type info is shown. From the side menu the specific areas are accessible.

 

 

Device Type - Location

It shows all the modules associated to the device type if the latitude and longitude data is specified. By clicking the flag marker, more info about the device is shown.

 

 

Device Type - Associated devices

It shows all the modules associated to the device type (same view as the devices list).

 

 

Device Type - Devices being transferred

It shows a list of devices being transferred.

 

 

Device Type - Statistics

It shows graphs about the transmitted information.

 

 

Device Type - Event configuration

It is possible to configure the alerts that are sent to the emails specified in this section. By clicking on New the page to cronfigure a new alert is shown.

 

 

User

The list of users created in your group. It is possible to create new users associated to the group or to edit the existing users. To create a new user, click the New button on the top right.

The Roles block allows to specify new user's permissions. It is possible to choose only one group. Once the group is selected, the role choice is enabled.

The email field is used to send registration email, it is required to choose an access password.

By clicking an user it is possible to edit it by clicking Edit from the dropdown menu. You can edit or delete every user excepting yours.

 

 

Group

In this section only the group you belong to is shown. From the side menu you can access the detail pages.

 

 

Group - Information

It shows all the information about the group selected previously.

 

 

Group - Associated users

It shows all the users associate to the group.

 

 

Group - Associated device types

It shows all the devices types associate to the group.

 

 

Group - Event configuration

It shows the events according to the group.

 

 

How to extract data from Sigfox server

Callback

The beck-end can automatically forward events using callback system. It is possible to create a new callback by clicking the Callbacks  button in the side menu of the Device Type section. A callback is activated when a new message is received or there is a communication loss.

There are three types of callbacks:

  • DATA
  • SERVICE
  • ERROR

There is a variables set for each type of callback. These variables are substituted with their values when a callback is called.

In the page all the configured callback are listed. If no callback is present a link to the documentation is shown (https://backend.sigfox.com/apidocs/callback).

Following there is the Databoom data forwarding callback, with the POST API https://api.databoom.com/v1/sigfox/data. A valid OAuth token is required in the header field.

https://api.databoom.com/v1/sigfox/data

{
  "devicetype": "sensit",
  "device": "{device}",
  "time": "{time}",
  "snr": "{snr}",
  "station": "{station}",
  "data": "{data}",
  "avgSignal": "{avgSnr}",
  "lat": "{lat}",
  "lng": "{lng}",
  "rssi": "{rssi}",
  "seqNumber": "{seqNumber}",
  "ack": "{ack}"
}

https://api.databoom.com/v1/sigfox/servicerepeater

{
  "device": "{device}",
  "time": "{time}",
  "duplicate": "{duplicate}",
  "snr": "{snr}",
  "rssi": "{rssi}",
  "station": "{station}",
  "avgSnr": "{avgSnr}",
  "lat": "{lat}",
  "lng": "{lng}",
  "batt": "{batt}",
  "whitelistDevices": "{whitelistDevices}",
  "repeatedMsg": "{repeatedMsg}",
  "unwantedDevices": "{unwantedDevices}",
  "unwantedMsg": "{unwantedMsg}",
  "wrongMsg": "{wrongMsg}",
  "overRegulMsg": "{overRegulMsg}"
}

https://api.databoom.com/v1/sigfox/servicegeoloc

{
  "device": "{device}",
  "time": "{time}",
  "duplicate": "{duplicate}",
  "snr": "{snr}",
  "rssi": "{rssi}",
  "station": "{station}",
  "avgSnr": "{avgSnr}",
  "lat": "{lat}",
  "lng": "{lng}",
  "radius": "{radius}",
  "seqNumber": "{seqNumber}"
}

https://api.databoom.com/v1/sigfox/servicestatus

{
  "device": "{device}",
  "time": "{time}",
  "duplicate": "{duplicate}",
  "snr": "{snr}",
  "rssi": "{rssi}",
  "station": "{station}",
  "avgSnr": "{avgSnr}",
  "lat": "{lat}",
  "lng": "{lng}",
  "temp": "{temp}",
  "batt": "{batt}",
  "seqNumber": "{seqNumber}"
}

https://api.databoom.com/v1/sigfox/serviceacknowledge

{
  "device": "{device}",
  "time": "{time}",
  "duplicate": "{duplicate}",
  "snr": "{snr}",
  "rssi": "{rssi}",
  "station": "{station}",
  "avgSnr": "{avgSnr}",
  "lat": "{lat}",
  "lng": "{lng}",
  "infoCode": "{infoCode}",
  "infoMessage": "{infoMessage}",
  "downlinkAck": "{downlinkAck}",
  "downlinkOverusage": "{downlinkOverusage}"
}

https://api.databoom.com/v1/sigfox/error

{
  "device": "{device}",
  "time": "{time}",
  "info": "{info}",
  "severity": "{severity}"
}

API access

Some features of the Sigfox back-end are accessible programmatically using a webservice API. This API uses the HTTP protocol with REST principles.

All the API endpoints returns data in JSON format, with application/json content-type in the header.

Creating an API access is really easy, click the New button in the Api Access page accessible frome the side menu in the group section, therefore fill the form with a name to identify the access and a role selected from the list.

Once it has been saved, credentials to connect to the API service are shown.

 

 

When is Sigfox recommended?

Sigfox is a protocol with good long-range performances.  Despite this, a long time is required to send a single packet (from 6 to 12 seconds) and there is a limit of 140 packets per day with a maximum payload of 12 bytes according to ETSI standard on 868MHz band in Europe.

  • Sigfox is not advised for projects with a regular duty cycle, that require frame forwarding every few minutes. Exceeding the 140 packets limits can cause fees increase or license deletion from Sigfox;
  • Sigfox is advised for long-range communications in cities where its stations are present;
  • Sigfox is not advised for bidirectional communications. It doesn't exist a real downlink, although acknowledgments and callbacks are available;
  • Sigfox is not advised for realtime straming. The transmission is not in realtime because there is a minimum delay for packages reception;
  • Sigfox is not recommended for the transmission of big amount of data. Maximum payload is of 12 bytes.

 

 

Databoom device configuration

When creating a new device it is possible to choose Sigfox as device type. 

Sigfox device type allows to specify some signals and a transformation function to manage the payload sent to callback https://api.databoom.com/v1/sigfox/data

Signals are the fields in the payload that will be read as signals, as for default Databoom considers the following fields: 

pressure type snr avgSignal lat lng rssi seqNumber avgSnr temp batt radius 
latitude longitude decibel variable temperature humidity counter status 
temperature0 temperature1 temperature2 temperature3 temperature4 
humidity0 humidity1 humidity2 humidity3 humidity4 
counter0 counter1 counter2 counter3 counter4 
status0 status1 status2 status3 status4 
s0 s1 s2 s3 s4 s5 s6 s7 s8 s9
By adding extra1, extra2 e extra3 as signals to the device, it means that the three fields will be searched in the payload and if found they will be stored in Databoom.
 
Payload transformation function is applied to payload data field and must return an object where keys are signal tokens and values are their values. Signals parsed in data don't need to be listed in valid signals as they are stored automatically.
 
The following code snippet is an example of payload sent to callback https://api.databoom.com/v1/sigfox/data
{
  "device":"0a50ptiq3w",
  "time": 1598281290,
  "data":"{\"pm1\": 13, \"pm2\": 14, \"pm3\": 15}",
  "extra1":4,
  "extra2":5,
  "extra3":6
}

The device set as in the screenshot allows to store extra1, extra2 and extra3 values while the data field is processed by the transformation function.

Example function converts data content in JSON and therefore returns it as an object so it can be stored correctly.

function managePayload(payload) {
 var object = JSON.parse(payload);
 var toReturn = {};
 
 for(var k in object){
 toReturn[k] = object[k];
 }
 
 return toReturn;
}
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
2022 © Copyright Databoom Srl - VAT IT 02437420223 - support@databoom.com