Implementieren Sie das AWS. SendCommand Betrieb

Dieser AWS.SendCommand Vorgang ermöglicht verwalteten Integrationen für AWS IoT Device Management, Befehle, die vom Endbenutzer initiiert wurden, über den AWS Kunden an Ihren Ressourcenserver zu senden. Ihr Ressourcenserver unterstützt möglicherweise mehrere Gerätetypen, wobei jeder Typ sein eigenes Antwortmodell hat. Die Befehlsausführung ist ein asynchroner Prozess, bei dem verwaltete Integrationen für AWS IoT Device Management eine Anfrage zur Befehlsausführung mit einer `TraceID` senden, die Ihr Connector in eine Befehlsantwort einfügt, die über die ``SendConnectorEventAPI an verwaltete Integrationen zurückgesendet wird. Verwaltete Integrationen für AWS IoT Device Management erwarten, dass der Ressourcenserver eine Antwort zurückgibt, die bestätigt, dass der Befehl empfangen wurde, aber nicht unbedingt angibt, dass der Befehl ausgeführt wurde.

Das folgende Diagramm veranschaulicht den Ablauf der Befehlsausführung anhand eines Beispiels, bei dem der Endbenutzer versucht, die Beleuchtung seines Hauses einzuschalten:

Arbeitsablauf für die Ausführung von Gerätebefehlen

1. Ein Endbenutzer sendet mithilfe der AWS Kundenanwendung einen Befehl zum Einschalten eines Lichts.

2. Der Kunde leitet die Befehlsinformationen zusammen mit den Geräteinformationen des Endbenutzers an verwaltete Integrationen für AWS IoT Device Management weiter.

3. Managed Integrations generiert eine „traceId“, die Ihr Connector verwendet, wenn er Befehlsantworten zurück an den Service sendet.

4. Managed Integrations for AWS IoT Device Management sendet die Befehlsanforderung über die AWS.SendCommand Bedienoberfläche an Ihren Connector.

   1. Die durch diese Schnittstelle definierte Nutzlast besteht aus der Gerätekennung, als Matter formulierten Gerätebefehlenendpoints/clusters/commands, dem Zugriffstoken des Endbenutzers und anderen erforderlichen Parametern.

5. Ihr Connector speichert die DatentraceId, die in die Befehlsantwort aufgenommen werden sollen.

   1. Ihr Connector übersetzt die Befehlsanforderung für verwaltete Integrationen in das entsprechende Format Ihres Ressourcenservers.

6. Ihr Connector ruft das Zugriffstoken des bereitgestellten Endbenutzers UserId ab und ordnet es dem Befehl zu.

   1. Sie UserId können entweder mit einem separaten Aufruf von Ihrem Ressourcenserver abgerufen oder im Fall von JWT und ähnlichen Token aus dem Zugriffstoken extrahiert werden.

   2. Die Implementierung hängt von Ihrem Ressourcenserver und den Details des Zugriffstokens ab.

7. Ihr Connector fordert den Ressourcenserver auf, das Licht des Endbenutzers einzuschalten.

8. Der Ressourcenserver interagiert mit dem Gerät.

   1. Der Konnektor leitet an verwaltete Integrationen für AWS IoT Device Management weiter, dass der Ressourcenserver den Befehl übermittelt hat, und antwortet mit einem ACK als erste, synchrone Befehlsantwort.

   2. Verwaltete Integrationen leiten ihn dann zurück an die Kundenanwendung.

9. Wenn das Gerät das Licht einschaltet, wird dieses Geräteereignis von Ihrem Ressourcenserver erfasst.

10. Ihr Ressourcenserver sendet das Geräteereignis an den Connector.

11. Ihr Connector wandelt das vom Ressourcenserver generierte Geräteereignis in den Vorgangstyp DEVICE_COMMAND_RESPONSE für verwaltete Integrationen um.

12. Ihr Connector ruft die SendConnectorEvent API mit der Operation „DEVICE_COMMAND_RESPONSE“ auf.

    1. Es fügt der ersten Anfrage die von Managed Integrations für AWS IoT Device Management traceId bereitgestellten Integrationen hinzu.

13. Managed Integrations benachrichtigt den Kunden über die Änderung des Gerätestatus des Endbenutzers.

14. Der Kunde informiert den Endbenutzer darüber, dass das Licht des Geräts eingeschaltet ist.

    Anmerkung

    Ihre Ressourcenserverkonfiguration bestimmt die Logik für die Behandlung fehlgeschlagener Gerätebefehle und Antwortnachrichten. Dies schließt Versuche ein, Nachrichten mit derselben ReferenceID für den Befehl erneut zu versuchen.

Anforderungen an den C2C-Anschluss für die Ausführung von Gerätebefehlen

In der folgenden Liste sind die Anforderungen für Ihren C2C-Anschluss aufgeführt, um eine erfolgreiche Ausführung von Gerätebefehlen zu ermöglichen.

• Der C2C-Konnektor Lambda kann AWS.SendCommand Betriebsanforderungsnachrichten von verwalteten Integrationen für AWS IoT Device Management verarbeiten.

• Ihr C2C-Konnektor muss die an Ihren Ressourcenserver gesendeten Befehle verfolgen und ihnen die entsprechende `TraceId` zuordnen.

• Sie können verwaltete Integrationen für AWS IoT Device Management Service APIs über Sigv4 aufrufen, indem Sie die AWS Anmeldeinformationen verwenden, die für die Registrierung des C2C-Connectors AWS-Konto verwendet wurden.

1. Managed Integrations sendet einen Befehl an den Connector (siehe Schritt 4 im vorherigen Diagramm).

   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. ACK-Befehl für den C2C-Anschluss (siehe Schritt 7 im vorherigen Diagramm, in dem der Connector ACK an die verwalteten Integrationen für AWS IoT Device Management Service sendet).

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

3. Der Connector sendet das Device Command Response-Ereignis (siehe Schritt 11 im vorherigen Diagramm).

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

   Anmerkung

   Änderungen des Gerätestatus als Ergebnis einer Befehlsausführung werden erst in verwalteten Integrationen für AWS IoT Device Management berücksichtigt, wenn das entsprechende DEVICE_COMMAND_RESPONSE-Ereignis über die API empfangen wurde. SendConnectorEvent Das bedeutet, dass der Gerätestatus erst aktualisiert wird, wenn Managed Integrations das Ereignis aus dem vorherigen Schritt 3 empfängt, unabhängig davon, ob Ihre Connector-Aufrufantwort erfolgreich ist oder nicht.

Interpretieren von „Endpunkten“, die in AWS enthalten sind. SendCommand Anfrage

Verwaltete Integrationen verwenden die bei der Geräteerkennung gemeldeten Gerätefunktionen, um zu ermitteln, welche Befehle ein Gerät annehmen kann. Jede Gerätefunktion wird durch AWS Implementierungen des Matter Data Model modelliert. Somit werden alle eingehenden Befehle aus dem Feld „Befehle“ innerhalb eines bestimmten Clusters abgeleitet. Es liegt in der Verantwortung Ihres Konnektors, das Feld „Endpunkte“ zu analysieren, den entsprechenden Matter-Befehl zu ermitteln und ihn so zu übersetzen, dass der richtige Befehl das Gerät erreicht. In der Regel bedeutet dies, das Matter-Datenmodell in die entsprechenden API-Anfragen zu übersetzen.

Nachdem der Befehl ausgeführt wurde, ermittelt Ihr Konnektor, welche `Attribute`, die durch die AWS Implementierungen des Matter-Datenmodells definiert wurden, sich dadurch geändert haben. Diese Änderungen werden dann über API-DEVICE_COMMAND_RESPONSE-Ereignisse, die mit der API gesendet werden, an verwaltete Integrationen für AWS IoT Device Management gemeldet. SendConnectorEvent

Betrachten Sie das Feld `endpoints`, das in der folgenden Beispielnutzlast enthalten ist: AWS.SendCommand

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

Aus diesem Objekt kann der Konnektor Folgendes ermitteln:

1. Legen Sie die Endpunkt- und Clusterinformationen fest:

   1. Setzen Sie den Endpunkt id auf „1".

      Anmerkung

      Wenn ein Gerät mehrere Endpunkte definiert, also einen einzelnen Cluster (z. B.On/Off) can control multiple capabilities (i.e. turn a light on/off as well as turning a strobe on/off), wird diese ID verwendet, um den Befehl an die richtige Funktion weiterzuleiten.

   2. Stellen Sie den Cluster id auf „0x0202" (Fan Control Cluster) ein.

2. Stellen Sie die Befehlsinformationen ein:

   1. Setzen Sie die Befehlskennung auf „0xff01" (Befehl „Status aktualisieren“, definiert von). AWS

   2. Aktualisieren Sie die enthaltenen Attributbezeichner mit den in der Anfrage angegebenen Werten.

3. Aktualisieren Sie das Attribut:

   1. Setzen Sie die Attribut-ID auf „0x0000" (FanMode Attribut des Fan Control Clusters).

   2. Setzen Sie den Attributwert auf „3" (Hohe Lüftergeschwindigkeit).

Managed Integrations hat zwei „benutzerdefinierte“ Befehlstypen definiert, die nicht unbedingt durch AWS Implementierungen des Matterdatenmodells definiert sind: Die Befehle ReadState und UpdateState . Um vom Thema definierte Clusterattribute abzurufen und festzulegen, senden verwaltete Integrationen Ihrem Connector eine AWS.SendCommand Anfrage mit einem Befehl, der sich auf UpdateState (id: 0xff01) oder ReadState (id: 0xff02) IDs bezieht, mit entsprechenden Attributparametern, die entweder aktualisiert oder gelesen werden müssen. Diese Befehle können für JEDEN Gerätetyp für Attribute aufgerufen werden, die in der entsprechenden Implementierung des Matter-Datenmodells als veränderbar (aktualisierbar) oder abrufbar (lesbar) festgelegt sind. AWS