Implemente AWS. SendCommand operación

La AWS.SendCommand operación permite que las integraciones administradas de AWS IoT Device Management envíen los comandos iniciados por el usuario final a través del AWS cliente a su servidor de recursos. Su servidor de recursos puede admitir varios tipos de dispositivos, cada uno de los cuales tiene su propio modelo de respuesta. La ejecución de comandos es un proceso asíncrono en el que las integraciones gestionadas para AWS IoT Device Management envían una solicitud de ejecución de comandos con un `TraceID`, que el conector incluirá en una respuesta de comando que se devolverá a las integraciones gestionadas a través de la `` SendConnectorEvent API. Las integraciones gestionadas para AWS IoT Device Management esperan que el servidor de recursos devuelva una respuesta confirmando que se ha recibido el comando, pero no que indique necesariamente que se ha ejecutado el comando.

El siguiente diagrama ilustra el flujo de ejecución de comandos con un ejemplo en el que el usuario final intenta encender las luces de su casa:

Flujo de trabajo de ejecución de comandos de

1. Un usuario final envía un comando para encender una luz mediante la aplicación del AWS cliente.

2. El cliente transmite la información de comandos a las integraciones gestionadas de AWS IoT Device Management con la información del dispositivo del usuario final.

3. Las integraciones gestionadas generan un «TraceID» que el conector utilizará al enviar las respuestas de los comandos al servicio.

4. las integraciones administradas para AWS IoT Device Management envían la solicitud de comando a su conector mediante la interfaz de AWS.SendCommand operación.

   1. La carga útil definida por esta interfaz consiste en el identificador del dispositivo, los comandos del dispositivo formulados como Matterendpoints/clusters/commands, el token de acceso del usuario final y otros parámetros necesarios.

5. El conector almacena los datos traceId que se incluirán en la respuesta al comando.

   1. El conector traduce la solicitud de comandos de integraciones gestionadas al formato adecuado del servidor de recursos.

6. El conector se UserId obtiene del token de acceso del usuario final proporcionado y lo asocia al comando.

   1. UserIdPuede obtenerse de su servidor de recursos mediante una llamada independiente o extraerse del token de acceso en el caso de JWT y tokens similares.

   2. La implementación depende del servidor de recursos y de los detalles del token de acceso.

7. El conector llama al servidor de recursos para «encender» la luz del usuario final.

8. El servidor de recursos interactúa con el dispositivo.

   1. El conector transmite a las integraciones administradas de AWS IoT Device Management las que el servidor de recursos ha entregado el comando y responde con un ACK como respuesta de comando sincrónica inicial.

   2. A continuación, las integraciones gestionadas lo devuelven a la aplicación del cliente.

9. Una vez que el dispositivo enciende la luz, el servidor de recursos captura ese evento del dispositivo.

10. El servidor de recursos envía el evento del dispositivo al conector.

11. El conector transforma el evento de dispositivo generado por el servidor de recursos en el tipo de operación de evento DEVICE_COMMAND_RESPONSE de integraciones administradas.

12. El conector llama a la SendConnectorEvent API con la operación «DEVICE_COMMAND_RESPONSE».

    1. Adjunta lo traceId proporcionado por las integraciones administradas para AWS IoT Device Management en la solicitud inicial.

13. Las integraciones administradas notifican al cliente el cambio de estado del dispositivo del usuario final.

14. El cliente notifica al usuario final que la luz del dispositivo se ha encendido.

    nota

    La configuración del servidor de recursos determina la lógica para gestionar los mensajes de solicitud y respuesta de comandos del dispositivo fallidos. Esto incluye los intentos de reintento de los mensajes utilizando el mismo ReferenceID para el comando.

Requisitos del conector C2C para la ejecución de comandos del dispositivo

La siguiente lista describe los requisitos de su conector C2C para facilitar la ejecución correcta de los comandos del dispositivo.

• El conector C2C Lambda puede AWS.SendCommand procesar los mensajes de solicitud de operación de las integraciones administradas para AWS IoT Device Management.

• Su conector C2C debe realizar un seguimiento de los comandos enviados a su servidor de recursos y asignarlos con el `TraceID` adecuado.

• Puede llamar a las integraciones administradas de las API del servicio AWS IoT Device Management mediante SiGv4 con AWS las credenciales Cuenta de AWS utilizadas para registrar el conector C2C.

1. Las integraciones administradas envían el comando al conector (consulte el paso 4 del diagrama anterior).

   1. /Send-Command
      {
           "header": {
                "auth": {                 
                    "token": "ashriu32yr97feqy7afsaf",  
                    "type": "OAuth2.0"
                }
           },
           "payload": {
                "operationName": "AWS.SendCommand",
                "operationVersion": "1.0",
                "connectorId": "Your-Connector-Id",
                "connectorDeviceId": "Your_Device_Id",
                "traceId": "traceId-3241u78123419",
                "endpoints": [{
                    "id": "1",    
                    "clusters": [{
                        "id": "0x0202",
                        "commands": [{
                            "0xff01": 
                                {
                                    "0x0000": "3”
                        		}
                        }]
                    }]
                }]
           }
        }
      

2. Comando ACK del conector C2C (consulte el paso 7 del diagrama anterior, donde el conector envía el ACK a las integraciones gestionadas de AWS IoT Device Management Service).

   1. {
           "header":{
                "responseCode":200
           },
           "payload":{
                "responseMessage": "Successfully received send-command request for connector 'Your-Connector-Id' and connector-device-id 'Your_Device_Id'" 
           }
        }
      

3. El conector envía el evento de respuesta al comando del dispositivo (consulte el paso 11 del diagrama anterior).

   1. AWS-API: /SendConnectorEvent
      URI: POST /connector-event/{Your-Connector-Id}
      
      {
         "UserId": "End-User-Id",
         "Operation": "DEVICE_COMMAND_RESPONSE",
         "OperationVersion": "1.0",
         "StatusCode": 200,
         "Message": “Example message”,
         "ConnectorDeviceId": "Your_Device_Id",
         "TraceId": "traceId-3241u78123419",
         "MatterEndpoint": {
              "id": "1",    
              "clusters": [{
                  "id": "0x0202",
                  "attributes": [
                      {
                          "0x0000": “3”
                      }
                  ],
                  "commands": [
                      "0xff01": 
                      {
                          "0x0000": "3”
                      }            
       		]
              }]
          }
      }
      

   nota

   Los cambios de estado del dispositivo como resultado de la ejecución de un comando no se reflejarán en las integraciones administradas de AWS IoT Device Management hasta que se reciba el evento DEVICE_COMMAND_RESPONSE correspondiente a través de la API. SendConnectorEvent Esto significa que hasta que las integraciones administradas reciban el evento del paso 3 anterior, independientemente de si la respuesta de invocación del conector indica que se ha realizado correctamente o no, el estado del dispositivo no se actualizará.

Interpretación de los «puntos finales» de la materia incluidos en AWS. SendCommand solicitud

Las integraciones gestionadas utilizarán las capacidades del dispositivo notificadas durante la detección del dispositivo para determinar qué comandos puede aceptar un dispositivo. Las capacidades de cada dispositivo se modelan mediante AWS implementaciones del modelo de datos de materia; por lo tanto, todos los comandos entrantes se derivarán del campo «comandos» de un clúster determinado. Es responsabilidad del conector analizar el campo «puntos finales», determinar el comando Matter correspondiente y traducirlo de forma que el comando correcto llegue al dispositivo. Normalmente, esto implica traducir el modelo de datos de Matter a las solicitudes de API relacionadas.

Una vez ejecutado el comando, el conector determina qué «atributos» definidos en AWS las implementaciones del modelo de datos de Matter han cambiado como consecuencia de ello. A continuación, estos cambios se notifican a las integraciones gestionadas de AWS IoT Device Management mediante los eventos DEVICE_COMMAND_RESPONSE de la API enviados con la API. SendConnectorEvent

Considere el campo «puntos finales» incluido en la siguiente carga útil de ejemplo: AWS.SendCommand

          "endpoints": [{
              "id": "1",    
              "clusters": [{
                  "id": "0x0202",
                  "commands": [{
                      "0xff01": 
                          {
                              "0x0000": "3”
                  		}
                  }]
              }]
          }]

A partir de este objeto, el conector puede determinar lo siguiente:

1. Configure la información del punto final y del clúster:

   1. Establezca el punto final id en «1".

      nota

      Si un dispositivo define varios puntos finales, como un solo clúster (por ejemploOn/Off) can control multiple capabilities (i.e. turn a light on/off as well as turning a strobe on/off), este identificador se utiliza para enrutar el comando a la capacidad correcta.

   2. Defina el clúster id en «0x0202" (clúster Fan Control).

2. Configure la información del comando:

   1. Establezca el identificador del comando en «0xff01" (comando de actualización de estado definido por). AWS

   2. Actualice los identificadores de atributos incluidos con los valores proporcionados en la solicitud.

3. Actualice el atributo:

   1. Establezca el identificador del atributo en «0x0000" (FanMode atributo del grupo de control del ventilador).

   2. Establezca el valor del atributo en «3" (velocidad alta del ventilador).

Managed Integrations ha definido dos tipos de comandos «personalizados» que AWS las implementaciones del Matter Data Model no definen estrictamente: los comandos ReadState y UpdateState . Para obtener y establecer los atributos del clúster definidos por Matter, las integraciones gestionadas enviarán al conector una AWS.SendCommand solicitud con el comando IDs correspondiente a UpdateState (id: 0xff01) o ReadState (id: 0xff02), con los parámetros correspondientes de los atributos que deben actualizarse o leerse. Estos comandos se pueden invocar en CUALQUIER tipo de dispositivo para los atributos que estén configurados como mutables (actualizables) o recuperables (legibles) a partir de la implementación correspondiente del modelo de datos de Matter. AWS