IoT Creators Integration

The iotcreators.com (T-Mobile – IoT CDP) integration connects ThingsBoard to the IoT Creators platform — the NB-IoT and LTE-M connectivity platform operated by T-Mobile / Deutsche Telekom. Use it to bring telemetry from cellular IoT devices already provisioned in IoT Creators into ThingsBoard for monitoring and rule-based automation.

An NB-IoT / LTE-M device sends an uplink over UDP or CoAP to the IoT Creators platform, which forwards it over HTTP (a JSON body containing a reports array) to the integration’s endpoint. The uplink converter decodes each report’s payload into telemetry and attributes, and the ThingsBoard Core Service stores the data, creating the device automatically on first contact. Downlink to cellular devices is handled by the IoT Creators platform itself — see Downlink to Devices.

Before creating the integration, ensure:

• You have access to ThingsBoard PE or ThingsBoard Cloud with integration functionality enabled for your tenant.
• You have permissions to create integrations and data converters.
• You have an IoT Creators account with at least one project and a Starterkit / SIM card.
• You have at least one NB-IoT or LTE-M device that sends its payload to the IoT Creators UDP/CoAP server, with its IMEI on hand.

The uplink converter decodes the incoming IoT Creators message (JSON containing a reports array) and maps it to the ThingsBoard data model — it resolves the target device from the report serialNumber (IMEI) and extracts fields into telemetry and attributes. For the full decoder function reference, see Uplink data converter.

As an example, this integration uses a real IMBUILDINGS Comfort Sensor, officially listed in the IoT Creators documentation. It measures temperature, humidity, CO₂, battery voltage, and presence. IoT Creators forwards the sensor payload as a hex string in the reports[0].value field.

Sample payload:

{
  "reports": [
    {
      "serialNumber": "IMEI:866425033313638",
      "timestamp": 1600439712734,
      "subscriptionId": "fa37d89c-a7e2-4f3d-b12f-6002a3642b4c",
      "resourcePath": "uplinkMsg/0/data",
      "value": "0101d880396f026e000158a50a4b121503d301"
    }
  ],
  "registrations": [],
  "deregistrations": [],
  "updates": [],
  "expirations": [],
  "responses": []
}

This is a real subscription callback payload from the IoT Creators documentation. The reports[0].value hex string decodes to:

{
  "status": 0,
  "batteryVoltage": 3.44,
  "temperature": 26.35,
  "humidity": 46.29,
  "co2": 979,
  "presence": true
}

The byte layout and decoding logic are described in the official IMBUILDINGS Comfort Sensor documentation.

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.
3. Converter type — leave Uplink (selected by default).
4. Integration type — in the search field, enter iotcreators and select iotcreators.com (T-Mobile – IoT CDP) from the list.
5. Name — enter a converter name, for example IoT Creators Uplink Converter.
6. In Main decoding configuration:
   • The default decoder is pre-filled. Leave it unchanged for this guide, or paste the decoder function below.
   • Because a single message may contain reports for several devices, the device name is set inside the decoder from each report’s serialNumber, rather than by a global device name pattern.
7. Enable Debug mode so you can inspect incoming and decoded messages on the Events tab while setting up.
8. Click Add.

The decoder below parses the forwarded JSON, uses the report’s serialNumber (with the IMEI: prefix stripped) as the device name, and decodes the hex value field byte-by-byte into telemetry according to the IMBUILDINGS Comfort Sensor payload specification. Adapt the hex field offsets to match your device protocol.

The decoder function used in this tutorial:

// Decode an IoT Creators subscription notification
// payload - array of bytes (the HTTP POST body)
// metadata - key/value object

/** Decoder **/

var data = decodeToJson(payload);

// The example notification contains one sensor report.
var report = data.reports[0];

// IoT Creators identifies the device using a serial number
// with the "IMEI:" prefix.
var serialNumber = "" + report.serialNumber;
var imei = serialNumber.replace("IMEI:", "");

// The Comfort Sensor payload is provided as a hex string.
var bytes = hexToBytes(report.value);

// Decode the measurement values according to the
// Comfort Sensor payload specification.
var status = bytes[8] & 0xFF;

var batteryVoltage = (((bytes[9] & 0xFF) << 8) | (bytes[10] & 0xFF)) / 100.0;

var temperature = (((bytes[12] & 0xFF) << 8) | (bytes[13] & 0xFF)) / 100.0;

var humidity = (((bytes[14] & 0xFF) << 8) | (bytes[15] & 0xFF)) / 100.0;

var co2 = ((bytes[16] & 0xFF) << 8) | (bytes[17] & 0xFF);

var presence = (bytes[18] & 0xFF) == 1;

// Result object with the decoded device data.
var result = {
  deviceName: "NB-IoT-" + imei,
  deviceType: "NB-IoT sensor",

  attributes: {
    serialNumber: serialNumber,
    subscriptionId: report.subscriptionId,
    resourcePath: report.resourcePath,
    model: "Comfort Sensor"
  },

  telemetry: {
    ts: report.timestamp,
    values: {
      status: status,
      batteryVoltage: batteryVoltage,
      temperature: temperature,
      humidity: humidity,
      co2: co2,
      presence: presence
    }
  }
};

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

return result;

// Decode an IoT Creators subscription notification
// payload - array of bytes (the HTTP POST body)
// metadata - key/value object

/** Decoder **/

var data = decodeToJson(payload);

// The example notification contains one sensor report.
var report = data.reports[0];

// IoT Creators identifies the device using a serial number
// with the "IMEI:" prefix.
var serialNumber = String(report.serialNumber);
var imei = serialNumber.replace("IMEI:", "");

// The Comfort Sensor payload is provided as a hex string.
var bytes = hexToBytes(report.value);

// Decode the measurement values according to the
// Comfort Sensor payload specification.
var status = bytes[8] & 0xFF;

var batteryVoltage = (((bytes[9] & 0xFF) << 8) | (bytes[10] & 0xFF)) / 100;

var temperature = (((bytes[12] & 0xFF) << 8) | (bytes[13] & 0xFF)) / 100;

var humidity = (((bytes[14] & 0xFF) << 8) | (bytes[15] & 0xFF)) / 100;

var co2 = ((bytes[16] & 0xFF) << 8) | (bytes[17] & 0xFF);

var presence = (bytes[18] & 0xFF) === 1;

// Result object with the decoded device data.
var result = {
  deviceName: "NB-IoT-" + imei,
  deviceType: "NB-IoT sensor",

  attributes: {
    serialNumber: serialNumber,
    subscriptionId: report.subscriptionId,
    resourcePath: report.resourcePath,
    model: "Comfort Sensor"
  },

  telemetry: {
    ts: report.timestamp,
    values: {
      status: status,
      batteryVoltage: batteryVoltage,
      temperature: temperature,
      humidity: humidity,
      co2: co2,
      presence: presence
    }
  }
};

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

return result;

To adapt this converter to your device:

• Device name — replace "NB-IoT-" + imei with any identifier present in your payload (e.g. a device label sent by the application layer).
• Multiple reports per message — a single IoT Creators notification can contain more than one entry in reports. Loop over data.reports and return an array of result objects if your subscription forwards several devices per callback.
• Byte offsets and scaling — the offsets into bytes (8, 9–10, 12–13, and so on) and the / 100 scaling factors are specific to the IMBUILDINGS Comfort Sensor. Adjust them to match your device’s payload specification.
• Timestamp — the decoder uses report.timestamp as Unix milliseconds. If the timestamp is an ISO 8601 string, use new Date(report.timestamp).getTime() instead.
• Base64 payload — if your device sends raw bytes as base64 (instead of hex), decode with base64ToBytes(report.value) instead of hexToBytes.
• Attributes — add or remove fields from attributes as required. Store frequently changing values as telemetry, and static device properties as attributes.

The IoT Creators integration wizard creates the uplink converter inline — you write the decoder function in step 2 of the wizard without leaving the dialog.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to iotcreators.com (T-Mobile – IoT CDP).
   • Enter a Name, or keep the default iotcreators.com (T-Mobile – IoT CDP) integration.
   • Leave Enable integration and Allow create devices or assets enabled so that devices are created automatically when data is received for the first time.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the IoT Creators Uplink Converter created above, or click Create new to define the decoder inline.
   • Click Next.
4. Connection:
   • Base URL — pre-filled with your ThingsBoard instance URL (for example, https://thingsboard.cloud).
   • Copy the HTTP endpoint URL — you will paste this into the IoT Creators portal as the callback address so the platform forwards uplinks to ThingsBoard.
5. Click Add to finish creating the integration.

Basic settings — set Integration type to "iotcreators.com (T-Mobile – IoT CDP)", enter a name, and click Next. Uplink data converter — Create new is selected by default. Replace the decoder with your custom function and click Next. Connection — copy the HTTP endpoint URL. ThingsBoard will receive IoT Creators subscription notifications at this address. Click Add to save.

Base URL

Your ThingsBoard instance base URL (e.g. https://thingsboard.cloud). This is pre-filled automatically and is used to construct the HTTP endpoint URL.

HTTP endpoint URL

The auto-generated webhook address for this integration, in the form:

https://{base-url}/api/v1/integrations/tmobile_iot_cdp/{integration-id}

Paste this URL into the IoT Creators portal as the callback address so the platform forwards device uplink messages to ThingsBoard.

Execute remotely

When enabled, ThingsBoard generates an Integration key and Integration secret for running the integration outside the ThingsBoard cluster — useful when ThingsBoard is not publicly reachable from the IoT Creators platform. See Remote Integration.

Advanced Settings

• Replace response status from ‘No-Content’ to ‘OK’ — makes ThingsBoard answer with HTTP 200 OK instead of 204 No Content. Enable this: the IoT Creators portal sends an empty test request when you save the callback URL and refuses to save it unless the endpoint returns 200.
• Description — optional free-text description for this integration.
• Metadata — key-value pairs injected into every uplink message as integrationMetadata in converter scripts; click Add to define entries.

Configure your IoT Creators project to forward uplink messages to the ThingsBoard HTTP endpoint URL copied in Create IoT Creators Integration.

1. Sign in to the IoT Creators portal.
2. Open Projects, select your project, and switch to the Your application server tab.
3. Paste the ThingsBoard HTTP endpoint URL into the Callback URL field.
4. Make sure the endpoint toggle is ON, then click Save.

1. Log in to the IoT Creators portal.
2. Open your project (e.g. Starterkit) from PROJECTS.
3. On the project page, the Devices tab is selected by default. Click REGISTER DEVICE above the devices table.
4. In the Register device dialog, enter the device’s IMEI.
5. Click REGISTER DEVICE to confirm.

The device now appears in the devices table with IMEI, IMSI, Last message, and Payload columns — the last two stay empty until the device sends its first uplink.

After the integration and converter are configured, and the device is transmitting through IoT Creators, confirm that ThingsBoard receives, decodes, and stores the data correctly.

Wait for your NB-IoT or LTE-M device to transmit an uplink through IoT Creators, or emulate one by sending an HTTP request directly to the ThingsBoard endpoint with curl — bypassing IoT Creators entirely. This is useful to verify the integration and converter before connecting real hardware.

Replace $HTTP_ENDPOINT_URL with the HTTP endpoint URL copied in Create IoT Creators Integration:

curl -v \
  -H "Content-Type: application/json" \
  -d '{"reports":[{"serialNumber":"IMEI:866425033313638","timestamp":1600439712734,"subscriptionId":"fa37d89c-a7e2-4f3d-b12f-6002a3642b4c","resourcePath":"uplinkMsg/0/data","value":"0101d880396f026e000158a50a4b121503d301"}],"registrations":[],"deregistrations":[],"updates":[],"expirations":[],"responses":[]}' \
  "$HTTP_ENDPOINT_URL"

The value matches the byte layout from the uplink converter and decodes to status = 0, batteryVoltage = 3.44, temperature = 26.35, humidity = 46.29, co2 = 979, presence = true.

Go to Integrations center ⇾ Integrations, open iotcreators.com (T-Mobile – IoT CDP) integration, and check the Events tab (Event type: Debug). An Uplink event with Status: OK confirms the message was processed. Click … in the Message column to open the raw payload received from IoT Creators.

Go to Integrations center ⇾ Data converters, open the uplink converter you configured for this integration, and click its Events tab.
Click … in each column to inspect:

• In — the raw { "reports": [ ... ] } JSON body received by the converter.
• Out — the decoded result produced by the script: telemetry.values (batteryVoltage, temperature, humidity, status) and attributes (serialNumber, subscriptionId, resourcePath, model).
• Metadata — integration-level context, including integrationName.

Go to Entities ⇾ Devices. A device named NB-IoT-<IMEI> is automatically provisioned on the first uplink, provided Allow create devices or assets is enabled. Open it and check:

• Latest telemetry — status, batteryVoltage, temperature, humidity, co2, and presence should reflect the values decoded from the uplink.
• Attributes (Client attributes scope) — serialNumber, subscriptionId, resourcePath, and model are set from the subscription notification.

Unlike LoRaWAN network servers, the IoT Creators integration is uplink-oriented — the Connection step exposes no downlink URL, and the Add integration wizard has no downlink converter step. Downlink to NB-IoT / LTE-M devices is handled by the IoT Creators platform itself, through its own downlink API — a write to the device’s downlinkMsg/0/data resource.

To drive commands from ThingsBoard, add a Rule Engine flow that calls the IoT Creators downlink API (for example, a REST API Call node triggered by a shared-attribute update), passing the device IMEI and the encoded payload. Refer to the IoT Creators API documentation for the downlink request format.

The SODAQ Universal Tracker guide demonstrates an end-to-end IoT Creators setup: a NB-IoT tracker sends hex-encoded GPS and sensor data over T-Mobile, the uplink converter decodes it into ThingsBoard telemetry, and a Tracker Alarms rule chain fires alerts based on configurable speed, voltage, and temperature thresholds.

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