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

Each Thing 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.

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.

Parameter Update Feedback

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

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.

1. The user presses the Update button on a parameter.
2. The Servitly backend publishes the parameter value to the parameter topic.
3. The Thing receives the new parameter value.
4. The Thing applies the new parameter value internally.
5. The Thing publishes the feedback metric with the received value on the right topic.
6. The Servitly backend receives the new value of the feedback metric.
7. The Servitly backend verifies that the value received is the same as the value sent.
8. The Servitly backend notifies the UI or applies the retry policy.

To keep the user interface aligned with the remote Thing, it is a good idea to publish the feedback metric each time the parameter changes; this can also happen when the Thing is started, reset, or the operator does something on the Thing, 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, devices 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 Thing. Echo could be helpful to manage parameters that are asynchronously read by remote Things through other channels (e.g. REST API).