 Wyświetl źródło w GitHubie
|
Narzędzie OpenWeave do obsługi administracyjnej fabrycznej umożliwia wygodne wdrażanie trwałych informacji o konfiguracji na urządzeniach z Weave. Narzędzie Factory do obsługi administracyjnej jest przeznaczone do stosowania w ramach linii produkcyjnej, który oznacza, że poszczególne urządzenia przed ich wysyłką do klienta nadają unikalną tożsamość i dane logowania. Deweloperzy mogą też używać tej funkcji do personalizowania przedprodukcyjnego sprzętu używanego podczas procesu tworzenia.
Teoria działania
Narzędzia OpenWeave Factory Provisioning Tool służy do wstrzykiwania wybranych informacji o konfiguracji do trwałego magazynu konfiguracji urządzenia, gdzie mogą być one pobierane i używane przez oprogramowanie układowe urządzenia w czasie działania. Trwała konfiguracja urządzenia jest zwykle przechowywana w wewnętrznej pamięci flash urządzenia, ale szczegóły dotyczące tego, jak i w jakim formacie są przechowywane, różnią się w zależności od platformy. Narzędzie do konfiguracji fabrycznej jest niezależne od ostatecznego formatu pamięci i używanie kodu w oprogramowaniu urządzenia do prawidłowego zapisywania danych. Interfejs narzędzia jest też w dużej mierze niezależny od rodzaju konfigurowanego sprzętu, co oznacza, że podobne procesy produkcyjne można stosować w różnych liniach produktów opartych na różnych platformach sprzętowych.
Narzędzie Factory Provisioning działa na hoście połączonym z urządzeniem docelowym za pomocą interfejsu debugowania lub sterowania, na przykład przez port JTAG lub SWD. Narzędzie działa poprzez wstrzyknięcie informacji o zarządzaniu w RAM urządzenia w specjalnie zakodowanej formie. Następnie urządzenie otrzymuje instrukcję ponownego uruchomienia. W tym momencie kod wbudowany w oprogramowaniu urządzenia odnajduje zakodowane dane, sprawdza ich integralność i zapisuje zawarte w nich wartości w trwałym magazynie danych w formacie odpowiednim dla danej platformy.
Kod na urządzeniu, który wykrywa i przetwarza wstrzykiwane dane obsługi administracyjnej, jest wbudowany w warstwa urządzeń OpenWeave i można go włączyć na dowolnej obsługiwanej platformie. Po włączeniu kod jest uruchamiany automatycznie przy każdym uruchomieniu urządzenia, na wczesnym etapie procesu inicjalizacji. Kod działa, skanując region pamięci RAM związany z daną platformą. Na platformach z niewielką ilością pamięci (np. poniżej 1 M) skanowanie obejmuje całą dostępną pamięć RAM.
Po umieszczeniu w pamięci RAM dane obsługi administracyjnej są kodowane za pomocą łatwo rozpoznawalnego prefiksu, który umożliwia ich szybkie znalezienie podczas skanowania. Wartość kontroli integralności oparta na skrótach kryptograficznych służy do potwierdzenia ważności danych przed przetworzeniem.
Domyślnie narzędzie do obsługi wdrażania wybiera lokalizację pamięci RAM, do której mają zostać wstrzyknięte dane wdrożeniowe, na podstawie platformy urządzenia docelowego. Ten wybór można zastąpić argumentem narzędzia. Ogólnie rzecz biorąc, nie jest wymagane, aby oprogramowanie układu scalonego urządzenia zarezerwowało miejsce w pamięci RAM na potrzeby otrzymywania danych provisioningu. Zwykle dane provisioningu są zapisywane w miejscu w pamięci RAM, które jest zarezerwowane na inne potrzeby, ale na początku procesu uruchamiania urządzenia jest zwykle nieużywane. Najczęściej wybierane są górna część początkowego stosu systemu lub dalsza część obszaru stosu.
Narzędzie fabryki do obsługi administracyjnej używa zestawu zewnętrznych narzędzi programistycznych do łączenia się z urządzeniem docelowym. Konkretne narzędzia zależą od typu urządzenia docelowego. Obecnie obsługiwane są 2 interfejsy urządzeń:
- sondy debugowania SEGGER J-Link podłączonej do portu JTAG lub SWD urządzenia;
- port szeregowy USB podłączony do Espressif ESP32
Interfejs J-Link korzysta z narzędzia SEGGER J-Link Commander (JLinkExe), które należy osobno zainstalować na hoście.
Interfejs ESP32 korzysta z polecenia Espressif esptool.py, które jest częścią pakietu SDK ESP-IDF firmy Espressif.
Rodzaje informacji, które można udostępniać
Narzędzie do obsługi fabrycznej OpenWeave umożliwia obsługę tych typów informacji:
- Numer seryjny urządzenia
- Przypisany przez producenta identyfikator urządzenia Weave
- Przypisany przez producenta certyfikat Weave i klucz prywatny
- Kod parowania Weave
- Numer wersji produktu
- Data produkcji
Chociaż do prawidłowego działania urządzenie wymaga zwykle wszystkich wymienionych powyżej informacji, nie trzeba ich udostępniać jednocześnie. W związku z tym udostępnianie różnych typów informacji może odbywać się w różnych punktach procesu produkcyjnego. Dodatkowo na kolejnym etapie obsługi administracyjnej można zastąpić wcześniej udostępnione wartości nowymi wartościami.
Źródła informacji o obsłudze administracyjnej
Informacje o provisioningu urządzenia można przesłać do narzędzia Factory Provisioning Tool w jeden z tych sposobów:
- Argumenty wiersza poleceń
- Korzystanie z pliku CSV do obsługi funkcji provisioning
- Pobieram wartości z serwera obsługi administracyjnej Nest
Wiersz poleceń
W najprostszej formie informacje o urządzeniu są podawane bezpośrednio w wierszu poleceń w narzędziu OpenWeave Factory Provisioning Tool. Na przykład:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--pairing-code NESTUS --mfg-date 2019/04/01
Wartości danych binarnych, takie jak certyfikat Weave i klucz prywatny, można określić jako ciągi tekstowe Base64 lub jako nazwy plików zawierających żądane dane w postaci nieprzetworzonej (binarnej).
Poniżej znajdziesz pełną listę dostępnych argumentów wiersza poleceń.
Plik CSV do obsługi funkcji provisioning
Aby umożliwić zbiorcze wdrożenie urządzeń, narzędzie Factory Provisioning Tool może też odczytywać dane wdrożenia z pliku danych w formacie CSV. Kolumny tego pliku powinny odpowiadać określonym typom danych konfiguracji, np. Serial_Num, Certificate, Private_Key itp. Wiersze w pliku zawierają poszczególne wartości dla konkretnych urządzeń, posortowane według identyfikatora urządzenia Weave (Device_Id). Identyfikator konkretnego urządzenia, które ma być skonfigurowane, musi być podany w wierszu poleceń. Na przykład:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--prov-csv-file ./dev-provisioning-data.csv
Obsługiwane są te kolumny CSV:
| Nazwa | Format | Opis |
|---|---|---|
Device_Id |
16 cyfr szesnastkowych | Identyfikator urządzenia Weave. To pole jest wymagane. |
Serial_Num |
ciąg znaków | Numer seryjny urządzenia. |
Certificate |
ciąg base64 | Przypisany przez producenta certyfikat urządzenia Weave. |
Private_Key |
ciąg znaków w formacie base-64, | Przypisany przez producenta klucz prywatny Weave. |
Pairing_Code |
ciąg znaków | Utkaj kod parowania. |
Product_Rev |
liczba całkowita | Numer wersji usługi. |
Mfg_Date |
RRRR/MM/DD | Data produkcji urządzenia. |
Kolumny mogą występować w dowolnej kolejności. Wszystkie kolumny są opcjonalne, z wyjątkiem kolumny Device_Id. Wartości, które nie znajdują się w pliku CSV, nie są po prostu udostępniane na urządzeniu.
Użytkownik może określić indywidualne wartości obsługiwanej funkcji w wierszu poleceń oprócz pliku CSV. W takim przypadku wartość w wierszu poleceń ma pierwszeństwo przed wartościami w pliku.
Format pliku CSV obsługiwany przez narzędzie do obsługi konfiguracji fabrycznej jest zgodny z danymi wyjściowymi polecenia gen-provisioning-data narzędzia weave.
Serwer inicjowania Nest
Narzędzie do obsługi administracyjnej obsługuje pobieranie wybranych informacji dotyczących obsługi administracyjnej z serwera obsługi administracyjnej Nest za pomocą protokołu HTTPS. Protokół serwera wdrożeniowego może służyć do pobierania z serwera wdrożeniowego przypisanego przez producenta certyfikatu urządzenia Weave, odpowiadającego mu klucza prywatnego i kodu parowania Weave.
Lokalizacja sieciowa serwera provisioning jest określana przez podanie podstawowego adresu URL w wierszu poleceń narzędzia provisioning. Wymagane informacje dotyczące obsługi administracyjnej są wybierane przez podanie identyfikatora urządzenia Weave w wierszu poleceń. Na przykład:
./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
--prov-server https://192.168.172.2:8000/
Oprócz adresu URL serwera obsługi administracyjnej użytkownik może podać także indywidualne wartości obsługi administracyjnej w wierszu poleceń. W takim przypadku wartości podane w wierszu poleceń mają pierwszeństwo przed wartościami zwracanymi przez serwer.
Włączanie i wyłączanie obsługi administracyjnej fabrycznej
Obsługa wstępnej konfiguracji OpenWeave w oprogramowaniu układowym urządzenia jest kontrolowana przez opcję konfiguracji WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONINGw czasie kompilacji. Ta opcja jest domyślnie włączona. Tę funkcję można wyłączyć, zastępując ją w pliku WeaveProjectConfig.h aplikacji. Na przykład:
#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 0
W ogóle można bezpiecznie włączyć wdrożenie fabryczne w oprogramowaniu urządzenia produkcyjnego pod warunkiem, że interfejs debugowania urządzenia jest odpowiednio wyłączony na urządzeniach produkcyjnych. Można to osiągnąć za pomocą sprzętu (np. przez przepalenie bezpieczników w układzie SoC) lub oprogramowania (np. za pomocą bezpiecznego programu ładowania, który blokuje dostęp do debugowania w ramach procesu uruchamiania).
Uruchamianie narzędzia do obsługi administracyjnej fabrycznej
Narzędzie do obsługi OpenWeave Factory obsługuje te opcje wiersza poleceń:
| Opcja | Opis |
|---|---|
| --target <string> | Typ urządzenia docelowego. Dostępne opcje: nrf52840, esp32 |
| --load-addr <hex-digits> | Adres w pamięci urządzenia, pod którym będą zapisywane dane provisioningu. |
| --verbose, -v | Dostosuj poziom szczegółowości danych wyjściowych. Użyj wielu argumentów, aby zwiększyć szczegółowość. |
| --serial-num <string> | Ustaw numer seryjny urządzenia. |
| --device-id <hex-digits> | Ustaw identyfikator urządzenia przypisany przez producenta. |
| --device-cert <base-64> | <file-name> | Ustaw przypisany przez producenta certyfikat urządzenia Weave. |
| --device-key <base-64> | <nazwa-pliku> | Ustaw klucz prywatny urządzenia Weave przypisany przez producenta. |
| --pairing-code <string> | Ustaw kod parowania urządzenia. |
| --product-rev <integer> | Ustaw wersję usługi dla urządzenia. |
| --mfg-date <RRRR/MM/DD> | dzisiaj | teraz | Ustaw datę produkcji urządzenia. |
| --jlink-cmd <nazwa-ścieżki> | Ścieżka do polecenia JLink. Domyślnie jest to „JLinkExe”. |
| --jlink-if SWD | JTAG | Typ interfejsu J-Link. Wartość domyślna to SWD. |
| --jlink-speed <integer> | adaptive | auto | Szybkość interfejsu J-Link. |
| --jlink-sn <string> | Numer seryjny sondy J-Link. |
| --esptool-cmd <path-name> | Ścieżka do polecenia esptool. Domyślnie jest to „esptool.py”. |
| --port <ścieżka> | Nazwa urządzenia portu COM dla ESP32. Wartość domyślna to /tty/USB0. |
| --speed <integer> | Prędkość transmisji portu COM. Domyślna wartość to 11 5 200. |
| --prov-csv-file <file-name> | Odczytywanie danych obsługi administracyjnej urządzeń z pliku CSV z informacjami dotyczącymi obsługi administracyjnej. |
| --prov-server <url> | odczytywanie danych obsługi administracyjnej urządzenia z serwera obsługi administracyjnej; |
| --disable-server-validation | Podczas korzystania z protokołu HTTPS wyłącz weryfikację certyfikatu przedstawionego przez serwer udostępniania. |
Przykłady
Poniższe polecenie ustawia identyfikator urządzenia, numer seryjny, wersję produktu i kod parowania na określone wartości. Data produkcji jest ustawiona na bieżącą datę. Certyfikat urządzenia i klucz prywatny mają wartości testowe podane w pliku CSV dostarczonym z repositoryum źródłowym 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