Recepción y confirmación de comandos

Flujo básico de integración de comandos

Basic command integration flow

El gateway, dispositivo o endpoint deberá estar escuchando comandos ejecutando el método correspondiente. Para esto se utiliza un mecanismo de long polling, donde el request permanecerá del lado del servidor por una cantidad de tiempo definido y volverá con la respuesta en caso de que el tiempo especificado se haya cumplido o que se haya detectado la ejecución de un comando.

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

Los comandos pueden ser escuchados a 3 niveles:

1. A nivel de Gateway
2. A nivel de Device
3. A nivel de Endpoint

Estos comandos deben llamarse de manera cíclica para escuchar constantemente los comandos ejecutados.

Comandos para endpoints

Se deberá llamar al método WaitForCommand_Endpoint mediante http POST:

POST /services/gear/DeviceIntegrationService.svc/WaitForCommand_Endpoint HTTP/1.1
Host: gear-dev.cloud.studio
Content-Type: application/json

{
    "accessToken": "",
    "endpointID": 1,
    "timeoutSeconds": 60
}

Parámetros

Respuesta

La respuesta es una lista dentro de la propiedad WaitForCommand_EndpointResult que tendrá cada uno de los comandos correspondientes:

{
   "WaitForCommand_EndpointResult":[
      {
         "Closure":null,
         "CommandID":1120907993,
         "CommandType":1,
         "Custom":null,
         "DeviceID":7246,
         "Dimmer":null,
         "EndpointID":113139,
         "Management":null,
         "OnOff":{
            "AutomaticOverrideMinutes":0,
            "CommandType":1
         },
         "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 con alguno de los métodos de WaitForCommands_* y luego de ejecutar las acciones correspondientes en el endpoint (hardware) se deberá responder el comando ya sea en caso de éxito o error.

Para informar que el comando ha sido ejecutado, se debe llamar al siguiente método:

POST /services/gear/DeviceIntegrationService.svc/RespondCommand HTTP/1.1
Host: gear-dev.cloud.studio
Content-Type: application/json

{
    "accessToken": "",
    "response":{
        "CommandID": 1120907993,
        "ResponseType": 0,
        "ErrorCode": "",
        "ErrorMessage": "",
        "ResponseData": "ok"
    }
}

El CommandID debe corresponder al obtenido en el método de espera de comandos correspondiente. El ResponseType debe ser alguno de los del enum, según corresponda. En este caso es 0, que significa "success".

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.

Siguiendo el ejemplo de appliance, se deberá llamar al siguiente método:

POST /services/gear/DeviceIntegrationService.svc/UpdateApplianceStatus HTTP/1.1
Host: gear-dev.cloud.studio
Content-Type: application/json

{
    "accessToken": "",
    "endpointID": 1,
    "isOn": true
}

Para más información acerca de este método ver la sección de artefactos on/off