Frequently Asked Questions

Here you find a set of commonly asked questions. If you have a question that is not answered here, please drop us a mail.

What’s in the box of the dev kit

boxcontents

QW GPS development kit box contents

  • ARMmbed driven Nucleo-L152RE baseboard
  • QW GPS Shield with the following features:
    • TD1204 modem
    • 2 user-programmable buttons + 1 reset button
    • 4 user-programmable bright blue LEDs + 1 bootloader LED attached to the modem
    • Proximity sensor (VCNL4010)
    • Ambient light sensor (VCNL4010)
    • Analog temperature sensor (MCP9700)
    • GPS receiver (UBX G7020 built into TD1204)
    • 3 axis accelerometer (STM LIS3DH built into TD1204)
    • TC2030 debugging header to upload (custom) firmware to the modem. Firmware updates are also possible through a serial bootloader.
    • Levelshifter that allows the hardware to be used on multiple platforms (mbed 3V3, arduino 5V)
    • Protection diode for external power input + onboard voltage regulator for standalone operation
    • Schematics available: download here
  • Active GPS Antenna
  • Omnidirectional 868MHz antenna with SMA connector
  • PAC code for registration on the Sigfox backend, Sigfox subscription included
  • USB cable

Are there precompiled binaries?

Yes there are! There are precompiled binaries for the following example programs:

  • HelloWorld a.k.a. connected button

    The QW development kits ship with this code example.

    This example allows you to talk straight to the TD1208 modem when using a virtual com port (note: local echo is off).
    This code-example also sends a SIGFOX message whenever you press a button. The message contains the button number and the measured environment temperature as an ASCII string. The first byte is always 0x01.

    If you want the SIGFOX backend to automatically decode these messages, you’ll need the following settings under Device type > Display type > Custom

    The SIGFOX backend will now decode the incoming messages automatically:

    You can download the precompiled binary here: http://lpwan.be/binaries/QW_button.bin

  • Ambient lightlevel and temperatureThis is a code example that demonstrates sending the light level sensor and temperature sensor output over Sigfox at regular time intervals.
    The payload that is sent over the network consists of 4 bytes:

    • The first byte is always 0x02 (this indicates the precompiled binary you are using)
    • Two bytes light level reading
    • One byte temperature reading.

    If you want the SIGFOX backend to automatically decode these messages, you’ll need the following settings under Device type > Display type > Custom

    The sigfox backend will know now what data is inside the packet payload and decode it for you automatically

    You can download the precompiled binary here: http://lpwan.be/binaries/QW_light_temp.bin

  • Downlinks This example demonstrates how you can use SIGFOX downlinks on your QW development kit.When the device boots, all leds are turned on. After successful initialization the LEDs are turned off again.
    A bidirectional message is sent to the SIGFOX cloud when the user pushes either SW1 or SW2.
    All the leds light up during SIGFOX transmission.

    The Downstream messages are, in fact, frame acknowledgment.
    It means that to receive a message on the device, you have to send one indicating the SIGFOX network you are expecting an acknowledgement.

    The device is sending a message with ack flag activated and then turns into receive mode during 25 seconds, looking for the network acknowledgment.
    Between the end of the send and the begin of the receive you have about 15 seconds of sleep.

    A moving LED animation is displayed while the modem waits to begin listening for its downlink packet.
    The first LED and the last LED start burning continuously when the modem is listening for a downlink packet.

    When reception is complete, the signal strength (RSSI) of your SIGFOX device is displayed on the led’s.

    • 1 LEDs = maximum -130dBm or lower
    • 2 LEDs = maximum -110dBm or lower
    • 3 LEDs = maximum -90dBm or lower
    • 4 LEDs = higher than -90dBm

    This is the RSSI at which the original uplink transmission was received on the basestation. You can also read what basestation received the uplink message if you connect to the virtual com-port of your QW development kit (9600 baud, 8-N-1)

    If something goes wrong, all leds will blink together for 5 seconds.
    If no downlink message was received you will get the following notification in your terminal window:

    This example makes use of the “default downlink settings” when you create a device type.
    This is a static “direct” message, no calls to an external server are used when using this type of downlink callback.

    The first 4 bytes of the downlink message contains the tap id that received your message, the next 2 bytes are user-payload, in this case 0x0000, the last 2 bytes contain the RSSI.

    SIGFOX downlink messages are always limited to 8 bytes total!

    You can alter this example to send your own type of payload back to the device. The sent back data can also be the result of a callback to your own server.

    You can download the precompiled binary here: http://lpwan.be/binaries/QW_Downlink.bin

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

Browse to http://backend.sigfox.com/activate 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.

Important note!
Free evaluation tokens will always show up under SIGFOX France.
If you have devices that are registered under multiple countries you may need to select the correct country in a drop down list on the top right.

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 under another FAQ topic.

How to register your device if you already have a specific (demo) contract with your SNO

If you already have a (demo) contract with your local SNO (SIGFOX Network Operator), you may want to register your kit under this contract.
Login to your SIGFOX account via http://backend.sigfox.com .

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 SIGFOXdevice. 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.

Creating device types

Creating a device type allows you to group devices that:

  • have the same functionality,
  • need to use tokens from the same contract,
  • need to perform the same decoding,
  • need to perform the same callbacks to your own servers/backend

Login to your SIGFOX account via http://backend.sigfox.com .

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 SIGFOXdevice. 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.

You can now add your SIGFOX devices to this group to allow for automatic decoding (if set), or callbacks (discussed in another FAQ topic).
This can be done whilst registering a SIGFOX device, or afterwards by editing the properties of your SIGFOX device under ‘Devices’.

You can check which devices have been assigned to your device type under ‘Associated Devices”.

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 http://backend.sigfox.com . 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.
If you did not create a device type yet, please follow the separate section about this topic in the FAQ.

Click on ‘Callbacks’ in the left pane.

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

SIGFOX provides multiple 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.

  • 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
  • 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
    • downlinkOverusage (bool): «true» if the device exceeded its daily quota, «false» else.
    • downlinkAck (bool): «true» if the station acknowledged the transmission, «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 to a text-file 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 :device={device}&data={data}&time={time}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:

      device={device}&data={data}&time={time}

      will result in the following body:

      id={device}&time={time}&key1={data}&key2={signal}&device={device}&data={data}&time={time}

    • 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: