Sdílet prostřednictvím

Registrace komponent ve službě Device Update

  • Článek

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 identita pod úrovní zařízení, která má vztah složení 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řed instalací, 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 na oddíly v 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 zařízením IoT přes síťový protokol (například SBĚRNICE USB nebo 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 bezdrátovou aktualizaci prostřednictvím připojení Azure IoT Hub hostitelského zařízení.

Agent Device Update je nezávislý na zařízení a komponentách. Agent sám o komponentách (nebo připojených) hostitelském zařízení v době aktualizace nezná 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í nebo dvojčete modulu.

    • Vyvolá obslužnou rutinu kroků pro zpracování aktualizace proxy serveru určené pro jednu nebo více komponent v 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.

  • Obslužná rutina podřízený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í aktualizační obslužné rutiny 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ů
  • Systém hostitelských kořenových souborů
  • 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:

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

Implementace enumerátoru komponent (jazyk C)

Požadavky

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

Function Argumenty Návraty
char* GetAllComponents() Nic Řetězec JSON, který obsahuje pole všech ComponentInfo 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 funkcemi GetAllComponents SelectComponents Nic

ComponentInfo

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

Name Typ Description
id string 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 string 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 string Skupina, do které tato komponenta patří.

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

Pro logickou komponentu, například diskový oddíl nebo adresář, může být definovaná hodnota libovolného tvůrce zařízení.
model string 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 properties.version naplní ze zadané hodnoty (napodobení) firmwareDataFile (/usr/local/contoso-devices/vacuum-1/hostfw/firmware.json).

{
    "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.