Onderdelen registreren bij Device Update

Dit artikel bevat een voorbeeldimplementatie van een Apparaatupdate voor IoT Hub-onderdelenumerator. U kunt naar dit voorbeeld verwijzen om een aangepaste enumerator voor uw IoT-apparaten te implementeren. Een onderdeel is een identiteit onder het apparaatniveau met een samenstellingsrelatie met het hostapparaat.

In dit artikel wordt een onderdeel-opsomming gedemonstreert met behulp van een virtueel IoT-apparaat met de naam Contoso Virtual Vacuum. Onderdelenumerators worden gebruikt voor het implementeren van de proxy-updatefunctie .

Proxy-update maakt het mogelijk om meerdere onderdelen op hetzelfde IoT-apparaat of meerdere sensoren die zijn verbonden met het IoT-apparaat bij te werken met één over-the-air-implementatie. Proxy-update ondersteunt een installatievolgorde voor het bijwerken van onderdelen. Het biedt ook ondersteuning voor het bijwerken van meerdere stappen met vooraf installatie-, installatie- en post-installatiemogelijkheden.

Gebruiksvoorbeelden waarbij proxy-updates van toepassing zijn, zijn onder andere:

• Specifieke updatebestanden richten op partities op het apparaat.
• Specifieke updatebestanden richten op apps of onderdelen op het apparaat.
• Specifieke updatebestanden richten op sensoren die zijn verbonden met IoT-apparaten via een netwerkprotocol (bijvoorbeeld USB of CAN-bus).

Zie Proxy-updates en het bijwerken van meerdere onderdelen voor meer informatie.

De Device Update-agent wordt uitgevoerd op het hostapparaat. Elke update kan naar een specifiek onderdeel of naar een groep onderdelen van dezelfde hardwareklasse worden verzonden (dat wil wel dat dezelfde software of firmware-update vereist is).

Wat is een enumerator voor onderdelen?

Een onderdeel-enumerator is een extensie voor de Device Update-agent die informatie biedt over elk onderdeel dat u nodig hebt voor een over-the-air-update via de Azure IoT Hub-verbinding van een hostapparaat.

De Device Update-agent is apparaat- en onderdeelneutraal. Op zichzelf weet de agent niets over onderdelen op een hostapparaat op het moment van de update.

Als u proxy-updates wilt inschakelen, moeten apparaatbouwers alle onderdelen op het apparaat identificeren die kunnen worden bijgewerkt en een unieke naam aan elk onderdeel toewijzen. Daarnaast kan een groepsnaam worden toegewezen aan onderdelen van dezelfde hardwareklasse, zodat dezelfde update kan worden geïnstalleerd op alle onderdelen in dezelfde groep. Vervolgens kan de update-inhoudshandler de update installeren en toepassen op de juiste onderdelen.

Dit zijn de verantwoordelijkheden van elk onderdeel van de proxy-updatestroom:

• Apparaatbouwer

  • Ontwerp en bouw het apparaat.

  • Integreer de Device Update-agent en de bijbehorende afhankelijkheden.

  • Implementeer een apparaatspecifieke enumerator-extensie en registreer u bij de Device Update-agent.

    De onderdeel-enumerator gebruikt de informatie van een onderdeelinventaris of een configuratiebestand om statische onderdeelgegevens (Apparaatupdate vereist) te verbeteren met dynamische gegevens (bijvoorbeeld firmwareversie, verbindingsstatus en hardware-id).

  • Maak een proxy-update die een of meer onderliggende updates bevat die zijn gericht op een of meer onderdelen op het apparaat (of verbonden met).

  • Verzend de update naar de oplossingsoperator.

• Oplossingsoperator

  • Importeer de update en het manifest in de Device Update-service.

  • Implementeer de update naar een groep apparaten.

• Device Update-agent

  • Informatie over het bijwerken van IoT Hub ophalen via de apparaatdubbel of moduledubbel.

  • Roep een stappenhandler aan om de proxy-update te verwerken die is bedoeld voor een of meer onderdelen op het apparaat.

    Het voorbeeld in dit artikel heeft twee updates: host-fw-1.1 en motors-fw-1.1. Voor elke onderliggende update roept de bovenliggende stappenhandler een handler voor onderliggende stappen aan om alle onderdelen op te sommen die overeenkomen met de Compatibilities eigenschappen die zijn opgegeven in het manifestbestand van de onderliggende update. Vervolgens downloadt, installeert en past de handler de onderliggende update toe op alle doelonderdelen.

    Om de overeenkomende onderdelen op te halen, roept de onderliggende update een SelectComponents API aan die wordt geleverd door de enumerator van het onderdeel. Als er geen overeenkomende onderdelen zijn, wordt de onderliggende update overgeslagen.

  • Verzamel alle updateresultaten van bovenliggende en onderliggende updates en rapporteer deze resultaten aan IoT Hub.

• Handler voor onderliggende stappen

  • Doorloop een lijst met onderdeelexemplaren die compatibel zijn met de onderliggende update-inhoud. Zie de stappenhandler voor meer informatie.

In productie kunnen apparaatbouwers bestaande handlers gebruiken of een aangepaste handler implementeren die elk installatieprogramma aanroept dat nodig is voor een over-the-air-update. Zie Een aangepaste update-inhoudshandler implementeren voor meer informatie.

Virtuele vacuümonderdelen

Voor dit artikel gebruiken we een virtueel IoT-apparaat om de belangrijkste concepten en functies te demonstreren. Het Virtual Vacuum-apparaat van Contoso bestaat uit vijf logische onderdelen:

• Hostfirmware
• Opstartbestandssysteem van host
• Hosthoofdbestandssysteem
• Drie motoren (linkerwiel, rechterwiel en vacuüm)
• Twee camera's (voor en achter)

De volgende mapstructuur simuleert de onderdelen:

/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 */

De map van elk onderdeel bevat een JSON-bestand waarin een mocksoftwareversienummer van elk onderdeel wordt opgeslagen. Voorbeeld-JSON-bestanden worden firmware.json en diskimage.json.

Voor deze demo kopiëren we firmware.json of diskimage.json (nettolading bijwerken) naar de map van de doelonderdelen om de firmware van de onderdelen bij te werken.

Hier volgt een voorbeeld van firmware.json bestand:

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

Notitie

Contoso Virtual Vacuum bevat software- of firmwareversies om proxy-update te demonstreren. Het biedt geen andere functionaliteit.

Een component-enumerator implementeren (C-taal)

Vereisten

Implementeer alle API's die zijn gedeclareerd in component_enumerator_extension.hpp:

Functie	Argumenten	Retouren
char* GetAllComponents()	Geen	Een JSON-tekenreeks die een matrix van alle ComponentInfo waarden bevat. Zie Voorbeeld van retourwaarden voor meer informatie.
char* SelectComponents(char* selector)	Een JSON-tekenreeks die een of meer naam-/waardeparen bevat die worden gebruikt voor het selecteren van updatedoelonderdelen	Een JSON-tekenreeks die een matrix met ComponentInfo waarden bevat. Zie Voorbeeld van retourwaarden voor meer informatie.
void FreeComponentsDataString(char* string)	Een aanwijzer naar tekenreeksbuffer die eerder is geretourneerd door GetAllComponents of SelectComponents functies	Geen

ComponentInfo

De ComponentInfo JSON-tekenreeks moet de volgende eigenschappen bevatten:

Name	Type	Omschrijving
id	tekenreeks	De unieke identiteit van een onderdeel (apparaatbereik). Voorbeelden hiervan zijn het serienummer van de hardware, de schijfpartitie-id en het unieke bestandspad van het onderdeel.
name	tekenreeks	De logische naam van een onderdeel. Deze eigenschap is de naam die een apparaatbouwer toewijst aan een onderdeel dat beschikbaar is op elk apparaat van dezelfde device klasse. Elk Contoso Virtual Vacuum-apparaat bevat bijvoorbeeld een motor die een linkerwiel aanstuurt. Contoso heeft een linkermotor toegewezen als een algemene (logische) naam voor deze motor om eenvoudig naar dit onderdeel te verwijzen, in plaats van hardware-id, die wereldwijd uniek kan zijn.
group	tekenreeks	Een groep waartoe dit onderdeel behoort. Zo kunnen alle motoren tot een motorengroep behoren.
manufacturer	tekenreeks	Voor een fysiek hardwareonderdeel is deze eigenschap een fabrikant of leveranciernaam. Voor een logisch onderdeel, zoals een schijfpartitie of map, kan dit de gedefinieerde waarde van elke apparaatbouwer zijn.
model	tekenreeks	Voor een fysiek hardwareonderdeel is deze eigenschap een modelnaam. Voor een logisch onderdeel, zoals een schijfpartitie of map, kan deze eigenschap de gedefinieerde waarde van elke apparaatbouwer zijn.
properties	object	Een JSON-object dat optionele apparaatspecifieke eigenschappen bevat.

Hier volgt een voorbeeld van code op basis van ComponentInfo de onderdelen van Contoso Virtual Vacuum:

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

Voorbeeld van retourwaarden

Hier volgt een JSON-document dat wordt geretourneerd door de GetAllComponents functie. Deze is gebaseerd op de voorbeeld-implementatie van de enumerator van het virtuele Vacuüm-onderdeel van Contoso.

{
    "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"
            }
        }
    ]
}

Het volgende JSON-document wordt geretourneerd vanuit de SelectComponents functie. Deze is gebaseerd op de voorbeeld-implementatie van de Contoso-component-opsomming.

Dit is de invoerparameter voor het selecteren van de groep motorenonderdelen :

{
    "group" : "motors"
}

Hier volgt de uitvoer van de parameter. Alle onderdelen behoren tot de motorengroep .

{
    "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"
            }
        }
    ]
}

Dit is de invoerparameter voor het selecteren van één onderdeel met de naam hostfw:

{
    "name" : "hostfw"
}

Dit is de uitvoer van de parameter voor het hostfw-onderdeel :

{
    "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"
            }
        }
    ]
}

Notitie

In het voorgaande voorbeeld is gebleken dat het, indien nodig, mogelijk is om een nieuwere update te verzenden naar elk exemplaar van een onderdeel dat door de eigenschap is geselecteerd name . Implementeer bijvoorbeeld de motor-fw-2.0 update voor vacuümmotor terwijl u doorgaat met het gebruik motor-fw-1.0 op de linkermotor en de rechtermotor.

Inventarisbestand

De voorbeeld-implementatie die eerder is weergegeven voor de enumerator van het onderdeel Contoso Virtual Vacuum leest de informatie van de apparaatspecifieke onderdelen uit het component-inventory.json-bestand . Deze voorbeelduitvoering is alleen bedoeld voor demonstratiedoeleinden.

In een productiescenario moeten sommige eigenschappen rechtstreeks worden opgehaald uit de werkelijke onderdelen. Deze eigenschappen zijn onder andere id, manufactureren model.

De opbouwfunctie voor apparaten definieert de name en group eigenschappen. Deze waarden moeten nooit worden gewijzigd nadat ze zijn gedefinieerd. De name eigenschap moet uniek zijn binnen het apparaat.

Voorbeeld van component-inventory.json bestand

Notitie

De inhoud in dit bestand ziet er bijna hetzelfde uit als de geretourneerde waarde van de GetAllComponents functie. ComponentInfo In dit bestand bevat version dit bestand echter geen eigenschappen.status De onderdeel-enumerator vult deze eigenschappen tijdens runtime.

Voor hostfw wordt de waarde van de eigenschap properties.version bijvoorbeeld ingevuld op basis van de opgegeven waarde (mock) 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",
            }
        }
    ]
}

Volgende stappen

In het voorbeeld in dit artikel is C gebruikt. Als u C++-voorbeeldbroncodes wilt verkennen, raadpleegt u:

• CMakeLists.txt
• contoso-component-enumerator.cpp
• inc/aduc/component_enumerator_extension.hpp

Zie de proxy-updatedemo voor verschillende voorbeeldupdates voor onderdelen die zijn verbonden met het Virtuele vacuümapparaat van Contoso.