Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

# Configuración guiada por el usuario para incorporar y operar dispositivos
<a name="managedintegrations-sdk-v2-cookbook-ugs"></a>

Configure sus dispositivos para que se integren a su centro de integraciones gestionadas creando un elemento gestionado y conectándolo a su centro. En esta sección se describen los pasos para completar el proceso de incorporación del dispositivo mediante una configuración guiada por el usuario.

## Requisitos previos
<a name="managedintegrations-sdk-v2-cookbook-ugs-prereq"></a>

Complete estos pasos antes de intentar incorporar un dispositivo:
+ Incorpore un dispositivo hub al hub de integraciones gestionadas.
+ Instale la última versión de AWS CLI desde la Referencia de comandos de [Managed Integrations AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/)
+ Suscríbase a las notificaciones de eventos de [DEVICE\_DISCOVERY\_STATUS](managedintegrations-notifications.md#managedintegrations-notification-setup).

**Topics**
+ [Requisitos previos](#managedintegrations-sdk-v2-cookbook-ugs-prereq)
+ [Requisito previo: active el modo de emparejamiento en su dispositivo Z Wave](#managedintegrations-sdk-v2-cookbook-pairing-mode)
+ [Paso 1: iniciar la detección del dispositivo](#managedintegrations-sdk-v2-cookbook-device-discovery)
+ [Paso 2: consulte el ID del trabajo de detección](#managedintegrations-sdk-v2-cookbook-query-discovery)
+ [Paso 3: Crea un elemento gestionado para tu dispositivo](#managedintegrations-sdk-v2-cookbook-ugs-managed-thing)
+ [Paso 4: consulta el elemento gestionado](#managedintegrations-sdk-v2-cookbook-query-managed-thing)
+ [Paso 5: Obtenga las capacidades de gestión de cosas](#managedintegrations-sdk-v2-cookbook-check-device-capabilties)
+ [Paso 6: Enviar un comando al elemento gestionado](#managedintegrations-sdk-v2-cookbook-ugs-control-device)
+ [Paso 7: Compruebe el estado de las cosas gestionadas](#managedintegrations-sdk-v2-cookbook-ugs-device-state)
+ [Paso 8: Elimina lo gestionado de tu hub](#managedintegrations-sdk-v2-cookbook-ugs-clean-up)

## Requisito previo: active el modo de emparejamiento en su dispositivo Z Wave
<a name="managedintegrations-sdk-v2-cookbook-pairing-mode"></a>

Habilita el modo de emparejamiento en el Z-wave dispositivo. El modo de emparejamiento puede variar para cada Z-Wave dispositivo, así que consulta las instrucciones del dispositivo para configurar correctamente el modo de emparejamiento. Por lo general, se trata de un botón que el usuario debe pulsar. 

## Paso 1: iniciar la detección del dispositivo
<a name="managedintegrations-sdk-v2-cookbook-device-discovery"></a>

Inicie la detección de dispositivos en su hub para obtener un ID de trabajo de detección que se utilizará para integrar el dispositivo.

**Para iniciar la detección de dispositivos**
+ Utilice el comando [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) para obtener el ID del trabajo de detección.

  **Ejemplo de 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}} \
  ```

  **Respuesta**:

  ```
  {
        "Id": {{DISCOVERY_JOB_ID}},
        "StartedAt": "2025-06-03T14:43:12.726000-07:00"
    }
  ```
**nota**  
Hay comandos separados para los dispositivos Zigbee y para los dispositivos Z-wave .

  *Para obtener más información, consulte la API [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) en la Referencia de comandos de integraciones gestionadas. AWS CLI *

## Paso 2: consulte el ID del trabajo de detección
<a name="managedintegrations-sdk-v2-cookbook-query-discovery"></a>

Utilice el `list-discovered-devices` comando para obtener el material de autenticación de su dispositivo.

**Para consultar su ID de trabajo de descubrimiento**
+ Use el ID del trabajo de descubrimiento con el comando list-discovered-devices para obtener el material de autenticación de su dispositivo.

  ```
  aws iot-managed-integrations list-discovered-devices --identifier {{DISCOVERY_JOB_ID}}
  ```

**Respuesta**:

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

### Complete la marca y el modelo de los dispositivos descubiertos
<a name="managedintegrations-sdk-v2-cookbook-brand-model"></a>

Durante la detección de los dispositivos, los dispositivos detectados pueden, si lo desean, proporcionar información sobre la marca y el modelo a través del clúster de información básica de Matter. A continuación, estos valores se devuelven en las [ListManagedThings](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListManagedThings.html#API_ListManagedThings_ResponseSyntax)respuestas [ListDiscoveredDevices](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListDiscoveredDevices.html#API_ListDiscoveredDevices_ResponseSyntax)y.

Indique el clúster de información básica (clúster`0x0028`) en el punto final raíz del dispositivo (`0`) y mapee:
+ `VendorName`(atributo`0x0001`) → `Brand`
+ `ProductName`(atributo`0x0003`) → `Model`

El siguiente ejemplo muestra cómo informar sobre el clúster de información básica en el punto final raíz:

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

Ambos valores son cadenas con una longitud máxima de 32 caracteres. Si no se informa del clúster de información básica o de alguno de los atributos, el campo correspondiente se omite en la respuesta.

## Paso 3: Crea un elemento gestionado para tu dispositivo
<a name="managedintegrations-sdk-v2-cookbook-ugs-managed-thing"></a>

Usa el `create-managed-thing` comando para crear un elemento gestionado para tu dispositivo. Cada dispositivo requiere su propio dispositivo gestionado. 

**Para crear un elemento gestionado**
+ Usa el `create-managed-thing` comando para crear un elemento gestionado para tu dispositivo.

  **Ejemplo de create-managed-thing**

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

  **Respuesta**:

  ```
  {    
      "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 obtener más información, consulte el comando [create-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/create-managed-thing.html) en la Referencia de comandos de integraciones gestionadas. AWS CLI *

## Paso 4: consulta el elemento gestionado
<a name="managedintegrations-sdk-v2-cookbook-query-managed-thing"></a>

Puede comprobar si un elemento gestionado está activado mediante el `get-managed-thing` comando. 

**Para consultar un elemento gestionado**
+ Utilice el `get-managed-thing` comando para comprobar si el estado de aprovisionamiento del elemento gestionado está establecido en. `ACTIVATED` Para obtener más información sobre el estado del aprovisionamiento, consulte Aprovisionamiento de [dispositivos](https://docs.aws.amazon.com/iot-mi/latest/devguide/device-provisioning.html).

  **Ejemplo de get-managed-thing**

  ```
  aws iot-managed-integrations get-managed-thing \
    --identifier "{{DEVICE_MANAGED_THING_ID}}"
  ```

  **Respuesta**:

  ```
  {
        "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 obtener más información, consulte el comando [get-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing.html) en la Referencia de comandos de integraciones gestionadas. AWS CLI *

## Paso 5: Obtenga las capacidades de gestión de cosas
<a name="managedintegrations-sdk-v2-cookbook-check-device-capabilties"></a>

Para ver una lista de las acciones disponibles de un elemento gestionado, utilice el`get-managed-thing-capabiltiies`. 

**Para obtener las capacidades de un dispositivo**
+ Utilice el `get-managed-thing-capabilities` comando para obtener el ID del punto final. Anote también la lista de posibles acciones.

  **Ejemplo de get-managed-thing-capabilities**

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

  **Respuesta**:

  ```
  {
        "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 obtener más información, consulte el comando [get-managed-thing-capabilities](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-capabilities.html) en la Referencia de comandos de integraciones gestionadas. AWS CLI*

## Paso 6: Enviar un comando al elemento gestionado
<a name="managedintegrations-sdk-v2-cookbook-ugs-control-device"></a>

Puedes usar el comando send-managed-thing-command para enviar un comando de alternancia a tu objeto gestionado. 

**Envía un comando al elemento gestionado mediante una acción de alternancia.**
+ Usa el `send-managed-thing-command` comando para enviar un comando de alternancia.

  **Ejemplo de 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**  
En este ejemplo se usa jq cli, pero también puedes pasar la cadena completa `endpointId`

  **Respuesta**:

  ```
  {    
    "TraceId": {{TRACE_ID}}
    }
  ```

  *Para obtener más información, consulte el comando [send-managed-thing-command en la Referencia de comandos de integraciones](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/send-managed-thing-command.html) gestionadas. AWS CLI *

## Paso 7: Compruebe el estado de las cosas gestionadas
<a name="managedintegrations-sdk-v2-cookbook-ugs-device-state"></a>

Compruebe el estado del elemento gestionado para comprobar que la acción de conmutación se ha realizado correctamente.

**Para comprobar el estado del dispositivo de un elemento gestionado**
+ Usa el `get-managed-thing-state` comando para validar que la acción de alternancia se realizó correctamente.

  **Ejemplo de get-managed-thing-state**

  ```
    aws iot-managed-integrations get-managed-thing-state --managed-thing-id {{DEVICE_MANAGED_THING_ID}}
  ```

  **Respuesta**:

  ```
  {
        "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 obtener más información, consulte el comando [get-managed-thing-state](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-state.html) en la Referencia de comandos de integraciones gestionadas. AWS CLI*

## Paso 8: Elimina lo gestionado de tu hub
<a name="managedintegrations-sdk-v2-cookbook-ugs-clean-up"></a>

Limpia tu hub quitando lo gestionado.

**Para eliminar una cosa gestionada**
+ Utilice el comando [delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) para eliminar un elemento gestionado. 

  **Ejemplo de delete-managed-thing**

  ```
  aws iot-managed-integrations delete-managed-thing \
    --identifier {{MANAGED_THING_ID}}
  ```

  *Para obtener más información, consulte el comando [delete-managed-thing en la Referencia](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) de comandos de integraciones gestionadas. AWS CLI *
**nota**  
Si el dispositivo está atascado en un `DELETE_IN_PROGRESS` estado, añada la bandera al comando. `--force` `delete-managed-thing`
**nota**  
En el Z-wave caso de los dispositivos, debe poner el dispositivo en modo de emparejamiento después de ejecutar el comando.