Particle Integration

Particle Integration receives events from Particle Device Cloud through a webhook. An uplink data converter transforms each event into device data, including telemetry and attributes. For downlink, ThingsBoard calls a cloud function on the device through the Particle Cloud API.

Use Particle Integration when:

• Your devices run Particle Device OS and publish events with Particle.publish().
• You need to call device functions (Particle.function()) from ThingsBoard, for example from a dashboard control.

1. Publish an event. The device firmware calls Particle.publish().
2. Forward the event. A Particle webhook that matches the event name sends it as an HTTP POST to the integration endpoint. The body holds the event name, data, publish time, and Device ID (coreid).
3. Decode the payload. The uplink converter maps coreid to the device name and the event data to telemetry and attributes. If Allow create devices or assets is on, ThingsBoard creates the device on its first event.
4. Call a device function (optional). The Rule Engine passes an RPC request to the integration. The downlink converter encodes it, and ThingsBoard calls POST https://api.particle.io/v1/devices/{deviceId}/{function}, which runs the matching Particle.function() on the device.

• Access to ThingsBoard Cloud with integrations enabled for your tenant. The ThingsBoard endpoint must be reachable from the internet, because Particle Device Cloud calls it.
• Permission to create integrations and data converters, and to edit rule chains for downlink.
• A Particle Console account with at least one device that connects to Particle Device Cloud.
• For downlink: the Particle CLI to create an access token.

Register the device and flash firmware that publishes a ThingsBoard event.

For a single development device, use Particle Device Setup. For a product fleet, use your existing provisioning and claiming process.

1. Power the device and complete network setup. Wi-Fi devices can use setup.particle.io.
2. Register or claim the device in your sandbox or product.
3. Open Particle Console ⇾ Devices and check that the device is listed and online.
4. Copy the Device ID. Webhooks send it as coreid, and this guide uses it as the ThingsBoard device name.

This guide publishes the event tb/telemetry. Webhooks match event names by prefix, so a webhook for tb/ also receives later events such as tb/status or tb/location.

Event names may contain letters, numbers, underscores, dashes, and slashes. Names that start with particle or spark are reserved.

The firmware below publishes example values every 30 seconds. Replace them with real sensor data.

#include "Particle.h"

SYSTEM_THREAD(ENABLED);

unsigned long lastPublishMs = 0;
const std::chrono::milliseconds publishPeriod = 30s;

void setup() {
}

void loop() {
  if (Particle.connected() &&
    millis() - lastPublishMs >= publishPeriod.count()) {

    lastPublishMs = millis();

    // Replace these values with data from your sensors/application.
    Variant data;
    data.set("deviceType", Variant("Particle device"));
    data.set("temperature", Variant(23.5));
    data.set("humidity", Variant(60));
    data.set("battery", Variant(87));

    Particle.publish("tb/telemetry", data);
  }
}

#include "Particle.h"

SYSTEM_THREAD(ENABLED);

unsigned long lastPublishMs = 0;
const std::chrono::milliseconds publishPeriod = 30s;

void setup() {
}

void loop() {
  if (Particle.connected() &&
    millis() - lastPublishMs >= publishPeriod.count()) {

    lastPublishMs = millis();

    // Replace these values with data from your sensors/application.
    char payload[160];
    snprintf(payload, sizeof(payload),
      "{\"deviceType\":\"Particle device\",\"temperature\":23.5,\"humidity\":60,\"battery\":87}");

    Particle.publish("tb/telemetry", payload);
  }
}

The webhook sends ThingsBoard a body like this. The event data arrives as a JSON string in data:

{
  "event": "tb/telemetry",
  "data": "{\"deviceType\":\"Particle device\",\"temperature\":23.5,\"humidity\":60,\"battery\":87}",
  "coreid": "3c003c000f51373331333230",
  "published_at": "2026-08-10T12:04:33.940Z"
}

Create the uplink converter and the integration, then point a Particle webhook at the integration endpoint.

The uplink converter parses the webhook body, then parses the event data inside it. Particle 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.

The decoder in this guide maps:

• coreid ⇾ device name.
• deviceType from the event data ⇾ device profile. Default: Particle.
• published_at ⇾ telemetry timestamp.
• Other event data fields ⇾ telemetry.
• coreid and the integration name ⇾ attributes particleDeviceId and integrationName.

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

2. Converter type — keep Uplink.

3. Integration type — select Particle.

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

5. Main decoding configuration — the editor opens with the generic decoder template, which does not read the Particle webhook format. Replace it with the decoder below. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.

   • TBEL (Recommended)
   • JavaScript

   /** Decoder **/
   
   // Particle webhook body
   var data = decodeToJson(payload);
   
   // Particle event data must contain valid JSON.
   var eventData = decodeToJson(data.data);
   
   var deviceName = data.coreid;
   var deviceType = eventData.deviceType != null ? eventData.deviceType : "Particle";
   var groupName = "Particle devices";
   
   var timestamp = Date.now();
   if (data.published_at != null) {
     timestamp = new Date(data.published_at).getTime();
   

   ▼Expand

   To adapt:

   • Other telemetry — change the fields the firmware publishes. Every field not in excludeFromTelemetryList becomes telemetry; nested objects become dot-separated keys.
   • Device type — publish deviceType from the firmware, for example Photon 2 or Tracker One, or change the Particle default.
   • Attributes — add fields such as a serial number to attributes and to excludeFromTelemetryList.
   • Plain-text event data — skip the second parse and store the value directly, for example telemetry: { rawData: data.data }.
   • Several event types — branch on data.event, for example tb/telemetry and tb/status.

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

7. Click Add.

Decoder Inputs

Test the Decoder

Click Test decoder function below the editor. Set Payload content type to JSON, replace the payload with the sample webhook body from Publish Events from Firmware, and click Test. With the default Metadata (integrationName = Test PARTICLE), the Output panel shows:

{
  "deviceName": "3c003c000f51373331333230",
  "deviceType": "Particle device",
  "groupName": "Particle devices",
  "attributes": {
    "integrationName": "Test PARTICLE",
    "particleDeviceId": "3c003c000f51373331333230"
  },
  "telemetry": {
    "ts": 1786363473940,
    "values": {
      "temperature": 23.5,
      "humidity": 60,
      "battery": 87
    }
  }
}

Check that deviceName holds the Device ID and telemetry.values holds the expected keys. 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 Particle.
   • Name — keep the default Particle integration or enter your own.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first event.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose Particle 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 call device functions.
5. Connection:
   • Copy the HTTP endpoint URL. You need it for the Particle webhook.
   • Leave the other parameters at their defaults. See Connection Settings for details.
6. Click Add.

The webhook forwards matching events to the integration endpoint. Event name matching is a case-sensitive prefix: tb/ matches tb/telemetry, tb/status, and any other event that starts with tb/.

1. Open Particle Console and select the sandbox, organization, or product that contains your device.
2. In the left sidebar, open Cloud services and click Go to Integrations.
3. Select Custom Webhook and click Start now.
4. On the Webhook Builder tab, set:
   • Name — for example ThingsBoard.
   • Event name — tb/.
   • URL — the HTTP endpoint URL of the integration.
   • Request type — POST.
   • Request format — JSON.
   • Keep Status enabled.
5. Click Enable integration.

From the Particle Console home, open the sandbox, organization, or product that contains your device Open Cloud services in the left sidebar, then click Go to Integrations In the integrations catalog, find Custom Webhook and click Start now Enter Name, set Event name to the prefix your device publishes (e.g. tb/), paste the ThingsBoard HTTP endpoint URL, set Request type to POST and Request format to JSON, then click Enable integration Particle Console confirms the integration was created; use Test, Edit, or Delete from this page at any time

Publish an event, then confirm that ThingsBoard decoded it and created the device.

Flash the firmware from Publish Events from Firmware and wait for the device to connect. It publishes tb/telemetry every 30 seconds. The device’s Events tab in Particle Console shows each published event.

To test without a running device, open the webhook’s View integration page in Particle Console and click Test. Enter your Device ID, put a JSON object in Event data, and click Run test:

{ "deviceType": "Particle device", "temperature": 23.5, "humidity": 60, "battery": 87 }

Open the integration's View integration page and click Test Provide valid JSON Event data and the real Device ID, then click Run test

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears with status OK.
• Converter events — open Particle Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the webhook 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 a device named after the Device ID, in the Particle devices group. Open it and check the values on the Latest telemetry tab and particleDeviceId 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. Particle logs the rejected call as a hook-error event.

1. In Particle Console, edit the webhook and add a custom HTTP header, for example X-API-Key with a secret value.
2. In ThingsBoard, open the integration and click Toggle edit mode (pencil icon).
3. Turn on Enable security.
4. Under Headers filter, click Add and enter the same Header and Value. A request must carry every header in the list. The value match is exact and case-sensitive.
5. Click Apply changes.

ThingsBoard sends each downlink right away as a Particle Cloud API call. Nothing is queued: if the device is offline or the call fails, ThingsBoard logs an error and drops the command.

The downlink converter turns an RPC request from the Rule Engine into a function call. For the full encoder reference, see Downlink data converter.

ThingsBoard authenticates to the Particle Cloud API with an access token. The Call a function endpoint requires the devices.function:call scope.

For production, use a Particle API user limited to that scope. For a quick test, create a user token with the Particle CLI:

1. Install the CLI, then close and reopen the terminal:

   bash <( curl -sL https://particle.io/install-cli )

2. Log in to your Particle account:

   particle login

3. Create a token that does not expire, and copy it. The CLI shows it only once.

   particle token create --never-expires

The installer confirms success — close and reopen your terminal (or start a new shell) before the particle command is available on your PATH Particle CLI — particle login prompts for credentials and confirms successful authentication Particle CLI — the generated access token is displayed once; copy it immediately for use in the integration

The firmware below registers the function setOutput, which turns the D7 output on or off. Replace the pin and handler with your own control logic.

#include "Particle.h"

SYSTEM_THREAD(ENABLED);

int setOutput(String command);

void setup() {
    pinMode(D7, OUTPUT);
    digitalWrite(D7, LOW);

    Particle.function("setOutput", setOutput);
}

void loop() {
}

int setOutput(String command) {
    if (command == "on") {
        digitalWrite(D7, HIGH);
        return 1;
    }

    if (command == "off") {
        digitalWrite(D7, LOW);
        return 0;
    }

    return -1;
}

The function name must match the RPC method. A cloud function takes one string argument and should return quickly: start long operations and return a status code.

Add a downlink converter to the integration and turn on Allow downlink with the access token.

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 Particle integration type are preselected.
3. Enter a name, for example Particle Downlink Converter.
4. Main encoding configuration opens with a generic encoder that does not set the Device ID. Replace it with the encoder below. The same code runs in TBEL and JavaScript.
5. To record downlink events, click the debug icon next to the name, select All messages, and click Apply.
6. Click Add.
7. Enable downlink: turn on Allow downlink and paste the token from Create a Particle Access Token into Token.
8. Click Apply changes.

Encoder used in this guide:

/** Encoder **/

// The integration calls the Particle function named by "method"
// and passes "params" as its string argument.
// msg.params is serialized JSON, for example "\"on\"": JSON.parse returns on.
var result = {
    contentType: "JSON",
    data: JSON.stringify({
        method: msg.method,
        params: JSON.parse(msg.params)
    }),
    metadata: {
        // Particle Device ID of the target device.
        // This guide uses it as the ThingsBoard device name.
        deviceId: metadata.deviceName
    }
};

return result;

The integration reads these fields from the encoder result:

Route RPC requests to the integration. Other message types have no method field, so the converter cannot turn them into function calls.

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, To Particle integration), select your Particle integration, and click Add.
4. Connect the message type switch node to the integration downlink node with the RPC Request to Device relation.
5. Click Apply changes.

Add a dashboard switch that calls setOutput with on or off.

1. Open a dashboard, click Edit mode, then click + Add widget.
2. In the Control widgets bundle, select Switch Control.
3. On the Data tab, set Target device to Device and select the Particle device.
4. On the Appearance tab:
   • Retrieve value using method — Don’t retrieve.
   • RPC set value method — setOutput.
   • Convert value function — return value ? "on" : "off";
5. Click Add, save the dashboard, and exit edit mode.
6. Toggle the switch.

Each toggle produces this call:

RPC method: setOutput, params: "on"
        │
        ▼
POST https://api.particle.io/v1/devices/{deviceId}/setOutput
Authorization: Bearer <token>
{"arg": "on"}
        │
        ▼
Particle.function("setOutput", ...) on the device

• Device — the D7 output (on many boards, the blue LED) turns on or off.
• Converter events — open the downlink converter’s Events tab. In shows the RPC request, and Out shows the encoded data and metadata.deviceId.
• Integration events — open the integration’s Events tab. A failed call appears with status ERROR and the Particle API response.

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.
• TBEL — built-in functions and syntax for converter scripts.
• Particle webhooks — event filters, default fields, templates, and delivery.
• Particle.publish() and typed publish — publish events from Device OS.
• Particle.function() — expose a device function through Particle Device Cloud.
• Particle Cloud API — the Call a function endpoint and its scope.
• Particle access tokens — user tokens, API users, and token security.