![]() |
Lo strumento di provisioning di fabbrica OpenWeave offre un mezzo pratico per eseguire il provisioning di informazioni di configurazione persistenti per dispositivo sui dispositivi abilitati per Weave. Lo strumento di provisioning di fabbrica è progettato per essere utilizzato nell'ambito di una procedura della linea di produzione che appone il timbro su singoli dispositivi con informazioni univoche su identità e credenziali prima della spedizione ai clienti. Può essere utilizzato anche dagli sviluppatori per personalizzare l'hardware di preproduzione utilizzato durante il processo di sviluppo.
Teoria del funzionamento
L'obiettivo dello strumento di provisioning di fabbrica di OpenWeave è inserire informazioni di configurazione selezionate nell'archivio di configurazione permanente di un dispositivo, dove possono essere raccolte e utilizzate in fase di runtime dal firmware del dispositivo. La configurazione del dispositivo permanente viene in genere memorizzata nella memoria flash interna del dispositivo, anche se i dettagli su come vengono archiviati i dati e in quale formato variano da una piattaforma all'altra. Lo strumento di provisioning di fabbrica è indipendente dal formato di archiviazione finale e si basa sul codice nel firmware del dispositivo per scrivere i dati nel modo corretto. Anche l'interfaccia utente dello strumento è in gran parte indipendente dal tipo di hardware configurato, il che significa che è possibile utilizzare processi di produzione simili tra linee di prodotti basate su piattaforme hardware diverse.
Lo strumento di provisioning di fabbrica è progettato per funzionare su una macchina host collegata a un dispositivo di destinazione tramite una qualche forma di interfaccia di controllo o di debug, ad esempio una porta JTAG o SWD. Lo strumento funziona iniettando le informazioni di provisioning nella RAM del dispositivo in una forma codificata in modo speciale. Il dispositivo viene quindi invitato a riavviarsi, a quel punto il codice integrato nel firmware del dispositivo individua i dati codificati, ne convalida l'integrità e scrive i valori contenuti nella memoria persistente in un formato appropriato per la piattaforma.
Il codice sul dispositivo che rileva ed elabora i dati di provisioning inseriti è integrato nel livello dispositivo OpenWeave e può essere attivato su qualsiasi piattaforma supportata. Una volta attivato, il codice viene eseguito automaticamente ogni volta che il dispositivo si avvia, all'inizio della procedura di inizializzazione del dispositivo. Il codice funziona scansionando una regione della RAM specifica della piattaforma. Su piattaforme con quantità modeste di memoria (ad es. meno di 1 MB), la scansione include tutta la RAM disponibile.
Quando vengono inseriti nella RAM, i dati di provisioning vengono codificati con un prefisso facilmente identificabile, che consente di trovarli rapidamente durante la procedura di scansione. Viene utilizzato un valore di controllo dell'integrità basato su un hash crittografico per confermare la validità dei dati prima dell'elaborazione.
Per impostazione predefinita, lo strumento di provisioning seleziona la posizione della RAM in cui iniettare i dati di provisioning in base alla piattaforma del dispositivo di destinazione. Questa scelta puoi essere sostituita tramite un argomento dello strumento. In generale, non è necessario che il firmware del dispositivo prenoti una posizione RAM specifica per la ricezione dei dati di provisioning. In genere, i dati di provisioning vengono scritti in una posizione della RAM allocata per altri scopi, ma generalmente non utilizzata all'inizio della procedura di avvio del dispositivo. Le scelte più comuni sono la parte superiore dello stack di sistema iniziale o l'estremità di un'arena heap.
Lo strumento di provisioning di fabbrica si basa su un insieme di strumenti di sviluppo esterni per interfacciarsi con il dispositivo di destinazione. Gli strumenti specifici utilizzati dipendono dal tipo di dispositivo di destinazione. Al momento sono supportate due interfacce di dispositivo:
- una sonda di debug SEGGER J-Link collegata alla porta JTAG o SWD di un dispositivo
- una porta seriale USB collegata a un Espressif ESP32
L'interfaccia di J-Link si basa sullo strumento SEGGER J-Link Commander (JLinkExe), che deve essere installato separatamente sul computer host.
L'interfaccia di ESP32 si basa sul comando Espressif esptool.py fornito come parte dell'SDK ESP-IDF di Espressif.
Tipi di informazioni di cui è possibile eseguire il provisioning
Lo strumento di provisioning di fabbrica OpenWeave è in grado di fornire i seguenti tipi di informazioni:
- Numero di serie del dispositivo
- ID dispositivo Weave assegnato dal produttore
- Certificato e chiave privata Weave assegnati dal produttore
- Codice di accoppiamento Weave
- Numero di revisione del prodotto
- Data di produzione
Sebbene in genere un dispositivo abbia bisogno di tutte le informazioni sopra indicate per funzionare correttamente, non è necessario eseguire il provisioning di tutte le informazioni contemporaneamente. Pertanto, il provisioning di diversi tipi di informazioni può avvenire in punti distinti del processo di produzione. Inoltre, è possibile sostituire i valori di cui è stato eseguito il provisioning in precedenza con nuovi valori in una fase di provisioning successiva.
Fonti di informazioni di provisioning
Le informazioni di provisioning del dispositivo possono essere fornite allo strumento di provisioning di fabbrica nei seguenti modi:
- Un argomento della riga di comando
- Utilizzo di un file CSV di provisioning
- Recuperando i valori da un server di provisioning Nest
Riga di comando
Nella forma più semplice, le informazioni di provisioning del dispositivo vengono specificate direttamente nella riga di comando dello strumento di provisioning in fabbrica OpenWeave. Ad esempio:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--pairing-code NESTUS --mfg-date 2019/04/01
I valori dei dati binari, come il certificato Weave e la chiave privata, possono essere specificati come stringhe base64 o come nomi di file contenenti i dati desiderati in formato non elaborato (binario).
Di seguito è riportato un elenco completo degli argomenti della riga di comando disponibili.
Provisioning del file CSV in corso...
Per supportare il provisioning collettivo dei dispositivi, lo strumento di provisioning di fabbrica può anche leggere i dati di provisioning da un file di dati di provisioning in formato CSV. Le colonne di questo file dovrebbero corrispondere a tipi di dati di provisioning specifici, ovvero Serial_Num
, Certificate
, Private_Key
e così via.
Le righe del file forniscono singoli valori per dispositivi specifici, indicizzati dall'ID dispositivo Weave (Device_Id
). L'ID del dispositivo specifico di cui eseguire il provisioning deve essere specificato sulla riga di comando. Ad esempio:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--prov-csv-file ./dev-provisioning-data.csv
Sono supportate le seguenti colonne CSV:
Nome | Formato | Descrizione |
---|---|---|
Device_Id |
16 cifre esadecimali | ID dispositivo Weave. Deve essere presente. |
Serial_Num |
stringa | Numero di serie del dispositivo: |
Certificate |
Stringa base-64 | Certificato del dispositivo Weave assegnato dal produttore. |
Private_Key |
Stringa base-64 | Chiave privata Weave assegnata dal produttore. |
Pairing_Code |
stringa | Codice di accoppiamento Weave. |
Product_Rev |
integer | Numero di revisione del prodotto. |
Mfg_Date |
AAAA/MM/GG | Data di produzione del dispositivo. |
Le colonne possono essere visualizzate nel file CSV in qualsiasi ordine. Tutte le colonne sono facoltative, ad eccezione di Device_Id
. Eventuali valori non presenti nel file CSV
non vengono semplicemente configurati sul dispositivo.
L'utente può specificare singoli valori di provisioning nella riga di comando oltre al file CSV. In questo caso, il valore della riga di comando ha la precedenza su quelli del file.
Il formato file CSV supportato dallo strumento di provisioning in fabbrica è compatibile con l'output del comando gen-provisioning-data
dello strumento weave
.
Server di provisioning Nest
Lo strumento di provisioning di fabbrica supporta il recupero di informazioni di provisioning selezionate da un server di provisioning Nest utilizzando un protocollo basato su HTTPS. Il protocollo del server di provisioning può essere utilizzato per recuperare il certificato del dispositivo Weave assegnato dal produttore, la chiave privata corrispondente e il codice di accoppiamento Weave dal server di provisioning.
La posizione di rete del server di provisioning viene specificata fornendo un URL di base sulla riga di comando dello strumento di provisioning. Le informazioni di provisioning preferite vengono selezionate specificando l'ID dispositivo Weave sulla riga di comando. Ad esempio:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--prov-server https://192.168.172.2:8000/
L'utente può specificare singoli valori di provisioning nella riga di comando oltre all'URL del server di provisioning. In questo caso, i valori specificati nella riga di comando hanno la precedenza sui valori restituiti dal server.
Attivare / disattivare il supporto del provisioning di fabbrica
Il supporto del provisioning di fabbrica OpenWeave nel firmware del dispositivo è controllato dall'opzione di configurazione WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING
in fase di compilazione. Questa opzione è attivata per impostazione predefinita. La funzionalità può essere disabilitata eseguendo l'override dell'opzione nel file WeaveProjectConfig.h
dell'applicazione. Ad esempio:
#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 0
In generale, è consigliabile attivare il provisioning di fabbrica nel firmware del dispositivo di produzione a condizione che l'interfaccia di debug del dispositivo sia disattivata in modo appropriato sui dispositivi di produzione. Questo può avvenire tramite mezzi hardware (ad esempio bruciando i fusibili nel SoC) o nel software (ad esempio, tramite un bootloader protetto che blocca l'accesso al debug come parte del processo di avvio).
Esecuzione dello strumento di provisioning di fabbrica
Lo strumento di provisioning in fabbrica OpenWeave supporta le seguenti opzioni della riga di comando:
Opzione | Descrizione |
---|---|
--target <string> | Tipo di dispositivo di destinazione. Le opzioni sono: nrf52840, esp32 |
--load-addr <hex-digits> | Indirizzo nella memoria del dispositivo in cui verranno scritti i dati di provisioning. |
--verbose, -v | Regola il livello di dettaglio dell'output. Utilizza più argomenti per aumentare il livello di dettaglio. |
--serial-num <string> | Imposta il numero di serie del dispositivo. |
--device-id <hex-digits> | Imposta l'ID dispositivo assegnato dal produttore. |
--device-cert <base-64> | <nome-file> | Imposta il certificato del dispositivo Weave assegnato dal produttore. |
--device-key <base-64> | <file-name> | Imposta la chiave privata del dispositivo Weave assegnata dal produttore. |
--pairing-code <string> | Imposta il codice di accoppiamento del dispositivo. |
--product-rev <integer> | Imposta la revisione del prodotto per il dispositivo. |
--mfg-date <AAAA/MM/GG> | oggi | ora | Imposta la data di produzione del dispositivo. |
--jlink-cmd <path-name> | Percorso del comando JLink. Il valore predefinito è "JLinkExe". |
--jlink-if SWD | JTAG | Tipo di interfaccia J-Link. Il valore predefinito è SWD. |
--jlink-speed <integer> | adaptive | auto | velocità dell'interfaccia J-Link. |
--jlink-sn <string> | Numero di serie della sonda J-Link. |
--esptool-cmd <nome-percorso> | Percorso del comando esptool. Il valore predefinito è "esptool.py". |
--port <nome-percorso> | Nome del dispositivo della porta COM per ESP32. Il valore predefinito è /tty/USB0. |
--speed <integer> | Velocità baud per la porta COM. Il valore predefinito è 115200. |
--prov-csv-file <file-name> | Leggi i dati di provisioning del dispositivo da un file CSV di provisioning. |
--prov-server <url> | Lettura dei dati di provisioning dei dispositivi da un server di provisioning. |
--disable-server-validation | Quando utilizzi HTTPS, disattiva la convalida del certificato presentato dal server di provisioning. |
Esempi
Il seguente comando imposta l'ID dispositivo, il numero di serie, la revisione del prodotto e il codice di accoppiamento su valori specifici. La data di produzione è impostata sulla data corrente. Inoltre, il certificato del dispositivo e la chiave privata sono impostati per testare i valori specificati in un file CSV fornito con il repository di origine openweave-core
.
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000042 \
--serial-num JAYS_DEVICE_42 --product-rev 1 --pairing-code NESTUS --mfg-date today \
--prov-csv-file ~/projects/openweave-core/certs/development/device/test-dev-provisioning-data.csv