Turning a machine MQTT event into an API record with Node-RED

A cutting machine reports its state over MQTT. The production application accepts updates through an HTTP API. Both can exchange data, but that does not mean they agree on what a machine state represents. Node-RED is useful here as a bridge: receive one message, check its meaning, reshape it and send a request to the application. The difficult part is the agreement between the two systems, not drawing the connecting line.

An earlier article introduced Node-RED’s visual flow model. This time the scope is narrower: one machine state, one MQTT topic and one API endpoint. What must the bridge decide before anyone trusts the record it creates? A flow may be quick to assemble, but its correctness depends on the rules around the flow.

One event in two formats

Imagine a sheet metal shop where a cutting machine publishes RUN or STOP to shop/cutting/machine3/state. The production application expects a JSON object with a machine identifier, event type, time and source. The MQTT topic says which machine sent the message; the payload says something about its state. Neither is a complete API record on its own.

Begin with the machine identity. The bridge must parse the topic according to an agreed pattern, then map machine3 to an identifier that exists in the application. What if the topic contains unknown instead? Sending it under a default machine may seem convenient, but it creates convincing and incorrect history. Reject and record the unmapped case separately. A visible missing record is easier to investigate than an event assigned to the wrong asset.

Then define the state vocabulary. Does RUN mean parts are being made, or just that the control is enabled? Does STOP indicate a planned pause, a fault or waiting for material? The two values do not answer those questions. The bridge should map only the meaning the source actually supplies. If the application requires a fault reason, that information needs another source or a schema change. Filling the gap with a guessed reason turns a data-format problem into an operational mistake.

What belongs in the flow?

In Node-RED, an MQTT input node subscribes to a topic on a broker. The received msg.topic identifies the concrete topic, while msg.payload normally contains its value. A validation step checks that both fit the contract. Simple field mapping can use a Change node; a Function node can implement rules that need code. An HTTP Request node sends the resulting object to the API, and another step examines the response. This is a possible design, not a claim that every shop has the same connector or authentication setup.

Write down the accepted topic structure and allowed state values next to the flow. Write down the outgoing JSON fields and the API responses that count as accepted or rejected. Not every incoming message should become a request. Empty payloads, unknown assets and unexpected states need an explicit error path. That path can preserve the relevant original data and a reason for rejection without logging passwords, tokens or unrelated production details.

Time needs its own rule. If the machine sends only a state value, the bridge does not know when the transition happened at the control. It knows when it received the message. Calling that timestamp the event time may make delayed data look current. If the source supplies a timestamp, validate and retain it, and distinguish it from receipt time. If it does not, name the timestamp honestly. A shift report will rely on that distinction when a network interruption delays a message across the shift boundary.

A bridge has to fail deliberately

The easy demonstration is to run the broker and API while both are healthy. The more useful test begins when the API is unavailable. Dropping failed requests loses events. Retrying forever may create repeated records after service resumes. Decide which failures are retried, where pending messages live, and how a person notices when the queue cannot make progress. Those decisions are part of the integration, not optional polish after deployment.

If the machine supplies an event identifier, the destination can potentially reject a repeated request using source and identifier together. If every message contains only RUN, the bridge cannot reliably tell a delivery retry from a genuine second transition. MQTT delivery settings and the API’s idempotency behavior must be considered together. A visual flow cannot manufacture missing source identity. It can, however, make the ambiguity visible so that the production team does not mistake a duplicated event for an extra stop.

Persistence deserves the same scrutiny. A message held only in process memory may disappear when Node-RED restarts. If the shop needs guaranteed recovery from an outage, consider durable messaging and define retention explicitly. Which events may be replayed? For how long? What happens if the API has rejected a message because its machine identifier was retired? A retry policy without a rejection policy leaves the queue full of records that can never be accepted.

Prove the mapping on one machine

Start with one machine and two known states rather than subscribing to every shop topic. Send a valid test message, an unknown topic and an unsupported payload. Inspect the destination application: only the valid event should exist, under the right machine identity. Then make the API unavailable in a controlled test. Confirm that the failure appears in the bridge’s monitoring, and verify what happens after the API returns. Check for missing and duplicate records in the destination rather than assuming that a successful retry log means the correct record was stored.

Finally, send a delayed message after simulating a disconnected source. If source and receipt times are recorded separately, someone reading the event can tell that the data arrived late. If the machine supplies no source time, document the limit instead of presenting the sequence as certain. Run these tests with a production lead as well as a developer; the lead can say whether a state has been interpreted correctly, while the developer can check transport and error behavior.

Node-RED does not replace the machine controller, ERP or MES in this arrangement. Its job is to translate a narrow interface boundary under rules that people can inspect and test. The bridge is ready only when it rejects wrong input, exposes failures and creates the intended record at the destination, not merely when a line between two nodes turns green.

Sources: Luke van Enkhuizen’s overview of open-source tools for metal fabricators, Node-RED concepts, working with messages and message design. The shop example is hypothetical.