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

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

Completa questi passaggi prima di tentare l'onboard di un dispositivo:
+ Effettua l'onboarding di un dispositivo hub nell'hub Managed Integrations.
+ Installa la versione più recente di AWS CLI dal [Managed AWS CLI Integrations](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/) Command Reference
+ Iscriviti alle notifiche degli [eventi DEVICE\_DISCOVERY\_STATUS](managedintegrations-notifications.md#managedintegrations-notification-setup).

**Topics**
+ [Prerequisiti](#managedintegrations-sdk-v2-cookbook-ugs-prereq)
+ [Prerequisito: abilitare la modalità di associazione sul dispositivo Z Wave](#managedintegrations-sdk-v2-cookbook-pairing-mode)
+ [Passaggio 1: avvia l'individuazione del dispositivo](#managedintegrations-sdk-v2-cookbook-device-discovery)
+ [Passaggio 2: interrogare l'ID del processo di rilevamento](#managedintegrations-sdk-v2-cookbook-query-discovery)
+ [Passaggio 3: Crea un oggetto gestito per il tuo dispositivo](#managedintegrations-sdk-v2-cookbook-ugs-managed-thing)
+ [Passaggio 4: interroga l'oggetto gestito](#managedintegrations-sdk-v2-cookbook-query-managed-thing)
+ [Fase 5: Ottieni funzionalità gestite per gli oggetti](#managedintegrations-sdk-v2-cookbook-check-device-capabilties)
+ [Passaggio 6: invio di un comando all'oggetto gestito](#managedintegrations-sdk-v2-cookbook-ugs-control-device)
+ [Passaggio 7: verifica lo stato dell'oggetto gestito](#managedintegrations-sdk-v2-cookbook-ugs-device-state)
+ [Passaggio 8: rimuovi l'oggetto gestito dal tuo hub](#managedintegrations-sdk-v2-cookbook-ugs-clean-up)

## Prerequisito: abilitare la modalità di associazione sul dispositivo Z Wave
<a name="managedintegrations-sdk-v2-cookbook-pairing-mode"></a>

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

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

## Passaggio 2: interrogare l'ID del processo di rilevamento
<a name="managedintegrations-sdk-v2-cookbook-query-discovery"></a>

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

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

Segnala il cluster di informazioni di base (cluster`0x0028`) sull'endpoint root del dispositivo (`0`) e mappa:
+ `VendorName`(attributo`0x0001`) → `Brand`
+ `ProductName`(attributo`0x0003`) → `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
<a name="managedintegrations-sdk-v2-cookbook-ugs-managed-thing"></a>

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

## Passaggio 4: interroga l'oggetto gestito
<a name="managedintegrations-sdk-v2-cookbook-query-managed-thing"></a>

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

## Fase 5: Ottieni funzionalità gestite per gli oggetti
<a name="managedintegrations-sdk-v2-cookbook-check-device-capabilties"></a>

È possibile visualizzare un elenco delle azioni disponibili di un oggetto gestito utilizzando`get-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](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-capabilities.html) nel Managed Integrations Command Reference. AWS CLI*

## Passaggio 6: invio di un comando all'oggetto gestito
<a name="managedintegrations-sdk-v2-cookbook-ugs-control-device"></a>

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

## Passaggio 7: verifica lo stato dell'oggetto gestito
<a name="managedintegrations-sdk-v2-cookbook-ugs-device-state"></a>

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

## Passaggio 8: rimuovi l'oggetto gestito dal tuo hub
<a name="managedintegrations-sdk-v2-cookbook-ugs-clean-up"></a>

Pulisci l'hub rimuovendo l'elemento gestito.

**Per eliminare un oggetto gestito**
+ Usa il comando [delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) 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](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) 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.