Implement the AWS.SendCommand operation

The AWS.SendCommand operation allows Managed integrations for AWS IoT Device Management to send commands initiated by the end user via the AWS customer to your resource server. Your resource server may support multiple types of devices, where each type has its own response model.

Command execution is an asynchronous process where Managed integrations for AWS IoT Device Management sends a request for command execution with a traceId, which your connector will include in a command response sent back to Managed integrations for AWS IoT Device Management via the SendConnectorEvent API. Managed integrations for AWS IoT Device Management expects the resource server to return a response acknowledging that command was received, but not necessarily indicating that command was executed.

Device Command Execution Workflow

The following diagram illustrates the command execution flow with an example where the end user tries to turn on the lights of their house:

Workflow Steps

C2C connector Requirements for Device Command Execution

The following list outlines the requirements for your C2C connector to facilitate a successful device command execution.

Command Execution Process

Step 1: Managed Integrations Sends Command to Connector

Send a POST request with one of the following payloads, depending on the authorization type:

OAuth 2.0 Request:

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

General Authorization request:

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

Step 2: C2C Connector ACK Command

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

Step 3: Connector Sends Device Command Response Event

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

Interpreting matter 'endpoints' included in AWS.SendCommand request

Managed integrations will use the device capabilities reported during device discovery to determine what commands a device can accept. Every device capability is modeled through AWS implementations of the Matter Data Model; thus, all incoming commands will be derived from the `commands` field within a given cluster. It is your connector’s responsibility to parse the `endpoints` field, determining the corresponding Matter command, and translating it such that correct command reaches the device. Typically, this means translating the Matter data model into the related API requests.

After the command has been executed, your connector then determines which `attributes` defined by the AWS implementations of the Matter Data Model have changed as a result. These changes are then reported to managed integrations for AWS IoT Device Management via API DEVICE_COMMAND_RESPONSE events sent with the SendConnectorEvent API.

Consider the `endpoints` field included in the following example AWS.SendCommand payload:

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

Managed integrations has defined two “custom” command types that are not strictly defined by AWS implementations of the Matter Data Model: The ReadState and UpdateState commands. To get and set Matter defined cluster attributes, managed integrations will send your connector an AWS.SendCommand request with command IDs pertaining to UpdateState (id: 0xff01) or ReadState (id: 0xff02), with corresponding parameters of attributes that must be either updated or read. These commands can be invoked for ANY device type for attributes that are set as mutable (updatable) or retrievable (readable) from the corresponding AWS implementation of the Matter Data Model.