![]() |
Das OpenWeave Factory-Bereitstellungstool bietet eine bequeme Möglichkeit, persistente, gerätespezifische Konfigurationsinformationen auf Weave-fähigen Geräten bereitzustellen. Das Tool zur Ersteinrichtung wird als Teil eines Fertigungsprozesses verwendet, bei dem einzelne Geräte vor dem Versand an Kunden mit eindeutigen Identitäts- und Anmeldedaten versehen werden. Entwickler können damit auch Vorproduktionshardware personalisieren, die während des Entwicklungsprozesses verwendet wird.
Operationstheorie
Das Ziel des OpenWeave-Werksbereitstellungstools besteht darin, ausgewählte Konfigurationsinformationen in den persistenten Konfigurationsspeicher eines Geräts einzuschleusen, wo sie von der Gerätefirmware zur Laufzeit abgerufen und verwendet werden können. Die persistente Gerätekonfiguration wird in der Regel im internen Flash-Speicher des Geräts gespeichert. Die Details dazu, wie und in welchem Format die Daten gespeichert werden, variieren jedoch von Plattform zu Plattform. Das Tool zur Ersteinrichtung ist unabhängig vom endgültigen Speicherformat und verwendet Code in der Firmware des Geräts, um die Daten korrekt zu schreiben. Die Benutzeroberfläche des Tools ist außerdem weitgehend unabhängig von der Art der zu konfigurierenden Hardware. Dies bedeutet, dass ähnliche Fertigungsprozesse für alle Produktlinien verwendet werden können, die auf verschiedenen Hardwareplattformen basieren.
Das Tool zur werkseitigen Bereitstellung ist für die Ausführung auf einem Hostcomputer konzipiert, der über eine Art Debug- oder Steuerschnittstelle mit einem Zielgerät verbunden ist, z. B. über einen JTAG- oder SWD-Port. Das Tool funktioniert, indem es Bereitstellungsinformationen in einer speziell codierten Form in den RAM des Geräts einschleust. Das Gerät wird dann zum Neustart aufgefordert. In der Firmware des Geräts integrierte Code sucht dann nach den codierten Daten, überprüft deren Integrität und schreibt die enthaltenen Werte in einem für die Plattform geeigneten Format in den nichtflüchtigen Speicher.
Der On-Device-Code, der die bereitgestellten Bereitstellungsdaten erkennt und verarbeitet, ist in die OpenWeave-Geräteebene integriert und kann auf jeder unterstützten Plattform aktiviert werden. Nach der Aktivierung wird der Code bei jedem Start des Geräts zu einem frühen Zeitpunkt während der Geräteinitialisierung automatisch ausgeführt. Der Code scannt eine plattformspezifische RAM-Region. Auf Plattformen mit wenig Arbeitsspeicher (z. B. weniger als 1 MiB) wird der gesamte verfügbare RAM geprüft.
Wenn sie im RAM gespeichert werden, werden die Bereitstellungsdaten mit einem leicht erkennbaren Präfix codiert, damit sie beim Scanvorgang schnell gefunden werden können. Mit einem Integritätsprüfungswert, der auf einem kryptografischen Hash basiert, wird vor der Verarbeitung die Gültigkeit der Daten bestätigt.
Das Bereitstellungstool wählt standardmäßig den RAM-Speicherort aus, an dem die Bereitstellungsdaten basierend auf der Zielgeräteplattform eingefügt werden sollen. Diese Auswahl kann über ein Argument für das Tool überschrieben werden. Im Allgemeinen ist es nicht erforderlich, dass die Gerätefirmware einen RAM-Speicherort speziell für den Empfang von Bereitstellungsdaten reserviert. Normalerweise werden Bereitstellungsdaten an einen RAM-Speicherort geschrieben, der für andere Zwecke zugewiesen ist, aber in der Anfangsphase des Gerätestartvorgangs in der Regel nicht verwendet wird. Gängige Optionen sind das obere Ende des Systemstapels oder das hintere Ende einer Heap-Arena.
Das Tool zur Ersteinrichtung nutzt eine Reihe externer Entwicklungstools, um eine Verbindung zum Zielgerät herzustellen. Welche Tools verwendet werden, hängt vom Typ des Zielgeräts ab. Derzeit werden zwei Geräteoberflächen unterstützt:
- einen SEGGER J-Link-Debug-Stecker, der mit dem JTAG- oder SWD-Port eines Geräts verbunden ist
- einen USB-Serienport, der mit einem Espressif ESP32 verbunden ist
Die J-Link-Oberfläche verwendet das SEGGER J-Link Commander-Tool (JLinkExe), das separat auf dem Hostcomputer installiert werden muss.
Die ESP32-Oberfläche verwendet den Espressif-Befehl „esptool.py“, der im ESP-IDF SDK von Espressif enthalten ist.
Arten von Informationen, die bereitgestellt werden können
Das OpenWeave-Tool zur Bereitstellung von Fabrikdaten kann die folgenden Arten von Informationen bereitstellen:
- Seriennummer des Geräts
- Vom Hersteller zugewiesene Weave-Geräte-ID
- Vom Hersteller zugewiesenes Weave-Zertifikat und privater Schlüssel
- Weave-Kopplungscode
- Produktversionsnummer
- Herstellungsdatum
Obwohl ein Gerät in der Regel alle oben genannten Informationen benötigt, um ordnungsgemäß zu funktionieren, müssen nicht alle Informationen gleichzeitig bereitgestellt werden. So kann die Bereitstellung verschiedener Arten von Informationen an verschiedenen Stellen im Herstellungsprozess erfolgen. Darüber hinaus ist es möglich, zuvor bereitgestellte Werte in einem nachfolgenden Bereitstellungsschritt durch neue Werte zu ersetzen.
Quellen für Bereitstellungsinformationen
Informationen zur Gerätebereitstellung können dem Factory Provisioning Tool folgendermaßen bereitgestellt werden:
- Befehlszeilenargumente
- CSV-Datei für die Bereitstellung verwenden
- Durch Abrufen von Werten von einem Nest-Bereitstellungsserver
Befehlszeile
In der einfachsten Form werden die Informationen zur Gerätebereitstellung direkt in der Befehlszeile für das OpenWeave-Tool zur Gerätebereitstellung in der Fabrik angegeben. Beispiel:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--pairing-code NESTUS --mfg-date 2019/04/01
Binäre Datenwerte wie das Weave-Zertifikat und der private Schlüssel können entweder als Base64-Strings oder als Namen von Dateien angegeben werden, die die gewünschten Daten in Rohform (binär) enthalten.
Unten finden Sie eine vollständige Liste der verfügbaren Befehlszeilenargumente.
CSV-Datei für die Bereitstellung
Für die Bulk-Bereitstellung von Geräten kann das Tool zur Ersteinrichtung auch Bereitstellungsdaten aus einer CSV-Datei lesen. Die Spalten dieser Datei sollten bestimmten Bereitstellungsdatentypen entsprechen, z. B. Serial_Num
, Certificate
, Private_Key
usw.
Die Zeilen in der Datei enthalten individuelle Werte für bestimmte Geräte, die durch die Weave-Geräte-ID (Device_Id
) indexiert werden. Die ID des Geräts, das bereitgestellt werden soll, muss in der Befehlszeile angegeben werden. Beispiel:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--prov-csv-file ./dev-provisioning-data.csv
Die folgenden CSV-Spalten werden unterstützt:
Name | Format | Beschreibung |
---|---|---|
Device_Id |
16 Hexadezimalziffern | Weave-Geräte-ID. Müssen vorhanden sein. |
Serial_Num |
String | Seriennummer des Geräts |
Certificate |
Base64-String | Vom Hersteller zugewiesenes Weave-Gerätezertifikat. |
Private_Key |
Base64-String | Vom Hersteller zugewiesener Weave-privater Schlüssel. |
Pairing_Code |
String | Weave-Kopplungscode |
Product_Rev |
Ganzzahl | Produktversion |
Mfg_Date |
JJJJ/MM/TT | Herstellungsdatum des Geräts. |
Die Spalten können in der CSV-Datei in beliebiger Reihenfolge erscheinen. Alle Spalten mit Ausnahme von Device_Id
sind optional. Werte, die nicht in der CSV-Datei vorhanden sind, werden einfach nicht auf dem Gerät bereitgestellt.
Der Nutzer kann zusätzlich zur CSV-Datei individuelle Bereitstellungswerte in der Befehlszeile angeben. In diesem Fall hat der Befehlszeilenwert Vorrang vor den Werten in der Datei.
Das vom Factory Provisioning-Tool unterstützte CSV-Dateiformat ist mit der Ausgabe des Befehls gen-provisioning-data
des weave
-Tools kompatibel.
Nest-Bereitstellungsserver
Das Tool zur Ersteinrichtung unterstützt das Abrufen ausgewählter Bereitstellungsinformationen von einem Nest-Bereitstellungsserver über ein HTTPS-basiertes Protokoll. Mit dem Bereitstellungsserverprotokoll können das vom Hersteller zugewiesene Weave-Gerätezertifikat, der entsprechende private Schlüssel und der Weave-Kopplungscode vom Bereitstellungsserver abgerufen werden.
Der Netzwerkspeicherort des Bereitstellungsservers wird durch Angabe einer Basis-URL in der Befehlszeile des Bereitstellungstools angegeben. Die gewünschten Bereitstellungsinformationen werden ausgewählt, indem die Weave-Geräte-ID in der Befehlszeile angegeben wird. Beispiel:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--prov-server https://192.168.172.2:8000/
Der Nutzer kann zusätzlich zur URL des Bereitstellungsservers einzelne Bereitstellungswerte in der Befehlszeile angeben. In diesem Fall haben die in der Befehlszeile angegebenen Werte Vorrang vor den vom Server zurückgegebenen Werten.
Unterstützung für die werkseitige Bereitstellung aktivieren / deaktivieren
Die Unterstützung der OpenWeave-Factory-Bereitstellung in der Gerätefirmware wird durch die Konfigurationsoption WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING
für die Kompilierungszeit gesteuert. Diese Option ist standardmäßig aktiviert. Die Funktion kann deaktiviert werden, indem die Option in der Datei WeaveProjectConfig.h
der Anwendung überschrieben wird. Beispiel:
#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 0
Im Allgemeinen ist es sicher, die Bereitstellung auf Werkseinstellungen in der Produktionsfirmware des Geräts zu aktivieren, sofern die Debug-Oberfläche für Geräte auf Geräten in der Produktionsphase ordnungsgemäß deaktiviert ist. Dies kann entweder über Hardware (z. B. durch das Durchbrennen von Sicherungen im SoC) oder über Software (z. B. über einen sicheren Bootloader, der den Debugzugriff im Rahmen des Bootvorgangs blockiert) erfolgen.
Tool zur Ersteinrichtung ausführen
Das OpenWeave Factory-Bereitstellungstool unterstützt die folgenden Befehlszeilenoptionen:
Option | Beschreibung |
---|---|
--target <string> | Zielgerättyp. Mögliche Optionen: nrf52840, esp32 |
--load-addr <hexadezimal-Ziffern> | Adresse im Gerätespeicher, an die Bereitstellungsdaten geschrieben werden. |
--verbose, -v | Ausführlichkeit der Ausgabe anpassen. Verwenden Sie mehrere Argumente, um die Detaillierung zu erhöhen. |
--serial-num <string> | Legen Sie die Seriennummer des Geräts fest. |
--device-id <hexadezimal-Ziffern> | Legen Sie die vom Hersteller zugewiesene Geräte-ID fest. |
--device-cert <base-64> | <Dateiname> | Legen Sie das vom Hersteller zugewiesene Zertifikat für Weave-Geräte fest. |
--device-key <base-64> | <file-name> | Legen Sie den vom Hersteller zugewiesenen privaten Weave-Geräteschlüssel fest. |
--pairing-code <string> | Legen Sie den Code zum Koppeln des Geräts fest. |
--product-rev <integer> | Legen Sie die Produktversion für das Gerät fest. |
--mfg-date <JJJJ/MM/TT> | heute | jetzt | Legen Sie das Herstellungsdatum des Geräts fest. |
--jlink-cmd <path-name> | Pfad zum JLink-Befehl. Standardmäßig ist „JLinkExe“ festgelegt. |
--jlink-if SWD | JTAG | J-Link-Schnittstellentyp Die Standardeinstellung ist SWD. |
--jlink-speed <integer> | adaptive | auto | J-Link-Schnittstellengeschwindigkeit. |
--jlink-sn <string> | Seriennummer der J-Link-Sonde. |
--esptool-cmd <path-name> | Pfad zum Befehl „esptool“. Standardmäßig ist „esptool.py“ festgelegt. |
--port <path-name> | Gerätename des COM-Ports für ESP32. Die Standardeinstellung ist /tty/USB0. |
--speed <integer> | Baudrate für den COM-Port. Die Standardeinstellung ist 115.200. |
--prov-csv-file <file-name> | Daten zur Gerätebereitstellung aus einer CSV-Datei zur Bereitstellung lesen |
--prov-server <url> | Gerätebereitstellungsdaten von einem Bereitstellungsserver lesen |
--disable-server-validation | Deaktivieren Sie bei Verwendung von HTTPS die Validierung des vom Bereitstellungsserver vorgelegten Zertifikats. |
Beispiele
Mit dem folgenden Befehl werden die Geräte-ID, die Seriennummer, die Produktversion und der Kopplungscode auf bestimmte Werte festgelegt. Das Herstellungsdatum ist auf das aktuelle Datum eingestellt. Das Gerätezertifikat und der private Schlüssel sind auf Testwerte aus einer CSV-Datei festgelegt, die im Quellverzeichnis openweave-core
enthalten ist.
./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