OpenWeave-Bereitstellungstool

Quelle auf GitHub ansehen

Das OpenWeave Factory-Bereitstellungstool bietet eine bequeme Möglichkeit, um nichtflüchtige, gerätespezifische Konfigurationsinformationen auf Weave-fähigen Geräten bereitzustellen. Das Factory Provisioning-Tool sollte im Rahmen eines Herstellungsverfahrens verwendet werden, das einzelne Geräte vor dem Versand an die Kunden mit einer eindeutigen ID und Anmeldedaten verbindet. Außerdem kann sie von Entwicklern verwendet werden, um die während der Entwicklung verwendete Hardware aus der Vorproduktion zu personalisieren.

Betriebstheorie

Das Tool des OpenWeave Factory Provisioning soll ausgewählte Konfigurationsinformationen in den dauerhaften Konfigurationsspeicher eines Geräts einschleusen. Dieser kann während der Laufzeit von der Geräte-Firmware abgerufen und verwendet werden. Eine dauerhafte Gerätekonfiguration wird in der Regel innerhalb des internen Flashs des Geräts gespeichert. Die Details dazu, wie die Daten genau gespeichert werden und in welchem Format, sind von Plattform zu Plattform unterschiedlich. Das Factory Assist-Tool ist unabhängig vom endgültigen Speicherformat und benötigt Code in der Firmware des Geräts, um die Daten richtig zu schreiben. Die Benutzeroberfläche des Tools ist auch weitgehend unabhängig von der Hardware, die konfiguriert werden soll. Das heißt, dass ähnliche Produktionsprozesse in allen Produktlinien angewendet werden können, die auf verschiedenen Hardwareplattformen basieren.

Das Factory Provisioning-Tool wird auf einem Hostcomputer ausgeführt, der über irgendeine Form der Debug- oder Steueroberfläche, z. B. einen JTAG- oder SWD-Port, mit einem Zielgerät verbunden ist. Das Tool fügt Bereitstellungsinformationen in eine speziell codierte Form in den RAM des Geräts ein. Das Gerät wird dann aufgefordert, neu zu starten. Anschließend werden die in die Firmware des Geräts integrierten Code die codierten Daten orten, ihre Integrität validieren und die enthaltenen Werte in einem für die Plattform geeigneten Format in den nichtflüchtigen Speicher schreiben.

Der On-Device-Code, der die eingefügten Nutzerverwaltungsdaten erkennt und verarbeitet, ist in die OpenWeave-Geräteebene integriert und kann auf jeder unterstützten Plattform aktiviert werden. Sobald die Option aktiviert ist, wird der Code bei jedem Start des Geräts automatisch ausgeführt, und zwar zu einem Zeitpunkt früher in der Geräteinitialisierung. Der Code scannt eine plattformspezifische RAM-Region. Auf Plattformen mit einfachen Arbeitsspeicher-Bereitstellungen (z. B. <1M) umfasst der Scan den gesamten verfügbaren RAM.

Wenn diese Daten im RAM platziert werden, werden sie mit einem leicht identifizierbaren Präfix codiert, sodass sie während des Scanvorgangs schnell gefunden werden können. Mit einem Integritätsprüfungswert auf Basis eines kryptografischen Hashs wird die Gültigkeit der Daten vor der Verarbeitung bestätigt.

Das Nutzerverwaltungstool wählt standardmäßig den RAM-Speicherort aus, an dem die Nutzerverwaltungsdaten auf der Zielgeräteplattform eingeschleust werden sollen. Diese Auswahl kann durch ein Argument für das Tool überschrieben werden. Im Allgemeinen ist es nicht erforderlich, dass die Geräte-Firmware einen RAM-Speicherort speziell für den Empfang von Daten zur Nutzerverwaltung reserviert. Üblicherweise werden Bereitstellungsdaten in einen RAM-Speicherort geschrieben, der für andere Zwecke zugewiesen ist, aber normalerweise zu Beginn des Gerätestarts nicht verwendet wird. Häufig werden am Anfang des ersten System-Stacks oder am Ende eines Heap-Stadions verschiedene Optionen angezeigt.

Das Factory Provisioning-Tool basiert auf einer Reihe von externen Entwicklertools, um eine Verbindung zum Zielgerät herzustellen. Welche Tools verwendet werden, hängt vom Typ des Zielgeräts ab. Derzeit werden zwei Geräteschnittstellen unterstützt:

  • Eine SEGGER-J-Link-Debugging-Prüfung, die mit einem JTAG- oder SWD-Port an ein Gerät verbunden ist.
  • Einen USB-Anschluss, der mit einem Espressif ESP32 verbunden ist

Die J-Link-Schnittstelle basiert auf dem SEGGER J-Link Commander-Tool (JLinkExe), das separat auf dem Hostcomputer installiert werden muss.

Die Schnittstelle ESP32 basiert auf dem Espressif-Esptool.py-Befehl, der als Teil des Espressif SDK bereitgestellt wird.

Arten von Informationen, die bereitgestellt werden können

Das OpenWeave Factory-Bereitstellungstool 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
  • Webcode-Kopplungscode
  • Überarbeitungsnummer des Produkts
  • Herstellungsdatum

Im Allgemeinen sind alle oben genannten Informationen für ein ordnungsgemäßes Funktionieren eines Geräts erforderlich. Es ist jedoch nicht erforderlich, alle Informationen gleichzeitig bereitzustellen. Die Bereitstellung verschiedener Arten von Informationen kann also an unterschiedlichen Punkten im Herstellungsprozess erfolgen. Darüber hinaus ist es möglich, zuvor bereitgestellte Werte in einem nachfolgenden Bereitstellungsschritt durch neue Werte zu ersetzen.

Quellen von Nutzerverwaltungsinformationen

Informationen zur Gerätebereitstellung können auf die Werkseinstellungen an das Factory Tool gesendet werden:

  • Befehlszeilenargumente
  • CSV-Datei mit Nutzerverwaltung wird verwendet
  • Durch Abrufen von Werten von einem Nest-Bereitstellungsserver

Befehlszeile

In der einfachsten Form werden Gerätebereitstellungsinformationen direkt in der Befehlszeile für das OpenWeave Factory-Bereitstellungstool angegeben. Beispiel:

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --pairing-code NESTUS --mfg-date 2019/04/01

Binärdatenwerte wie das Weave-Zertifikat und der private Schlüssel können entweder als base-64-Strings oder als Namen von Dateien mit den gewünschten Daten im Rohformat angegeben werden.

Unten finden Sie eine vollständige Liste der verfügbaren Befehlszeilenargumente.

CSV-Datei wird bereitgestellt

Für die Bulk-Bereitstellung von Geräten kann das Factory Provisioning-Tool auch Bereitstellungsdaten aus einer CSV-formatierten Datendatei für die Nutzerverwaltung lesen. Die Spalten dieser Datei entsprechen normalerweise bestimmten Nutzerverwaltungsdatentypen, d. h. Serial_Num, Certificate, Private_Key usw. 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 Formatieren Beschreibung
Device_Id 16 Hexadezimalziffern Weave-Geräte-ID. Muss vorhanden sein.
Serial_Num string Geräteseriennummer
Certificate base-64-String Vom Hersteller zugewiesenes Weave-Gerätezertifikat.
Private_Key base-64-String Vom Hersteller zugewiesener privater Weave-Schlüssel.
Pairing_Code string Weben Sie den Kopplungscode.
Product_Rev integer Überarbeitungsnummer des Produkts
Mfg_Date JJJJ/MM/TT Herstellungsdatum des Geräts.

Spalten können in beliebiger Reihenfolge in der CSV-Datei enthalten sein. Alle Spalten mit Ausnahme von Device_Id sind optional. Alle Werte, die nicht in der CSV-Datei vorhanden sind, werden einfach nicht auf dem Gerät bereitgestellt.

Nutzer können neben der CSV-Datei auch einzelne Nutzerverwaltungswerte in der Befehlszeile angeben. In diesem Fall hat der Befehlszeilenwert Vorrang vor denen in der Datei.

Die Unterstützung des CSV-Dateiformats für das Factory Provisioning-Tool ist mit der Ausgabe des weave-Befehls gen-provisioning-data kompatibel.

Nest-Nutzerverwaltungsserver

Das Factory Provisioning-Tool unterstützt das Abrufen ausgewählter Nutzerverwaltungsinformationen von einem Nest-Bereitstellungsserver, der ein HTTPS-basiertes Protokoll verwendet. Das Nutzerverwaltungsserver-Protokoll kann verwendet werden, um das vom Hersteller zugewiesene Weave-Gerätezertifikat, den entsprechenden privaten Schlüssel und den Weave-Kopplungscode vom Nutzerverwaltungsserver abzurufen.

Der Netzwerkstandort des Bereitstellungsservers wird durch Angabe einer Basis-URL in der Befehlszeile des Nutzerverwaltungstools angegeben. Die gewünschten Informationen zur Bereitstellung werden durch die Angabe der Weave-Geräte-ID in der Befehlszeile ausgewählt. Beispiel:

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --prov-server https://192.168.172.2:8000/

Nutzer können zusätzlich zur URL des Nutzerverwaltungs-Servers individuelle Werte für die Befehlszeile angeben. In diesem Fall haben die in der Befehlszeile angegebenen Werte Vorrang vor den Werten, die vom Server zurückgegeben werden.

Support für Factory-Bereitstellungen aktivieren / deaktivieren

Die Unterstützung für die OpenWeave-Factory-Bereitstellung in der Geräte-Firmware wird über die Konfigurationsoption WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING kompiliert. Diese Option ist standardmäßig aktiviert. Die Funktion kann durch Überschreiben der Option in der WeaveProjectConfig.h-Datei der Anwendung deaktiviert werden. Beispiel:

#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 0

Im Allgemeinen ist es sicher, die Nutzerverwaltung für Produktionsgeräte in der Firmware des Produktionsgeräts zu aktivieren, sofern die Debug-Oberfläche des Geräts auf den Produktionsgeräten entsprechend deaktiviert wird. Das kann entweder über Hardware (z. B. das Festlegen von Sicherungen im SoC) oder über Software (z. B. über einen sicheren Bootloader, der den Zugriff während des Bootvorgangs blockiert) erfolgen.

Factory Provisioning-Tool ausführen

Das OpenWeave Factory-Bereitstellungstool unterstützt die folgenden Befehlszeilenoptionen:

Option Beschreibung
--target <string> Zielgerätetyp Auswahl: nrf52840, esp32
--load-addr <hex-Ziffern> Adresse im Gerätespeicher, unter der Nutzerverwaltungsdaten geschrieben werden.
--Ausführlich, -v Ausführlichkeit der Ausgabe anpassen. Verwenden Sie mehrere Argumente, um die Ausführlichkeit zu erhöhen.
--Seriennummer <string> Legen Sie die Seriennummer des Geräts fest.
--device-id <hex-Ziffern> Legen Sie die vom Hersteller zugewiesene Geräte-ID fest.
--device-cert <base-64> | <file-name> Legen Sie das vom Hersteller zugewiesene Weave-Gerätezertifikat fest.
--device-key <base-64> | <file-name> Legen Sie den vom Hersteller zugewiesenen privaten Weave-Schlüssel fest.
--pairing-code <string> Legen Sie den Kopplungscode für das Gerät fest.
--product-rev <integer> Legen Sie die Produktüberarbeitung 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. Die Standardeinstellung ist 'JLinkExe'.
--jlink-SWD | JTAG J-Link-Schnittstellentyp. Die Standardeinstellung ist SWD.
--jlink-speed <integer> | adaptiv | auto Die J-Link-Schnittstellengeschwindigkeit
--jlink-sn <string> J-Link-Seriennummer
--esptool-cmd <path-name> Pfad zum esptool-Befehl. Standardmäßig wird 'esptool.py' verwendet.
--port <path-name> COM-Port-Gerätename für ESP32. Der Standardwert ist /tty/USB0.
--Geschwindigkeit <integer> Baudrate für COM-Port. Der Standardwert ist 115200.
--prov-csv-file <file-name> Daten zur Gerätebereitstellung aus einer CSV-Datei für die Nutzerverwaltung lesen.
--prov-server <url> Daten zur Gerätebereitstellung von einem Bereitstellungsserver lesen.
--disable-server-validierung Wenn Sie HTTPS verwenden, deaktivieren Sie die Validierung des Zertifikats vom Nutzerverwaltungsserver.

Beispiele

Mit dem folgenden Befehl werden die Geräte-ID, die Seriennummer, die Produktüberarbeitung und der Kopplungscode auf bestimmte Werte festgelegt. Das Herstellungsdatum wird auf das aktuelle Datum festgelegt. Und das Gerätezertifikat und der private Schlüssel werden auf Testwerte gesetzt, die in einer CSV-Datei bereitgestellt werden, die im Quell-Repository 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