Write parameter values from a dashboard

This guide adds writes to a dashboard you develop locally. The write API is described in Live data in dashboards, and the write controls in Dashboard UI and forms. Writing needs the operator role or higher.

Offer a write only where it can succeed

1. Check the parameter’s metadata with isParameterValueWritable(parameter) before you offer an edit or a command.
2. Offer the edit only while the value it changes is current (isCurrentParameterValue).
3. Offer a command only while the device will act on it. To turn a command off while the device is disconnected, pass disabled and keep the control mounted, so a command already being sent still reports its result.

Choose one write model per editor

Pick one model for every control in an editor. Do not mix them.

• Drafts and Apply, usual for device editors with several fields: fields stay uncommitted until Apply sends the changed fields. Live tiles keep showing the device’s values from reads, not the drafts.
• Immediate write: every control writes when it changes. The editor then has no Apply or submit button.

Send confirmed changes in one batch

1. Collect the fields the operator confirmed and send them with one writeValues call from useParameterValueActions(). It follows the writes with a targeted read.
2. Before a change of several fields, open a confirmation dialog that lists only the changed fields as old value to new value. ParameterWriteReviewDialog does this and returns the keys of the failed changes; mark the matching form fields with them.
3. Handle each output.results[paramId] separately. Writes are not a transaction:
   • Commit the successful fields at once.
   • Keep the failed drafts and show each error on its field.
   • Do not roll back successful siblings.
   • Show a failure of the whole request in the form banner.
   • Show each failure where the operator is looking, inside an open confirmation too. Let the operator cancel or try again, even if trying again means reopening the dialog. Cancelling must not make the failed write look applied. The write controls already do this.
4. Keep the operator’s unsaved drafts while new readings arrive.
5. Show write errors inline, in the dashboard’s language, built from code and reason (such as write_value_below_min). Never show the English message. A success toast is optional.
6. A write acknowledgement is not the device’s physical result. Where the device has a feedback parameter, read it before you tell the operator that the command took effect.

When the fields are part of a form that saves through the API, build it as described in Build a form that saves through the API.

Write in a fixed order

One writeValues batch does not guarantee the order in which the device applies the writes. When a device needs an order, such as a password before a command:

1. Use ParameterWriteSequenceDialog. It writes one step at a time, stops at the first step that is not acknowledged, and names that step.
2. For a single command button, use DeviceCommandButton, which wraps the dialog.
3. For a section of device settings, use DeviceSettingsSection with a write plan; see Build a dashboard for one device model.
4. When a step’s value must be current at the time of writing, such as a clock set to the time of sending, pass steps as a function.

With your own interface on executeParameterWriteSequence, check permissions and ask for confirmation yourself; the function does neither.

Ask for a device password

1. Pass secret to ParameterWriteSequenceDialog, or unlock to DeviceCommandButton or DeviceSettingsSection. The dialog shows a masked field and writes the typed password in a step before the others, without reading it back.
2. When the device may already be unlocked on HMI’s connection, set optional.
3. To offer the last password that worked while the page is open, keep it in component state from onSent and pass it back as initialValue.
4. Never put a password in steps, in the dashboard configuration, or in browser storage.

Write without an operator action

A dashboard can call writeValues from its own code when readings change, with nobody pressing anything. For example, it starts a pump when the tank level reaches a start mark, stops it at a stop mark, or sends a controller a stricter start limit while a temperature is too high. This code runs only while the dashboard is open in a browser.

Each such command depends on some readings: the start condition, such as a level or a temperature, and the equipment’s own feedback, such as a running relay.

1. Check those readings per command with isCurrentParameterValue or a reader with { current: true }. Treat a null from evaluateParameterCondition as unknown, not as false.
2. Decide for each command what it does when one of its readings is not current:
   • A reading that is not current never starts equipment.
   • It does not block the writes that make equipment safer, or stops whose own readings are current.
3. Do not use a single check that skips every write unless all readings are current. It breaks the second rule: if the temperature stops updating, the stricter start limit is never sent and the controller keeps the looser one, and a second pump with a current level and relay reading never gets its normal stop.
4. Keep equipment protection in the controller. Closing the dashboard stops these commands without sending a final stop, and limits already written stay on the controller.

Test automatic writes

1. Run the code with made-up readings and record the writes it requests instead of sending them.
2. Compare those writes with the ones you expect in each of these cases:
   • a start condition reading goes stale, is still loading, fails, or is missing;
   • another pump reaches its stop mark meanwhile;
   • a reading equals a start or stop mark exactly;
   • readings recover;
   • manual mode, where nothing is written automatically;
   • after the dashboard closes, when nothing more is written.

Related

• Dashboard UI and forms
• Live data in dashboards
• Show live values in a dashboard