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
<a name="managedintegrations-sdk-v2-cookbook-ugs"></a>

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
<a name="managedintegrations-sdk-v2-cookbook-ugs-prereq"></a>

Effectuez les étapes suivantes avant de tenter d'intégrer un appareil :
+ Intégrez un appareil central au hub Managed Integrations.
+ Installez la dernière version de AWS CLI depuis le manuel [Managed Integrations AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/)
+ Abonnez-vous aux notifications d'événements [DEVICE\_DISCOVERY\_STATUS](managedintegrations-notifications.md#managedintegrations-notification-setup).

**Topics**
+ [Conditions préalables](#managedintegrations-sdk-v2-cookbook-ugs-prereq)
+ [Prérequis : activer le mode de jumelage sur votre appareil Z Wave](#managedintegrations-sdk-v2-cookbook-pairing-mode)
+ [Étape 1 : démarrer la découverte des appareils](#managedintegrations-sdk-v2-cookbook-device-discovery)
+ [Étape 2 : demander l'ID de la tâche de découverte](#managedintegrations-sdk-v2-cookbook-query-discovery)
+ [Étape 3 : créer un objet géré pour votre appareil](#managedintegrations-sdk-v2-cookbook-ugs-managed-thing)
+ [Étape 4 : Interrogez l'objet géré](#managedintegrations-sdk-v2-cookbook-query-managed-thing)
+ [Étape 5 : Bénéficiez de fonctionnalités de gestion des objets](#managedintegrations-sdk-v2-cookbook-check-device-capabilties)
+ [Étape 6 : Envoyer une commande à l'objet géré](#managedintegrations-sdk-v2-cookbook-ugs-control-device)
+ [Étape 7 : vérifier l'état de l'objet géré](#managedintegrations-sdk-v2-cookbook-ugs-device-state)
+ [Étape 8 : Supprimer l'objet géré de votre hub](#managedintegrations-sdk-v2-cookbook-ugs-clean-up)

## Prérequis : activer le mode de jumelage sur votre appareil Z Wave
<a name="managedintegrations-sdk-v2-cookbook-pairing-mode"></a>

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
<a name="managedintegrations-sdk-v2-cookbook-device-discovery"></a>

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](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) 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](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) dans le manuel Managed Integrations AWS CLI Command Reference.*

## Étape 2 : demander l'ID de la tâche de découverte
<a name="managedintegrations-sdk-v2-cookbook-query-discovery"></a>

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
<a name="managedintegrations-sdk-v2-cookbook-brand-model"></a>

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 [ListManagedThings](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListManagedThings.html#API_ListManagedThings_ResponseSyntax)réponses [ListDiscoveredDevices](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListDiscoveredDevices.html#API_ListDiscoveredDevices_ResponseSyntax)et.

Signalez le cluster d'informations de base (cluster`0x0028`) sur le point de terminaison racine de l'appareil (`0`) et cartographiez :
+ `VendorName`(attribut`0x0001`) → `Brand`
+ `ProductName`(attribut`0x0003`) → `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
<a name="managedintegrations-sdk-v2-cookbook-ugs-managed-thing"></a>

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](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/create-managed-thing.html) Command Reference. AWS CLI *

## Étape 4 : Interrogez l'objet géré
<a name="managedintegrations-sdk-v2-cookbook-query-managed-thing"></a>

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](https://docs.aws.amazon.com/iot-mi/latest/devguide/device-provisioning.html).

  **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](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing.html) Command Reference. AWS CLI *

## Étape 5 : Bénéficiez de fonctionnalités de gestion des objets
<a name="managedintegrations-sdk-v2-cookbook-check-device-capabilties"></a>

Vous pouvez consulter la liste des actions disponibles pour un objet géré en utilisant le`get-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](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-capabilities.html) dans le manuel Managed Integrations Command Reference. AWS CLI*

## Étape 6 : Envoyer une commande à l'objet géré
<a name="managedintegrations-sdk-v2-cookbook-ugs-control-device"></a>

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](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/send-managed-thing-command.html) Reference. AWS CLI *

## Étape 7 : vérifier l'état de l'objet géré
<a name="managedintegrations-sdk-v2-cookbook-ugs-device-state"></a>

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](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-state.html) dans le manuel Managed Integrations Command Reference. AWS CLI*

## Étape 8 : Supprimer l'objet géré de votre hub
<a name="managedintegrations-sdk-v2-cookbook-ugs-clean-up"></a>

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

**Pour supprimer un objet géré**
+ Utilisez la commande [delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) 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](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) Command Reference. AWS CLI *
**Note**  
Si l'appareil est bloqué dans un `DELETE_IN_PROGRESS` état, ajoutez l'`--force`indicateur à 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.