Sigfox Back-End

The Sigfox Back-End provides a web application interface for device management and configuration of data integration, as well as standards based web APIs to automate the device management and implement the data integration.

The APIs are based on HTTPS REST requests, as GET or POST and the payload format is JSON.

Activation process

The first thing you need to do is to contact Sigfox in order to hire the connectivity service for the modules with which you want to transmit to the Sigfox network.

Sigfox will give instructions to you about how to do it. Basically you have to create an account with a valid email address and a password. Then you will create your group, user, device type and device units. You need to pair the Serial Number and PAC number of every module with a license.

Login

Once you complete the activation process, you will have the credentials (email address and password) needed to connect to the system in https://backend.sigfox.com

Figure: Sigfox login page

Once logged in, you arrive to the main page of the Sigfox back-end with the latest news and updates, events and coverage map. You can check all this information in the links located on the left menu.

Figure: Sigfox welcome page

Device

By hitting on “Device” button (top menu), you will get information related to all devices associated to your account. The operations allowed on this list are:

Figure: Sigfox device list page

1. The gray zone is a filter form where you can perform your devices searches.

2. By clicking on this icon you can select the columns you want to see on the list.

3. Device type associated to the device (for further information please refer to Device type chapter).

4. This is the most important operation because it will take you to all the information related to this specific device. On the left side of the window, a menu will appear with all the possibilities available for a single module.

Once a specific device ID is clicked, the back-end leads you to that specific device information area. The next chapters are related to all the options available inside the device area.

Information

Shows all information related to the selected device.

Figure: Sigfox device information page

Location

Displays the device position on a map if the user sets up a specific location in the device's information. If you click on the flag marker you will get more information about the device.

Furthermore, you can select from the drop-down the option “Coverage overlay” to see the coverage information on the map. It is just an approximation based on what base stations received the latest messages.

Figure: Sigfox device information page

Messages

In this section you can find all information about all messages received on the Sigfox platform. It is possible to see several columns for:

• The packet arrival timestamp

• The packet data

• Location

• Signal strength

• Packet transmission status depending if callback or ACK is required

Figure: Sigfox device messages page

Events

A device event is a specific communication parameter change that can occur during a device lifetime. Device events are used by Sigfox to monitor device activity and to notify administrators of irregular device activity.

Figure: Sigfox device events page

Statistics

It shows some graphs about the transmitted information:

• Messages

• Bytes

• Received message SNR

• RSSI

• Temperature

• Vdd

• Frequency

Figure: Sigfox device statistics page

Event configuration

You can configure your own device alerts and be notified by an email when these situations happen. These emails are generic notifications and not customizable. After clicking “New”, the configuration information is shown in order to set the event type and email addresses. For further information, press the “Online help” button.

Figure: Sigfox device event configuration process

Device Type

In the “Device Type” section, you will find information about the characteristics of your device. Firstly, you will find the typical list. Besides there is a “New” button to create new Device Types.

Figure: Sigfox device type list page

1. The gray zone is a filter form where you can perform your devices searches.

2. By clicking on this icon you can select the columns you want to see on the list.

3. This link shows the group information page which the device type selected belongs to.

4. This link takes to the Device Type Information area. Information is shown divided in sections that you can access clicking on the left menu (read the Device Type Information section).

5. The Edit Operation link takes to a form where the user can edit the information of the selected Device Type (read the Edit section).

Once a specific device type is clicked, the back-end leads you to that specific device type information area. The next chapters are related to all the options available inside the device type area.

Edit

On the top right side of the website you find the “Edit” button in order to change the settings of the device type as you consider appropriate for your requirements.

Figure: Sigfox device type edit page

In the “Edition” window it is possible to change:

• Device type information

• Downlink data

• Display type

Device type information block

It is possible to change the “Name” of the device type, add a “Description”, set the “Keep-alive” settings and define the email address where the callbacks are going to be sent in case this device type is enabled for that purpose.

Figure: Sigfox Device Type information block

Downlink data block

In this section it is needed to define the type of downlink data mode used:

• Direct (default): If the Sigfox module requires an ACK when a transmission is done, the “Downlink data area” can be filled to answer the module with that information. In the next example, we have used this format: {time}0000{rssi}. When a module sends a frame requiring ACK, it will receive this hexadecimal data as a response. For instance: 55dd7bde0000ffa3. Where 0x55dd7bde is the Unix timestamp (1440578526 → 08/26/2015 @ 8:42am UTC) and 0xffa3 (-93 dBm) is the RSSI value.

• Callback: If this mode is enabled, an automatic email is sent upon data arrival to the address defined in the “Device type information” block. The user must keep in mind that when the callback mode is selected in this block, no ACK (downlink data) will be performed to the module. In other words, if the module attempts to send a packet requiring an ACK, the process will fail.

Display type block

Here you can create the format of your message. On the list you have to choose:

• None: If you do not want to specify any frame format. It is used for raw data.

• Geolocation: (Not available) This feature is reserved for compatible embedded GPS devices only.

• String: If you want to send a string text.

• Test: Only for testing.

• Custom: You can create your own frame format to send information.

Figure: Sigfox Device Type display type block

In this example, we used this format:

Temp::float:32 AccX::uint:16:little-endian AccY::uint:16:little-endian AccZ::uint:16:little-endian Battery::uint:8 Digital8::bool:7 Digital7::bool:6 Digital6::bool:5 Digital5::bool:4 Digital4::bool:3 Digital3::bool:2 Digital2::bool:1 Digital1::bool:0

Then in your messages you will see the information like this:

Figure: Sigfox message information received

Here you can find more information about how to customize your own frame:

• 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 position in the message, its length and its type:

• The field name is an identifier including letters, digits and the '-' and '_' characters.

• The byte index is the offset in the message buffer where the field is to be read from, starting from zero. If omitted, the position used is the current byte for boolean fields and the next byte for all other types. For the first field, an omitted position means zero (start of the message buffer).

Next comes the type name and parameters, which varies depending on the type:

• boolean: parameter is the bit position in the target byte.

• char: parameter is the number of bytes to gather in a string.

• float: parameter is the length in bits of the value (only 32 bits). Decoding is done according to the IEEE 754 standard.

• uint (unsigned integer): parameters are the number of bits to include in the value, and optionally the endianness for multi-bytes integers. Default is big endian.

Examples:

Format	Message (in hex)	Result
int1::uint:8 int2::uint:8	1234	{int1:0x12, int2:0x34 }
b1::bool:7 b2::bool:6 i1:1:uint:16	C01234	{b1:true, b2:true, i1:0x1234}
b1::bool:7 b2::bool:6 i1:1:uint:16:little-endian	801234	{b1:true, b2:false, i1:0x3412}
b1::bool:7 b2::bool:6 i1:1:uint:16:little-endian i2::uint:8	80123456	{b1:true, b2:false, i1:0x3412, i2:0x56}
str::char:6 i1::uint:16 i2::uint:32	41424344454601234567890A	{str:“ABCDEF”, i1:0x123, i2:0x4567890A}

Information

On the left side of the device type window it is possible to select the information area. It shows all information of the selected Device Type.

Figure: Sigfox device type information page

Location

Displays all modules assigned to this device type, if they have latitude/longitude data. By hitting on the markers located on the map, another window is opened with more information about the device.

Figure: Sigfox device type location page

Associated devices

Shows a device list (same as Devices section) with all devices associated to this specific device type.

Figure: Sigfox device type associated devices page

Devices being transferred

Here you can find a list with the devices which are being transferred. You have to select the group and confirm the filter form to see the results.

Figure: Sigfox device type devices being transferred page

Statistics

It shows some graphs about the transmitted information.

Figure: Sigfox device type statistics page

Event configuration

You can configure alerts which will be sent by email to the addresses you indicate in this section. You have to click on “New” and fill the form with the alert you want to configure.

Figure: Sigfox device type event configuration process

User

In this area you can see all users created in your group. You can create users always associated to your group or edit anyone created before, even your own user.

To create a user, you have to click on the “New” button and fill the form.

Figure: Sigfox new user page

The roles block is required to set the privileges of the user you want to create. First, you have to select the group, you can only choose one: to the one you belong to. Once the group was selected, you can choose between two roles. If you hit on the info link (the question mark icon near the name), you will get the permissions assigned to the role.

Figure: Sigfox new user roles block

The email field is very important and you must enter an existing account because when you create the user, an email will be sent in order to establish the password. To create the password, you have to follow the link and the instructions sent.

Figure: Sigfox new user roles block

You can edit all users created and delete all, except your own user. If you want to do any of these operations, you have to click on the user register outside of blue links.

Figure: Sigfox user list options

You can edit all information you can see in the form, even the password, but take into account your password will be required to change other user's password (excluding your own user), as you can see in the next figures.

Figure: Sigfox edit user options

Group

In this section you can see only the group you belong to. You will find more information shown on the left menu.

Figure: Sigfox groups page

Information

Shows all information of the group selected previously.

Figure: Sigfox information group page

Associated users

Shows a users list (same as User section) with all users associated to this group.

Figure: Sigfox group users associated page

Associated device types

Shows a device types list (same as Device type section) with all device types associated to this group.

Figure: Sigfox group device types associated page

Event configuration

You will see information similar to the shown in the Device event configuration section, but in this case depending on your group type.

Figure: Sigfox group device types associated page

How to extract the data from the Sigfox servers

Callbacks

The Back-End can automatically forward some events using the «callback» system. The “Callbacks” button in the “Device Type” section permits to create new callbacks associated to that device type. The callbacks are triggered when a new device message is received or when a device communication loss has been detected.

There are three different callback types:

• DATA

• SERVICE

• ERROR

There is a set of available variables for each type of callback. These variables are replaced by their value when a callback is called.

Firstly, in this page you will see all the callbacks you configured. If you did not configure anything yet, a link with the Sigfox callback documentation link is printed. Anyway, you can access to this manual on this URL: https://backend.sigfox.com/apidocs/callback (you must be logged in the Back-End).

Here we show a callback example: once Sigfox Back-End receives one frame, it will execute the callback which is in charge of writing all data in a file of one server. Furthermore, it will send an ACK frame to the sender to verify the information has been received correctly and it will send data to the device. To create this callback you have to hit on “New” button and fill the following form:

Figure: Sigfox device type callbacks form

The URL pattern would be something like this:

http://YOUR_DOMAIN/data.php?id={device}&time={time}&duplicate={duplicate}&snr={snr}&station={station}&data={data}&avgSignal={avgSignal}&lat={lat}&lng={lng}&rssi={rssi}&seqNumber={seqNumber}&ack=true

In this case, it is necessary to activate the downlink data in order to send information to the device from the created script. So once the callback is saved, we are able to activate it just clicking on the circle located near the downlink table header. It will be marked, indicating it is active.

Figure: Sigfox downlink activation

Then in our server we need to create the data.php file, in order to get all data sent from the callback and save it in the final file.

<?php
    $data['data'] = array(
	"id" 		=> $_GET["id"],
     	"time" 	=> $_GET["time"],
     	"duplicate" 	=> $_GET["duplicate"],
     	"snr" 		=> $_GET["snr"],
     	"station" 	=> $_GET["station"],
     	"data" 	=> $_GET["data"],
     	"avgSignal" 	=> $_GET["avgSignal"],
     	"lat"		=> $_GET["lat"],
     	"lng"		=> $_GET["lng"],
     	"rssi" 	=> $_GET["rssi"],
	"seqNumber"	=> $_GET["seqNumber"], 
     );

     if ($fd = fopen('YOUR_PATH/sigfox.json','a')){
       fwrite($fd,json_encode($data));
       fclose($fd);
     }

     header('Content-Type: application/json');
     $downlink= (array(
                        $_GET["id"] => (array('downlinkData' => '0102030405060708')) /*downlink data must be 8 bytes in hexadecimal format*/
                ));
     echo json_encode($downlink);
?>

Whenever the callback is executed, the PHP will save in the file a JSON string like this:

{"data":{"id":"10186","time":"1440687059","duplicate":"false","snr":"17.66","station":"0CD2","data":"41ea000064014c00daff2b00","avgSignal":"22.65","lat":"42","lng":"-1","rssi":"-129.90","seqNumber":"259"}}

{"data":{"id":"10186","time":"1440687059","duplicate":"false","snr":"17.66","station":"0CD2","data":"41ea000064014c00daff2b00","avgSignal":"22.65","lat":"42","lng":"-1","rssi":"-129.90","seqNumber":"259"}}

At the same time, in the device messages list, we can find the information received, the callback status, the downlink status and content, and if the ACK was received.

Figure: Sigfox device type callbacks and downlinks

And finally in our device, we will receive the downlink data sent from the callback process.

Figure: Sigfox downlink received

API access

Some of the features found on the Sigfox Back-End website can also be accessed programmatically using a webservice API. This API uses the HTTP protocol, following the REST principles.

All API endpoints return data in the JSON format, with the corresponding «application/json» content type header.

Creating an API access is very simple, just click on the “New” button, and fill the form with a name to identify this API access and a role picked from the list.

Figure: Sigfox group API creation process

Once it is saved, you will find your user and password to connect to the API service and a link to the API documentation with instructions and examples which are very helpful to create your application.

Figure: Sigfox group API access page

An example of this functionality could be getting a list of all messages received by a device. First of all, read and understand the General protocol information you can find in the documentation. This is highly recommended because it explains the functionality and a short example of the API. Then, we find the section Messages sent by a device, needed to develop our example and where we can see the URL to obtain the information we want to use. We are going to use PHP to do the example, using CURL to get the information.

<?php

$user = "##YOUR_USER##";
$password = "##YOUR_PASSWORD##";
$url = "https://backend.sigfox.com/api/devices/##YOUR_DEVICE_ID##/messages";

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_USERPWD, "$user:$password");
$result=curl_exec($ch);
curl_close($ch);

$data = (json_decode($result, true));

?>


<html>
	<table>
	<thead>
		<tr>
			<th>device</th>
			<th>time</th>
			<th>data</th>
			<th>snr</th>
		</tr>
	</thead>
	<tbody>
		<?php
			foreach($data['data'] as $reg){
		?>
			<tr>
				<td><?php echo $reg['device']?></td>
				<td><?php echo $reg['time']?></td>
				<td><?php echo $reg['data']?></td>
				<td><?php echo $reg['snr']?></td>
			</tr>
		<?php
			}
		?>
	</tbody>
</html>

In this example, you have to replace the three variables at the top of the code with your API credentials ($user and $password) and the device ID you want to get the messages ($url). Then a table is printed on your web browser with the messages.

device	time	data	snr
1B9C5	1441211241	41e0000066013200eeff4d00	23.66
1B9C5	1441207554	000102030405060708090a0b	24.23
1B9C5	1441207440	0011223344aabb	23.69
1B9C5	1441193326	000102030405060708090a0b	23.65
1B9C5	1441023751	010203040506070809	24.41