Introduction

The SIGFOX backend allows to manage entities on the

SIGFOX network, such as Base Stations and Modems.
This can be achieved through differents means:
Graphical User Interface
Application Programming Interface
Message data access via the use of Callbacks

Introduction
 Introduction

Introduction
 GUI Principles

GUI Principles
 GUI Principles

General layout has the main menu as a top bar, and

secondary menus as tabs on the left side of each page:

GUI Principles
 GUI Principles

Action buttons are always placed on the upper right

corner of each page:

GUI Principles
 About the unique IDs

Each physical object (Device, Base Station) receives a

unique ID, not moveable, not exchangeable. This ID
references the entity over all the SIGFOX network,
amongst all country Distributors.

About the unique IDs

 Entity Hierarchy

Entity hierarchy
 Entity hierarchy : Devices and Device Types

A Device belongs to a
Device Type Water metering 1 Device Type

A Device Type may

contain one or more
Device Device Devices

0001 00B2

Entity hierarchy : Devices and Device Types

 Entity hierarchy : Groups and Device Types

A Device Type belongs

Group Company 1 to a Group

Device Type
Device Type Water A Group may contain
Power
metering 1
metering one or more Device
Types
Device Device Device Device

0001 00B2 0AB3 1875

Entity hierarchy : Groups and Device Types

 Entity hierarchy : User roles

View
A user is linked to a
Create group through its role
User 1 : ADMIN Entities
within it.
Group Metering company

Modify

Delete

User 2 : USER Entities View The allowed actions

User 3 :
INTEGRATOR
Entities for a user depend on
User 4
its role level.

Entity hierarchy : User roles

 Entity hierarchy : User roles
Authorization system makes it possible for a
user to belong to several groups, under
different roles

ADMIN Group
INTEGRATOR Company 1
User 1
Group
USER
Company 2

Entity hierarchy : User roles

 Entity hierarchy : User roles
Examples using a Device Message list :
What a USER role will see :

What an INTEGRATOR role will see :

Entity hierarchy : User roles

 Groups

Groups
 Groups

The main groups page contains a hierarchical tree of

the available groups for the viewing user

Groups
 Groups

A Group can have as many sub-Groups as needed

A User belonging to a Group can only see what
belongs to its Group and the Groups underneath.

Group creation is a
one-form process.
Making it billable will
allow to attach
contracts to it (see
Billing)

Groups
 Users

Users
 Users

A user is a point of entry on the backend for managing

other entities.
Its uniqueness is guaranteed by its e-mail address
A User can belong to several Groups

Users
 Users

Users are shown as a list, along with their privileges

and attached Groups:

Users
 Users

User creation on a single form:

On form validation,
an e-mail is sent to
the user for
password generation
It is possible, in very
specific cases, to
allow a simple user
to view some Base
Stations, granting
him the
INSTALLATOR role,
and specifying the
stations IDs

Users
 Roles

Roles
 Roles

A Role is what binds a User to a Group.

A Role can be inherited
A User with an ADMIN Role can create other Entities
(Users, Groups, etc.)
A User can only grant a Role he posesses on its own
Group. Example:
User A has INTEGRATOR Role on Group SIGFOX
User A belongs to a sub-Group of Group SIGFOX
User A, even being an ADMIN of its sub-Group, wont be
able to grant the INTEGRATOR Role to another User of its
Group or sub-Groups.
See Entity hierarchy: user roles
Roles
 Roles

Roles are granted at User creation or Edition.

Roles
 Data retrieval methods

Data retrieval methods

 Data retrieval : two methods
Final client needs to access data, and has two
methods :
PUSH: using the callbacks
Lightweight, and only used when data is transmitted on the
network

PULL: using the API

Used to retrieve data afterwards, if the previous method
failed for any reason. It is not recommended for default data
retrieval, is resource consuming for client and server, and is
not real time.
It is rate limited.

Data retrieval : two methods

 Data retrieval : the callback method
Callbacks are defined in the Device Type
details
SSL capable
Batch capable

A fixed URL pattern is defined, and will be

called on each incoming message. This URL
points to the clients information system.
Inline documentation gives all the details of the
usable variables:
https://backend.sigfox.com/apidocs/callback
Data retrieval : the callback method
 Data retrieval : the callback method
Device Type edition to create a callback

Data retrieval : the callback method

 Data retrieval : the callback method
The type of data to be sent can be:
DATA :User data (the actual payload sent by the
Device)
SERVICE : Service data (network, out-of-band data
sent by the Device)
ERROR :Error data (network status, sent to the
client should any problem occur)

Data retrieval : the callback method

 Data retrieval : the callback method
The channel is the sending method, and can
be:
URL : creates a HTTP callback, one for each
received message
BATCH_URL: if traffic is important, groups several
messages within 1 second, in one single HTTP
callback
EMAIL: mainly for testing purposes, sends an e-mail
to the specified mailbox

Data retrieval : the callback method

 Data retrieval : the callback method
In the common case where a Device is
received by several Base Stations, a single
message will have duplicates.
Tick this checkbox for testing purposes, to fire a
callback at each new received duplicate.
Example: If 6 stations receive the same
message, 6 callbacks will be fired.

Data retrieval : the callback method

 Data retrieval : the callback method
Using the list of available variables provided, according to the type
of callback (DATA, SERVICE or ERROR), one can fill the URL
pattern. For example :

http://clientsystem.org/application?variable1={device}&variable2={signal}

To enable SSL encryption, simply replace the http:// scheme with

https://
NOTE: SSL with self-signed certificates is not supported.

Data retrieval : the callback method

 Data retrieval : the callback method

The default HTTP method for sending data is

GET, but it is also possible to issue a POST
request by ticking the Use HTTP POST
checkbox.

Data retrieval : the callback method

 Data retrieval : the API method
It is possible to retrieve useful information days after the data has been
sent, using the API.

This interface also allows users to perform actions on several entities

present on the backend system :
List, edit, create, or move Device Types
List, edit, register, or move Devices
List, send commands to Base Stations
Retrieve billing information
Retrieve coverage information
Etc.

Rate limiting applies depending on the action type.

Available actions depend on group privileges

Data retrieval : the API method

 Data retrieval : the API method
Access to the API is granted on a Group level :
the credentials are generated for a whole
group.
Granting different levels of access is possible by
cascading groups.

To activate the API access for a group, one

must generate its credentials.
To do so, simply edit the Group, and follow
instructions.

Data retrieval : the API method

 Data retrieval : the API method
Once the API access is opened, a thorough documentation is
available, following the link provided on the Information page of
the Group.

This documentation contents is taylored to fit Group privileges.

Data retrieval : the API method

 Device Types

Device Types
 Device Type : information and details

The first view allows to list the available Device Types,

according to the privileges of the user viewing it.

Device Type: information and details

 Device Type : information and details
To edit a Device Type, simply click on the Edit button
on the upper right corner of the Device Types
Information page.

Device Type: information and details

 Device Type : information and details
The Keep alive values allows to trigger
an alert when a Device in this Device
Type does not communicate within this
delay.
It is possible to move a Device Type to
another Group by simply specifying a
new Group.
The Device Type can be attached to a
contract to activate billing and
accounting.
If defined, the alert e-mail will be used to
send error events to the client, such as a
device failing to communicate within the
Keepalive period.

Device Type: information and details

 Device Type : information and details

The display type allows to translate the raw data of a message to a

known translation for demonstration purposes.
Example: hex to ASCII conversion, geolocation payload (only available
on SIGFOX Blackbox), etc.

Chosing the display type is only informational on Device Messages list

on the backend, and will not affect the transmitted data, whether within
a callback, or through the API.

Device Type: information and details

 Device Type : information and details
For Custom Display type,
grammar is as follows:
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:" ("16" | "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 bytes, 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 at 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, which can be either 16 or 32 bits. Decoding is done according to the IEEE754
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.

Device Type: information and details

 Devices at a glance

Devices at a glance
 Devices at a glance
Devices are displayed as a list.

Devices at a glance
 A Device in detail

A Device in detail
 A Device in detail
Once a Device is selected, the left menu shows the following items:

Location: coarse location derived from last receiving

stations and signal strength.
Messages: actual data sent by the Device
Events: events occuring during the Devices life, like
a contract problem, for example
Statistics: available data about the Device during
time
Event Configuration: configurable triggers on
events occuring on the Device

A Device in detail
 A Device in detail
Device location is derived from hints, like the receiving stations
simulated coverage, and the received signal strength. It is not a real
geolocation tool.

A Device in detail
 A Device in detail
Device messages are shown according to the privileges of the user
viewing it. This is a view for a user with INTEGRATOR privileges, who
can see duplicates (amongst receiving stations) and repetitions:

A Device in detail
 A Device in detail
Device events are shown as a list, and can be filtered. This event
shows a contract problem on a Device.

A Device in detail
 A Device in detail
Device statistics allow to determine the overall health of the Device.

A Device in detail
 A Device in detail
It is possible to define new Event Configurations on a single Device.

A Device in detail