SigFox Integration

Sigfox Integration connects ThingsBoard to the Sigfox Backend via HTTP callbacks, receiving device payloads and converting them into ThingsBoard telemetry and attributes.

• A ThingsBoard PE account with permission to create integrations.
• A Sigfox account with a registered device.

In this tutorial, device Sigfox-2216792 is a Sigfox Airwits CO2 sensor that publishes temperature, humidity, co2, and co2Baseline readings encoded as a binary hex string.

The uplink converter transforms incoming Sigfox payloads into the ThingsBoard data format. Sigfox uses a generic uplink converter. ThingsBoard provides a pre-built converter for Sigfox — import the JSON file and customize the decoder function to match your device payload structure.

Sample payload from a Sigfox device:

{
  "device": "BF1327",
  "time": "1661868952",
  "data": "2502af2102462a",
  "seqNumber": "3737"
}

The device field maps to the device name. The data field is a hex-encoded sensor reading — each byte pair encodes a measurement: bytes 1–2 = temperature (offset −40, scale ÷10), byte 3 = humidity, bytes 4–5 = CO₂, byte 6 = CO₂ baseline. The first byte encodes device configuration flags (autoCalibration, transmitPower, etc.) stored as attributes.

1. Download the uplink converter file:
   • TBEL (Recommended)
   • JavaScript
   sigfox_tbel_uplink_converter.json
2. Go to Integrations center ⇾ Data converters.
3. Click + Add data converter ⇾ Import converter.
4. Drag and drop the downloaded JSON file into the Import converter window and click Import.

The decoder function used in this tutorial:

/** Decoder **/

// decode payload to string
var json = decodeToJson(payload);
var deviceName = 'Sigfox-' + json.device;
var deviceType = 'Sigfox Airwits CO2';
var groupName = 'UC-0023 Sigfox Airwits CO2';

var attrByte = parseInt(json.data.substring(0, 2), 16);
var autoCalibration = (attrByte & 0x1) === 1 ? "on" : "off";
var zeroPointAdjusted = ((attrByte & 0x2) >> 1) === 1 ? true : false;
var transmitPower = ((attrByte & 0x4) >> 2) === 1 ? "full" : "low";
var powerControl = ((attrByte & 0x8) >> 3) === 1 ? "on" : "off";
var firmwareVersion = attrByte >> 4;

var temperature = parseInt(json.data.substring(2, 6), 16) / 10.0 - 40;
var humidity = parseInt(json.data.substring(6, 8), 16);
var co2 = parseInt(json.data.substring(8, 12), 16);

var co2Baseline = 0;
var co2BaselineN = parseInt(json.data.substring(12, 14), 16);
if (co2BaselineN === 0) {
    co2Baseline = 400;
} else {
    co2Baseline = co2BaselineN * 10;
}

var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    groupName: groupName,
    telemetry: {
        ts: json.time + "000",
        values: {
            temperature: toFixed(temperature, 1),
            humidity: humidity,
            co2: co2,
            co2Baseline: co2Baseline
        }
    },
    attributes: {
        sigfox_id: json.device,
        autoCalibration: autoCalibration,
        zeroPointAdjusted: zeroPointAdjusted,
        transmitPower: transmitPower,
        powerControl: powerControl,
        fwVersion: firmwareVersion
    }
};

/** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

/** Decoder **/

// decode payload to string
var json = decodeToJson(payload);
var deviceName = 'Sigfox-' + json.device;
var deviceType = 'Sigfox Airwits CO2';
var groupName = 'UC-0023 Sigfox Airwits CO2';

var attrByte = parseInt(json.data.substring(0, 2), 16);
var autoCalibration = (attrByte & 0x1) === 1 ? "on" : "off";
var zeroPointAdjusted = ((attrByte & 0x2) >> 1) === 1 ? true : false;
var transmitPower = ((attrByte & 0x4) >> 2) === 1 ? "full" : "low";
var powerControl = ((attrByte & 0x8) >> 3) === 1 ? "on" : "off";
var firmwareVersion = attrByte >> 4;

var temperature = parseInt(json.data.substring(2, 6), 16) / 10 - 40;
var humidity = parseInt(json.data.substring(6, 8), 16);
var co2 = parseInt(json.data.substring(8, 12), 16);

var co2Baseline = 0;
var co2BaselineN = parseInt(json.data.substring(12, 14), 16);
if (co2BaselineN === 0) {
    co2Baseline = 400;
} else {
    co2Baseline = co2BaselineN * 10;
}

var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    groupName: groupName,
    telemetry: {
        ts: json.time + "000",
        values: {
            temperature: parseFloat(temperature.toFixed(1)),
            humidity: parseFloat(humidity),
            co2: co2,
            co2Baseline: co2Baseline
        }
    },
    attributes: {
        sigfox_id: json.device,
        autoCalibration: autoCalibration,
        zeroPointAdjusted: zeroPointAdjusted,
        transmitPower: transmitPower,
        powerControl: powerControl,
        fwVersion: firmwareVersion
    }
};

/** Helper functions **/

function decodeToString(payload) {
    return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
    var str = decodeToString(payload);
    var data = JSON.parse(str);
    return data;
}

return result;

To adapt this converter to your device:

• Different device name — change 'Sigfox-' + json.device to any identifier present in your payload.
• Different payload encoding — update the substring ranges and arithmetic to match your device’s byte layout.
• Additional telemetry — add more keys to telemetry.values (e.g. pressure: ...).
• Attributes — the first byte of json.data is decoded into device attributes; update the bit-mask logic to match your device’s configuration byte structure.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to SigFox.
   • Enable integration and Allow create devices or assets are on by default.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the previously created SigFox Uplink Converter.
   • Click Next.
4. Downlink data converter:
   • Leave empty and click Skip — the downlink converter can be added later.
5. Connection settings:
   • Copy the generated HTTP endpoint URL — you will need it when configuring the Sigfox Backend callback.
   • Enable Security (Headers filter) and add a header key-value pair to restrict access to this endpoint.
   • Click Add to save the integration.

Set Integration type to SigFox, enter a name, and click Next Click Select existing, choose SigFox Uplink Converter, and click Next Leave the downlink converter empty and click Skip Copy the HTTP endpoint URL; optionally enable Security to add a header filter, and click Add

HTTP endpoint URL

ThingsBoard generates a unique HTTP endpoint URL for each integration. Copy this URL and paste it into the URL pattern field in your Sigfox Backend callback. The URL is stable as long as the integration exists.

Security (Headers filter)

When enabled, ThingsBoard validates every incoming request against the configured header name-value pairs — requests missing the expected header are rejected. Add the same header key-value pair to the Sigfox Backend callback Headers field to authenticate requests.

Execute remotely

When enabled, ThingsBoard generates an Integration key and Integration secret that allow the integration to run as a separate process outside the ThingsBoard cluster — useful when your ThingsBoard instance is in a private network not reachable from the Sigfox cloud.

Advanced settings

Configure your Sigfox account to forward device messages to ThingsBoard.

1. In your Sigfox Backend, go to Device type and locate the device type associated with your device (e.g. thermostats).
2. Click the row’s context menu and select Edit.
3. In the Downlink data section, set Downlink mode to CALLBACK.
4. Click Ok to save.

Sigfox Backend — open the device type context menu and click Edit Set Downlink mode to CALLBACK in the Downlink data section and click Ok

1. Go to the Callbacks tab of the device type and click New in the upper right corner.
2. Select Custom callback.
3. Configure the callback:
   • Type: DATA, Channel: URL, Subtype: BIDIR (required for downlink support).
   • Custom payload config: enter the format string for your device (e.g. int1: sint.8 #0;).
   • URL pattern: paste the ThingsBoard HTTP endpoint URL copied from the integration.
   • Headers: if Security is enabled on the integration, add the same header key-value pair here.
   • Content type: application/json.
4. Enter the message body below and click Ok.

Sigfox Backend — Callbacks tab: click New to create a callback Select Custom callback Paste the ThingsBoard endpoint URL into URL pattern, add the security header, set the JSON message body, and click Ok

Callback message body:

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

After creating the callback, click the circle in the Downlink column to designate it as the active downlink handler. The circle turns solid (filled) to indicate active status.

Send an uplink message from your Sigfox device. ThingsBoard automatically creates the device and sends a notification. Click the bell icon and then Go to device to open the provisioned device.

Open the device to review its data:

Latest Telemetry tab showing the decoded sensor values: co2, co2Baseline, humidity, and temperature Attributes tab showing device attributes decoded from the first byte of the payload

You can also inspect the raw and decoded data in the uplink converter’s Events tab:

Events tab — In block showing the raw Sigfox message received by ThingsBoard Events tab — Out block showing the decoded telemetry and attributes

To send messages from ThingsBoard back to a Sigfox device, create a downlink converter and configure a rule chain. For the full encoder reference, see Downlink data converter.

The encoder function used in this tutorial:

// Encode downlink data from incoming Rule Engine message
var result = {
    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "TEXT",
    // downlink data
    data: msg.test,
    // Optional metadata object presented in key/value format
    metadata: {
        "device": "2203961"
    }
};
return result;

// Encode downlink data from incoming Rule Engine message
var result = {
    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "TEXT",
    // downlink data
    data: msg.test,
    // Optional metadata object presented in key/value format
    metadata: {
        "device": "2203961"
    }
};
return result;

To adapt this encoder to your use case:

• data — replace msg.test with the field from the Rule Engine message that carries the value to send (e.g. msg["base-key"] when the triggering shared attribute is named base-key). The Sigfox network supports up to 8 bytes of downlink payload.
• contentType — use TEXT for a plain string, JSON for a JSON object, or BINARY for a base64-encoded binary payload.
• metadata.device — replace the hardcoded device ID with the Sigfox device ID (without the Sigfox- prefix) that should receive the downlink message.

1. Go to Integrations center ⇾ Integrations and open SigFox Integration.
2. Click Toggle edit mode.
3. In the Downlink data converter field, click Create new.
4. In the Add data converter dialog, enter a name, and paste the encoder function from above into the editor and click the Add button.
5. Click Apply changes.

Open the SigFox Integration — the Downlink data converter field is empty; click Toggle edit mode Integration in edit mode — click Create new in the Downlink data converter field Enter the converter name, paste the encoder function in the TBEL editor, and click Add SigFox Downlink Converter is now assigned — click Apply changes to save

1. Go to Rule chains and open the Root Rule Chain.
2. Find the Integration Downlink node, drag it onto the canvas, name it SigFox integration downlink, select the SigFox integration, and click Add.
3. Connect the Message Type Switch node to the Integration Downlink node using both Attributes Updated and Post Attributes relation types.
4. Save the rule chain.

Name the node SigFox integration downlink, select SigFox Integration, and click Add Connect Message Type Switch → Attributes Updated and Post Attributes → SigFox integration downlink, then save

Adding or updating a shared attribute triggers the Attributes Updated relation in the rule chain, which forwards the change to the SigFox integration downlink node. ThingsBoard encodes the value using the downlink converter and sends it to Sigfox via the Cloud API. Sigfox queues the message and delivers it on the device’s next uplink transmission.

1. Go to Entities ⇾ Devices and open your device.
2. Click the Attributes tab and switch to Shared attributes.
3. Click +, enter a key (e.g. base-key) and a string value (e.g. 74524517), and click Add.

After the device sends its next uplink, the downlink is delivered. In your Sigfox Backend, go to the device Messages tab to confirm the downlink was acknowledged, and check the device type Statistics tab to see it reflected in the message chart.

Sigfox Backend — device Messages tab confirming the downlink was acknowledged with the transmitted hex data Sigfox Backend — device type Statistics tab showing uplink and downlink message traffic

• Integration Overview
• Uplink Converters
• Downlink Converters
• Rule Engine
• ThingsBoard Expression Language (TBEL)