Sdílet prostřednictvím

Registrace komponent ve službě Device Update

Tento článek ukazuje ukázkovou implementaci enumerátoru komponenty služby Device Update pro IoT Hub. Na tento příklad můžete odkazovat a implementovat vlastní výčet komponent pro vaše zařízení IoT. Komponenta je jednotka pod úrovní zařízení, která má kompoziční vztah s hostitelským zařízením.

Tento článek ukazuje výčet komponent pomocí virtuálního zařízení IoT s názvem Virtuální vakuum Contoso. Enumerátory komponent se používají k implementaci funkce aktualizace proxy serveru.

Aktualizace proxy serveru umožňuje aktualizovat více komponent na stejném zařízení IoT nebo několika senzorech připojených k zařízení IoT s jedním nasazením přes vzduch. Aktualizace proxy serveru podporuje pořadí instalace pro aktualizace součástí. Podporuje také vícekrokové aktualizace s předinstalací, instalací a možnostmi po instalaci.

Případy použití, kdy se používají aktualizace proxy serveru, patří:

  • Cílení na konkrétní aktualizační soubory do oddílů na zařízení
  • Cílení konkrétních aktualizačních souborů na aplikace nebo komponenty v zařízení
  • Cílení konkrétních aktualizačních souborů na senzory připojené k IoT zařízením přes komunikační protokol (například USB nebo sběrnici CAN).

Další informace naleznete v tématu Aktualizace proxy serveru a aktualizace více komponent.

Agent Aktualizace zařízení běží na hostitelském zařízení. Může každou aktualizaci odeslat konkrétní komponentě nebo skupině komponent stejné hardwarové třídy (to znamená, že vyžaduje stejnou aktualizaci softwaru nebo firmwaru).

Co je výčet komponent?

Enumerátor součástí je rozšíření pro agenta Device Update, které poskytuje informace o každé komponentě, kterou potřebujete pro OTA aktualizaci prostřednictvím připojení hostitelského zařízení k Azure IoT Hub.

Agent Device Update je nezávislý na zařízení a komponentách. Agent sám o komponentách hostitelského zařízení nebo připojených k němu neví v době aktualizace nic.

Aby bylo možné povolit aktualizace proxy serveru, musí tvůrci zařízení identifikovat všechny komponenty v zařízení, které je možné aktualizovat, a přiřadit každému komponentě jedinečný název. Název skupiny lze také přiřadit komponentám stejné třídy hardwaru, aby stejnou aktualizaci bylo možné nainstalovat na všechny komponenty ve stejné skupině. Obslužná rutina obsahu aktualizace pak může nainstalovat a použít aktualizaci na správné součásti.

Diagram znázorňující tok aktualizace proxy serveru

Tady jsou povinnosti každé části toku aktualizace proxy serveru:

  • Tvůrce zařízení

    • Navrhujte a sestavte zařízení.

    • Integrujte agenta Device Update a jeho závislosti.

    • Implementujte rozšíření enumerátoru pro konkrétní zařízení a zaregistrujte se v agentu Device Update.

      Enumerátor komponenty používá informace z inventáře součástí nebo konfiguračního souboru k rozšíření dat statických komponent (vyžaduje se aktualizace zařízení) dynamickými daty (například verze firmwaru, stav připojení a identita hardwaru).

    • Vytvořte aktualizaci proxy serveru, která obsahuje jednu nebo více podřízených aktualizací, které cílí na jednu nebo více komponent v zařízení (nebo k němu připojené).

    • Odešlete aktualizaci operátoru řešení.

  • Operátor řešení

    • Naimportujte aktualizaci a manifest do služby Device Update.

    • Nasaďte aktualizaci do skupiny zařízení.

  • Agent aktualizace zařízení

    • Získejte informace o aktualizaci ze služby IoT Hub prostřednictvím dvojčete zařízení či modulu.

    • Vyvolejte obsluhu kroků ke zpracování aktualizace proxy určené pro jednu nebo více komponent zařízení.

      Příklad v tomto článku obsahuje dvě aktualizace: host-fw-1.1 a motors-fw-1.1. Pro každou podřízenou aktualizaci vyvolá obslužná rutina nadřazených kroků obslužnou rutinu podřízených kroků k vytvoření výčtu všech komponent, které odpovídají Compatibilities vlastnostem zadaným v souboru manifestu podřízené aktualizace. Dále obslužná rutina stáhne, nainstaluje a použije podřízenou aktualizaci na všechny cílové komponenty.

      Pokud chcete získat odpovídající komponenty, podřízená aktualizace volá SelectComponents rozhraní API poskytované enumerátorem komponenty. Pokud neexistují žádné odpovídající komponenty, podřízená aktualizace se přeskočí.

    • Shromážděte všechny výsledky aktualizací z nadřazených a podřízených aktualizací a nahlašte tyto výsledky do IoT Hubu.

  • Správce dětských kroků

    • Iterujte seznamem instancí komponent, které jsou kompatibilní s podřízeným obsahem aktualizace. Další informace naleznete v tématu Kroky obslužné rutiny.

V produkčním prostředí můžou tvůrci zařízení používat existující obslužné rutiny nebo implementovat vlastní obslužnou rutinu, která vyvolá jakýkoli instalační program potřebný k aktualizaci přes vzduch. Další informace naleznete v tématu Implementace vlastní obslužné rutiny pro aktualizaci obsahu.

Virtuální vakuové komponenty

V tomto článku používáme virtuální zařízení IoT k předvedení klíčových konceptů a funkcí. Virtuální vakuové zařízení Contoso se skládá z pěti logických komponent:

  • Firmware hostitele
  • Hostitelský spouštěcí systém souborů
  • Kořenový souborový systém hostitele
  • Tři motory (levé kolo, pravé kolo a vakuum)
  • Dvě kamery (přední a zadní)

Diagram znázorňující komponenty virtuálního vakua Contoso

Následující adresářová struktura simuluje komponenty:

/usr/local/contoso-devices/vacuum-1/hostfw
/usr/local/contoso-devices/vacuum-1/bootfs
/usr/local/contoso-devices/vacuum-1/rootfs
/usr/local/contoso-devices/vacuum-1/motors/0   /* left motor */
/usr/local/contoso-devices/vacuum-1/motors/1   /* right motor */
/usr/local/contoso-devices/vacuum-1/motors/2   /* vacuum motor */
/usr/local/contoso-devices/vacuum-1/cameras/0  /* front camera */
/usr/local/contoso-devices/vacuum-1/cameras/1  /* rear camera */

Adresář každé komponenty obsahuje soubor JSON, který ukládá číslo napodobené verze softwaru každé komponenty. Ukázkové soubory JSON jsou firmware.json a diskimage.json.

V této ukázce budeme kvůli aktualizaci firmwaru komponent kopírovat firmware.json nebo diskimage.json (aktualizovat datovou část) do adresáře cílových komponent.

Tady je příklad souboru firmware.json :

{
    "version": "0.5",
    "description": "This component is generated for testing purposes."
}

Poznámka:

Contoso Virtual Vacuum obsahuje verze softwaru nebo firmwaru pro účely předvedení aktualizace proxy. Neposkytuje žádné další funkce.

Implementace enumerátoru komponent (jazyk C)

Požadavky

Implementujte všechna rozhraní API deklarovaná v component_enumerator_extension.hpp:

Funkce Argumenty Návraty
char* GetAllComponents() Žádné Řetězec JSON, který obsahuje pole všechComponentInfo hodnot. Další informace najdete v tématu Příklad návratových hodnot.
char* SelectComponents(char* selector) Řetězec JSON, který obsahuje jeden nebo více párů názvů a hodnot používaných pro výběr cílových komponent aktualizace Řetězec JSON, který obsahuje pole ComponentInfo hodnot. Další informace najdete v tématu Příklad návratových hodnot.
void FreeComponentsDataString(char* string) Ukazatel na vyrovnávací paměť řetězce vrácenou dříve funkcí GetAllComponents nebo SelectComponents Žádné

Informace o komponentě

Řetězec ComponentInfo JSON musí obsahovat následující vlastnosti:

Název Typ Popis
id řetězec Jedinečná identita komponenty (obor zařízení). Mezi příklady patří sériové číslo hardwaru, ID oddílu disku a jedinečná cesta k souboru komponenty.
name řetězec Logický název komponenty. Tato vlastnost je název, který tvůrce zařízení přiřadí komponentě, která je k dispozici v každém zařízení stejné device třídy.

Například každé zařízení Contoso Virtual Vacuum obsahuje motor, který řídí levé kolo. Společnost Contoso přiřadil levý motor jako běžný (logický) název tohoto motoru, který umožňuje snadno odkazovat na tuto komponentu místo ID hardwaru, což může být globálně jedinečné.
group řetězec Skupina, do které tato komponenta patří.

Například všechny motory můžou patřit do skupiny motorů .
manufacturer řetězec Pro fyzickou hardwarovou komponentu je tato vlastnost výrobcem nebo názvem dodavatele.

Například pro logickou komponentu, jako je diskový oddíl nebo adresář, může být použita hodnota definovaná výrobcem zařízení.
model řetězec Pro fyzickou hardwarovou komponentu je tato vlastnost název modelu.

Pro logickou komponentu, například diskový oddíl nebo adresář, může být tato vlastnost definovaná hodnotou libovolného tvůrce zařízení.
properties objekt Objekt JSON, který obsahuje volitelné vlastnosti specifické pro zařízení.

Tady je příklad ComponentInfo kódu založeného na komponentách virtuálního vakua Contoso:

{
    "id": "contoso-motor-serial-00000",
    "name": "left-motor",
    "group": "motors",
    "manufacturer": "contoso",
    "model": "virtual-motor",
    "properties": {
        "path": "\/usr\/local\/contoso-devices\/vacuum-1\/motors\/0",
        "firmwareDataFile": "firmware.json",
        "status": "connected",
        "version" : "motor-fw-1.0"
    }
}

Příklad návratových hodnot

Následuje dokument JSON vrácený z GetAllComponents funkce. Je založená na ukázkové implementaci enumerátoru komponenty Contoso Virtual Vacuum.

{
    "components": [
        {
            "id": "hostfw",
            "name": "hostfw",
            "group": "firmware",
            "manufacturer": "contoso",
            "model": "virtual-firmware",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/hostfw",
                "firmwareDataFile": "firmware.json",
                "status": "ok",
                "version" : "host-fw-1.0"
            }
        },
        {
            "id": "bootfs",
            "name": "bootfs",
            "group": "boot-image",
            "manufacturer": "contoso",
            "model": "virtual-disk",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/bootfs",
                "firmwareDataFile": "diskimage.json",
                "status": "ok",
                "version" : "boot-fs-1.0"
            }
        },
        {
            "id": "rootfs",
            "name": "rootfs",
            "group": "os-image",
            "manufacturer": "contoso",
            "model": "virtual-os",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/rootfs",
                "firmwareDataFile": "diskimage.json",
                "status": "ok",
                "version" : "root-fs-1.0"
            }
        },
        {
            "id": "contoso-motor-serial-00000",
            "name": "left-motor",
            "group": "motors",
            "manufacturer": "contoso",
            "model": "virtual-motor",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/motors\/0",
                "firmwareDataFile": "firmware.json",
                "status": "ok",
                "version" : "motor-fw-1.0"
            }
        },
        {
            "id": "contoso-motor-serial-00001",
            "name": "right-motor",
            "group": "motors",
            "manufacturer": "contoso",
            "model": "virtual-motor",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/motors\/1",
                "firmwareDataFile": "firmware.json",
                "status": "ok",
                "version" : "motor-fw-1.0"
            }
        },
        {
            "id": "contoso-motor-serial-00002",
            "name": "vacuum-motor",
            "group": "motors",
            "manufacturer": "contoso",
            "model": "virtual-motor",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/motors\/2",
                "firmwareDataFile": "firmware.json",
                "status": "ok",
                "version" : "motor-fw-1.0"
            }
        },
        {
            "id": "contoso-camera-serial-00000",
            "name": "front-camera",
            "group": "cameras",
            "manufacturer": "contoso",
            "model": "virtual-camera",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/camera\/0",
                "firmwareDataFile": "firmware.json",
                "status": "ok",
                "version" : "camera-fw-1.0"
            }
        },
        {
            "id": "contoso-camera-serial-00001",
            "name": "rear-camera",
            "group": "cameras",
            "manufacturer": "contoso",
            "model": "virtual-camera",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/camera\/1",
                "firmwareDataFile": "firmware.json",
                "status": "ok",
                "version" : "camera-fw-1.0"
            }
        }
    ]
}

Následující dokument JSON se vrátí z SelectComponents funkce. Je založená na ukázkové implementaci enumerátoru komponenty Contoso.

Tady je vstupní parametr pro výběr skupiny komponent motorů :

{
    "group" : "motors"
}

Tady je výstup parametru. Všechny komponenty patří do skupiny motorů .

{
    "components": [
        {
            "id": "contoso-motor-serial-00000",
            "name": "left-motor",
            "group": "motors",
            "manufacturer": "contoso",
            "model": "virtual-motor",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/motors\/0",
                "firmwareDataFile": "firmware.json",
                "status": "ok",
                "version" : "motor-fw-1.0"
            }
        },
        {
            "id": "contoso-motor-serial-00001",
            "name": "right-motor",
            "group": "motors",
            "manufacturer": "contoso",
            "model": "virtual-motor",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/motors\/1",
                "firmwareDataFile": "firmware.json",
                "status": "ok",
                "version" : "motor-fw-1.0"
            }
        },
        {
            "id": "contoso-motor-serial-00002",
            "name": "vacuum-motor",
            "group": "motors",
            "manufacturer": "contoso",
            "model": "virtual-motor",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/motors\/2",
                "firmwareDataFile": "firmware.json",
                "status": "ok",
                "version" : "motor-fw-1.0"
            }
        }
    ]
}

Tady je vstupní parametr pro výběr jedné komponenty s názvem hostfw:

{
    "name" : "hostfw"
}

Tady je výstup parametru pro komponentu hostfw :

{
    "components": [
        {
            "id": "hostfw",
            "name": "hostfw",
            "group": "firmware",
            "manufacturer": "contoso",
            "model": "virtual-firmware",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/hostfw",
                "firmwareDataFile": "firmware.json",
                "status": "ok",
                "version" : "host-fw-1.0"
            }
        }
    ]
}

Poznámka:

Předchozí příklad ukázal, že v případě potřeby je možné odeslat novější aktualizaci na libovolnou instanci komponenty, která je vybrána vlastností name . Například nasaďte motor-fw-2.0 aktualizaci na vakuový motor a pokračujte v používání motor-fw-1.0 na levém a pravém motoru.

Inventarizační soubor

Ukázková implementace uvedená dříve pro enumerátor virtuálních součástí Contoso virtual Vacuum načte informace o komponentách specifických pro zařízení ze souboru component-inventory.json . Tato ukázková implementace je určena pouze pro demonstrační účely.

V produkčním scénáři by se některé vlastnosti měly načíst přímo ze skutečných součástí. Mezi tyto vlastnosti patří id, manufacturera model.

Tvůrce zařízení definuje name vlastnosti a group vlastnosti. Tyto hodnoty by se neměly po definování měnit. Vlastnost name musí být v rámci zařízení jedinečná.

Příklad souboru component-inventory.json

Poznámka:

Obsah v tomto souboru vypadá téměř stejně jako vrácená hodnota funkce GetAllComponents . ComponentInfo V tomto souboru ale neobsahuje version a status vlastnosti. Enumerátor komponenty naplní tyto vlastnosti za běhu.

Například pro hostfw se hodnota vlastnosti naplní ze zadané hodnoty (napodobení) properties.version (firmwareDataFile).

{
    "components": [
        {
            "id": "hostfw",
            "name": "hostfw",
            "group": "firmware",
            "manufacturer": "contoso",
            "model": "virtual-firmware",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/hostfw",
                "firmwareDataFile": "firmware.json",
            }
        },
        {
            "id": "bootfs",
            "name": "bootfs",
            "group": "boot-image",
            "manufacturer": "contoso",
            "model": "virtual-disk",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/bootfs",
                "firmwareDataFile": "diskimage.json",
            }
        },
        {
            "id": "rootfs",
            "name": "rootfs",
            "group": "os-image",
            "manufacturer": "contoso",
            "model": "virtual-os",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/rootfs",
                "firmwareDataFile": "diskimage.json",
            }
        },
        {
            "id": "contoso-motor-serial-00000",
            "name": "left-motor",
            "group": "motors",
            "manufacturer": "contoso",
            "model": "virtual-motor",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/motors\/0",
                "firmwareDataFile": "firmware.json",
            }
        },
        {
            "id": "contoso-motor-serial-00001",
            "name": "right-motor",
            "group": "motors",
            "manufacturer": "contoso",
            "model": "virtual-motor",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/motors\/1",
                "firmwareDataFile": "firmware.json",
            }
        },
        {
            "id": "contoso-motor-serial-00002",
            "name": "vacuum-motor",
            "group": "motors",
            "manufacturer": "contoso",
            "model": "virtual-motor",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/motors\/2",
                "firmwareDataFile": "firmware.json",
            }
        },
        {
            "id": "contoso-camera-serial-00000",
            "name": "front-camera",
            "group": "cameras",
            "manufacturer": "contoso",
            "model": "virtual-camera",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/camera\/0",
                "firmwareDataFile": "firmware.json",
            }
        },
        {
            "id": "contoso-camera-serial-00001",
            "name": "rear-camera",
            "group": "cameras",
            "manufacturer": "contoso",
            "model": "virtual-camera",
            "properties": {
                "path": "\/usr\/local\/contoso-devices\/vacuum-1\/camera\/1",
                "firmwareDataFile": "firmware.json",
            }
        }
    ]
}

Další kroky

Příklad v tomto článku byl použit jazyk C. Pokud chcete prozkoumat ukázkové zdrojové kódy C++, přečtěte si:

Různé ukázkové aktualizace komponent připojených k zařízení Contoso Virtual Vacuum najdete v ukázce aktualizace proxy serveru.

  • Last updated on