View a markdown version of this page

Configurazione guidata dall'utente per l'installazione e il funzionamento dei dispositivi - Integrazioni gestite per AWS IoT Device Management
PrerequisitiPrerequisito: abilitare la modalità di associazione sul dispositivo Z WavePassaggio 1: avvia l'individuazione del dispositivoPassaggio 2: interrogare l'ID del processo di rilevamentoPassaggio 3: Crea un oggetto gestito per il tuo dispositivoPassaggio 4: interroga l'oggetto gestitoFase 5: Ottieni funzionalità gestite per gli oggettiPassaggio 6: invio di un comando all'oggetto gestitoPassaggio 7: verifica lo stato dell'oggetto gestitoPassaggio 8: rimuovi l'oggetto gestito dal tuo hub

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Configurazione guidata dall'utente per l'installazione e il funzionamento dei dispositivi

Configura i tuoi dispositivi per l'onboarding nel tuo hub di Managed Integrations creando un oggetto gestito e collegandolo al tuo hub. Questa sezione descrive i passaggi per completare il processo di onboarding del dispositivo utilizzando la configurazione guidata dall'utente.

Prerequisiti

Completa questi passaggi prima di tentare l'onboard di un dispositivo:

Prerequisito: abilitare la modalità di associazione sul dispositivo Z Wave

Abilita la modalità di associazione sul dispositivo. Z-wave La modalità di associazione può variare per ogni Z-Wave dispositivo, quindi consulta le istruzioni del dispositivo per configurare correttamente la modalità di associazione. Di solito è un pulsante che l'utente deve premere.

Passaggio 1: avvia l'individuazione del dispositivo

Avvia il rilevamento dei dispositivi per l'hub per ottenere un Discovery Job ID da utilizzare per effettuare l'onboard del dispositivo.

Per avviare l'individuazione dei dispositivi

  • Utilizzate il comando start-device-discovery per ottenere l'ID del processo di rilevamento.

    Esempio start-device-discovery

    #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 \

    Risposta:

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

    Esistono comandi separati per i dispositivi Zigbee. Z-wave

    Per ulteriori informazioni, consulta l'API start-device-discovery nel Managed Integrations Command Reference. AWS CLI

Passaggio 2: interrogare l'ID del processo di rilevamento

Usa il list-discovered-devices comando per ottenere il materiale di autenticazione del tuo dispositivo.

Per interrogare il tuo Discovery Job ID

  • Usa il discovery job ID con il comando list-discovered-devices per ottenere il materiale di autenticazione del tuo dispositivo.

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

Risposta:

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

Inserisci marca e modello per i dispositivi rilevati

Durante l'individuazione dei dispositivi, i dispositivi rilevati possono facoltativamente riportare informazioni sulla marca e sul modello tramite il cluster Matter Basic Information. Questi valori vengono quindi restituiti nelle ListManagedThingsrisposte ListDiscoveredDevicese.

Segnala il cluster di informazioni di base (cluster0x0028) sull'endpoint root del dispositivo (0) e mappa:

  • VendorName(attributo0x0001) → Brand

  • ProductName(attributo0x0003) → Model

L'esempio seguente mostra come riportare il cluster di informazioni di base sull'endpoint root:

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

Entrambi i valori sono stringhe con una lunghezza massima di 32 caratteri. Se il cluster di informazioni di base o uno degli attributi non vengono segnalati, il campo corrispondente viene omesso dalla risposta.

Passaggio 3: Crea un oggetto gestito per il tuo dispositivo

Usa il create-managed-thing comando per creare un oggetto gestito per il tuo dispositivo. Ogni dispositivo richiede la propria funzionalità gestita.

Per creare un oggetto gestito

  • Usa il create-managed-thing comando per creare un oggetto gestito per il tuo dispositivo.

    Esempio create-managed-thing

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

    Risposta:

    {    
    "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"
  }

    Per ulteriori informazioni, consulta il comando create-managed-thing nel Managed Integrations Command Reference. AWS CLI

Passaggio 4: interroga l'oggetto gestito

È possibile verificare se una cosa gestita è attivata utilizzando il get-managed-thing comando.

Per interrogare una cosa gestita

  • Usa il get-managed-thing comando per verificare se lo stato di provisioning dell'oggetto gestito è impostato ACTIVATED su. Per ulteriori informazioni sullo stato del provisioning, vedere Device Provisioning.

    Esempio get-managed-thing

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

    Risposta:

    {
      "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": {}
  }

    Per ulteriori informazioni, consulta il comando get-managed-thing nel Managed Integrations Command Reference. AWS CLI

Fase 5: Ottieni funzionalità gestite per gli oggetti

È possibile visualizzare un elenco delle azioni disponibili di un oggetto gestito utilizzandoget-managed-thing-capabiltiies.

Per sfruttare le funzionalità di un dispositivo

  • Usa il get-managed-thing-capabilities comando per ottenere l'ID dell'endpoint. Nota anche l'elenco delle azioni possibili.

    Esempio get-managed-thing-capabilities

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

    Risposta:

    {
      "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"
                          ],
                          ...
  }

    Per ulteriori informazioni, vedere il comando get-managed-thing-capabilities nel Managed Integrations Command Reference. AWS CLI

Passaggio 6: invio di un comando all'oggetto gestito

Puoi usare il comando send-managed-thing-command per inviare un comando toggle action all'oggetto gestito.

Invia un comando all'oggetto gestito utilizzando un'azione di commutazione.

  • Usa il send-managed-thing-command comando per inviare un comando di toggle action.

    Esempio send-managed-thing-command

    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

    Questo esempio usa jq cli to, ma puoi anche passare l'intera stringa endpointId

    Risposta:

    {    
  "TraceId": TRACE_ID
  }

    Per ulteriori informazioni, consulta il comando send-managed-thing-command nel Managed Integrations Command Reference. AWS CLI

Passaggio 7: verifica lo stato dell'oggetto gestito

Controlla lo stato dell'oggetto gestito per confermare che l'azione di attivazione è riuscita.

Per controllare lo stato del dispositivo di un oggetto gestito

  • Usa il get-managed-thing-state comando per confermare che l'azione di attivazione è riuscita.

    Esempio get-managed-thing-state

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

    Risposta:

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

    Per ulteriori informazioni, consulta il comando get-managed-thing-state nel Managed Integrations Command Reference. AWS CLI

Passaggio 8: rimuovi l'oggetto gestito dal tuo hub

Pulisci l'hub rimuovendo l'elemento gestito.

Per eliminare un oggetto gestito

  • Usa il comando delete-managed-thing per rimuovere un oggetto gestito.

    Esempio delete-managed-thing

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

    Per ulteriori informazioni, consulta il comando delete-managed-thing nel Managed Integrations Command Reference. AWS CLI

    Nota

    Se il dispositivo è bloccato in uno DELETE_IN_PROGRESS stato, aggiungi il flag al comando. --force delete-managed-thing

    Nota

    Per Z-wave i dispositivi, è necessario mettere il dispositivo in modalità di associazione dopo aver eseguito il comando.