View a markdown version of this page

Configuration guidée par l'utilisateur pour embarquer et faire fonctionner les appareils - Intégrations gérées pour AWS IoT Device Management
Conditions préalablesPrérequis : activer le mode de jumelage sur votre appareil Z WaveÉtape 1 : démarrer la découverte des appareilsÉtape 2 : demander l'ID de la tâche de découverteÉtape 3 : créer un objet géré pour votre appareilÉtape 4 : Interrogez l'objet géréÉtape 5 : Bénéficiez de fonctionnalités de gestion des objetsÉtape 6 : Envoyer une commande à l'objet géréÉtape 7 : vérifier l'état de l'objet géréÉtape 8 : Supprimer l'objet géré de votre hub

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Configuration guidée par l'utilisateur pour embarquer et faire fonctionner les appareils

Configurez vos appareils pour qu'ils soient intégrés à votre hub d'intégrations gérées en créant un objet géré et en le connectant à votre hub. Cette section décrit les étapes à suivre pour terminer le processus d'intégration de l'appareil à l'aide de la configuration guidée par l'utilisateur.

Conditions préalables

Effectuez les étapes suivantes avant de tenter d'intégrer un appareil :

Prérequis : activer le mode de jumelage sur votre appareil Z Wave

Activez le mode de jumelage sur l' Z-wave appareil. Le mode de couplage peut varier d'un Z-Wave appareil à l'autre. Reportez-vous donc aux instructions de l'appareil pour configurer correctement le mode de couplage. Il s'agit généralement d'un bouton sur lequel l'utilisateur doit appuyer.

Étape 1 : démarrer la découverte des appareils

Lancez la découverte des appareils pour votre hub afin d'obtenir un identifiant de tâche de découverte qui sera utilisé pour intégrer votre appareil.

Pour démarrer la découverte des appareils

  • Utilisez la commande start-device-discovery pour obtenir l'ID de la tâche de découverte.

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

    Réponse :

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

    Il existe des commandes distinctes pour Z-wave les appareils Zigbee.

    Pour plus d'informations, consultez l'API start-device-discovery dans le manuel Managed Integrations AWS CLI Command Reference.

Étape 2 : demander l'ID de la tâche de découverte

Utilisez la list-discovered-devices commande pour obtenir le matériel d'authentification de votre appareil.

Pour demander votre identifiant de tâche de découverte

  • Utilisez l'ID de la tâche de découverte avec la commande list-discovered-devices pour obtenir le matériel d'authentification de votre appareil.

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

Réponse :

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

Renseignez la marque et le modèle des appareils découverts

Lors de la découverte des appareils, les appareils découverts peuvent éventuellement communiquer des informations sur la marque et le modèle via le cluster Matter Basic Information. Ces valeurs sont ensuite renvoyées dans les ListManagedThingsréponses ListDiscoveredDeviceset.

Signalez le cluster d'informations de base (cluster0x0028) sur le point de terminaison racine de l'appareil (0) et cartographiez :

  • VendorName(attribut0x0001) → Brand

  • ProductName(attribut0x0003) → Model

L'exemple suivant montre comment signaler le cluster d'informations de base sur le point de terminaison racine :

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

Les deux valeurs sont des chaînes d'une longueur maximale de 32 caractères. Si le cluster d'informations de base ou l'un des attributs n'est pas indiqué, le champ correspondant est omis de la réponse.

Étape 3 : créer un objet géré pour votre appareil

Utilisez la create-managed-thing commande pour créer un objet géré pour votre appareil. Chaque appareil a besoin de son propre appareil géré.

Pour créer un objet géré

  • Utilisez la create-managed-thing commande pour créer un objet géré pour votre appareil.

    Exemple create-managed-thing

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

    Réponse :

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

    Pour plus d'informations, consultez la commande create-managed-thing dans le manuel Managed Integrations Command Reference. AWS CLI

Étape 4 : Interrogez l'objet géré

Vous pouvez vérifier si un objet géré est activé à l'aide de la get-managed-thing commande.

Pour interroger un objet géré

  • Utilisez la get-managed-thing commande pour vérifier si le statut de provisionnement de l'objet géré est défini sur. ACTIVATED Pour plus d'informations sur l'état du provisionnement, consultez la section Approvisionnement des appareils.

    Exemple get-managed-thing

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

    Réponse :

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

    Pour plus d'informations, consultez la commande get-managed-thing dans le manuel Managed Integrations Command Reference. AWS CLI

Étape 5 : Bénéficiez de fonctionnalités de gestion des objets

Vous pouvez consulter la liste des actions disponibles pour un objet géré en utilisant leget-managed-thing-capabiltiies.

Pour obtenir les fonctionnalités d'un appareil

  • Utilisez la get-managed-thing-capabilities commande pour obtenir l'ID du point de terminaison. Notez également la liste des actions possibles.

    Exemple get-managed-thing-capabilities

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

    Réponse :

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

    Pour plus d'informations, consultez la commande get-managed-thing-capabilities dans le manuel Managed Integrations Command Reference. AWS CLI

Étape 6 : Envoyer une commande à l'objet géré

Vous pouvez utiliser la commande send-managed-thing-command pour envoyer une commande d'action à bascule à votre objet géré.

Envoyez une commande à l'objet géré à l'aide d'une action de bascule.

  • Utilisez la send-managed-thing-command commande pour envoyer une commande d'action à bascule.

    Exemple 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
    Note

    Cet exemple utilise jq cli to, mais vous pouvez également transmettre la chaîne entière endpointId

    Réponse :

    {    
  "TraceId": TRACE_ID
  }

    Pour plus d'informations, consultez la commande send-managed-thing-command dans le manuel Managed Integrations Command Reference. AWS CLI

Étape 7 : vérifier l'état de l'objet géré

Vérifiez l'état de l'objet géré pour valider la réussite de l'action de bascule.

Pour vérifier l'état de l'appareil d'un objet géré

  • Utilisez la get-managed-thing-state commande pour valider la réussite de l'action de bascule.

    Exemple get-managed-thing-state

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

    Réponse :

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

    Pour plus d'informations, consultez la commande get-managed-thing-state dans le manuel Managed Integrations Command Reference. AWS CLI

Étape 8 : Supprimer l'objet géré de votre hub

Nettoyez votre hub en supprimant l'élément géré.

Pour supprimer un objet géré

  • Utilisez la commande delete-managed-thing pour supprimer un objet géré.

    Exemple delete-managed-thing

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

    Pour plus d'informations, consultez la commande delete-managed-thing dans le manuel Managed Integrations Command Reference. AWS CLI

    Note

    Si l'appareil est bloqué dans un DELETE_IN_PROGRESS état, ajoutez l'--forceindicateur à la delete-managed-thing commande.

    Note

    Pour Z-wave les appareils, vous devez mettre l'appareil en mode jumelage après avoir exécuté la commande.