Parameters and commands messages are sent in the same way as for metrics, but in this case the direction is from cloud to the product (Thing).

Each product must subscribe to a specific topic to receive parameter updates or command execution requests from the cloud. 

Here below, you can find sample MQTT messages for parameters and commands:

Parameter Update

TOPIC: <username>/<thing-mapping-asset-id>(/<thing-mapping-path>)?/<parameter-mapping-path>
MESSAGE:
{
  "ts": 1687528337000,
  "data": {
        "<parameter-mapping-name>": 123
  }
}

Data property values can be strings, numbers, or boolean encoded by using the standard JSON data encoding (same as for publishing).

Command Execution

TOPIC: <username>/<thing-mapping-asset-id>(/<thing-mapping-path>)?/<command-mapping-path> 
MESSAGE:
{
  "ts": 1687528337000,
  "data": {
        "<command-parameter-1>": "123",
        "<command-parameter-2>": 567,
        "<command-parameter-n>": true
  }
}

Data property values can be strings, numbers, or boolean encoded by using the standard JSON data encoding (same as for publishing).

Parameter Update Feedback

Due to the limitations of the MQTT protocol, and the number of software and hardware elements that lie between the UI and the connected product, when updating configuration parameters, to allow Servitly detects whether the new parameter value has been correctly received, it is a good practice to resend the parameter value as a metric once the new value has been received and applied internally by the product.

In this way, the Servitly backend can check, within a specific timeout, whether the feedback metric associated with the parameter has been updated with the newly sent value. Based on the presence of a new value, the Servitly backend can inform the user through the UI or manage the retry policy, if configured.

Here is described the parameter update flow:

1. The user presses the Update button on a parameter.
2. The Servitly backend publishes the parameter value to the parameter topic.
3. The remote product receives the new parameter value.
4. The remote product applies the new parameter value internally (e.g. a register is updated).
5. The remote product publishes the feedback metric with the received parameter value.
6. The Servitly backend receives a new value for the feedback metric.
7. The Servitly backend verifies that the received value is the same as the value previously sent.
8. The Servitly backend notifies the UI or applies the retry policy (in case of mismatch).

To keep the user interface aligned with the connected product, it is a good idea to publish the feedback metric each time the parameter changes; this can also happen when the product is started, reset, or the operator does something on it, for instance, presses a button, moves a lever, turns a knob.

Value Retention

Optionally, on the parameter, you can set this flag:

[] When connecting to the cloud, the thing is notified with the latest parameter value

If checked, products that are not always connected, are automatically notified with the last parameter value when they establish the connection with the MQTT broker. 

Publishing Echo

Normally, the parameter and the associated feedback metric must use different mapping paths. If they use the same mapping, when the parameter is published on the cloud side, the value is immediately sent back by the MQTT broker, and this causes an echo. In this case, the backend cannot determine whether the parameter is correctly received by the remote product. Echo could be helpful to manage parameters that are asynchronously read by remote product through other channels (e.g. REST API), or leveraging the value retention.