 Ver el código fuente en GitHub
|
La herramienta de aprovisionamiento de fábrica de OpenWeave proporciona un medio conveniente para aprovisionar información de configuración persistente por dispositivo en dispositivos compatibles con Weave. La herramienta de aprovisionamiento de fábrica está diseñada para usarse como parte de un proceso de línea de fabricación que marca dispositivos individuales con información de identidad y credenciales únicas antes de enviarlos a los clientes. Los desarrolladores también pueden usarlo para personalizar el hardware de preproducción que se usa durante el proceso de desarrollo.
Teoría de la operación
El objetivo de la herramienta de aprovisionamiento de fábrica de OpenWeave es insertar información de configuración seleccionada en el almacén de configuración persistente de un dispositivo, donde el firmware del dispositivo puede recuperarla y usarla durante el tiempo de ejecución. Por lo general, la configuración persistente del dispositivo se almacena en la memoria flash interna del dispositivo, aunque los detalles de cómo se almacenan los datos y en qué formato varían de una plataforma a otra. La herramienta de aprovisionamiento de fábrica es independiente del formato de almacenamiento final y se basa en el código del firmware del dispositivo para escribir los datos de la manera correcta. La interfaz de usuario de la herramienta también es independiente en gran medida del tipo de hardware que se configura, lo que significa que se pueden emplear procesos de fabricación similares en líneas de productos que se basan en diferentes plataformas de hardware.
La herramienta de aprovisionamiento de fábrica está diseñada para ejecutarse en una máquina host conectada a un dispositivo de destino a través de algún tipo de interfaz de depuración o control, por ejemplo, un puerto JTAG o SWD. La herramienta funciona inyectando información de aprovisionamiento en la RAM del dispositivo de forma especialmente codificada. Luego, se le ordena al dispositivo que se reinicie. En ese momento, el código integrado en el firmware del dispositivo localiza los datos codificados, valida su integridad y escribe los valores contenidos en el almacenamiento persistente en un formato adecuado para la plataforma.
El código integrado en el dispositivo que detecta y procesa los datos de aprovisionamiento insertados está integrado en la capa de dispositivos de OpenWeave y se puede habilitar en cualquier plataforma compatible. Una vez habilitado, el código se ejecuta automáticamente cada vez que se inicia el dispositivo, en un punto temprano del proceso de inicialización. El código funciona mediante el análisis de una región de RAM específica de la plataforma. En plataformas con aumentos modestos de memoria (por ejemplo, <1 M), el análisis abarca toda la RAM disponible.
Cuando se colocan en la RAM, los datos de aprovisionamiento se codifican con un prefijo fácil de identificar, lo que permite que se encuentren rápidamente durante el proceso de análisis. Se usa un valor de verificación de integridad basado en un hash criptográfico para confirmar la validez de los datos antes de procesarlos.
De forma predeterminada, la herramienta de aprovisionamiento selecciona la ubicación de la RAM en la que se insertarán los datos de aprovisionamiento según la plataforma del dispositivo de destino. Esta opción se puede anular a través de un argumento a la herramienta. En general, no es necesario que el firmware del dispositivo reserve una ubicación de RAM específica para recibir datos de aprovisionamiento. Por lo general, los datos de aprovisionamiento se escriben en una ubicación de RAM que se asignó para otros fines, pero que, en general, no se usa al principio del proceso de inicio del dispositivo. Las opciones comunes son la parte superior de la pila del sistema inicial o el extremo de un campo de montón.
La herramienta de aprovisionamiento de fábrica se basa en un conjunto de herramientas de desarrollo externas para interactuar con el dispositivo de destino. Las herramientas específicas que se utilizan dependen del tipo de dispositivo de destino. Actualmente, se admiten dos interfaces de dispositivos:
- Una sonda de depuración J-Link de SEGGER conectada al puerto JTAG o SWD de un dispositivo
- un puerto en serie USB conectado a un Espressif ESP32
La interfaz de J-Link se basa en la herramienta SEGGER J-Link Commander (JLinkExe), que se debe instalar por separado en la máquina host.
La interfaz ESP32 se basa en el comando esptool.py de Espressif, que se proporciona como parte del SDK de ESP-IDF de Espressif.
Tipos de información que se pueden aprovisionar
La herramienta de aprovisionamiento de fábrica de OpenWeave puede aprovisionar los siguientes tipos de información:
- Número de serie del dispositivo
- ID de dispositivo Weave asignado por el fabricante
- Certificado y clave privada de Weave asignados por el fabricante
- Código de vinculación de Weave
- Número de revisión del producto
- Fecha de fabricación
Si bien, por lo general, un dispositivo necesitará toda la información anterior para funcionar correctamente, no es necesario que aprovisione toda la información al mismo tiempo. Por lo tanto, el aprovisionamiento de diferentes tipos de información puede ocurrir en distintos puntos del proceso de fabricación. Además, es posible reemplazar los valores aprovisionados anteriormente por valores nuevos en un paso de aprovisionamiento posterior.
Fuentes de información de aprovisionamiento
La información de aprovisionamiento del dispositivo se puede suministrar a la herramienta de aprovisionamiento de fábrica de las siguientes maneras:
- Los argumentos de la línea de comandos
- Cómo usar un archivo CSV de aprovisionamiento
- Recuperando valores de un servidor de aprovisionamiento de Nest
Línea de comandos
En la forma más simple, la información de aprovisionamiento del dispositivo se especifica directamente en la línea de comandos de la herramienta de aprovisionamiento de fábrica de OpenWeave. Por ejemplo:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--pairing-code NESTUS --mfg-date 2019/04/01
Los valores de datos binarios, como el certificado y la clave privada de Weave, se pueden especificar como cadenas de base 64 o como los nombres de los archivos que contienen los datos deseados en formato sin procesar (binario).
Consulta a continuación una lista completa de los argumentos de línea de comandos disponibles.
Archivo CSV de aprovisionamiento
Para admitir el aprovisionamiento masivo de dispositivos, la herramienta de aprovisionamiento de fábrica también puede leer datos de aprovisionamiento desde un archivo de datos de aprovisionamiento con formato CSV. Se espera que las columnas de este archivo correspondan a tipos de datos de aprovisionamiento específicos, es decir, Serial_Num, Certificate, Private_Key, etc. Las filas del archivo proporcionan valores individuales para dispositivos específicos, indexados por el ID del dispositivo Weave (Device_Id). El ID del dispositivo específico que se aprovisionará se debe especificar en la línea de comandos. Por ejemplo:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--prov-csv-file ./dev-provisioning-data.csv
Se admiten las siguientes columnas CSV:
| Nombre | Formato | Descripción |
|---|---|---|
Device_Id |
16 dígitos hexadecimales | ID de dispositivo de Weave. Debe estar presente. |
Serial_Num |
string | Número de serie del dispositivo. |
Certificate |
Cadena de base 64 | Certificado de dispositivo Weave asignado por el fabricante |
Private_Key |
Cadena de base 64 | Clave privada de Weave asignada por el fabricante. |
Pairing_Code |
string | Código de vinculación de Weave. |
Product_Rev |
integer | Número de revisión del producto. |
Mfg_Date |
AAAA/MM/DD | Fecha de fabricación del dispositivo |
Las columnas pueden aparecer en el archivo CSV en cualquier orden. Todas las columnas son opcionales, excepto Device_Id. Cualquier valor que no esté presente en el archivo CSV simplemente no se aprovisiona en el dispositivo.
El usuario puede especificar valores de aprovisionamiento individuales en la línea de comandos, además del archivo CSV. En ese caso, el valor de la línea de comandos tiene prioridad sobre los del archivo.
La compatibilidad con el formato de archivo CSV de la herramienta de aprovisionamiento de fábrica es compatible con el resultado del comando gen-provisioning-data de la herramienta weave.
Servidor de aprovisionamiento de Nest
La herramienta de aprovisionamiento de fábrica admite la recuperación de información de aprovisionamiento seleccionada de un servidor de aprovisionamiento de Nest mediante un protocolo basado en HTTPS. El protocolo del servidor de aprovisionamiento se puede usar para recuperar el certificado del dispositivo Weave asignado por el fabricante, la clave privada correspondiente y el código de vinculación de Weave desde el servidor de aprovisionamiento.
Para especificar la ubicación de red del servidor de aprovisionamiento, proporciona una URL base en la línea de comandos de la herramienta de aprovisionamiento. Para seleccionar la información de aprovisionamiento deseada, especifica el ID del dispositivo Weave en la línea de comandos. Por ejemplo:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--prov-server https://192.168.172.2:8000/
El usuario puede especificar valores de aprovisionamiento individuales en la línea de comandos, además de la URL del servidor de aprovisionamiento. En este caso, los valores que se proporcionan en la línea de comandos tienen prioridad sobre los valores que muestra el servidor.
Habilita o inhabilita la compatibilidad con el aprovisionamiento de fábrica
La compatibilidad con el aprovisionamiento de fábrica de OpenWeave en el firmware del dispositivo se controla mediante la opción de configuración en tiempo de compilación WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING. Esta opción está habilitada de forma predeterminada. Para inhabilitar la función, anula la opción en el archivo WeaveProjectConfig.h de la aplicación. Por ejemplo:
#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 0
En general, es seguro habilitar el aprovisionamiento de fábrica en el firmware de dispositivos de producción siempre que la interfaz de depuración del dispositivo esté inhabilitada correctamente en dispositivos de producción. Esto se puede lograr a través de medios de hardware (por ejemplo, haciendo saltar fusibles en el SoC) o de software (por ejemplo, a través de un cargador de arranque seguro que bloquea el acceso de depuración como parte del proceso de inicio).
Cómo ejecutar la herramienta de aprovisionamiento de fábrica
La herramienta de aprovisionamiento de fábrica de OpenWeave admite las siguientes opciones de línea de comandos:
| Opción | Descripción |
|---|---|
| --target <cadena> | Tipo de dispositivo de destino. Las opciones son: nrf52840 y esp32 |
| --load-addr <hex-digits> | Es la dirección en la memoria del dispositivo en la que se escribirán los datos de aprovisionamiento. |
| --detallado, -v | Ajusta el nivel de verbosidad de la salida. Usa varios argumentos para aumentar la verbosidad. |
| --serial-num <string> | Establece el número de serie del dispositivo. |
| --device-id <hex-digits> | Establece el ID de dispositivo asignado por el fabricante. |
| --device-cert <base-64> | <nombre-del-archivo> | Establece el certificado de dispositivo Weave asignado por el fabricante. |
| --device-key <base-64> | <file-name> | Establece la clave privada del dispositivo Weave asignada por el fabricante. |
| --pairing-code <string> | Establece el código de vinculación del dispositivo. |
| --product-rev <integer> | Establece la revisión del producto para el dispositivo. |
| --mfg-date <YYYY/MM/DD> | today | now | Establece la fecha de fabricación del dispositivo. |
| --jlink-cmd <path-name> | Es la ruta de acceso al comando JLink. El valor predeterminado es “JLinkExe”. |
| --jlink-if SWD | JTAG | Tipo de interfaz J-Link. La configuración predeterminada es SWD. |
| --jlink-speed <integer> | adaptive | auto | Velocidad de la interfaz J-Link. |
| --jlink-sn <string> | Es el número de serie del sondeo J-Link. |
| --esptool-cmd <path-name> | Es la ruta de acceso al comando esptool. La configuración predeterminada es “esptool.py”. |
| --port <nombre-ruta> | Es el nombre del dispositivo del puerto COM para ESP32. El valor predeterminado es /tty/USB0. |
| --speed <integer> | Tasa de baudios para el puerto COM. El valor predeterminado es 115200. |
| --prov-csv-file <file-name> | Lee los datos de aprovisionamiento del dispositivo desde un archivo CSV de aprovisionamiento. |
| --prov-server <url> | Lee datos de aprovisionamiento de dispositivos desde un servidor de aprovisionamiento. |
| --disable-server-validation | Cuando uses HTTPS, inhabilita la validación del certificado que presenta el servidor de aprovisionamiento. |
Ejemplos
El siguiente comando establece el ID del dispositivo, el número de serie, la revisión del producto y el código de vinculación en valores específicos. La fecha de fabricación
es la fecha actual. Además, el certificado del dispositivo y la clave privada se configuran para probar valores proporcionados en un archivo CSV proporcionado con el repositorio de código fuente 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