Receiving Commands
Comandos
Flujo básico de integración de comandos
El gateway, dispositivo o endpoint deberá estar escuchando por comandos suscribiendose al siguiente topic:
**{client-secure-id}/commands/requests/{device-address}**
- cliente-secure-id: es el usuario utilizado en la conexión. La estructura de topics incluye el id de usuario como primer elemento, dado que cada usuario tiene permiso únicamente para los topics que comiencen con ese ID.
- device-address: Es el ingresado en el campo “address” al crear el dispositivo.
Esta respuesta deberá ser interpretada por el dispositivo, realizar las acciones correspondientes y responder a través del método de respuesta de comandos para informar si la ejecución del mismo fue correcta o no.
En caso de ser correcta, se deberá ejecutar el método para actualizar el estado del dispositivo según corresponda.
Por último, asegurarse de seguir escuchando comandos con el primer método mencionado.
1. Esperar por comandos
Para que un dispositivo esté escuchando por comandos debe suscribirse al topic: {client-secure-id}/commands/requests/{device-address}
- cliente-secure-id: es el usuario utilizado en la conexión. La estructura de topics incluye el id de usuario como primer elemento, dado que cada usuario tiene permiso únicamente para los topics que comiencen con ese ID. Este valor se puede consultar en la sección de seguridad > configuración MQTT
- device-address: Es el ingresado en el campo “address” al crear el dispositivo. Si es un dispositivo ya creado, este valor se puede obtener desde el listado:
Respuesta
La respuesta es una lista dentro de la propiedad WaitForCommand_EndpointResult que tendrá cada uno de los comandos correspondientes:
{
"Closure":null,
"CommandID":1120907993,
"CommandType":1,
"Custom":null,
"DeviceID":7246,
"Dimmer":null,
"EndpointID":113139,
"Management":null,
"OnOff":{
"AutomaticOverrideMinutes":0,
"CommandType":0
},
"Thermostat":null
}Para mas información acerca de las propiedades de la respuesta ver la documentación
Según el tipo de comando que se haya ejecutado, se deberá tener en cuenta la propiedad correspondiente para conocer la acción a realizar.
Por ejemplo, si el CommandType es 1, quiere decir que es un comando para un endpoint tipo "Appliance". Por lo que se deberá tener en cuenta lo que se informe en la propiedad OnOff
Los distintos command types se pueden ver en esta documentación.
2. Responder un comando
En caso de haber recibido un comando y luego de ejecutar las acciones correspondientes en el dispositivo(hardware) se deberá responder el comando ya sea en caso de éxito o error.
Para informar que el comando ha sido ejecutado, se debe hacer un publish al topic {client-secure-id}/HttpApi/DeviceIntegration con el siguiente payload:
{
"accessToken":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"mqttMethod":"RespondCommand",
"mqttRID":"c392",
"response":{
"CommandID":1120907993,
"ResponseType":0,
"ResponseData":"ok",
"ErrorCode":"1",
"ErrorMessage":""
}
}Descripción de los campos del payload:
| Name | Description | Data Type |
|---|---|---|
| accessToken | Access token with permissions to update endpoint information. See this page for more information. | text |
| mqttMethod | Método correspondiente del servicio. Para comandos debe ser siempre RespondCommand | string |
| mqttRID | Identificador opcional para la petición, en caso de que se desee obtener una respuesta de confirmación. | string |
| response | Objeto con la respuesta del comando | object |
Descripción de los campos del sub objeto “response”:
| Name | Description | Data Type |
|---|---|---|
| CommandID | Debe corresponder al obtenido en la suscripción del topic {client-secure-id}/HttpApi/DeviceIntegration (paso 1). | integer |
| ResponseType | Debe ser alguno de los del enum, según corresponda. En este caso es 0, que significa "success". | integer |
| ResponseData | Texto informativo acerca del comando | string |
| ErrorCode | Código de error, solo válido si ResponseType es Error. | string |
| ErrorMessage | Mensaje de error, solo válido si ResponseType es Error. | string |
Para mas información acerca del objeto “response” ver la documentación.
3. Actualizar estado del endpoint
En caso de que la ejecución del comando haya sido exitosa, se deberá informar el nuevo estado del endpoint. Para esto se deberá utilizar el método correspondiente al tipo de endpoint (ver “Integración por tipo de sensor”).
Siguiendo el ejemplo de appliance, se debe hacer un publish al topic {client-secure-id}/HttpApi/DeviceIntegration con el siguiente payload:
{
"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"endpointID": 113139,
"isOn": true,
"mqttMethod": "UpdateApplianceStatus",
"mqttRID": "tkrs34"
}Para más información acerca de este método ver la sección de artefactos on/off