@vintecc/node-red-capture

Node-RED nodes for connecting to the Capture platform's MQTT broker — subscribe to live raw/uns data, and publish values back into a source's data/read tree.

Install

Via the Node-RED palette manager (Menu → Manage palette → Install), search for @vintecc/node-red-capture.

Or from the command line, inside your Node-RED user directory (usually ~/.node-red):

npm install @vintecc/node-red-capture

After installing, restart Node-RED. A new Capture category will appear in the palette with three nodes: capture-broker (config), capture-in and capture-out.

Nodes

| Node | Type | What it does | |---|---|---| | capture-broker | config | Holds the broker URL and credentials, shared by one or more capture-in/capture-out nodes. | | capture-in | input | Subscribes to Capture's raw or uns topic tree and emits a message per incoming value. | | capture-out | output | Publishes an incoming msg into a source's data/read tree. |

capture-broker

Config node with:

• Broker URL — e.g. mqtts://mqtt.captureplatform.com:8883.
• Username / Password — see Credentials below; which type you need depends on whether this broker is used for subscribing or publishing.
• Reject unauthorized — leave checked for any real Capture broker (production or dev); they present valid, publicly-trusted certificates. Only uncheck it for a broker with a self-signed certificate you can't otherwise validate.
• CA cert — optional PEM-encoded CA certificate, if the broker's certificate is signed by a private/internal CA not in the system trust store.

One broker config node holds one identity — if you need a subscriber and a publisher running at the same time, use two separate capture-broker nodes.

capture-in

Subscribes to live data. Has two modes:

• UNS — give a UNS path, e.g. AcmeCorp/Plant1/Line2 (or with a trailing /# to subscribe to everything below it). Topic: v1/uns/<path>.
• Raw — fill in Company (required, exact match), and optionally Source ID, Connection Tag, Measurement, Key. Leaving a field empty subscribes to everything below that level (#). Topic: v1/raw/<Company>/<SourceID>/<ConnectionTag>/<Measurement>/<Key>.

Use the Browse topics… button in the node's edit panel to explore the live topic tree under whatever prefix you've filled in so far, and click a node in the tree to fill in the rest of the path for you.

Output message:

• msg.payload — the value (Value field of the incoming Capture message).
• msg.tags — e.g. product, batch, line, site.
• msg.timestamp — the message's UtcTimestamp.
• msg.capture — the full original Capture payload, unmodified.

Example, for topic v1/raw/AcmeCorp/aaaaaaaa-…aaaa/PackML/Filler01/StateCurrent:

msg.payload:  <value of StateCurrent>
msg.tags:     { product: "Water-500ml", batch: "267", line: "Line1", … }

capture-out

Publishes the incoming msg into a source's data/read tree. Topic segments come from the message, not from node config:

• Single mode — one value per message. Topic: v1/sources/<msg.sourceId>/data/read/<msg.connectionTag>/<msg.measurement>/<msg.key>. Expected payload:

  { "Value": 55, "Tags": { "MachineName": "MyMachine" }, "UtcTimestamp": "2024-11-08T10:22:06.26Z" }

• Multiple mode — several fields per message, no key segment. Topic: v1/sources/<msg.sourceId>/data/read/<msg.connectionTag>/<msg.measurement>. Expected payload:

  { "Fields": { "CPU_Temp": 55, "CPU_Load": 23.4 }, "Tags": { "MachineName": "MyMachine" }, "UtcTimestamp": "2024-11-08T10:22:06.26Z" }

msg.payload is published unchanged — the node does not validate its contents. QoS (0/1/2) is configurable per node.

Credentials

Per Capture's MQTT docs, data/read can only be published to by a source/device account (credentials from that source's auth config in the Capture portal), not a regular user login — capture-out will get disconnected by the broker if used with the wrong credential type.

• capture-in (subscribe) — use a regular Capture user account (username/password), or a user API token as username with an empty password.
• capture-out (publish) — use the target device's own credentials: username is that device's ActivationUID, password is the one Capture generated for it (visible on the source's detail page, or via the config API's GetLoggerLicense). A user account, or a different device's credentials, will connect fine but get rejected the moment it tries to publish.

Troubleshooting

Hard-won lessons from getting this working end-to-end against a real Capture environment — read this before re-debugging from scratch.

"Connection refused: Not authorized" right at connect time. This is an auth/authorization rejection, not a network issue (per Capture's own docs: "if you get disconnected immediately after connecting, it is most likely an authorization issue"). Check, in order:

1. Is the capture-broker URL pointing at the right environment? A device created via one environment's config API (e.g. a dev broker) does not exist in a different environment's (e.g. production) user/device database — same credentials, different broker host, will get rejected outright.
2. Are the credentials actually the right type for this node (see Credentials above)?

Connects fine, publishes report success, but nothing ever shows up anywhere (not the device's "Last data package", not the raw topic tree, nothing). This is more subtle: at QoS 0, client.publish()'s callback fires the instant the packet hits the socket — the broker never has to acknowledge anything, so a broker-side rejection (wrong topic scope, bad routing, whatever) is completely invisible to the client. Don't trust a clean "Published" status alone. To actually confirm data landed:

• Subscribe directly to the equivalent v1/raw/<Company>/<SourceID>/<ConnectionTag>/<Measurement>/# topic with a user account and watch for the message to arrive there — this doesn't depend on any UNS mapping.
• Check the device's own info panel in the Capture portal for "Last data package"/"Last heartbeat" actually updating.
• If neither ever updates despite clean, error-free publishes, the issue is on the device/environment side, not in this code — try the same publish with an already-proven tool/device before assuming a bug here.

Two connections sharing the same credentials fight each other. Capture's broker appears to allow only one live session per identity. Two capture-in/capture-out nodes pointed at the same capture-broker config, or a second external client (MQTT Explorer, another tool) connecting with the same device's credentials at the same time, causes either visible reconnect-cycling or — more confusingly — one connection silently not having its publishes routed while it still reports "connected". If something that used to work suddenly stops, check for a second connection using the same identity first.

Data lands in the raw tree but not the UNS builder. These are independent. Raw is populated automatically from data/read publishes; UNS requires a separate, explicit one-time mapping of the measurement/fields to UNS variables in the portal's UNS builder. No data in raw either means something's wrong upstream of UNS entirely — check that before assuming a mapping problem.

Development

This repo can be run locally against a real Node-RED instance via Docker Compose:

docker compose up

Node-RED will be available at http://localhost:1880. The repo is mounted straight into Node-RED's node_modules, so the Capture category shows up in the palette on startup.

Changes to nodes/*.js/nodes/*.html need a container restart to be picked up:

docker compose restart

License

MIT