How to register your device in the SIGFOX backend as a free eval board

Browse to and choose Quicksand as your kit provider

Pick the country that you will be using your device in.

Enter the device ID and PAC code of your development kit. This code is included on a note inside the box of your kit.

If you already have a SIGFOX account, than you can register using this account. Otherwise, fill in your details to create a new account.

Once registration is complete, you will need to activate your account using an e-mail SIGFOX sends you.
This is not the case when using an existing account.

Accept the Terms and Conditions.

A new device type is automatically created and your new device is automatically added to it.

Press one of the two user buttons on your device, and you should see the raw data arriving inside the SIGFOX backend.

This concludes the registration of your device. The next thing you'll want to do is create a custom decoding string or a callback of the data to your own servers. This information can be found below.

How to register your device if you already have a specific contract

The first step is creating a suitable device type for your application. On the 'Device Type' page, please click 'New' under the menu item 'List'.

You will need to provide a name and description for your device type. The keep-alive parameter defines how long your device can go without sending a message to the SIGFOX backend. An alert will be generated if no messages were received inside the keep-alive interval. You will also need to pick the contract from which you want to assign tokens to this device-type and an e-mail address to sent alerts to.

You can also define what kind of 'Downlink data' mode you will be using. 'Direct' sends the variable defined under 'Downlink data in hexa' back to your device. In the example above it will send back the ID of the tap that received your message, the hex value 0x0000 and the RSSI value at which your Uplink message was received.

Another option is to provide the downlink data via a callback. In this case your own servers will need to provide a hex string to send back to your SIGFOX device. The textbox to set static downlink hex data will be greyed out.

The display type is the last parameter that needs to be set when creating a device type. Here you have 4 options:

  • None: display raw data.
  • Custom display a format defined by the user (details provided in image below).
  • Geolocation: when using a TD1204 modem (like on the QW kits), an automatic decoding of the GPS position will happen and the device can be tracked on maps. Pick TD_GEOLOCATION as subtype. In case of no fix, the decoding will fall back to ASCII.
  • String: display raw data as ASCII formatted data.

Click 'ok' to complete registration of your device type.

Now that we have a device type created, we can add our device to the SIGFOX backend and assign it to this type. On the top-menu, pick 'Device'.
Next, click on 'New' to register a single device. You can use 'New Series' if you want to register a whole batch of devices using a .csv file.

Every SIGFOX device has a unique ID and PAC code. The ID identifies the device on the network and is a hex number. This is the first parameter that is required when registering the device. Some modems like the TD1204 have the ID printed on the modem, others use an AT-command to readout the ID. The second thing you need when registering a SIGFOX device is the Porting Authorisation Code (PAC). The PAC code is a unique identifier that allows you to claim the SIGFOX device or modem as yours. The PAC code can only be used once to register the device. If you want to move the device to another account, you will need to generate a new PAC code from the SIGFOX backend.

Our QW development kits are shipped with the ID and PAC code printed on a paper inside the box. So please do not lose this note before registering your device.

The name of your device can be chosen freely. If you are building a prototype using your device, you will need to check 'Prototype'. If your device is certified, you can specify the product certificate instead. Because we created a device type earlier, you can select the device type you want straight away in this screen. If you want to be able to locate a device easily on a map (without using GPS), you can provide a location as well.

The 'prevent token renewal' checkmark is used if you don't want a device to automatically renew its token when a contract expires and a new contract with new tokens is available. You can leave this unchecked.

Finish the registration by clicking 'Ok'. Congratulations! Your device is now ready to send data to the SIGFOX backend.

You can watch the incoming data of a device by clicking on its ID in the list of devices. You will need to go to the subsection 'Messages'.

By default every QW development kit comes with a preloaded 'Hello World' example program. This code sends 0x01 in the first byte to indicate the code example and after that the pressed button and measured temperature in plain ASCII code. Other example programs are available on the MBED page.

How to set and use callbacks

Once a device sends a message, there are 3 ways to fetch and use the data:

The web interface allows to filter data based on timestamp and export the raw data and other metrics (RSSI, TAP that received the message,...) to a .csv file for analysis.

To access the REST API, you need to set up your access first. To do so, go to the 'Group' section on . In the sidebar, click on 'API access' and then click 'New' in the top-right corner. You should now see your credentials, and a link to the API documentation relevant to your access rights. Using the API you can :

  • Retrieve the list of devices associated to a device type
  • Retrieve the messages of a given device
  • Get metrics about a device's messages
  • Register devices
  • ...

Callbacks are the easiest way to get the data from the SIGFOX backend to your own database. You can subscribe to receive a HTTP callback for every message received and processed by the SIGFOX backend.

To set a callback, navigate to the 'Device Type' section and select the device type for which you want to create the callback. Click on 'Callbacks' in the left pane.

Create a new callback by clicking 'New' in the upper right corner.

SIGFOX provides three types of callbacks. For this tutorial we will be using the custom callback.

You can set a separate callback for data-, service- and error- messages. When receiving a callback, the client system must return an HTTP 2xx code within 10 seconds. If the client system fails to process the callback during this time, an automatic retry will be scheduled 1 minute later.

  • A data callback can be uplink only (just pushing data to your servers) or bidirectional.
    In case of a bidirectional callback, your server will need to respond with the json formatted hex data that needs to be sent back to the SIGFOX device requesting the downlink.

    You can also decide not to send any answer to the device, even though it requested data. This allows you to create an 'almost' interactive application, without breaking the 4-downlink-per-day rule (note that this does come at a battery-lifetime cost). To do so, you can respond to the callback with the HTTP NO_CONTENT code (204) OR respond with json data containing the noData field set to true.

    You can enter a configuration to define custom variables that will be replaced by the parsed data. You can then use these variables in your callback. To get more information about the format of the configuration, please read the online help, they correspond to the custom automatic decoding when creating a device type.

    The available variables to use in a callback are:

    • - device (string): device identifier (in hexadecimal – up to 8 characters <=> 4 bytes)
    • - duplicate (bool): «true» if the message is a duplicate one, meaning that the backend has already processed this message from a different base station, «false» otherwise. To receive duplicate messages, you have to check the «send duplicate» box in the callback configuration page
    • - snr (float): the signal to noise ratio (in dB – Float value with two maximum fraction digits)
    • - rssi (float): the RSSI (in dBm – Float value with two maximum fraction digits). If there is no data to be returned, then the value is null.
    • - avgSnr (float): the average signal to noise ratio computed from the last 25 messages (in dB – Float value with two maximum fraction digits) or «N/A». The device must have send at least 15 messages.
    • - station (string): the base station identifier (in hexadecimal – 4 characters <=> 2 bytes)
    • - data (string): the user data (in hexadecimal)
    • - lat (float): the latitude, rounded to the nearest integer, of the base station which received the message
    • - lng (float): the longitude, rounded to the nearest integer, of the base station which received the message
    • - seqNumber (int): the sequence number of the message if available
  • A service callback defines the reception of an operational message from a device.
    It has the following additional status variables next to those available for a data callback:

    • - batt (float): the voltage of the battery (in Volt – Float value with two maximum fraction digits)
    • - temp (float): the temperature of the device (in °C – Float value with two maximum fraction digits)
    • - infocode (int): this is the status code of the downlink

      • 0 (ACKED) the station emitted the answer
      • 1 (NO_ANSWER) the client did not give any answer
      • 2 (INVALID_PAYLOAD) the data to send to the device is invalid,
      • 3 (OVERRUN_ERROR) the device exceeded its daily downlink quota, so it was blocked because of a lower priority than transmissions for devices that did not exceed their quota
      • 4 (NETWORK_ERROR) it was not possible to transmit the answer
      • 5 (PENDING) not technically a code that is sent in the callback because it is a transient state before the answer is sent
      • 6 (NO_DOWNLINK_CONTRACT) the device asked for an answer but its BSS order does not allow downlink
      • 7 (TOO_MANY_REQUESTS) the device asked for an answer before the expiration of the listening time
      • 8 (INVALID_CONFIGURATION) the device type is configured to get data by callback, but no BIDIR callback was defined
    • - infomessage (string): a message associated to the code
    • - downlinkAck (bool): «true» if the station acknowledged the transmission, «false» else.
    • - downlinkOverusage (bool): «true» if the device exceeded its daily quota, «false» else.
  • An error callback defines the communication los for a device.
    Custom variables are:

    • - info (string): information on error, in case of communication loss, contains the last received message date of the device.
    • - severity (string): «ERROR» when it’s a device problem, «WARN» when the network has experienced some issues that could cause some message loss or delay.

There are three mediums the callbacks can be sent to: URL, BATCH_URL and EMAIL.

  • EMAIL: You will need to setup a valid e-mail, a subject and the message body. The subject and the body can contain arbitrary text with defined markup which are the name of variables surrounded by brackets for this callback type.

  • URL: For URL and BATCH_URL, you will need to implement a RESTful, web-facing service. With URL, each message is directly forwarded in a single HTTP request. You can use a HTTP GET, POST or PUT method, although POST method is recommended.According the type of callback, different variables are available. The available variables list is displayed above the URL field. These variables can be used in 3 places :
    • - URL: as path variables or request parameters.
    • - Headers: as values of a header. Variables cannot be used in header keys because the format is standardized.
    • - Body: If you choose to use the POST or PUT method, you can define a body template that contains variables. These variables are replaced the same way as in URL or Headers.
    GET method, everything inURL (recommended as an easy way to get started):

    GET http://hostname/path?id={device}&time={time}&key1={data}&key2={signal}

    A simple example PHP script that can store the incoming URLs with the set values would be:

        $actual_link = "http://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]\r\n";
        $file = 'test.txt';
        // Open the file to get existing content
        $current = file_get_contents($file);
        // Append the data to the file
        $current .= $actual_link;
        // Write the contents back to the file
        file_put_contents($file, $current);

    In practice you would use $_GET["name"] to fetch the individual variables.

    POST or PUT method allows you to set the content-type and the body of your request You can choose the content-type between 3 :

    • application/x-www-form-urlencoded
      This is the default content type for a POST or PUT request. When using this content-type, you can set the body in a form encoded format :


      If this format is not respected, it will be rejected. Note that if you put some variables in the query part of the URL, these parameters will be appended to the body, whether it is empty or not. Eg :

      POST http://hostname/path?id={device}&time={time}&key1={data}&key2={signal}

      with a body template:

      will result in the following body:

    • application/json
      You can set a JSON object in the body:

      "device" : "{device}",
      "data" : "{data}",
      "time" : {time}

      When this content type is chosen, JSON content is validated. If the content does not respect the JSON standard, it will be rejected.

    • text/plain
      This content type can be freely chosen. No validation is performed (except forbidden characters). Eg:

      device => {device}
      data => {data}
      time => {time}

  • BATCH_URL: Messages are gathered together per callbacks, each line representing a message, then sent in batch using a single HTTP request every second. This avoids a possible peak load that your server can't handle. As the payload contains multiple messages, only HTTP POST method are supported.

    POST http://hostname/path?batch={batch} where batch={device};{data};{signal};...

If a data-callback is succesfull, you will see a green arrow next to the message like you can see in the following image:

Want to know more?

Feel free to contact us!