SigFox downlink howto

antennaSigFox downlink is now available since the Telecom Design SDK 5. This allow to send a message to your SigFox device from the network. You have a 4 message a day limitation.

This post will explain how to configure and use SigFox downlink

 

How it works

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 a ack.

This ack is a 8bytes message the network can send directly with predefined value like current time or any used defined fixed value. It can also be a dynamic message sent by your own backend.

The device is sending a message with ack flag activated and then turn into receive mode during 25 seconds, looking for the network acknowledgment. This one received it will go back sleeping. Between the end of the send and the begin or the receive you have about 15 seconds sleep.

Step 1 – configure your device group for downlink

The first step is to have a sigfox account configured to accept downlink, for this you have to contact your sigfox support. Once done, you can configure a device group to support downlink.

You have two type of Downlink

  • Direct is automatically sent by sigfox network if you fill the downlink data field
SigFox backend donwlink configuration
SigFox backend donwlink configuration

With a such configuration each time a frame is send with a requested ack, the 8 bytes message containing 32b time + 2 bytes RSSI + 0000 will be sent back to the device.

This could be, as an example, an easy way to get current time on startup and manage a RTC

  • The second mode is a callback based acknowledgment ; in this mode your backend server will return the value to send back to the device. To configure it, just change the Downlink mode from DIRECT to CALLBACK
SigFox backend with ACK based on callback
SigFox backend with ACK based on callback

Then you have to setup your callback, for this you can choose BIDIR mode, then you will have two new parameters you can add to the URL : ack indicating if an ack is requiered and longPolling (not documented). Basically we are expecting to get ack to know what to do on backend side

SigFox callback configured for bi-directionnal
SigFox callback configured for bi-directionnal

The last step is to link this callback with the Acknowledge source, this is done by clicking on the expected callback source.

Select the ack source in the callback list
Select the ack source in the callback list

 In the next steps, I will describe what to do to manage a callback acknowledgment

Step 2 – code your device

The Telecom Design SDK provides a complete example to manage bidirectional messages ; take a look to sigfox_downlink in the RF_Example list.

First you need to configure a callback for the downlink messages

 // Register down-link callback function
 TD_SIGFOX_DOWNLINK_SetUserCallback(downlink_callback);

This callback look like this :

static int downlink_callback(uint8_t *rx_frame, uint8_t length)
{
    if (rx_frame == 0) {
        // rx_frame == 0 when the receiving process is ending
        // it goes here even if you have receive a frame previously 
        // or if the reception windows is finished
        return 1;
    } else {
        if (length == 0) {
            // You are in this step when the reception starts
            // it will be only once           
            return 1;
        } else {
           // You are in this step when a ack is received
           // the message is in the rx_frame table
           return 1;
        }
    }
}

To send a message indicating you expect an ack from the network you have to use the following function :

TD_SIGFOX_SendV1(MODE_FRAME, false, message, 12, 2, true, false);

Only the TD_SIGFOX_SendV1 allow you to indicate the ack status, here in red.

Then you need to call the DownLink Process in the user loop to make it works

void TD_USER_Loop(void)
{
    // Process down-link events
    TD_SIGFOX_DOWNLINK_Process();
}

You can easily identify, in the sigfox backend, what are the messages requesting a ack.

The message, once sent to the SigFox network will be displayed with bi directional arrows indicating the status of the downlink message like in the picture below :

cap_backendsigfox_down_traceI do not know if it is a bug or not but the callback arrow is always green, even if you reject to answer to the ack. I assume it could be gray in that case to get a better visibility on what are the callback answered or not. If you move your mouse on the arrow you will get a different message “acked” when acked and “no answer” when not acked.

The arrow is RED if you respond with a malformed message ; arrow is yellow when the message has been received from your backend server and is pending to be transfered back to the device.

Step 3 – setup your web server backend

The backend server will receive a new parameter : ack ; the value will be “false” or “true” ; when true an acknowledgment is expected.

Then you have two choices :

  • You can refuse to respond to the ack, for this you have two ways

The first one is to respond with a HTTP 204 (no Content) ; this can be done in php simply executing

<?php
header("HTTP/1.0 204 No Content");
?>

The second way is to use the standard json way indicating you do not want to ack. For this you can use something like this :

<?php
   $_id = $_GET["id"];
   $_time = $_GET["time"];
   $_ack = $_GET["ack"];
   $_data = $_GET["data"];

   if ( $_ack == "true" ) {
     echo "{";
     echo "\"". $_id ."\" : { \"noData\" : true }";
     echo "}";
   }
?>
  • You can answer to the acknowledgment by a 8 byte message like this
<?php
   $_id = $_GET["id"];
   $_time = $_GET["time"];
   $_ack = $_GET["ack"];
   $_data = $_GET["data"];

   if ( $_ack == "true" ) {
     echo "{";
     echo "\"". $_id ."\" : { \"downlinkData\" : \"0102030405060708\" }";
     echo "}";
   } 
   header("HTTP/1.0 200 OK");
   header("Content-Type : application/json");
?>

 

What about battery consumption

During the RX period, the device is consuming 15mA until the message is received, this has to be added to the device consumption and it reduce the battery life if you are expecting potential acknowledgment on every message. If no ack is sent the system will listen for 25 seconds. If an ack is sent, the device will transmit again and consume an extra 45mA during less than a second.

Downlink message

The number of message in downlink depends on your contract, it can be up to 4 on platinum contract. It seems (but it have to be verified) that you can send more than that but it will be transferred on best effort – meaning you have no insurance it will be transmitted or not and no and no feedback on transmission or not.

 

 

This entry was posted in IoT, Sigfox and tagged , , , , . Bookmark the permalink.

21 Responses to SigFox downlink howto

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.