How to integrate with Particle by Digi

General Tutorials
1

This tutorial provides a step-by-step guide to integrate Particle (Particle.io by Digi International) with the TagoIO platform. By following these instructions, you will enable uplink and downlink operations, allowing data exchange between your Particle devices and your TagoIO application.

Uplink is the process of sending data from the devices to TagoIO: every event your device publishes with Particle.publish is forwarded by a Particle webhook to TagoIO. Downlink is used to send data back to the devices.

Prerequisites

Before you begin, ensure you have the following:

  • TagoIO account: if you don’t have one, register here.
  • Particle account and device: your device must be claimed on the Particle Console and publishing events with Particle.publish.

Step 1: Create Authorization in TagoIO

  1. Access Authorizations

    • Go to Devices in the TagoIO Admin.
    • Click on Authorizations at the top of the page.

  2. Create a New Authorization

    • Click the Create Authorization button.
    • Provide a meaningful name for the authorization (e.g., Particle-Integration).
    • Click Save.

  3. Copy the Authorization Token

    • After creation, copy the authorization token. You will need it in Step 3.

:information_source: Note: You only need one authorization for all your Particle devices. Create additional authorizations only if you want to separate integrations based on your specific needs.

Step 2: Add Your Device to TagoIO

  1. Find your Device ID on Particle

    • In the Particle Console, open your device and copy its Device ID (a 24-character hexadecimal string, e.g., e00fce68380835xxxxxxxxxx).

  2. Create the device in TagoIO

    • In the TagoIO Admin, go to Devices and click New Device.
    • Search for the Particle network and select the connector for your device. If your device type is not listed, use the Custom Particle connector.
    • Enter the Device ID from Particle as the Core ID. The Core ID must match the Particle Device ID exactly; this is what links the two platforms.

For detailed instructions on adding devices, visit the Adding Devices page.

Screenshot 2026-07-31 at 16.51.43
Screenshot 2026-07-31 at 16.51.431376×1154 94.4 KB

Step 3: Create the TagoIO integration in the Particle Console

Particle provides a ready-made TagoIO integration template, so there is no URL to type.

  1. In the Particle Console, go to Integrations, click Add New Integration, and select TagoIO.

  2. Fill in the form:

    • Name: a name for the integration (for example, TagoIO).
    • Event name: the event your firmware publishes (for example, loc).
    • TagoIO account region: us-e1 for USA accounts, eu-w1 for European accounts.
    • TagoIO auth token: a cloud secret holding the token from Step 1 (see below).

  3. The auth token is stored as a cloud secret. Click Or click here to create a new secret. in the Parameters section, give the secret a name (for example, TAGOIO_AUTHORIZATION), paste the Authorization token from Step 1 as its value, and save. Back in the form, select the secret in the TagoIO auth token field. If it does not show up, reload the page and it will appear.

  4. Click Enable integration.

Screenshot 2026-08-05 at 14.52.46
Screenshot 2026-08-05 at 14.52.46783×677 33.4 KB

Using TagoDeploy?

The TagoIO template targets the us-e1 and eu-w1 regions. If your account runs on a TagoDeploy instance, the Particle middleware URL is specific to your environment, so the region parameter does not apply. In the integration form, click Go to advanced view and enter the middleware URL of your instance directly:

https://<your-particle-middleware-domain>/uplink?authorization=YOUR_AUTHORIZATION

Finalizing Setup

  1. Publish an event

    • Power on your device, or wait for the next Particle.publish from the firmware.

  2. Verify data reception

    • In TagoIO, open your device and check the Data tab. The network’s payload parser decodes each uplink into variables; the exact variables depend on the connector and on the payload your firmware publishes.
    • Alternatively, use the Live Inspector in your device settings to monitor incoming data in real time.

You also can create your own parser to change how the published payload is decoded into variables.

Downlink Configuration

The Particle integration supports two ways of sending data back to the device.

Option A: Downlink on the next uplink (class A)

The middleware answers each uplink webhook with any pending downlink payload, and the Particle Cloud republishes that response to your device as a hook-response/<event> event. No Particle credential is needed.

  1. Subscribe to the response in your firmware

    void downlinkHandler(const char *event, const char *data) {
  // apply the command
}

void setup() {
  Particle.subscribe("hook-response/loc/", downlinkHandler);
}

  2. Queue the downlink in TagoIO

    • Open your device in the TagoIO Admin and go to the Configuration Parameters section (More tab).
    • Create a parameter with key downlink and the payload as its value, and leave it unsent.
    • On the next uplink, the middleware delivers the payload (one parameter per uplink, oldest first) and marks it as sent.

:information_source: Note: With more than one device on your Particle account, open the integration’s advanced view and set the Response Topic to {{{PARTICLE_DEVICE_ID}}}/hook-response/{{{PARTICLE_EVENT_NAME}}} and subscribe with System.deviceID() + "/hook-response/" so each device only receives its own downlinks. Responses above 512 bytes arrive split into chunks (/0, /1, …).

Option B: Immediate downlink

The middleware can also call a Particle cloud function on your device right away. This requires:

  1. A cloud function in your firmware

    int downlinkHandler(String payload) {
  // apply the command
  return 0; // any value >= 0 means success
}

void setup() {
  Particle.function("downlink", downlinkHandler);
}

  2. A Particle API token stored in TagoIO

    • In the Particle Console, create an API user with the devices.function:call scope (Product > Team > API Users) and copy its token.
    • In the TagoIO Admin, open the authorization created in Step 1 and paste the Particle token into the Additional Parameter field.

  3. Send the downlink

    curl -X POST "https://particle.middleware.REGION.tago.io/downlink" \
  -H "Content-Type: application/json" \
  -d '{
    "device": "YOUR_PARTICLE_DEVICE_ID",
    "authorization": "YOUR_AUTHORIZATION_TOKEN",
    "payload": "0A0B"
  }'

    Replace REGION with us-e1 or eu-w1, matching your TagoIO account region. The response includes the value returned by your cloud function. If your firmware registers the function under a different name, create a device Configuration Parameter with key downlink_function and the function name as its value.

:warning: The device must be online for the immediate downlink; otherwise the request returns an error. For devices that sleep between transmissions, use Option A.

Troubleshooting

Error 401 - Unauthorized

  • Invalid Authorization Token: verify that the secret selected in TagoIO auth token holds the exact token from Step 1 (or the authorization query parameter, if you entered the URL through the advanced view).
  • Device not found (downlink): the device sent to /downlink does not match the Core ID of any device in your TagoIO account. Both must match exactly.
  • Wrong region: confirm the URL region (us-e1 or eu-w1) matches your TagoIO account region.

Error 400 - Bad Request

  • Missing Particle token: the immediate downlink requires the Particle API token in the Additional Parameters of your authorization (Option B, item 2).
  • Invalid or expired Particle token: the error message includes the reason returned by Particle (e.g., invalid_token). Generate a new API user token and update the Additional Parameters field.
  • Function not registered: the cloud function name called by the middleware does not exist on the firmware. Check the downlink_function parameter and the name registered with Particle.function.
  • Payload too large: downlink payloads are limited to 1024 bytes.

Error 502 - Bad Gateway

  • Device offline: the immediate downlink only works while the device is connected to the Particle Cloud. Queue it as a class A downlink instead (Option A).

No Data Received

  • Device ID mismatch: compare the Device ID on the Particle Console with the device serial on TagoIO.
  • Webhook throttled by Particle: when a webhook returns more errors than successes, the Particle Cloud starts skipping attempts and publishes a hook-error event reading “Sleeping, too many errors, please wait and try again”. Skipped events are retried twice and then dropped. Check the webhook logs in the Particle Console and fix the reported error.
  • Check the Live Inspector: open the Live Inspector while the device publishes to see the requests reaching TagoIO.

With data flowing into TagoIO, you can start creating Dashboards, Analyses, and Actions to visualize and manage your device data.