Particle Integration

Particle is an IoT cloud platform for connected devices. After integrating Particle with ThingsBoard, device events flow from the Particle Cloud to ThingsBoard via a webhook — and ThingsBoard can send RPC commands back to devices through the Particle Cloud function API.

• A Particle Console account with at least one registered device.
• The Particle CLI installed if you want to send downlink commands.

Follow the official Particle setup guide to connect your Photon to Wi-Fi and register it with the Particle Cloud. The device must be online before events can be forwarded to ThingsBoard.

1. Power on your device. Plug the USB cable into a power source. The RGB LED blinks blue when the device is ready for setup. If it is not blinking blue, hold the SETUP button until it does.
2. Connect to Wi-Fi. Go to setup.particle.io, click Setup a Photon, download photonsetup.html, and open it in your browser to complete Wi-Fi configuration.

Once connected, the device appears in the Particle Console under Devices with Status: Online. Note the device ID (the coreid column) — the uplink converter uses it as the ThingsBoard device name.

The uplink converter parses incoming Particle event payloads and maps them to ThingsBoard telemetry and attributes. Particle uses a generic uplink converter. Each Particle event contains a coreid field (the device ID, used as the ThingsBoard device name), a data field (the event payload), and metadata such as published_at. The decoder stores online/offline events as a status attribute and all other event data as raw rawData telemetry.

1. Go to Integrations center ⇾ Data converters
2. Click + Add data converter ⇾ Create new converter.
3. Ensure the type is Uplink.
4. Enter a converter name (e.g. Particle Uplink Converter).
5. Paste the decoder script and click Add.

The decoder function used in this tutorial:

/** Decoder **/

// decode payload to JSON
var data = decodeToJson(payload);
if (data.coreid != "api") {
    var deviceName = data.coreid;
    var deviceType = 'Photon';
    var groupName = 'Particle devices';

    var attributes = {
        integrationName: metadata['integrationName']
    };

    var telemetry = {};

    if (data.data == 'online' || data.data == 'offline') {
        attributes.status = data.data;
    } else {
        telemetry.rawData = data.data;
    }

    var result = {
        deviceName: deviceName,
        deviceType: deviceType,
        groupName: groupName,
        attributes: attributes,
        telemetry: telemetry
    };

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

    return result;
}

/** Decoder **/

// decode payload to JSON
var data = decodeToJson(payload);
if (data.coreid != "api") {
    var deviceName = data.coreid;
    var deviceType = 'Photon';
    var groupName = 'Particle devices';

    var attributes = {
        integrationName: metadata['integrationName']
    };

    var telemetry = {};

    if (data.data == 'online' || data.data == 'offline') {
        attributes.status = data.data;
    } else {
        telemetry.rawData = data.data;
    }

    var result = {
        deviceName: deviceName,
        deviceType: deviceType,
        groupName: groupName,
        attributes: attributes,
        telemetry: telemetry
    };

    return result;
}

/** 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;
}

To adapt this converter to your device:

• Structured payload — if your device publishes JSON (e.g. {"temp": 23.5, "humidity": 60}), parse it with decodeToJson(data.data) and map individual fields to telemetry keys instead of storing rawData.
• Different device name — coreid is the Particle device ID (a hex string). To use a human-readable name, include a name field in the event data and extract it from data.data after parsing.
• Additional attributes — add more keys to the attributes object (e.g. firmware version, hardware revision).
• Event filtering — the data.coreid != "api" check discards Particle Cloud API events that have no associated physical device.

The downlink converter encodes outgoing ThingsBoard RPC messages into commands sent to your Particle device. For the full encoder reference, see Downlink data converter. via the Particle Cloud function API. It reads the RPC method and params from the incoming ThingsBoard message and forwards them to the registered Particle function on the device.

1. Go to Integrations center ⇾ Data converters, click + Add data converter ⇾ Create new converter.
2. Switch the type to Downlink.
3. Enter a converter name (e.g. Particle Downlink Converter).
4. Paste the encoder script and click Add.

The encoder used in this tutorial:

/** Encoder **/

var command = {};
command["method"] = msg.method;
if (msg.params == "false" || msg.params == "true") {
    command["params"] = Boolean.valueOf(msg.params);
} else {
    command["params"] = msg.params;
}

var result = {
    contentType: "JSON",
    data: JSON.stringify(command),
    metadata: {
        deviceId: metadata.deviceName
    }
};

return result;

/** Encoder **/

var command = {};
command["method"] = msg.method;
if (msg.params == "false" || msg.params == "true") {
    command["params"] = Boolean.valueOf(msg.params);
} else {
    command["params"] = msg.params;
}

var result = {
    contentType: "JSON",
    data: JSON.stringify(command),
    metadata: {
        deviceId: metadata.deviceName
    }
};

return result;

The metadata.deviceId is set to the ThingsBoard device name (which equals the Particle coreid) and is used by the integration to identify the target device when calling the Particle Cloud API.

To allow ThingsBoard to call Particle Cloud device functions for downlink, generate an access token using the Particle CLI.

Install the CLI:

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

Then, according to official documentation, you will need to log in to your Particle account:

particle login

Create an access token. Use the never-expires option for a long-lived integration token:

# Never-expiring token (recommended for integrations)
particle token create --never-expires

# Token with default 90-day expiration
particle token create

Save the token — you will need it in the next step.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to Particle.
   • Enable integration and Allow create devices or assets are on by default.
   • Click Next.
3. Uplink data converter:
   • Click Select existing, choose the previously created Particle Uplink Converter.
   • Click Next.
4. Downlink data converter:
   • Click Select existing, choose the previously created Particle Downlink Converter.
   • Click Next.
5. Connection settings:
   • Note the HTTP endpoint URL displayed — you will paste it into the Particle Console webhook in the next section.
   • Enable Allow downlink and paste the Particle access token you generated into the Token field.
6. Click Add to save the integration.

Set Integration type to Particle, enter a name, and click Next Click Select existing, choose Particle Uplink Converter, and click Next Click Select existing, choose Particle Downlink Converter, and click Next Copy the HTTP endpoint URL for use in the Particle Console webhook; enable Allow downlink, paste the access token, and click Add

To push device events from Particle Cloud to ThingsBoard, create a webhook in the Particle Console that forwards matching events to the ThingsBoard integration endpoint.

1. In the Particle Console, open your product, go to Integrations, and click + Add New Integration.
2. Select Webhook from the integration type list.
3. Fill in the webhook form:
   • Name — e.g. ThingsBoard
   • Event Name — the Particle event name your device publishes (e.g. spark). Only events matching this name trigger the webhook.
   • URL — paste the HTTP endpoint URL copied from the ThingsBoard integration Connection step.
   • Request Type — POST
   • Request Format — JSON
   • Leave Status as Enabled.
4. Click Create Webhook.

Open the Integrations section and click + Add New Integration Select Webhook from the integration type list Enter Name, set Event Name to the event your device publishes (e.g. spark), paste the ThingsBoard HTTP endpoint URL, set Request Type to POST and Format to JSON, then click Create Webhook Webhook created — the confirmation page shows the event name, target URL, and status; the success toast confirms creation

To trigger a test event, publish a Particle event from the CLI using the same event name you configured in the webhook (e.g. spark):

particle publish spark "test data" --private

Alternatively, open the webhook in the Particle Console, go to Integrations, select the ThingsBoard webhook, and click Test to send a sample payload.

Once the webhook forwards an event to ThingsBoard, go to Entities ⇾ Devices — the device is automatically provisioned using the Particle coreid as the device name, assigned the Photon profile, and placed in the Particle devices group.

To route RPC commands from ThingsBoard dashboards to your Particle device, connect the Integration Downlink node to the Root Rule Chain.

1. Go to Rule chains and open the Root Rule Chain.
2. Find the Integration Downlink node in the node panel, drag it onto the canvas, enter a name (e.g. To Particle integration), select the Particle integration, and click Add.
3. Connect the Message Type Switch node to the Integration Downlink node using the RPC Request to Device relation type.
4. Click Apply changes to save the rule chain.

Drag the Integration Downlink node onto the canvas, enter a name, select the Particle integration, and click Add Connect Message Type Switch to the Integration Downlink node via the RPC Request to Device relation, then click Apply changes

To test RPC commands, use the Web-Connected LED example from the Particle Web IDE. This firmware registers a Particle Cloud function called led that accepts on and off string arguments to control the onboard LED.

1. Open the Particle Web IDE and click Web-Connected LED in the example apps list.
2. Click Use this example to copy it to your apps.
3. Click the flash (thunder) icon to compile and upload the firmware to your device.

1. Open an existing ThingsBoard dashboard or create a new one and enter Edit mode.
2. Click Add widget ⇾ Control widgets ⇾ Switch Control to add the widget.
3. On the Data tab, set Target device to your Particle device (create a new alias pointing to the provisioned device if needed).
4. Open the Appearance tab.
5. Set Retrieve value using method to Don’t retrieve.
6. Set RPC set value method to led.
7. Paste the following into the Convert value function field:

   return value ? "on" : "off";

8. Click Add to save the widget, then click Save to save the dashboard.

In edit mode, click Add widget, open the Control widgets bundle, and select Switch Control On the Data tab, create a new alias named Particle Device pointing to the provisioned Particle device, then open the Appearance tab Set Retrieve value using method to Don't retrieve, set RPC set value method to led, paste the convert value function, then click Add and save the dashboard

Toggle the switch on the dashboard. ThingsBoard sends a led RPC call with on or off to the Particle Cloud API, which forwards it to the registered led function on your Photon — the onboard LED changes state accordingly.

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