Mettre en œuvre l' AWS.SendCommand opération

L'AWS.SendCommandopération permet à Managed Integrations AWS IoT Device Management d'envoyer des commandes initiées par l'utilisateur final via le AWS client à votre serveur de ressources. Votre serveur de ressources peut prendre en charge plusieurs types de périphériques, chaque type ayant son propre modèle de réponse.

L'exécution de commandes est un processus asynchrone dans lequel Managed Integrations for AWS IoT Device Management envoie une demande d'exécution de commande avec untraceId, que votre connecteur inclura dans une réponse de commande renvoyée à Managed Integrations via l' AWS IoT Device Management API. SendConnectorEvent Managed Integrations for AWS IoT Device Management attend du serveur de ressources qu'il renvoie une réponse confirmant la réception de la commande, mais n'indiquant pas nécessairement que la commande a été exécutée.

Flux de travail d'exécution des commandes des appareils

Le schéma suivant illustre le flux d'exécution des commandes avec un exemple dans lequel l'utilisateur final essaie d'allumer les lumières de sa maison :

Étapes du flux de travail

Exigences relatives au connecteur C2C pour l'exécution des commandes du périphérique

La liste suivante décrit les exigences relatives à votre connecteur C2C afin de faciliter l'exécution réussie des commandes du périphérique.

Processus d'exécution des commandes

Étape 1 : Managed Integrations envoie une commande au connecteur

Envoyez une requête POST avec l'une des charges utiles suivantes, selon le type d'autorisation :

Demande OAuth 2.0 :

/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”
                  		}
                  }]
              }]
          }]
     }
  }

Demande d'autorisation générale :

/Send-Command
{
     "header": {
          "auth": {
              "secretsManager": {
                  "arn": "string",
                  "versionId": "string"
              },
              "type": "GeneralAuthorization"
          }
     },
     "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"
                  		}
                  }]
              }]
          }]
     }
}

Étape 2 : commande ACK du connecteur C2C

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

Étape 3 : le connecteur envoie un événement de réponse à la commande du périphérique

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”
                }            
 		]
        }]
    }
}

Interprétation des « points finaux » inclus dans la demande AWS.SendCommand

Les intégrations gérées utiliseront les fonctionnalités de l'appareil signalées lors de la découverte de l'appareil pour déterminer les commandes qu'un appareil peut accepter. Les capacités de chaque appareil sont modélisées grâce à AWS des implémentations du modèle Matter Data ; ainsi, toutes les commandes entrantes seront dérivées du champ « commandes » d'un cluster donné. Il est de la responsabilité de votre connecteur d'analyser le champ `endpoints`, de déterminer la commande Matter correspondante et de la traduire de telle sorte que la bonne commande atteigne le périphérique. Cela implique généralement de traduire le modèle de données Matter dans les demandes d'API associées.

Une fois la commande exécutée, votre connecteur détermine quels « attributs » définis par les AWS implémentations du Matter Data Model ont changé en conséquence. Ces modifications sont ensuite signalées aux intégrations gérées pour AWS IoT Device Management via les événements API DEVICE_COMMAND_RESPONSE envoyés avec l'API. SendConnectorEvent

Considérez le champ `endpoints` inclus dans l'exemple de charge utile suivant : AWS.SendCommand

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

Managed Integrations a défini deux types de commandes « personnalisés » qui ne sont pas strictement définis par AWS les implémentations du modèle de données Matter : les commandes ReadState et UpdateState . Pour obtenir et définir les attributs de cluster définis par Matter, Managed Integrations enverra à votre connecteur une AWS.SendCommand demande avec des identifiants de commande relatifs à UpdateState (id : 0xff01) ou ReadState (id : 0xff02), avec les paramètres correspondants des attributs qui doivent être mis à jour ou lus. Ces commandes peuvent être invoquées pour TOUT type d'appareil pour les attributs définis comme mutables (modifiables) ou récupérables (lisibles) à partir de l' AWS implémentation correspondante du modèle de données de matière.