View a markdown version of this page

Configura i provisionees per WiFi una configurazione semplice - Integrazioni gestite per AWS IoT Device Management
Requisiti del fornitoreRequisiti di produzioneAbilita la funzionalità di provisioningFlusso di lavoro per la scansione dei codiciFinestra di attivazione e timeoutRiprova la configurazione WSSDisabilita la funzionalità di provisioning

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

In questa pagina:

Requisiti del fornitore

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

Hardware e sicurezza

  • 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

  • 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

  • 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

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

Approvvigionamento sicuro dei materiali

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

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

Configurazione dell'account AWS:

  1. Crea endpoint personalizzati utilizzando l'API GetCustomEndpoint

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

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

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

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

Registrazione del dispositivo


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

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

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

Fase 1: Preparazione

  • 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

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

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

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

  4. L'app mobile convalida i dati scansionati

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

Elaborazione automatica nel cloud:

  1. Crea un record di oggetti gestito con configurazione WSS

  2. Attiva una finestra di configurazione di 15 minuti

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

  4. Invia notifiche di approvvigionamento a tutti i provider idonei

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

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

  2. L'utente accende il dispositivo fornito

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

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

Finestra di attivazione

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

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

  • 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

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

Riprova il flusso di lavoro

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

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

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

Utilizzo dell'API UpdateManagedThing


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

Utilizzo dell' DeleteManagedThing API


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

Confronto

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

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