Read and write configuration parameters, and report changes made on the device.
Configuration API are used to allow Things5 users to read and write configuration parameters (like set-points, durations, ...) from the device.
The other way around is also possible: the device can let Things5 know when parameters have changed using [Pub]Variables changed request
When the user goes to Device>Configuration the [Sub] Parameters read request will be sent to the device. When the user set his new parameters from the UI, the [Sub] Parameters write request will be sent to the device.
The main parameters of the communication are:
| field | type | description |
|---|---|---|
| name | string | name of the variable |
| type | string | variable type. Value can be "string", "integer", "float" |
| Topic | Direction |
|---|---|
things5-production/v1/devices/{device_id}/cmd/read_variables_req | Things5 → device |
things5-production/v1/devices/{device_id}/cmd/read_variables_res | Device → Things5 |
things5-production/v1/devices/{device_id}/cmd/write_variables_req | Things5 → device |
things5-production/v1/devices/{device_id}/cmd/write_variables_res | Device → Things5 |
things5-production/v1/devices/{device_id}/event/variables_changed_req | Device → Things5 |
things5-production/v1/devices/{device_id}/event/variables_changed_res | Things5 → device |
Things5 → device: cmd/read_variables_req
cmd/read_variables_reqSubscribe to this topic to receive read variables requests.
Publish on read variables response to send the requested variables.
things5-production/v1/devices/<device-id>/cmd/read_variables_req
Payload
{
"request_id": "UUID",
"assets": ["configuration"],
"filters": {
"configuration": ["var_a","var_b"]
}
}
Payload Parameters
| type | description | example |
|---|---|---|
| request_id | the request id to be sent back by the device when sending the response | |
| assets | list of requested variables. Can be "configuration", "states", "metrics" | ["configuration", "states"] |
| filters (optional) | an object with the list of fields to request per each asset |
Expected response
Response has to be sent into the read variables response:
Device → Things5: cmd/read_variables_res
cmd/read_variables_resthings5-production/v1/devices/<device-id>/cmd/read_variables_res
Success payload
{
"request_id": "UUID sent in the request",
"assets": [{
"name": "configuration",
"values": [{
"name": "minimum_setpoint",
"value": "-20",
"type": "integer"
}, {
"name": "power_on_delay",
"value": "30",
"type": "integer"
}, {
"name": "temperature_hysteresis",
"value": "10.4",
"type": "float"
}, {
"name": "appliance_type",
"value": "visup_v2.3.0-beta",
"type": "string"
}]
}]
}
{
"request_id": "UUID sent in the request",
"assets": [{
"name": "metrics",
"values": [{
"name": "cabinet_probe",
"value": "-10",
"type": "integer"
}]
}]
}
{
"request_id": "UUID sent in the request",
"assets": [{
"name": "states",
"values": [{
"name": "door",
"value": "open",
"type": "string"
}]
}]
}
{
"request_id": "UUID sent in the request",
"errors": [
"invalid request"
]
}
Thee UUID in the response must match the one in the request; if the UUID in the response does not match any request the message will be discarded.
Things5 → device: cmd/write_variables_req
cmd/write_variables_reqSubscribe to this topic to accept write variables requests. Only configuration variables can be written.
Publish on write variables response to send the requested variables.
things5-production/v1/devices/<device-id>/cmd/write_variables_req
Payload
{
"request_id": "UUID sent in the request",
"assets": [{
"name": "configuration",
"values": [{
"name": "minimum_setpoint",
"value": "-20",
"type": "integer"
}, {
"name": "power_on_delay",
"value": "30",
"type": "integer"
}, {
"name": "temperature_hysteresis",
"value": "10.4",
"type": "float"
}, {
"name": "appliance_type",
"value": "visup_v2.3.0-beta",
"type": "string"
}]
}]
}
Payload Parameters
| name | description | example |
|---|---|---|
| request_id | the request id to be sent back by the device when sending the response | |
| assets | list of assets to write. Currently only configuration assets can be written |
: Response has to be sent into the write variables response:
Device → Things5: cmd/write_variables_res
cmd/write_variables_resthings5-production/v1/devices/<device-id>/cmd/write_variables_res
Success payload
The assets variables with their updated value
{
"request_id": "UUID sent in the request",
"assets": [{
"name": "configuration",
"values": [{
"name": "minimum_setpoint",
"value": "-20",
"type": "integer"
}, {
"name": "power_on_delay",
"value": "30",
"type": "integer"
}, {
"name": "temperature_hysteresis",
"value": "10.4",
"type": "float"
}, {
"name": "appliance_type",
"value": "visup_v2.3.0-beta",
"type": "string"
}]
}]
}
Asset error payload Representation
It is possibile to set errors for one or more asset fields if values are invalid
{
"request_id": "UUID sent in the request",
"assets": [
{
"name": "configuration",
"values": [
{
"name": "minimum_setpoint",
"value": "-20",
"type": "integer",
"errors": [
"variable error message if any",
"other variable error message if any"
]
},
{
"name": "power_on_delay",
"value": "30",
"type": "integer"
},
{
"name": "temperature_hysteresis",
"value": "10.4",
"type": "float"
},
{
"name": "appliance_type",
"value": "visup_v2.3.0-beta",
"type": "string"
}
]
}
],
"errors": [
"service error message if any",
"other service error message if any"
]
}
Generic error payload Representation
{
"request_id": "UUID sent in the request",
"errors": [
"invalid request"
]
}
Device → Things5: event/variables_changed_req
event/variables_changed_reqUse this topic to let Things5 know when variables have been changed directly on the device. This applies only to configuration variables. A response will be published by things5 on variables changed response
things5-production/v1/devices/<device-id>/event/variables_changed_req
Payload
{
"request_id": "generate a UUID that will be used for the response",
"assets": [{
"name": "configuration",
"values": [{
"name": "minimum_setpoint",
"value": "-20",
"type": "integer"
}, {
"name": "power_on_delay",
"value": "30",
"type": "integer"
}, {
"name": "temperature_hysteresis",
"value": "10.4",
"type": "float"
}, {
"name": "appliance_type",
"value": "visup_v2.3.0-beta",
"type": "string"
}]
}]
}
Payload Parameters
| name | description | example |
|---|---|---|
| request_id | the request id to be sent back by things5 when sending the response | |
| assets | list of assets to write. Currently only configuration assets can be written |
Response has to be sent into the write variables response:
Things5 → device: event/variables_changed_res
event/variables_changed_resListen for messages to this topic for a confirmation that Things5 have correclty processed the variables changed request variables changed request
things5-production/v1/devices/<device-id>/event/variables_changed_res
Payload
{
"request_id": "UUID generated by the request",
"errors": []
}
Payload Parameters
| name | description | example |
|---|---|---|
| request_id | the request id to be sent back by things5 when sending the response | |
| errors | list of errors. If empty no errors have occurred. | ["unexpected error"] |
Device commands
The commands defined on the device model (Device commands) reach the device as a parameters write request: they are a predefined set of values to write.