Send a downlink

A downlink sends information toward a device or an HTTP destination. Open a device and choose its Downlinks tab to create reusable command definitions.

A definition contains a name, an MQTT or HTTP transport, selected device inputs and outputs, default output values, and JavaScript encoder source. The encoder turns the device context into the final request.

Create and test a definition

Choose the transport

Choose MQTT to publish through the device’s configured broker, or HTTP to call a public HTTP endpoint.

MQTT encoder output contains topic, payload, and optional qos and retain values. HERAIOT scopes the topic under the tenant’s devices prefix and rejects MQTT wildcards.
HTTP encoder output contains the URL and request options. Private and reserved network destinations are blocked, redirects are not followed, and the request times out after 10 seconds.

Select the data available to the encoder

Select the device inputs and outputs the command needs. Input values come from the latest measurement unless the run supplies an override. Outputs use the values entered for the run, saved defaults, or the latest value in that order.

If Trigger on measurements is enabled, at least one input and output must be selected and every selected output needs a default value.

Write the encoder

The encoder receives device, measurements, outputs, and console. It must define Encoder(...) and return the request object expected by the chosen transport. Keep it focused on building data: network and process APIs are blocked, source size is limited, and execution has a short timeout.

Preview without sending

Use Test to inspect resolved inputs and outputs, encoder console output, and the final request. The response is marked as a dry run; it does not publish to MQTT or call the endpoint.

Save the definition

Saving validates the encoder with the selected fields. If someone changed the same definition after you opened it, refresh the page before applying your changes.

Run a command

Choose Run, review or override its output values, preview the generated request, then execute. Each run records its source, request preview, response preview, status, duration, console output, and error details. Reusing the same idempotency key returns the existing execution instead of sending it twice.

A successful MQTT publish means the broker accepted the message. A successful HTTP result means the endpoint responded. Neither proves that physical equipment changed state. Verify the device’s next state report before treating a command as applied.

That distinction matters for commands that open a valve, start a motor, or change a setpoint. Build confirmation into the operating procedure.

Trigger on measurements

When enabled, a new event triggers the downlink only when its payload contains one of the definition’s selected input names. HERAIOT uses the incoming values, fills remaining selected inputs from the latest event, applies output defaults, and records the run as a measurement-triggered execution.

Test the exact encoder and destination manually first. A new matching event is a new execution, so make the receiving operation safe to repeat when devices report frequently.

Automatic execution has no final confirmation screen. Keep it disabled until the preview and a manual run are correct, especially for physical actions.

Use a downlink in a rule

A measurement rule can run a saved single-device MQTT downlink. Create and test the definition here first, then select it in the rule’s action. Rule-driven HTTP and bulk downlinks are not currently executed by the worker. See Rules and actions.

Troubleshooting

Symptom	Check
Encoder test fails	Required return fields, selected inputs/outputs, source size and blocked APIs
MQTT run fails	Device broker, generated topic, payload and QoS
HTTP run fails	Public DNS target, method, headers, body, timeout and response status
Trigger never runs	Trigger enabled, payload contains a selected input, defaults exist
Run succeeds but device does not react	Device subscription, payload contract, and next state report

See MQTT connections for broker and topic setup.