Usługa IoT Plug and Play w usłudze Azure Device Update dla usługi IoT Hub
Usługa Device Update dla usługi IoT Hub używa technologii IoT Plug and Play do odnajdywania urządzeń obsługujących aktualizację za pośrednictwem powietrza i zarządzania nimi. W tym artykule opisano sposób wysyłania i odbierania właściwości i komunikatów z urządzeń za pomocą interfejsów IoT Plug and Play.
Aby uzyskać więcej informacji, zobacz przewodnik dewelopera urządzeń IoT Plug and Play i How To Build the Device Update Agent (Jak skompilować agenta aktualizacji urządzenia).
Modele aktualizacji urządzeń
Urządzenia inteligentne używają identyfikatorów modeli IoT Plug and Play do anonsowania ich możliwości w aplikacjach usługi Azure IoT. Aktualizacja urządzenia wymaga, aby inteligentne urządzenie IoT Plug and Play ogłosiło identyfikator modelu w ramach połączenia urządzenia. Aby uzyskać więcej informacji, zobacz Ogłoszenie o identyfikatorze modelu.
Usługa Device Update ma kilka zdefiniowanych modeli usługi IoT Plug and Play, które obsługują funkcje aktualizacji urządzeń. Model **dtmi:azure:iot:deviceUpdateContractModel;3** usługi Device Update obsługuje podstawowe funkcje aktualizacji urządzeń i używa podstawowego interfejsu usługi Device Update do wysyłania akcji aktualizacji i metadanych do urządzeń oraz odbierania stanu aktualizacji z urządzeń.
Innym obsługiwanym modelem jest **dtmi:azure:iot:deviceUpdateModel;3**, który rozszerza **deviceUpdateContractModel;3** , a także korzysta z interfejsów IoT Plug and Play, które wysyłają informacje o właściwości urządzenia i włączają funkcje diagnostyczne. Aby zapoznać się z tymi i innymi wersjami, zobacz Azure IoT Plug and Play Device Update Models (Modele aktualizacji urządzeń plug and play usługi Azure IoT Plug and Play).
Agent usługi Device Update używa **dtmi:azure:iot:deviceUpdateModel;3** programu , który obsługuje wszystkie najnowsze funkcje w wersji Device Update 1.1.0. Ten model obsługuje importowanie manifestu w wersji 5.0. Starsze manifesty działają z najnowszymi agentami, ale nowe funkcje wymagają najnowszej wersji manifestu.
Metadane agenta
Agent usługi Device Update używa następujących pól metadanych agenta do wysyłania informacji do usług Device Update Services.
| Nazwisko | Schemat | Kierunek | opis |
|---|---|---|---|
| deviceProperties | Mapowanie | urządzenie do chmury | Zestaw właściwości, które zawierają informacje o producentach, modelu i innych urządzeniach. Aby uzyskać szczegółowe informacje, zobacz Właściwości urządzenia. |
| compatPropertyNames | Ciąg (rozdzielony przecinkami) | urządzenie do chmury | Do pięciu właściwości używanych do sprawdzania zgodności urządzenia w celu wdrożenia aktualizacji. Przykład: "compatPropertyNames": "manufacturer,model" |
| lastInstallResult | Mapowanie | urządzenie do chmury | Wynik zgłoszony przez agenta, zawierający kod wyniku, rozszerzony kod wyniku i szczegóły wyniku dla głównej aktualizacji i innych aktualizacji kroków. |
| resultCode | integer | urządzenie do chmury | Kod zawierający informacje o wyniku ostatniej akcji aktualizacji. Może zostać wypełniony powodzeniem lub niepowodzeniem. Przykład: 700 |
| extendedResultCode | integer | urządzenie do chmury | Kod zawierający więcej informacji na temat wyniku. Może zostać wypełniony powodzeniem lub niepowodzeniem. Przykład: 0x80004005 |
| resultDetails | string | urządzenie do chmury | Podany przez użytkownika ciąg wolny, aby podać więcej szczegółów wyników. Wrócił do bliźniaczej reprezentacji bez analizowania. |
| stepResults | map | urządzenie do chmury | Wynik zgłoszony przez agenta, zawierający kod wyniku, rozszerzony kod wyniku i szczegóły wyniku dotyczące aktualizacji kroków. Przykład: "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""} |
| stan | integer | urządzenie do chmury | Liczba całkowita wskazująca bieżący stan agenta usługi Device Update. Aby uzyskać szczegółowe informacje, zobacz Stan . |
| przepływ pracy | complex | urządzenie do chmury | Zestaw wartości wskazujących wdrożenie, nad którym obecnie pracuje agent, identyfikator aktualnie zainstalowanego wdrożenia i potwierdzenie każdego żądania ponawiania próby wysłanego z usługi do agenta. Identyfikator workflow zgłasza "nodeployment" wartość po anulowaniu wdrożenia. Przykład: "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"} |
| installedUpdateId | string | urządzenie do chmury | Identyfikator aktualnie zainstalowanego wdrożenia usługi Device Update. Ta wartość przechwytuje kod JSON aktualizacji identyfikatora aktualizacji lub null urządzenia, które nigdy nie miało aktualizacji za pośrednictwem usługi Device Update. Przykład: "installedUpdateID": "{\"provider\"\"contoso\",\"name\":"image-update\",\"version\":\"1.0.0\"}" |
Przykład bliźniaczej reprezentacji urządzenia usługi IoT Hub:
"deviceUpdate": {
"__t": "c",
"agent": {
"deviceProperties": {
"manufacturer": "contoso",
"model": "virtual-vacuum-v1",
"contractModelId": "dtmi:azure:iot:deviceUpdateContractModel;3",
"aduVer": "DU;agent/1.1.0",
},
"compatPropertyNames": "manufacturer,model",
"lastInstallResult": {
"resultCode": 700,
"extendedResultCode": 0,
"resultDetails": "",
"stepResults": {
"step_0": {
"resultCode": 700,
"extendedResultCode": 0,
"resultDetails": ""
}
}
},
"state": 0,
"workflow": {
"action": 3,
"id": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01",
"retryTimestamp": "2022-01-26T11:33:29.9680598Z"
},
"installedUpdateId": "{\"provider\":\"Contoso\",\"name\":\"Virtual-Vacuum\",\"version\":\"5.0\"}"
},
Uwaga
Urządzenie lub moduł musi dodać {"__t": "c"} znacznik, aby wskazać, że element odwołuje się do składnika. Aby uzyskać więcej informacji, zobacz Konwencje IoT Plug and Play.
Właściwości urządzenia
Pole deviceProperties zawiera informacje o producencie i modelu dla urządzenia.
| Nazwisko | Schemat | Kierunek | opis |
|---|---|---|---|
| manufacturer | string | urządzenie do chmury | Producent urządzenia zgłaszany za pośrednictwem devicePropertiespolecenia .Interfejs DeviceUpdateCore najpierw próbuje odczytać aduc_manufacturer wartość z pliku konfiguracji. Jeśli wartość nie zostanie wypełniona w pliku konfiguracji, interfejs domyślnie zgłasza definicję czasu kompilacji dla elementu ADUC_DEVICEPROPERTIES_MANUFACTURER. Ta właściwość jest zgłaszana tylko w czasie rozruchu. Wartość domyślna: "Contoso" |
| model | string | urządzenie do chmury | Model urządzenia zgłoszony za pośrednictwem devicePropertieselementu . Interfejs DeviceUpdateCore najpierw próbuje odczytać aduc_model wartość z pliku konfiguracji. Jeśli wartość nie zostanie wypełniona w pliku konfiguracji, interfejs domyślnie zgłasza definicję czasu kompilacji dla elementu ADUC_DEVICEPROPERTIES_MODEL. Ta właściwość jest zgłaszana tylko w czasie rozruchu. Wartość domyślna: "Wideo" |
| contractModelId | string | urządzenie do chmury | Właściwość używana przez usługę do identyfikowania podstawowej wersji modelu używanej przez agenta usługi Device Update do zarządzania agentem i komunikowania się z nim. Wartość: dtmi:azure:iot:deviceUpdateContractModel;3 w przypadku urządzeń korzystających z agenta usługi Device Update w wersji 1.1.0. Uwaga: Agenci używający polecenia dtmi:azure:iot:deviceUpdateModel;2 muszą zgłosić element contractModelId jako dtmi:azure:iot:deviceUpdateContractModel;3, ponieważ deviceUpdateModel;3 został rozszerzony z deviceUpdateContractModel;3. |
| aduVer | string | urządzenie do chmury | Wersja agenta usługi Device Update uruchomionego na urządzeniu. Ta wartość jest odczytywana z kompilacji tylko wtedy, gdy ENABLE_ADU_TELEMETRY_REPORTING jest ustawiona na 1 wartość (true) w czasie kompilacji. Możesz zrezygnować z raportowania wersji, ustawiając wartość na 0 (false). Aby uzyskać więcej informacji, zobacz How To Build the Device Update Agent (Jak skompilować agenta aktualizacji urządzenia). |
| Dover | string | urządzenie do chmury | Wersja agenta optymalizacji dostarczania uruchomionego na urządzeniu. Wartość jest odczytywana z kompilacji tylko wtedy, gdy ENABLE_ADU_TELEMETRY_REPORTING jest ustawiona na 1 wartość (true) w czasie kompilacji. Możesz zrezygnować z raportowania wersji, ustawiając wartość na 0 (false). Aby uzyskać więcej informacji, zobacz Jak dostosować właściwości agenta optymalizacji dostarczania. |
| Niestandardowe właściwości zgodności | Zdefiniowane przez użytkownika | urządzenie do chmury | Inne właściwości urządzenia zdefiniowane przez użytkownika do użycia podczas sprawdzania zgodności podczas określania celu wdrożenia aktualizacji. |
Stan
Pole stanu to stan zgłaszany przez agenta usługi Device Update w odpowiedzi na akcję wysłaną do agenta aktualizacji urządzenia z usługi Device Update. Aby uzyskać więcej informacji na temat żądań przepływu między usługą Device Update i agentem usługi Device Update, zobacz przepływ pracy agenta.
| Nazwa/nazwisko | Wartość | Opis |
|---|---|---|
| Okresy | 0 | Urządzenie jest gotowe do otrzymania akcji z usługi Device Update. Po pomyślnej aktualizacji stan powraca do Idle stanu. |
| DeploymentInprogress | 6 | Wdrożenie jest w toku. |
| Niepowodzenie | 255 | Wystąpił błąd podczas aktualizowania. |
| DownloadSucceed | 2 | Wystąpiło pomyślne pobranie. Ten stan zgłasza tylko urządzenia z agentem w wersji 0.7.0 lub starszej. |
| InstallSucceeded | 100 | Wystąpiła pomyślna instalacja. Ten stan zgłasza tylko urządzenia z agentem w wersji 0.7.0 lub starszej. |
Akcja
Pole akcji reprezentuje akcję, którą agent usługi Device Update powinien wykonać zgodnie z instrukcją usługi Device Update. Agent usługi Device Update zgłasza stan przetwarzania odbieranej akcji. Aby uzyskać więcej informacji na temat żądań przepływu między usługą Device Update i agentem usługi Device Update, zobacz przepływ pracy agenta.
| Nazwa/nazwisko | Wartość | Opis |
|---|---|---|
| applyDeployment | 3 | Zastosuj wdrożona aktualizację. |
| Anuluj | 255 | Zatrzymaj przetwarzanie bieżącej akcji i wróć do Idle, lub poinformuj agenta Failed w stanie, aby wrócić do Idle. |
| download | 0 | Pobierz opublikowaną zawartość lub aktualizację oraz dowolną inną wymaganą zawartość. Ta akcja jest wysyłana tylko do urządzeń z agentem w wersji 0.7.0 lub starszej. |
| instalacja | 1 | Zainstaluj zawartość lub aktualizację, zazwyczaj w celu wywołania instalatora zawartości lub aktualizacji. Usługa Device Update wysyła tę akcję tylko do urządzeń z agentem w wersji 0.7.0 lub starszej. |
| apply | 2 | Finalizuj aktualizację, uruchamiając ponownie w razie potrzeby. Usługa Device Update wysyła tę akcję tylko do urządzeń z agentem w wersji 0.7.0 lub starszej. |
Metadane usługi
Metadane usługi zawierają pola używane przez usługę Device Update do przekazywania akcji i danych agentowi usługi Device Update.
| Nazwisko | Schemat | Kierunek | opis |
|---|---|---|---|
| action | integer | chmura-urządzenie | Liczba całkowita odpowiadająca akcji, którą powinien wykonać agent. Aby uzyskać szczegółowe informacje, zobacz Akcja . |
| updateManifest | string | chmura-urządzenie | Opisuje zawartość aktualizacji. Wygenerowany na podstawie manifestu importu. |
| updateManifestSignature | Obiekt JSON | chmura-urządzenie | Sygnatura internetowa JSON (JWS) z kluczami internetowymi JSON do użycia na potrzeby weryfikacji źródła. |
| fileUrls | Mapowanie | chmura-urządzenie | Mapuj na FileIDDownloadUrl. Informuje agenta, które pliki mają być pobierane, a skrót do użycia w celu sprawdzenia, czy pliki zostały pobrane poprawnie. |
Interfejs informacji o urządzeniu
Interfejs informacyjny urządzenia jest koncepcją używaną w architekturze IoT Plug and Play. Interfejs zawiera właściwości urządzenia do chmury, które zawierają informacje o sprzęcie i systemie operacyjnym urządzenia. Usługa Device Update używa DeviceInformation.manufacturer właściwości i DeviceInformation.model do telemetrii i diagnostyki. Aby zapoznać się z przykładem interfejsu informacyjnego urządzenia, zobacz https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json.
Podczas implementowania tego interfejsu oczekiwana nazwa składnika w modelu to deviceInformation. Aby uzyskać więcej informacji, zobacz przewodnik modelowania technologii IoT Plug and Play.
| Nazwisko | Typ | Schemat | Kierunek | opis | Przykład |
|---|---|---|---|---|---|
| manufacturer | Właściwości | string | urządzenie do chmury | Nazwa firmy producenta urządzenia. Producent może być taki sam jak nazwa producenta oryginalnego sprzętu (OEM). | Contoso |
| model | Właściwości | string | urządzenie do chmury | Nazwa lub identyfikator modelu urządzenia. | Urządzenie usługi IoT Edge |
| swVersion | Właściwości | string | urządzenie do chmury | Wersja oprogramowania na urządzeniu. swVersion może być wersją oprogramowania układowego. | 4.15.0-122 |
| osName | Właściwości | string | urządzenie do chmury | Nazwa systemu operacyjnego na urządzeniu. | Ubuntu Server 18.04 |
| processorArchitecture | Właściwości | string | urządzenie do chmury | Architektura procesora na urządzeniu. | ARM64 |
| processorManufacturer | Właściwości | string | urządzenie do chmury | Nazwa producenta procesora na urządzeniu. | Microsoft |
| totalStorage | Właściwości | string | urządzenie do chmury | Łączna ilość dostępnego miejsca na urządzeniu w kilobajtach. | 2048 |
| totalMemory | Właściwości | string | urządzenie do chmury | Łączna ilość dostępnej pamięci na urządzeniu w kilobajtach. | 256 |