SigFox Integration

SigFox Integration receives device messages from the Sigfox Backend through a custom HTTP callback. An uplink data converter transforms each message into device data, including telemetry and attributes. For downlink, ThingsBoard returns the queued command in the HTTP response to the callback, and the Sigfox Backend sends it to the device.

Use SigFox Integration when:

• Your devices transmit over the Sigfox network and their messages reach the Sigfox Backend.
• You need to send short configuration commands (up to 8 bytes) back to devices that request a downlink.

1. Transmit an uplink. The device sends a message over the Sigfox network to the Sigfox Backend.
2. Forward the message. A custom callback on the device type sends the message as an HTTP POST with a JSON body to the integration endpoint. The body holds the Sigfox variables you choose, such as device, time, and data.
3. Decode the payload. The uplink converter maps the Sigfox device ID to the device name and decodes the hex data into telemetry and attributes. If Allow create devices or assets is on, ThingsBoard creates the device on its first message.
4. Return downlink data (optional). If a downlink is queued for the device, ThingsBoard encodes it and returns it in the response to the same callback request. ThingsBoard cannot open a connection to the Sigfox Backend on its own.

• Access to ThingsBoard Cloud with integrations enabled for your tenant. The ThingsBoard endpoint must be reachable from the internet, because the Sigfox Backend calls it.
• Permission to create integrations and data converters, and to edit rule chains for downlink.
• A Sigfox Backend account with permission to edit the device type of your device.
• At least one device registered in the Sigfox Backend.

Callbacks and downlink settings belong to the device type, not to a single device. Every device of that type uses them.

1. Log in to the Sigfox Backend and open Device.
2. Open your device and note its Id, for example 1CB0F1. The callback sends it as {device}, and this guide uses it in the ThingsBoard device name.
3. Note the device type the device belongs to, for example thermostats. You create the callback on this device type.

This guide uses a CO₂ sensor that sends a 7-byte payload. The Sigfox Backend passes it to the callback as a hex string in {data}, for example 2502af2102462a:

The default SigFox decoder reads this layout. Replace the decoding with your device’s layout from its datasheet.

Create the uplink converter and the integration, then point a Sigfox callback at the integration endpoint.

The uplink converter parses the callback body, resolves the device, and decodes the hex data. SigFox Integration uses the Generic converter: you write the decoder in TBEL or JavaScript. For converter types and the full decoder reference, see Uplink data converter.

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.

2. Converter type — keep Uplink.

3. Integration type — select SigFox.

4. Name — enter a name, for example SigFox Uplink Converter.

5. Main decoding configuration — in TBEL, the editor opens with the default SigFox decoder below. It names the device Sigfox- plus the Sigfox device ID, puts it in the Control room devices group, decodes the payload format used in this guide, and takes the timestamp from time. The JavaScript editor opens with a generic decoder that does not read the Sigfox body: if you use JavaScript, replace it with the JavaScript version below. Use the TBEL / JS toggle to switch.

   • TBEL (Recommended)
   • JavaScript

   /** Decoder **/
   
   // Decode payload to json
   var json = decodeToJson(payload);
   
   // Set general device information
   var deviceName = 'Sigfox-' + json.device;
   var deviceType = 'Sigfox device';
   var groupName = 'Control room devices';
   // var customerName = 'Customer A';
   // use assetName and assetType instead of deviceName and deviceType
   // to automatically create assets instead of devices.
   // var assetName = 'Asset A';
   // var assetType = 'building';
   
   

   ▼Expand

   To adapt:

   • Device name — change 'Sigfox-' + json.device. Keep the Sigfox device ID in the name or in the sigfoxId attribute, so you can match ThingsBoard devices to the Sigfox Backend.
   • Payload layout — change the substring ranges, scaling, and offsets to your device’s byte layout. A Sigfox uplink carries up to 12 bytes, so data holds up to 24 hex characters.
   • Other callback variables — add them to the callback body and read them from json, for example json.seqNumber.
   • Custom variables — customData1 and customData2 read customData#int1 and customData#int2, which the Sigfox Backend fills from the callback’s Custom payload config. Remove them if you do not use it.
   • Customer or assets — uncomment customerName, or assetName and assetType, and use them in the result.

6. Click Test decoder function and check the result (see Test the Decoder).

7. Click Add.

Decoder Inputs

Fields that are missing from the body read as null. ThingsBoard skips telemetry and attributes whose value is null, so the default decoder works without deviceTypeId or the custom variables.

Test the Decoder

Click Test decoder function below the editor. The dialog opens with a generic sample payload that has no device or data field, so the SigFox decoder fails on it. Keep Payload content type set to JSON, replace the payload with a callback body, and click Test:

{
  "device": "1CB0F1",
  "time": "1661868952",
  "data": "2502af2102462a",
  "seqNumber": "3737",
  "deviceTypeId": "5e5e9d4c2b3a1f0012345678"
}

The Output panel shows:

{
  "deviceName": "Sigfox-1CB0F1",
  "deviceType": "Sigfox device",
  "groupName": "Control room devices",
  "attributes": {
    "sigfoxId": "1CB0F1",
    "deviceTypeId": "5e5e9d4c2b3a1f0012345678",
    "autoCalibration": "on",
    "zeroPointAdjusted": false,
    "transmitPower": "full",
    "powerControl": "off",
    "fwVersion": 2
  },
  "telemetry": {
    "ts": "1661868952000",
    "values": {
      "temperature": 28.7,
      "humidity": 33,
      "co2": 582,
      "co2Baseline": 420,
      "customData1": null,
      "customData2": null
    }
  }
}

Check that deviceName holds the Sigfox device ID and telemetry.values holds the expected readings. If the output is empty or shows an error, fix the decoder and test again.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select SigFox.
   • Name — keep the default SigFox integration or enter your own.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first message.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose SigFox Uplink Converter.
   • Alternatively, click Create new to write a decoder here.
   • Click Next.
4. Downlink data converter:
   • Click Skip. Add a downlink converter later if you need to send commands to the device.
5. Connection:
   • Copy the HTTP endpoint URL. You need it for the Sigfox callback.
   • Leave the other parameters at their defaults. See Connection Settings for details.
6. Click Add.

The integration answers each callback request with one of these statuses:

The integration reads the Sigfox device ID for the response from the body field device, or Device if device is missing. To read it from another field, add the key SigFoxDeviceIdAttributeName to the integration’s Metadata with that field’s name as the value. Every request must carry this field, even if you do not use downlink.

1. In the Sigfox Backend, open Device type and select the device type of your device.
2. Open Callbacks and click New.
3. Select Custom callback.
4. Set the callback fields:
   • Type — DATA, and BIDIR if you plan to use downlink, or UPLINK for uplink only.
   • Channel — URL.
   • Custom payload config — optional. Leave it empty to decode the whole payload in ThingsBoard. A config such as int1::uint:8 int2::uint:8 adds the custom variables customData#int1 and customData#int2.
   • Url pattern — the HTTP endpoint URL of the integration.
   • Use HTTP Method — POST.
   • Headers — leave empty for now. See Secure the Endpoint with Header Filters.
   • Content type — application/json.
   • Body — the JSON below.
5. Click Ok.

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

The values in braces are Sigfox variables, and their names are case-sensitive. Keep device: the decoder and the downlink response need it. If you set a Custom payload config, add "customData#int1": "{customData#int1}" and the other custom variables to the body.

Open Callbacks on the device type and click New Select Custom callback Set the type, Url pattern, method, content type, and body, then click Ok. This example also sets a custom payload config and a header filter.

Send a message, then confirm that ThingsBoard decoded it and created the device.

Wait for the device to transmit. The device’s Messages page in the Sigfox Backend lists each message and the status of its callbacks.

To test without a device, send the callback body to the endpoint yourself. Replace $HTTP_ENDPOINT_URL with the HTTP endpoint URL and run:

curl -v -X POST \
  -H "Content-Type: application/json" \
  -d '{"device":"1CB0F1","time":"1742481772","data":"2502af2102462a","seqNumber":"512"}' \
  "$HTTP_ENDPOINT_URL"

The endpoint returns 204. HTTP/2 responses (for example, from ThingsBoard Cloud) show only the code (HTTP/2 204). HTTP/1.1 responses add the reason phrase (HTTP/1.1 204 No Content).

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears with status OK.
• Converter events — open SigFox Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the callback body, Out shows the decoded result, and Metadata shows the request headers and integration name.
• Device — go to Devices & assets ⇾ Devices. The integration has created Sigfox-1CB0F1 with the Sigfox device profile, in the Control room devices group. Open it and check temperature = 28.7, humidity = 33, co2 = 582, and co2Baseline = 420 on the Latest telemetry tab, and sigfoxId and the decoded flags on the Attributes tab.

Anyone who knows the endpoint URL can send data to it. A header filter rejects every request that does not carry the required headers with the exact values, and returns 403 Forbidden before the converter runs. The Sigfox Backend shows the failed call in the callback status of the message.

1. In ThingsBoard, open the integration and click Toggle edit mode (pencil icon).
2. Turn on Enable security (Headers filter).
3. Click Add and enter a Header and Value, for example x-api-key and a secret value. The header name is not case-sensitive. A request must carry every header in the list. The value match is exact and case-sensitive.
4. Click Apply changes.
5. In the Sigfox Backend, edit the callback and add the same header and value under Headers. Click Ok.

Sigfox downlinks are not pushed. ThingsBoard queues the downlink for the device and returns it in the response to the next callback request for that device:

• The queue holds one downlink per device. A newer Rule Engine message replaces the queued one.
• ThingsBoard sends the queued downlink in response to any callback request it receives for the device, then removes it from the queue. The Sigfox Backend delivers it only if the device requested a downlink in that message.
• The device firmware decides when to request a downlink. ThingsBoard cannot trigger one.
• A Sigfox downlink carries exactly 8 bytes, written as 16 hex characters.

The downlink converter turns a Rule Engine message into the downlink payload. For the full encoder reference, see Downlink data converter.

1. Open Device type, open the context menu of your device type, and select Edit.
2. In Downlink data, set Downlink mode to CALLBACK, and click Ok.
3. Open Callbacks. Check that the callback has the subtype BIDIR.
4. Click the circle in the Downlink column of the callback. The filled circle marks the callback that answers downlink requests. A device type has one such callback.

Open the context menu of the device type and select Edit Set Downlink mode to CALLBACK and click Ok Click the circle in the Downlink column to make the callback answer downlink requests

1. Open the integration in Integrations ⇾ Integrations and click Toggle edit mode (pencil icon).
2. In the Downlink data converter field, click Create new. The Downlink converter type and SigFox integration type are preselected.
3. Enter a name, for example SigFox Downlink Converter.
4. Main encoding configuration opens with a generic encoder that builds a JSON object. Sigfox needs a hex string, so replace it with the encoder below.
5. To record downlink events, click the debug icon next to the name, select All messages, and click Apply.
6. Click Add, then Apply changes.

Encoder used in this guide. It sends the value of the shared attribute downlink:

/** Encoder **/

// Sigfox downlink: 8 bytes as 16 hexadecimal characters.
// msg.downlink holds the value of the shared attribute "downlink".
var result = [];

if (msg.downlink != null) {
    var payload = "" + msg.downlink;

    // A value saved as a number loses its leading zeros. Restore them.
    while (payload.length() < 16) {
        payload = "0" + payload;
    }

    if (payload.length() > 16) {

/** Encoder **/

// Sigfox downlink: 8 bytes as 16 hexadecimal characters.
// msg.downlink holds the value of the shared attribute "downlink".
var result = [];

if (msg.downlink != null) {
    var payload = String(msg.downlink);

    // A value saved as a number loses its leading zeros. Restore them.
    while (payload.length < 16) {
        payload = "0" + payload;
    }

    if (payload.length > 16) {

The integration reads these fields from the encoder result:

The encoder must return exactly one result. An empty array, or more than one result, sends no downlink: the endpoint returns 204 and the queued message is dropped.

To test the encoder, click Test encoder function, replace the message with {"downlink": "0000780001900000"}, and click Test. Output shows data = 0000780001900000.

To adapt:

• Another attribute — replace msg.downlink with your attribute key, for example msg.config.
• Payload built from several values — build the hex string in the encoder, for example from msg.interval and msg.mode, and pad each field to its byte length.
• Fixed-length payload of another size — keep the result at 16 hex characters. Fill unused bytes with 0.

Route shared attribute updates to the integration.

1. Go to Data processing ⇾ Rule chains and open the Root Rule Chain.
2. From the Action section, drag an integration downlink node onto the canvas.
3. Enter a Name (for example, Downlink to SigFox integration), select your SigFox integration, and click Add.
4. Connect the message type switch node to the integration downlink node with the Attributes Updated relation.
5. Click Apply changes.

Add a shared attribute to queue a downlink, then send an uplink to receive it.

1. Go to Devices & assets ⇾ Devices, select Sigfox-1CB0F1, and open the Attributes tab.
2. Select Shared attributes and click +.
3. Set Key to downlink, Type to String, Value to 0000780001900000, and click Add. ThingsBoard queues the downlink.
4. Send the test uplink again, or wait for the device to send an uplink that requests a downlink.

In this guide’s sensor, the payload 0000780001900000 sets a 2-hour reporting interval:

The command format is device-specific. Take it from your device’s datasheet.

• HTTP response — the endpoint returns 200 with the body {"1CB0F1":{"downlinkData":"0000780001900000"}}.

• Integration events — the Events tab shows a Downlink: ATTRIBUTES_UPDATED event from the attribute update, then an Uplink and a Downlink event from the uplink request.
• Converter events — open the downlink converter’s Events tab. The event appears only after the uplink, because the converter runs when the response is built. In shows the Rule Engine message, Out shows the encoded result, and Metadata shows the integration metadata and the uplink request headers as header:<name>.
• Sigfox Backend — on a real device, open the device’s Messages page. The downlink icon in the Callbacks column shows the downlink status, for example Acked. The device type’s Statistics page counts downlink messages.

The device Messages page shows the downlink status The device type Statistics page counts uplink and downlink messages

To read debug events, open the integration or converter, click Events, and select an event: In is the received data, Out is the converter result, and Error holds the error text.

• Integrations overview — how integrations, converters, uplinks, and downlinks fit together.
• Uplink data converter — decoder inputs, output format, and scripting patterns.
• Downlink data converter — encoder reference.
• Integration downlink node — route Rule Engine messages to an integration.
• message type switch node — route messages by type, for example attribute updates.
• HTTP Integration — the generic HTTP endpoint that SigFox Integration builds on.
• Remote Integration — run the integration outside the ThingsBoard cluster.
• TBEL — built-in functions and syntax for converter scripts.