Integration between SIGFOX and Carriots platforms: Bidirectional communication


SIGFOX is the first company providing global cellular connectivity for the Internet of Things, fully dedicated to low-throughput communications. SIGFOX is re-inventing connectivity by radically lowering prices and energy consumption for connected devices.

The SIGFOX connectivity solution is based on an antenna and base station infrastructure that is completely independent from existing networks, such as telecommunications networks. This low-throughput only network will be rolled out in 60 countries within the next five years.

In this guide we'll set a callback in the SIGFOX platform in order to receive messages from our devices, redirect them to Carriots platform and then deliver its response to the device. Completing in this way a bidirectional communication.

Setting up a SIGFOX callback

SIGFOX can automatically forward some events using the "Callbacks" system. The configuration of callbacks is done in the "Device type" page, so "callbacks" are defined by objects families. The callbacks are triggered when a new device message is received, change on status or errors are detected.

In this guide we’ll be using the message ones to forward them to Carriots platform and return a response to the device.

First log into your SIGFOX account at the SIGFOX backend:

  • SIGFOX cloud welcome

Clicking on the "DEVICE TYPE" menu on the top banner we get to the “device type” list.

In this page we get a list of the defined device types for our account.

  • Device type list

Select the one grouping the devices to be used by clicking in its name.

Now we are seeing the device's information.

  • Device information

In the left sidebar menu select the "CALLBACKS" option to access the callback list.

Here we have a list of callbacks defined for this device type; this will affect all devices matching type.

  • Callbacks list

On the upper right corner we click on the "new" button and select the "Custom Callback" to get to the callback configuration form.

On the callback configuration form we fill the fields with the following parameters:

    This will indicate SIGFOX the callback will trigger upon incoming data and that the behavior will be "Bidirectional".
    This defines the way to forward will be an URL, in our case the Carriots synchronous service.
  • SEND DUPLICATE: Left unchecked

    This is the URL for the service to forward the incoming data. The URL corresponds to the one automatically created for our Carriots listener (see below).
    We also added the "persist" and "device" parameters to make Carriots persist the data as an incoming stream for the specified device.
  • SEND SNI: Checked for SSL connections
    Carriots-apikey: apikeyretrievedfromcarriotsplatformwithpernmissiontobeidentified
    We add the "Carriots Apikey" header with its value. This value is retrieved from Carriots.
  • CONTENT TYPE: application/json
  • BODY:

    In this field we define the body for the http POST; this is the content we will be processing on the Carriots listener. The values between brackets are keywords to be filled by the SIGFOX system, among them, “data” is the message the device sent itself.

The filled form will ends somewhat like this:

  • Callbacks edition

Clicking on the OK button down left of the form we create the callback. We will automatically return to the callbacks list were we can see the new one.

  • Callbacks list

There is a circle next to it, click to activate as a downlink callback (A warning popup has to be confirmed).

Setting up the Carriots listener

Now we are going to set up the Carriots listener to process the incoming data from SIGFOX and return a formatted response following the SIGFOX directions. To accomplish this we will be using the new “runners” capably, which allows to call the execution of a listener directly by an Http POST request.

We create the new listener as usual. Naming it as used in the SIGFOX callback: Bidirectional_SIGFOX_test

In the new listener resume page we can now see its "Run URL"

  • RUN URL:

This is the URL which the SIGFOX callback should be pointed at.

The response to SIGFOX will be following the next pattern: {"SIGFOX_device_ID": {"downlinkData": "data_to_be_returned"}}

Where the SIGFOX_device_ID is retrieved from the incoming POST form and the “data_to_be_returned” must be an 8 bytes hexadecimal string.

So the code would be like this:

  • CODE:

The listener resume will be something like this:

  • Carriots listener

Test the communication

At this point all has been prepared, any data sent by any of our devices belonging to the selected type should be transmitted to Carriots by the SIGFOX callback, persisted on a Carriots data stream, processed by our Carriots listener and response returned to the device via the SIGFOX platform.

Entering the SIGFOX device messages page we can see the received message and two green indicators meaning that the data has been sent to Carriots and the response delivered to the device respectively.

  • SIGFOX message list

Clicking on any of those icons we’ll see a pop up showing the contents of both, the incoming data and the returned response.

Any problems should appear as red arrows, clicking them will show a pop up with a brief description of the problem.

Finally, a yellow arrow means pending operations.