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à.

# Configura i provisionees per WiFi una configurazione semplice
<a name="managedintegrations-sdk-v2-cookbook-wss-provisionee-config"></a>

**In questa pagina:**
+ [Requisiti del fornitore](#managedintegrations-sdk-v2-cookbook-wss-provisionee-requirements)
+ [Requisiti di produzione](#managedintegrations-sdk-v2-cookbook-wss-manufacturing-requirements)
+ [Abilita la funzionalità di provisioning](#managedintegrations-sdk-v2-cookbook-wss-enable-provisionee)
+ [Flusso di lavoro per la scansione dei codici](#managedintegrations-sdk-v2-cookbook-wss-barcode-scanning-workflow)
+ [Finestra di attivazione e timeout](#managedintegrations-sdk-v2-cookbook-wss-activation-window-timeouts)
+ [Riprova la configurazione WSS](#managedintegrations-sdk-v2-cookbook-wss-retry-setup)
+ [Disabilita la funzionalità di provisioning](#managedintegrations-sdk-v2-cookbook-wss-disable-provisionee)

## Requisiti del fornitore
<a name="managedintegrations-sdk-v2-cookbook-wss-provisionee-requirements"></a>

I dispositivi Provisionee devono soddisfare questi requisiti per supportare Simple Setup. WiFi 

### Hardware e sicurezza
<a name="managedintegrations-sdk-v2-cookbook-wss-provisionee-hardware"></a>
+ Integrazioni gestite Integrazione dell'SDK del dispositivo finale completata con il flag di compilazione abilitato `IOTMI_USE_WSS_PROVISIONEE`
+ Modulo di sicurezza hardware (HSM) o Trusted Platform Module (TPM) per uno storage sicuro
+ WiFi capacità di connettività
+ Potenza di elaborazione sufficiente per le operazioni crittografiche (SHA-384, HKDF)

### Materiali di autenticazione
<a name="managedintegrations-sdk-v2-cookbook-wss-authentication-materials"></a>
+ Certificato di richiesta e chiave privata archiviati in modo sicuro in HSM/TPM
+ Numero di serie unico (SN): 12-50 caratteri alfanumerici
+ Codice universale del prodotto (UPC): 12 cifre OPPURE codice articolo europeo (EAN): 13 cifre
+ Etichette con codice a barre che riportano SN e UPC/EAN (sul dispositivo o sulla confezione)

**Nota**  
**Supporto EAN:** attualmente i provider supportano solo UPC. Il supporto EAN è previsto per le versioni future. I provider supportano sia UPC che EAN.

**Importante:** il codice SN abbinato a UPC/EAN deve essere unico per oggetto gestito all'interno dell'account AWS del cliente.

### Componenti software
<a name="managedintegrations-sdk-v2-cookbook-wss-software-components"></a>
+ Implementazione CorePKCS11 Platform Abstraction Layer (PAL) che collega l'API PKCS \#11 a HSM/TPM
+ TLS 1. 2/1.3 client con funzionalità Pre-Shared Key (PSK) (porta 4433, suite di crittografia: TLS\_AES\_256\_GCM\_SHA384 o equivalente)
+ Supporto client proxy SOCKS5 (porta 1080)
+ Funzioni crittografiche per e HKDF SHA-384 

**Nota:** CorePKCS11 PAL deve interfacciarsi con l'hardware effettivo, non con l'implementazione solo software. HSM/TPM 

## Requisiti di produzione
<a name="managedintegrations-sdk-v2-cookbook-wss-manufacturing-requirements"></a>

I produttori di dispositivi devono fornire materiali e identificatori sicuri durante la produzione.

### Approvvigionamento sicuro dei materiali
<a name="managedintegrations-sdk-v2-cookbook-wss-secure-material-provisioning"></a>

**Certificato di richiesta e chiave privata:**
+ Generato durante il processo di produzione
+ Archivia in HSM o TPM (richiesto per i dispositivi di produzione)
+ Non esporre mai la chiave privata al di fuori dell'archiviazione sicura
+ Accesso tramite interfaccia PAL CorePKCS11

**Identificatori del dispositivo:**
+ Numero di serie (SN): identificatore univoco di 12-50 caratteri
+ Codice prodotto universale (UPC): codice prodotto a 12 cifre OPPURE codice prodotto europeo (EAN): codice prodotto a 13 cifre
+ Archivia in modo sicuro insieme al certificato di richiesta in HSM/TPM

### Requisiti dei codici a barre
<a name="managedintegrations-sdk-v2-cookbook-wss-barcode-requirements"></a>

**Le etichette fisiche devono includere:**
+ Codice a barre SN sul dispositivo o sulla confezione (si consiglia il formato Code 128)
+ UPC/EAN codice a barre sul dispositivo o sulla confezione (UPC-A o EAN-13 formato)
+ Etichette facilmente scansionabili (ben illuminate, focalizzate, senza ostacoli)
+ Etichette che resistono alla spedizione e alla manipolazione

### Configurazione del Fleet Provisioning
<a name="managedintegrations-sdk-v2-cookbook-wss-fleet-provisioning-setup"></a>

**Configurazione dell'account AWS:**

1. Crea endpoint personalizzati utilizzando l'API GetCustomEndpoint 

1. Crea un profilo di provisioning utilizzando l'API CreateProvisioningProfile 

1. Ottieni il certificato di richiesta e la chiave privata per la famiglia di dispositivi

1. Configura il modello Fleet Provisioning con i campi obbligatori:
   + `deviceSerialNumber`(SN)
   + `universalProductCode`(UPC) o `europeanArticleNumber` (EAN)
   + Supporto per la generazione di certificati per dispositivi
   + Registrazione degli oggetti in AWS IoT Core

## Abilita la funzionalità di provisioning
<a name="managedintegrations-sdk-v2-cookbook-wss-enable-provisionee"></a>

Abilita WSS per i dispositivi che utilizzano l' CreateManagedThing API durante il collegamento degli account.

### Registrazione del dispositivo
<a name="managedintegrations-sdk-v2-cookbook-wss-device-registration"></a>

```
{
  "role": "DEVICE",
  "credentialLockerId": "ad5cdc9f786b4dbe9490e57c0b1d900e",
  "authenticationMaterialType": "WIFI_SETUP_QR_BAR_CODE",
  "authenticationMaterial": "SN:123456789331;UPC:123456789331",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": true,
    "timeoutInMinutes": 15
  }
}
```

**Parametri:**
+ `role`: Deve essere «DISPOSITIVO» per i dispositivi forniti
+ `credentialLockerId`: associa il dispositivo alla famiglia (come il fornitore)
+ `authenticationMaterialType`: Usa «WIFI\_SETUP\_QR\_BAR\_CODE» per WSS
+ `authenticationMaterial`: UPC/EAN SN e dai codici a barre del dispositivo
+ `enableAsProvisionee`: impostato su true per attivare WSS
+ `timeoutInMinutes`: durata della finestra di attivazione (5-15 minuti, impostazione predefinita 15)

### Riprova o riattiva
<a name="managedintegrations-sdk-v2-cookbook-wss-retry-reactivate"></a>

Usa UpdateManagedThing per riprovare dopo un errore iniziale:

```
{
  "managedThingId": "existing-device-id",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": true,
    "timeoutInMinutes": 15
  }
}
```

## Flusso di lavoro per la scansione dei codici
<a name="managedintegrations-sdk-v2-cookbook-wss-barcode-scanning-workflow"></a>

Flusso di lavoro completo dall'inizio alla fine, dalla scansione dei codici a barre all'attivazione del dispositivo.

### Fase 1: Preparazione
<a name="managedintegrations-sdk-v2-cookbook-wss-preparation"></a>
+ Assicurati che l'applicazione mobile sia installata e autenticata
+ Verifica che il dispositivo del provider (hub) sia acceso e connesso
+ Assicurati che il dispositivo e l'imballaggio siano accessibili per la scansione

### Fase 2: Scansione e registrazione
<a name="managedintegrations-sdk-v2-cookbook-wss-scan-register"></a>

1. Apri l'applicazione mobile e vai alla configurazione del dispositivo

1. Scansiona il codice a barre del numero di serie (SN) del dispositivo

1. Scansiona il codice a barre Universal Product Code (UPC) o European Article Number (EAN)

1. L'app mobile convalida i dati scansionati

1. L'app mobile chiama l' CreateManagedThing API con dati scansionati e configurazione WSS

**Importante**  
**Limitazione dell'onboarding di un unico fornitore: è possibile effettuare l'onboarding** di un solo fornitore alla volta. Se esegui la scansione di più dispositivi contemporaneamente, verrà inserito solo il dispositivo scansionato più recente. Per inserire dispositivi precedentemente scansionati ma non attivati, è necessario eseguire l'operazione per riattivare la finestra `UpdateManagedThing` di configurazione.

### Fase 3: Attivazione nel cloud
<a name="managedintegrations-sdk-v2-cookbook-wss-cloud-activation"></a>

Elaborazione automatica nel cloud:

1. Crea un record di oggetti gestito con configurazione WSS

1. Attiva una finestra di configurazione di 15 minuti

1. Identifica i provider idonei (stesso blocco delle credenziali,,) `enableAsProvisioner=true` `supportAsProvisioner=true`

1. Invia notifiche di approvvigionamento a tutti i provider idonei

1. I provider creano SoftAP temporanei e si preparano per la connessione dei dispositivi

**GetManagedThing esempio di risposta:**

```
{
  "managedThingId": "device-id", 
  "role": "DEVICE",
  "credentialLockerId": "ad5cdc9f786b4dbe9490e57c0b1d900e",
  "authenticationMaterialType": "WIFI_SETUP_QR_BAR_CODE",
  "authenticationMaterial": "SN:123456789331;UPC:123456789331",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisioner": false,
    "supportAsProvisioner": false,
    "enableAsProvisionee": true,
    "wssExpirationTimeStamp": "2025-06-04T20:22:04.069610Z"
  }
}
```

**Campi chiave:**
+ `enableAsProvisionee`: dispositivo configurato per il provisioning WSS
+ `wssExpirationTimeStamp`: ora di fine della finestra di configurazione attiva (nulla se scaduta)

### Fase 4: accensione del dispositivo
<a name="managedintegrations-sdk-v2-cookbook-wss-device-power-on"></a>

1. L'app per dispositivi mobili visualizza il messaggio «Accendi subito il dispositivo»

1. L'utente accende il dispositivo fornito

1. Il flusso di lavoro WSS procede automaticamente:
   + Il dispositivo rileva il provider SoftAP
   + Autenticazione e scambio di credenziali completati
   + Il dispositivo si connette a WiFi
   + L'app per dispositivi mobili riceve una notifica di successo

## Finestra di attivazione e timeout
<a name="managedintegrations-sdk-v2-cookbook-wss-activation-window-timeouts"></a>

WSS utilizza finestre e timeout operativi limitati nel tempo per migliorare la sicurezza e gestire il provisioning.

### Finestra di attivazione
<a name="managedintegrations-sdk-v2-cookbook-wss-activation-window"></a>

**Impostazione predefinita:** 15 minuti dalla scansione del codice a barre all'attivazione del dispositivo

**Configurazione:**
+ Impostato tramite `timeoutInMinutes` parametro (intervallo: 5-15 minuti)
+ Impostazione predefinita: 15 minuti bilanciano praticità e sicurezza

**Comportamento di scadenza:**
+ I provider rimuovono il dispositivo dalla lista consentita dopo il timeout
+ Il dispositivo non può connettersi tramite WSS dopo la scadenza
+ L'utente deve scansionare nuovamente i codici a barre o chiamare per riattivarli UpdateManagedThing 

### Timeout operativi
<a name="managedintegrations-sdk-v2-cookbook-wss-operation-timeouts"></a>


**Timeout delle operazioni WSS**  

| Operation | Timeout | Comportamento | 
| --- | --- | --- | 
| SofTap discovery | 30 secondi | Riprova fino a 5 volte, quindi torna alla configurazione guidata dall'utente | 
| Approvvigionamento della flotta | 30 secondi | Riprova con un backoff esponenziale se fallisce | 
| WiFi connessione | 60 secondi | Segnala un errore e suggerisce la risoluzione dei problemi in caso di errore | 

### Best practice
<a name="managedintegrations-sdk-v2-cookbook-wss-best-practices"></a>
+ Accendi il dispositivo entro 5 minuti dalla scansione del codice a barre e posizionalo vicino alla portata del software del provider WiFi 
+ Assicurati che il provider sia acceso e collegato prima della scansione
+ Utilizza il timeout predefinito di 15 minuti, a meno che requisiti specifici non impongano diversamente

## Riprova la configurazione WSS
<a name="managedintegrations-sdk-v2-cookbook-wss-retry-setup"></a>

Se la configurazione iniziale di WSS fallisce, riprova a utilizzare l'API. UpdateManagedThing 

### Riprova il flusso di lavoro
<a name="managedintegrations-sdk-v2-cookbook-wss-retry-workflow"></a>

**Fase 1: Identificare l'errore**
+ L'app mobile riceve una notifica di errore WSS
+ Il timeout scade senza un'attivazione riuscita
+ L'utente visualizza il messaggio «Configurazione fallita» o «Riprova»

**Passaggio 2: Riprova tramite UpdateManagedThing**

```
{
  "managedThingId": "device-managed-thing-id",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": true,
    "timeoutInMinutes": 15
  }
}
```

**Fase 3: Riattivazione**
+ Il cloud riattiva la finestra di configurazione di 15 minuti
+ I provider ricreano SofTap e la voce Allowlist
+ L'utente accende il dispositivo (se non è già acceso)
+ Il flusso di lavoro WSS procede

### Scenari di nuovi tentativi comuni
<a name="managedintegrations-sdk-v2-cookbook-wss-retry-scenarios"></a>


**Scenari di nuovi tentativi WSS**  

| Scenario | Soluzione | 
| --- | --- | 
| Il dispositivo non si accende in tempo | Chiama UpdateManagedThing e accendi il dispositivo prontamente | 
| Provider non disponibile | Assicurati che l'hub sia online, quindi riprova | 
| Problemi di connettività di rete | Verifica che la rete sia stabile, quindi riprova | 
| Errore dell'utente | Riprova con il dispositivo corretto | 

**Importante:** ogni UpdateManagedThing chiamata crea una nuova finestra di 15 minuti. Dopo 3-4 errori, valuta la possibilità di controllare lo stato del provider, verificare la funzionalità del dispositivo o utilizzare la configurazione guidata dall'utente.

## Disabilita la funzionalità di provisioning
<a name="managedintegrations-sdk-v2-cookbook-wss-disable-provisionee"></a>

Disabilita o rimuovi definitivamente WSS per un dispositivo assegnato al provisioning.

### Utilizzo dell'API UpdateManagedThing
<a name="managedintegrations-sdk-v2-cookbook-wss-using-update"></a>

```
{
  "managedThingId": "device-managed-thing-id",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": false
  }
}
```

### Utilizzo dell' DeleteManagedThing API
<a name="managedintegrations-sdk-v2-cookbook-wss-using-delete"></a>

```
{
  "managedThingId": "device-managed-thing-id"
}
```

### Confronto
<a name="managedintegrations-sdk-v2-cookbook-wss-comparison"></a>


**Confronto tra Disabilita ed Elimina**  

| Azione | UpdateManagedThing | DeleteManagedThing | 
| --- | --- | --- | 
| Registrazione del dispositivo | Conservato nel cloud | Rimosso definitivamente | 
| Stato del dispositivo | Modificato in disabilitato | Non esiste più | 
| Riattivazione | Re-enable WSS in qualsiasi momento | È necessario registrare nuovamente il dispositivo | 
| Caso d'uso | Disattivazione temporanea, test | Dispositivo ritirato, incidente di sicurezza | 

### Considerazioni relative alla sicurezza
<a name="managedintegrations-sdk-v2-cookbook-wss-security-considerations"></a>

Da utilizzare disable/delete quando:
+ Rilevata attività sospetta
+ Dispositivo segnalato come rubato
+ È richiesta un'indagine sugli incidenti di sicurezza
+ Dispositivo dismesso o restituito

Dopo disabling/deleting, considera:
+ Modifica WiFi della password se le credenziali potrebbero essere state compromesse
+ Revisione delle notifiche di sicurezza per attività insolite
+ Verifica la presenza di problemi simili su altri dispositivi domestici