View a markdown version of this page

Configuração guiada pelo usuário para integrar e operar dispositivos - Integrações gerenciadas para AWS IoT Device Management
Pré-requisitosPré-requisito: ativar o modo de emparelhamento em seu dispositivo Z WaveEtapa 1: iniciar a descoberta do dispositivoEtapa 2: consultar o ID do trabalho de descobertaEtapa 3: criar uma coisa gerenciada para o seu dispositivoEtapa 4: consultar a coisa gerenciadaEtapa 5: Obtenha recursos de gerenciamento de coisasEtapa 6: enviar um comando para a coisa gerenciadaEtapa 7: verificar o estado da coisa gerenciadaEtapa 8: Remover o item gerenciado do seu hub

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Configuração guiada pelo usuário para integrar e operar dispositivos

Configure seus dispositivos para serem integrados ao seu hub de integrações gerenciadas criando uma coisa gerenciada e conectando-a ao seu hub. Esta seção descreve as etapas para concluir o processo de integração do dispositivo usando a configuração guiada pelo usuário.

Pré-requisitos

Conclua estas etapas antes de tentar integrar um dispositivo:

Pré-requisito: ativar o modo de emparelhamento em seu dispositivo Z Wave

Ative o modo de emparelhamento no Z-wave dispositivo. O modo de emparelhamento pode variar para cada Z-Wave dispositivo, portanto, consulte as instruções do dispositivo para configurar corretamente o modo de emparelhamento. Geralmente, é um botão que o usuário deve pressionar.

Etapa 1: iniciar a descoberta do dispositivo

Inicie a descoberta de dispositivos em seu hub para obter um ID de trabalho de descoberta que é usado para integrar seu dispositivo.

Para iniciar a descoberta de dispositivos

  • Use o comando start-device-discovery para obter o ID do trabalho de descoberta.

    start-device-discovery exemplo

    #For Zigbee
  aws iot-managed-integrations start-device-discovery --discovery-type ZIGBEE \
  --controller-identifier HUB_MANAGED_THING_ID
  
  #For Zwave
  aws iot-managed-integrations start-device-discovery --discovery-type ZWAVE \
  --controller-identifier HUB_MANAGED_THING \
  --authentication-material-type ZWAVE_INSTALL_CODE \
  --authentication-material 13333
  
  #For Cloud
  aws iot-managed-integrations start-device-discovery --discovery-type CLOUD \
  --account-association-id C2C_ASSOCIATION_ID \
  
  #For Custom
  aws iot-managed-thing start-device-discovery --discovery-type CUSTOM \
  --controller-identifier HUB_MANAGED_THING_ID \
  --custom-protocol-detail NAME : NON_EMPTY_STRING \

    Resposta:

    {
      "Id": DISCOVERY_JOB_ID,
      "StartedAt": "2025-06-03T14:43:12.726000-07:00"
  }
    nota

    Existem comandos separados para dispositivos Z-wave Zigbee.

    Para obter mais informações, consulte a API start-device-discovery na Referência de comandos de integrações gerenciadas. AWS CLI

Etapa 2: consultar o ID do trabalho de descoberta

Use o list-discovered-devices comando para obter o material de autenticação do seu dispositivo.

Para consultar seu ID de trabalho de descoberta

  • Use o ID do trabalho de descoberta com o comando list-discovered-devices para obter o material de autenticação do seu dispositivo.

    aws iot-managed-integrations list-discovered-devices --identifier DISCOVERY_JOB_ID

Resposta:

"Items": [
    {
        "DeviceTypes": [],
        "DiscoveredAt": "2025-06-03T14:43:37.619000-07:00",
        "AuthenticationMaterial": AUTHENTICATION_MATERIAL
    }
]

Preencha a marca e o modelo dos dispositivos descobertos

Durante a descoberta do dispositivo, os dispositivos descobertos podem, opcionalmente, relatar informações de marca e modelo por meio do cluster Matter Basic Information. Esses valores são então retornados nas ListManagedThingsrespostas ListDiscoveredDevicese.

Relate o cluster de informações básicas (cluster0x0028) no endpoint raiz do dispositivo (0) e mapeie:

  • VendorName(atributo0x0001) → Brand

  • ProductName(atributo0x0003) → Model

O exemplo a seguir mostra como relatar o cluster de informações básicas no endpoint raiz:

"endpoints": [{
    "id": "0",
    "clusters": [{
        "id": "0x0028",
        "attributes": [{
            "id": "0x0001",
            "value": "ExampleBrand"
        }, {
            "id": "0x0003",
            "value": "ExampleModel-X1"
        }]
    }]
}]

Ambos os valores são cadeias de caracteres com um comprimento máximo de 32 caracteres. Se o cluster de informações básicas ou qualquer um dos atributos não for relatado, o campo correspondente será omitido da resposta.

Etapa 3: criar uma coisa gerenciada para o seu dispositivo

Use o create-managed-thing comando para criar uma coisa gerenciada para o seu dispositivo. Cada dispositivo requer sua própria coisa gerenciada.

Para criar uma coisa gerenciada

  • Use o create-managed-thing comando para criar uma coisa gerenciada para o seu dispositivo.

    create-managed-thing exemplo

    aws iot-managed-integrations create-managed-thing \
  --role  DEVICE --authentication-material-type DISCOVERED_DEVICE \
  --authentication-material "AUTHENTICATION_MATERIAL"

    Resposta:

    {    
    "Id": "DEVICE_MANAGED_THING_ID"
    "Arn": "arn:aws:iotmanagedintegrations:AWS_REGION:AWS_ACCOUNT_ID:managed-thing/DEVICE_MANAGED_THING_ID"
    "CreatedAt": "2025-06-09T13:58:52.977000+08:00"
  }

    Para obter mais informações, consulte o comando create-managed-thing na Referência de comandos de integrações gerenciadas. AWS CLI

Etapa 4: consultar a coisa gerenciada

Você pode verificar se uma coisa gerenciada está ativada usando o get-managed-thing comando.

Para consultar uma coisa gerenciada

  • Use o get-managed-thing comando para verificar se o status de provisionamento do item gerenciado está definido como. ACTIVATED Para obter mais informações sobre o status do provisionamento, consulte Provisionamento de dispositivos.

    get-managed-thing exemplo

    aws iot-managed-integrations get-managed-thing \
  --identifier "DEVICE_MANAGED_THING_ID"

    Resposta:

    {
      "Id": "DEVICE_MANAGED_THING_ID",
      "Arn": "arn:aws:iotmanagedintegrations:AWS_REGION:AWS_ACCOUNT_ID:managed-thing/DEVICE_MANAGED_THING_ID,
      "Role": "DEVICE",
      "ProvisioningStatus": "ACTIVATED",
      "MacAddress": "MAC_ADDRESS",
      "ParentControllerId": "PARENT_CONTROLLER_ID",
      "CreatedAt": "2025-06-03T14:46:35.149000-07:00",
      "UpdatedAt": "2025-06-03T14:46:37.500000-07:00",
      "Tags": {}
  }

    Para obter mais informações, consulte o comando get-managed-thing na Referência de comandos de integrações gerenciadas. AWS CLI

Etapa 5: Obtenha recursos de gerenciamento de coisas

Você pode ver uma lista das ações disponíveis de uma coisa gerenciada usando get-managed-thing-capabiltiies o.

Para obter os recursos de um dispositivo

  • Use o get-managed-thing-capabilities comando para obter o ID do endpoint. Observe também a lista de ações possíveis.

    get-managed-thing-capabilities exemplo

    aws iot-managed-integrations get-managed-thing-capabilities \
  --identifier "DEVICE_MANAGED_THING_ID"

    Resposta:

    {
      "ManagedThingId": "DEVICE_MANAGED_THING_ID",
      "CapabilityReport": {
          "version": "1.0.0",
          "nodeId": "zb.539D+4A1D",
          "endpoints": [
              {
                  "id": "1",
                  "deviceTypes": [
                      "Unknown Device"
                  ],
                  "capabilities": [
                      {
                          "id": "matter.OnOff@1.4",
                          "name": "On/Off",
                          "version": "6",
                          "properties": [
                              "OnOff",
                              "OnOff",
                              "OnTime",
                              "OffWaitTime"
                          ],
                          "actions": [
                              "Off",
                              "On",
                              "Toggle",
                              "OffWithEffect",
                              "OnWithRecallGlobalScene",
                              "OnWithTimedOff"
                          ],
                          ...
  }

    Para obter mais informações, consulte o comando get-managed-thing-capabilities na Referência de comandos de integrações gerenciadas. AWS CLI

Etapa 6: enviar um comando para a coisa gerenciada

Você pode usar o comando send-managed-thing-command para enviar um comando de ação de alternância para sua coisa gerenciada.

Envie um comando para a coisa gerenciada usando uma ação de alternância.

  • Use o send-managed-thing-command comando para enviar um comando de ação de alternância.

    send-managed-thing-command exemplo

    json=$(jq -cr '.|@json') <<EOF
  [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "matter.OnOff@1.4",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "Toggle",
              "parameters": {}
            }
          ]
        }
      ]
    }
  ]
  EOF
  aws iot-managed-integrations send-managed-thing-command \
  --managed-thing-id ${device_managed_thing_id} --endpoints ENDPOINT_ID
    nota

    Este exemplo usa jq cli para, mas você também pode passar a string inteira endpointId

    Resposta:

    {    
  "TraceId": TRACE_ID
  }

    Para obter mais informações, consulte o comando send-managed-thing-command na Referência de comandos de integrações gerenciadas. AWS CLI

Etapa 7: verificar o estado da coisa gerenciada

Verifique o estado da coisa gerenciada para validar se a ação de alternância foi bem-sucedida.

Para verificar o estado do dispositivo de uma coisa gerenciada

  • Use o get-managed-thing-state comando para validar se a ação de alternância foi bem-sucedida.

    get-managed-thing-state exemplo

    
  aws iot-managed-integrations get-managed-thing-state --managed-thing-id DEVICE_MANAGED_THING_ID

    Resposta:

    {
      "Endpoints": [
          {
              "endpointId": "1",
              "capabilities": [
                  {
                      "id": "matter.OnOff@1.4",
                      "name": "On/Off",
                      "version": "1.4",
                      "properties": [
                          {
                              "name": "OnOff",
                              "value": {
                                  "propertyValue": true,
                                  "lastChangedAt": "2025-06-03T21:50:39.886Z"
                              }
                          }
                      ]
                  }
              ]
          }
      ]
  }

    Para obter mais informações, consulte o comando get-managed-thing-state na Referência de comandos de integrações gerenciadas. AWS CLI

Etapa 8: Remover o item gerenciado do seu hub

Limpe seu hub removendo a coisa gerenciada.

Para excluir uma coisa gerenciada

  • Use o comando delete-managed-thing para remover uma coisa gerenciada.

    delete-managed-thing exemplo

    aws iot-managed-integrations delete-managed-thing \
  --identifier MANAGED_THING_ID

    Para obter mais informações, consulte o comando delete-managed-thing na Referência de comandos de integrações gerenciadas. AWS CLI

    nota

    Se o dispositivo estiver preso em um DELETE_IN_PROGRESS estado, anexe o --force sinalizador ao delete-managed-thing comando.

    nota

    Para Z-wave dispositivos, você precisa colocar o dispositivo no modo de emparelhamento depois de executar o comando.