Particle

​

Overview

• ParticleRestApi (https://api.particle.io) lets the Coreflux broker read a machine value from a device, call a function to change a setpoint, broadcast an event to devices, check device vitals and SIM data usage, follow trackers on a map, and push setpoints to devices through a Cloud to Device ledger.
• ParticleWebhookReceiver (cloud-iot_particle_webhook.lot, opt-in, server mode) receives Particle webhooks so device events reach MQTT without polling.

​

Authentication

• A user token is the quickest start: particle token create (valid 90 days unless you pass --expires-in). It can do anything your account can.
• For unattended plant use, create a product or organization API user with only the scopes its events need, for example devices:list, devices.variable:get, devices.function:call, events:send, integrations:create, ledger.instances:get and ledger.instances:set. An API user has one token at a time and must use the product (/v1/products/...) or organization (/v1/orgs/...) events.

​

Basic Syntax

DEFINE ROUTE ParticleRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.particle.io"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetVariable
        WITH SOURCE_TOPIC "cloud-iot/particle/device-variable/get"
        WITH DESTINATION_TOPIC "cloud-iot/particle/device-variable/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/devices/{value.json.device_id}/{value.json.variable_name}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CallFunction
        WITH SOURCE_TOPIC "cloud-iot/particle/device-function/call"
        WITH DESTINATION_TOPIC "cloud-iot/particle/device-function/call/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/devices/{value.json.device_id}/{value.json.function_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT PublishEvent
        WITH SOURCE_TOPIC "cloud-iot/particle/event/publish"
        WITH DESTINATION_TOPIC "cloud-iot/particle/event/publish/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/devices/events"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"

​

MQTT examples

{
  "access_token": "<Particle access token>",
  "device_id": "0123456789abcdef01234567",
  "variable_name": "temperature",
  "query": ""
}

{
  "access_token": "<Particle access token>",
  "device_id": "0123456789abcdef01234567",
  "function_name": "setSpeed",
  "body": { "arg": "1200" }
}

{
  "access_token": "<Particle access token>",
  "body": { "name": "coreflux/line-porto-1/shift", "data": "{\"shift\":\"B\",\"target\":1200}", "ttl": 60 }
}

{
  "access_token": "<Particle access token>",
  "ledger_name": "line-setpoints",
  "scope_value": "0123456789abcdef01234567",
  "query": "set_mode=Merge",
  "body": { "instance": { "data": { "speed_rpm": 1200, "recipe": "R-42" } } }
}

​

Receive Particle events (webhook receiver)

DEFINE ROUTE ParticleWebhookReceiver WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '9001'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT WebhookTelemetry
        WITH ENDPOINT "/particle/webhook/telemetry"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cloud-iot/particle/webhook-telemetry/received"
    ADD EVENT WebhookEvents
        WITH ENDPOINT "/particle/webhook/events"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cloud-iot/particle/webhook-event/received"

{
  "access_token": "<Particle access token>",
  "body": {
    "integration_type": "Webhook",
    "event": "telemetry",
    "url": "https://broker.example.com/particle/webhook/telemetry",
    "requestType": "POST",
    "noDefaults": true,
    "json": {
      "event": "{{{PARTICLE_EVENT_NAME}}}",
      "data": "{{{PARTICLE_EVENT_VALUE}}}",
      "coreid": "{{{PARTICLE_DEVICE_ID}}}",
      "published_at": "{{{PARTICLE_PUBLISHED_AT}}}"
    },
    "headers": { "Authorization": "Bearer <receiver secret>" }
  }
}

1. Deploying the receiver opens HTTP port 9001 on the broker.
2. Particle delivers from its cloud to a public URL. Put a reverse proxy or tunnel with a public TLS certificate in front of port 9001 and forward /particle/webhook/....
3. Accept only Particle. The connector does not check secrets itself: let the proxy check the Authorization header you set on the webhook (or Basic auth, or a Particle cloud secret inserted with {{{SECRET_NAME}}}).
4. Use the JSON request format. The default Web Form format arrives URL-encoded.
5. Answer fast: Particle waits 20 seconds and throttles a webhook whose target fails or times out too often.
6. data is the string the device published (often JSON text): parse it in a LoT action. Retries can repeat a delivery, so deduplicate on coreid + published_at.

​

Helper actions

DEFINE ACTION ParticleSetLineSpeed
ON TOPIC "porto/line-1/speed/set" DO
    SET "tok" WITH GET SECRET "PARTICLE_ACCESS_TOKEN"
    SET "dev" WITH GET SECRET "PARTICLE_DEVICE_ID"
    SET "rpm" WITH GET JSON "rpm" IN PAYLOAD AS STRING
    PUBLISH TOPIC "cloud-iot/particle/device-function/call" WITH { "access_token": {tok}, "device_id": {dev}, "function_name": "setSpeed", "body": { "arg": {rpm} } }

DEFINE ACTION ParticlePollTemperature
ON EVERY 1 MINUTE DO
    SET "tok" WITH GET SECRET "PARTICLE_ACCESS_TOKEN"
    SET "dev" WITH GET SECRET "PARTICLE_DEVICE_ID"
    PUBLISH TOPIC "cloud-iot/particle/device-variable/get" WITH { "access_token": {tok}, "device_id": {dev}, "variable_name": "temperature", "query": "" }

DEFINE ACTION ParticleWebhookToPlant
ON TOPIC "cloud-iot/particle/webhook-telemetry/received" DO
    SET "dev" WITH (GET JSON "coreid" IN PAYLOAD AS STRING)
    SET "data" WITH (GET JSON "data" IN PAYLOAD AS STRING)
    PUBLISH TOPIC "plant/particle/" + {dev} + "/telemetry" WITH {data}

​

Notes

• Rate limits: 10,000 API requests every 5 minutes per public IP address; a 429 means slow down (retrying at once does not help). The serial-number lookup and the event streams have stricter limits. Polling many variables quickly hits the limit and costs data operations on cellular devices; prefer events plus the webhook receiver.
• Errors come back on the response topic: 400 (bad request, or the variable / function is not exposed), 401 (token invalid or expired), 403 (token not allowed for this device or product), 404 (device offline or unknown), 408 (the device did not answer in time), 429, 5xx.
• Ledger: names are lowercase letters, digits and dashes, up to 32 characters. Device-synced ledgers hold up to 16 KB of JSON, cloud-only ledgers up to 1 MB. Device to Cloud and Cloud to Device ledgers need Device OS 6.1.0 or later. The API reference lists the set body as {"data": ...}; the official JavaScript SDK sends {"instance": {"data": ...}} with set_mode. This template passes the body through unchanged, so either form can be sent.
• Not packaged: Server-Sent Event streams (GET /v1/devices/events/..., product and organization streams) because a REST_API connector cannot hold a stream open (use the webhook receiver instead), every DELETE (unclaim, remove from product, delete ledger instance, delete integration), firmware flashing and compiling, claiming and importing devices, SIM activation, customers, groups, Logic functions, environment variables, cloud secrets and OAuth clients.
• Only the global host https://api.particle.io is documented (TLS 1.2 or later).

​

Related

• REST API Connectors
• REST API app templates
• Losant
• balena