En Google, luchamos por la equidad racial de la comunidad negra. Más información

Herramienta de aprovisionamiento de fábrica de OpenWeave

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.
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 habilitados para 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 consiste en aplicar sellos a los dispositivos individuales con información única de identidad y credenciales antes del envío a los clientes. Los desarrolladores también pueden usarla para personalizar el hardware de preproducción que se usa durante el proceso de desarrollo.

Teoría de operación

El objetivo de la herramienta de aprovisionamiento de la fábrica de OpenWeave es insertar información de configuración seleccionada en un almacén de configuración persistente de un dispositivo, en el que el firmware del dispositivo puede recogerlo y usarlo durante el tiempo de ejecución. Por lo general, la configuración de los dispositivos persistentes se almacena dentro del flash interno del dispositivo, aunque los detalles sobre cómo se almacenan exactamente 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 depende del código del firmware del dispositivo para escribir los datos de la manera correcta. La interfaz de usuario de la herramienta también depende en gran medida del tipo de hardware que se configura, lo que significa que se pueden emplear procesos de fabricación similares en todas las líneas de productos que se basan en diferentes plataformas de hardware.

La herramienta de aprovisionamiento de fábrica se diseñó para ejecutarse en una máquina anfitrión que está conectada a un dispositivo de destino a través de alguna interfaz de depuración o control; por ejemplo, un puerto JTAG o SWD. La herramienta inserta información de aprovisionamiento en la RAM del dispositivo de forma especial y codificada. Luego, se le indica al dispositivo que se reinicie, en cuyo punto el código de firmware integrado en el dispositivo localiza los datos codificados, valida su integridad y escribe los valores contenidos en un almacenamiento persistente en un formato adecuado para la plataforma.

El código 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 una etapa temprana del proceso de inicialización del dispositivo. El código funciona analizando una región de RAM específica de la plataforma. En plataformas con sencillas activaciones de memoria (por ejemplo, <1M), el análisis abarca toda la RAM disponible.

Cuando se colocan en la RAM, los datos de aprovisionamiento se codifican con un prefijo de identificación sencilla, lo que permite encontrarlos 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 RAM en la que se deben insertar los datos de aprovisionamiento según la plataforma del dispositivo de destino. Esta opción se puede anular mediante un argumento a la herramienta. En general, no es necesario que el firmware del dispositivo reserve una ubicación de RAM específicamente para recibir datos de aprovisionamiento. Por lo general, los datos de aprovisionamiento se escriben en una ubicación de RAM que se asigna para otros fines, pero, por lo general, no se usa al comienzo del proceso de inicio del dispositivo. Las opciones comunes son la parte superior de la pila inicial del sistema o el extremo más lejano de un estadio 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 empleadas dependen del tipo de dispositivo de destino. Actualmente, se admiten dos interfaces de dispositivos:

  • un sondeo de depuración J-Link de SEGGER conectado a un puerto JTAG o SWD de un dispositivo
  • Un puerto en serie USB conectado a Espressif ESP32

La interfaz J-Link se basa en la herramienta SEGGER J-Link Commander (JLinkExe), que se debe instalar por separado en la máquina anfitrión.

La interfaz del ESP32 se basa en el comando Espressif esptool.py, que se proporciona como parte del SDK de ESP-IDF de Espressif.

Tipos de información que se puede 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 del dispositivo de Weave asignado por el fabricante
  • Certificado de Weave asignado por el fabricante y clave privada
  • Código de vinculación de Weave
  • Número de revisión del producto
  • Fecha de fabricación

Si bien un dispositivo generalmente necesita toda la información anterior para funcionar correctamente, no es necesario aprovisionar toda la información al mismo tiempo. Por lo tanto, el aprovisionamiento de diferentes tipos de información puede ocurrir en distintos momentos del proceso de fabricación. Además, es posible reemplazar los valores aprovisionados con anterioridad por valores nuevos en un paso de aprovisionamiento posterior.

Fuentes de información de aprovisionamiento

La información de aprovisionamiento de dispositivos se puede proporcionar a la herramienta de aprovisionamiento de fábrica de las siguientes maneras:

  • Argumentos de la línea de comandos
  • 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 de dispositivos se especifica directamente en la línea de comandos a 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 de Weave y la clave privada, se pueden especificar como strings base66 o como nombres de archivos que contengan los datos deseados en formato sin procesar (binario).

Consulta a continuación la lista completa de argumentos de línea de comandos disponibles.

Aprovisionamiento del archivo CSV

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 en 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 de dispositivo de 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 de CSV:

Nombre Formato Descripción
Device_Id 16 dígitos hexadecimales ID de dispositivo de Weave. Debe estar presente.
Serial_Num string Es el número de serie del dispositivo.
Certificate string base 64 Certificado de dispositivo de Weave asignado por el fabricante.
Private_Key string base 64 Clave privada de Weave asignada por el fabricante.
Pairing_Code string Código de vinculación de tejido.
Product_Rev integer Es el 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, a excepción de 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 cuyo 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 de la herramienta weave y el comando gen-provisioning-data.

Servidor de aprovisionamiento de Nest

La herramienta de aprovisionamiento de fábrica admite la recuperación de información de aprovisionamiento seleccionada desde un servidor de aprovisionamiento de Nest con un protocolo basado en HTTPS. El protocolo del servidor de aprovisionamiento se puede usar para obtener el certificado del dispositivo de Weave asignado por el fabricante, la clave privada correspondiente y el código de vinculación de Weave del servidor de aprovisionamiento.

La ubicación de red del servidor de aprovisionamiento se especifica proporcionando una URL base en la línea de comandos de la herramienta de aprovisionamiento. La información de aprovisionamiento deseada se selecciona mediante la especificación del ID de dispositivo de 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 proporcionados en la línea de comandos tienen prioridad sobre los valores que muestra el servidor.

Habilitar o inhabilitar la compatibilidad con el aprovisionamiento de fábrica

La opción de configuración en el tiempo de compilación WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING controla la compatibilidad con el aprovisionamiento de fábrica de OpenWeave en el firmware del dispositivo. Esta opción está habilitada de forma predeterminada. Esta función se puede inhabilitar mediante la anulación de 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 del dispositivo de producción siempre que la interfaz de depuración del dispositivo esté inhabilitada de forma correcta. Esto se puede lograr a través de medios de hardware (por ejemplo, mediante fusibles en el SoC) o de software (por ejemplo, a través de un cargador de inicio seguro que bloquea el acceso a la depuración como parte del proceso de inicio).

Ejecuta 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 <string>; Tipo de dispositivo de destino. Las opciones son: nrf52840, esp32
--load-addr <hex-digits> 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 salida. Usa varios argumentos para aumentar la verbosidad.
--serial-num <string> Establece el número de serie del dispositivo.
--ID de dispositivo <hex-digits> Configura el ID de dispositivo asignado por el fabricante.
--device-cert <base-64> | <file-name> Configura el certificado de dispositivo de Weave asignado por el fabricante.
--device-key <base-64> | <file-name> Configura la clave privada de dispositivo de Weave asignada por el fabricante.
--sincronización-código <string> Configura el código de vinculación del dispositivo.
--product-rev <integer> Configura la revisión del producto para el dispositivo.
--mfg-date <AAAA/MM/DD> | hoy | ahora Establece la fecha de fabricación del dispositivo.
--jlink-cmd <path-name>. Ruta de acceso al comando de JLink. El valor predeterminado es &J3Exe'
--jlink-if SWD | JTAG Tipo de interfaz J-Link. La configuración predeterminada es SWD.
--jlink-speed <integer> | adaptive | auto Velocidad de la interfaz de J-Link.
--jlink-sn <string> Número de serie del sondeo de J-Link.
--esptool-cmd <path-name> Ruta de acceso al comando de esptool. El valor predeterminado es &es_tool.py'
--puerto <path-name> Nombre del dispositivo del puerto COM para ESP32. La configuración predeterminada es /tty/USB0.
--speed <integer>; Velocidad en baudios para el puerto COM El valor predeterminado es 115200.
--prov-csv-file <file-name> Lee los datos de aprovisionamiento de dispositivos desde un archivo CSV de aprovisionamiento.
--prov-server <url>; Leer datos del 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.

Examples

El siguiente comando establece el ID de dispositivo, el número de serie, la revisión del producto y el código de vinculación para valores específicos. La fecha de fabricación está establecida en la fecha actual. Además, el certificado del dispositivo y la clave privada están configurados para probar los valores proporcionados en un archivo CSV proporcionado con el repositorio de fuentes 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