@mmeisterhans/node-red-contrib-particle-cloud 0.2.0

Rewrite of the abandoned official Particle nodes for Node-RED 5 and current Particle Cloud APIs

npm install @mmeisterhans/node-red-contrib-particle-cloud

@mmeisterhans/node-red-contrib-particle-cloud

A rewrite of the abandoned official Particle nodes for Node-RED 5 and current Particle Cloud APIs. The nodes use device-model-independent Cloud interfaces and distinct particle-cloud-* type IDs, so this package can coexist with the original package during migration.

What Changed From the Official Nodes

This package rewrites the abandoned official nodes with a current runtime and a clearer configuration model:

• Current runtime support: Node.js 22.9 through 24.x (Node.js 24 LTS recommended), Node-RED 5, and particle-api-js 12.
• Safer authentication: Access-token authentication is recommended, secrets use the Node-RED credential store, and Particle Two-Legged Auth clients can create and renew client-owner access tokens automatically.
• Startup resilience: Authentication failures are handled as node errors when a node connects or runs; they do not crash Node-RED during startup.
• Reliable event streams: Subscribe nodes own independent streams with bounded reconnect backoff and clean shutdown handling.
• Correct and secure requests: false and 0 values are preserved, modern Node-RED callbacks are supported, and generic API requests cannot send credentials to external hosts or redirects.
• Broad device compatibility: The nodes use Particle Cloud interfaces shared by Particle devices without device-specific runtime behavior.

Requirements

• Node.js >=22.9 <25 (Node.js 24 LTS recommended)
• Node-RED 5.x
• A Particle Cloud access token or an OAuth client configured as Two-Legged Auth (Server)

Install

Back up your flows and credentials before installing this package:

cd ~/.node-red
npm install @mmeisterhans/node-red-contrib-particle-cloud

To install the current Git revision instead of the npm release:

cd ~/.node-red
npm install github:mmeisterhans/node-red-contrib-particle-cloud

For local development, clone this repository, run npm ci, and install its path from the Node-RED user directory:

cd ~/.node-red
npm install /absolute/path/to/node-red-contrib-particle-cloud

After any install, npm audits the entire ~/.node-red dependency tree. Reported vulnerabilities may therefore come from other installed nodes rather than this package. Run npm audit --omit=dev in this repository to check this package's runtime dependencies.

Restart Node-RED after installation. Flows from the abandoned official package are not automatically migrated because its routing and credential schemas differ. Recreate those nodes with the particle-cloud-* nodes and re-enter secrets through the Node-RED credential editor.

Update

For an npm installation, update from the Node-RED user directory:

cd ~/.node-red
npm install @mmeisterhans/node-red-contrib-particle-cloud@latest

For a Git installation, pull the desired revision and reinstall it from ~/.node-red. For a local clone:

git pull --ff-only
npm ci
cd ~/.node-red
npm install /absolute/path/to/node-red-contrib-particle-cloud

Review CHANGELOG.md before updating. Maintainers should follow MAINTAINING.md.

Authentication

Create a particle-cloud-config node and choose one mode:

• Access token (recommended): Store a Particle access token in Node-RED credentials. Product integrations should use a least-privilege API-user token where possible.
• Two-Legged Auth (Server): Store the ID and secret of an OAuth client created as Two-Legged Auth (Server). The nodes exchange these credentials for a client-owner access token and manage that token automatically. Create the client from the Authentication page for the Particle user or product whose resources it should access. Your Particle role must permit OAuth client creation.

Particle access tokens differ by identity and scope:

• A human user token, such as one created by particle token create, can access the Sandbox, products, and organizations that the human user is authorized to access.
• An API-user token is scoped to one product or one actual Particle organization. Particle does not provide a personal-account-wide or Sandbox-scoped API user.
• An organization-scoped API user applies only to that organization and requires organization administrator access; it does not cover the user's Sandbox or unrelated organizations.

Authentication and endpoint selection are independent. Use Particle's User endpoint and Product endpoint terminology as follows:

The endpoint selects the Particle Cloud API route, not the authentication method. In particular, an API-user token must use the Product endpoint to subscribe to the matching product's event stream.

For a least-privilege API-user token, grant only the scopes required by the nodes in the flow:

Grant the first four scopes to support all operation-specific nodes. These scope names apply to API users; human user tokens and product bearer tokens derive access from their owning user or OAuth client instead.

A Two-Legged Auth client can be created on behalf of a Particle user or a Particle product. A user-owned client is intended for devices claimed by that user. A product-owned client produces a product bearer token restricted to that product; use it with the Product endpoint and select the same product. Access to Sandbox, product, or organization resources otherwise depends on the client owner and the client's configured scopes. The Two-Legged Auth (Server) client type does not by itself determine resource scope or endpoint selection.

The nodes never refresh or revoke a configured access token. For Two-Legged Auth, they replace the generated client-owner token before it expires, revoke replaced tokens, and revoke the current generated token during node shutdown. See Particle's OAuth documentation, access token documentation, and product authentication documentation.

Client secrets and access tokens are stored only in Node-RED credentials and should never appear in exported flows.

Nodes

Configured node values take precedence over message fields. Publish data and function arguments serialize objects and arrays as JSON and convert other non-string values to strings. Each operation selects either the User endpoint (/v1/devices/...) or the Product endpoint (/v1/products/:productIdOrSlug/...). These names describe the API route, not the credential scope: a User endpoint is not necessarily limited to Sandbox devices. Product endpoints require a product ID or slug; the selected credential determines whether Particle authorizes the request.

For particle-cloud-api, configure a relative API path and method or supply them as msg.url and msg.method. Optional msg.query values become query parameters, msg.headers adds non-authentication request headers, and msg.payload supplies a JSON or text body for methods other than GET. Responses set msg.statusCode and decode JSON into msg.payload; text and CSV remain strings, and empty responses produce an empty string. Absolute URLs, redirects, path traversal, authentication-header overrides, binary responses, event streams, and multipart file transfers are rejected. Use the operation-specific Subscribe node for Particle event streams.

Import examples/particle-cloud-flow.json for publish, subscribe, function, variable, and API manual tests. After import, configure the Particle credentials node and replace REPLACE_WITH_PRODUCT_ID_OR_SLUG and REPLACE_WITH_DEVICE_ID. Flash examples/photon2-cloud-smoke/photon2-cloud-smoke.ino to run the nrSetState function and nrState variable tests. Example files contain no credentials.

Device Compatibility

These nodes are designed to work with any Particle device that connects to the Particle Cloud and supports the configured Cloud feature, such as events, functions, or variables. They do not depend on device pins, processor architecture, or board-specific firmware APIs.

The optional Photon 2 smoke test in examples/photon2-cloud-smoke/photon2-cloud-smoke.ino exposes a test event, function, and variable without relying on board-specific pins.

Troubleshooting

• Authentication errors: verify the token or OAuth client credentials and their permissions.
• No events: event filters use prefix matching; verify the device is online and publishing private events to the selected endpoint.
• Rate limits: check Particle's current Cloud API limits.
• Missing nodes after updating from 0.1.0: replace the previous particle-* type IDs with the corresponding particle-cloud-* nodes and redeploy.

Development

npm ci
npm run check

npm run check lints, tests, audits production dependencies, and inspects the package tarball. It does not publish, tag, or create a release.