Zelfstudie: Uw apparaten configureren vanuit een back-endservice

Als onderdeel van de levenscyclus van het apparaat moet u mogelijk uw IoT-apparaten configureren vanuit uw back-endservice. Wanneer u een gewenste configuratie naar uw apparaten verzendt, wilt u ook status- en nalevingsupdates van deze apparaten ontvangen. U kunt bijvoorbeeld een bereik voor operationele doeltemperatuur instellen voor een apparaat of firmwareversiegegevens van uw apparaten verzamelen.

Als u statusinformatie tussen een apparaat en een IoT-hub wilt synchroniseren, gebruikt u apparaatdubbels. Een apparaatdubbel is een JSON-document dat is gekoppeld aan een specifiek apparaat en is opgeslagen door IoT Hub in de cloud, waar u een query kunt uitvoeren . Een apparaatdubbel bevat gewenste eigenschappen, gerapporteerde eigenschappen en tags.

• Een gewenste eigenschap wordt ingesteld door een back-endtoepassing en gelezen door een apparaat.
• Een gerapporteerde eigenschap wordt ingesteld door een apparaat en gelezen door een back-end toepassing.
• Een tag wordt ingesteld door een back-endtoepassing en wordt nooit naar een apparaat verzonden. U gebruikt tags om uw apparaten te ordenen.

In deze zelfstudie leert u hoe u de gewenste en gerapporteerde eigenschappen gebruikt om statusinformatie te synchroniseren.

In deze zelfstudie voert u de volgende taken uit:

Als u nog geen abonnement op Azure hebt, maak dan een gratis account aan voordat u begint.

Vereiste voorwaarden

• In deze handleiding wordt de Azure CLI gebruikt om cloudresources te maken. Als u al een IoT-hub hebt waarop een apparaat is geregistreerd, kunt u deze stappen overslaan. Er zijn twee manieren om CLI-opdrachten uit te voeren:

  • Gebruik de Bash-omgeving in Azure Cloud Shell. Zie Azure Cloud Shell-snelstart: Bash voor meer informatie.

  • Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

    • Meld u aan bij de Azure CLI met behulp van de opdracht az login .
    • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.
    • Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om naar de nieuwste versie te upgraden.

• De twee voorbeeldtoepassingen die u in deze zelfstudie uitvoert, worden geschreven met behulp van Node.js. Node.js v10.x.x of hoger moet zijn geïnstalleerd op uw ontwikkelcomputer.

  • U kunt Node.js voor meerdere platforms downloaden van nodejs.org.

  • Gebruik de volgende opdracht om de huidige versie van Node.js op uw ontwikkelcomputer te controleren:

    node --version
    

• Kloon of download het voorbeeldproject Node.js van Azure IoT-voorbeelden voor Node.js.

• Zorg ervoor dat de poort 8883 is geopend in uw firewall. In het apparaatvoorbeeld in deze zelfstudie wordt het MQTT-protocol gebruikt, dat communiceert via poort 8883. Deze poort is in sommige netwerkomgevingen van bedrijven en onderwijsinstellingen mogelijk geblokkeerd. Zie Verbinding maken met IoT Hub (MQTT) voor meer informatie en manieren om dit probleem te omzeilen.

Azure-resources instellen

Om deze zelfstudie te voltooien, moet uw Azure-abonnement een IoT-hub bevatten met een apparaat dat is toegevoegd aan het apparaatidentiteitsregister. Met de vermelding in het apparaat-id-register kan het gesimuleerde apparaat dat u in deze zelfstudie uitvoert, verbinding maken met uw hub.

Als u nog geen IoT-hub hebt ingesteld in uw abonnement, kunt u er een instellen met het volgende CLI-script. Dit script maakt gebruik van de naam tutorial-iot-hub met een willekeurig getal dat is toegevoegd voor de naam van de IoT-hub. U kunt deze naam vervangen door uw eigen wereldwijd unieke naam wanneer u deze uitvoert. Het script maakt de resourcegroep en hub in de regio VS - centraal, die u kunt wijzigen naar een regio dichterbij. Met het script wordt de verbindingsreeks van uw IoT Hub-service opgehaald, die u in het back-endvoorbeeld gebruikt om verbinding te maken met uw IoT-hub:

let "randomIdentifier=$RANDOM*$RANDOM"  
hubname="tutorial-iot-hub-$randomIdentifier"
location=centralus

# Install the IoT extension if it's not already installed:
az extension add --name azure-iot

# Create a resource group:
az group create --name tutorial-iot-hub-rg --location $location

# Create your free-tier IoT hub. You can only have one free IoT hub per subscription.
# Change the sku to S1 to create a standard-tier hub if necessary.
az iot hub create --name $hubname --location $location --resource-group tutorial-iot-hub-rg --partition-count 2 --sku F1

# Make a note of the service connection string, you need it later:
az iot hub connection-string show --hub-name $hubname --policy-name service -o table

In deze zelfstudie wordt een gesimuleerd apparaat met de naam MyTwinDevice gebruikt. Het volgende script voegt dit apparaat toe aan uw identiteitsregister en haalt de bijbehorende verbindingsreeks op:

# Create the device in the identity registry:
az iot hub device-identity create --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg

# Retrieve the device connection string, you need this later:
az iot hub device-identity connection-string show --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg -o table

Statusinformatie verzenden naar een apparaat

U gebruikt de gewenste eigenschappen om statusinformatie van een back-endtoepassing naar een apparaat te verzenden. In deze sectie ziet u het volgende:

• Configureer een apparaat voor het ontvangen en verwerken van gewenste eigenschappen.
• Verzend de gewenste eigenschappen van een back-endtoepassing naar een apparaat.

Voorbeeld van gewenste eigenschappen

U kunt uw gewenste eigenschappen structuren op elke manier die handig is voor uw toepassing. In dit voorbeeld wordt één eigenschap op het hoogste niveau met de naam fanOn gebruikt en worden de resterende eigenschappen gegroepeerd in afzonderlijke onderdelen. In het volgende JSON-fragment ziet u de structuur van de gewenste eigenschappen die in deze zelfstudie worden gebruikt. De JSON bevindt zich in het bestand desired.json.

{
  "fanOn": "true",
  "components": {
    "system": {
      "id": "17",
      "units": "farenheit",
      "firmwareVersion": "9.75"
    },
    "wifi" : { 
      "channel" : "6",
      "ssid": "my_network"
    },
    "climate" : {
      "minTemperature": "68",
      "maxTemperature": "76"
    }
  }
}

Gewenste eigenschappen ontvangen in een apparaattoepassing

Als u de voorbeeldcode van het gesimuleerde apparaat wilt weergeven die de gewenste eigenschappen ontvangt, gaat u naar de map iot-hub/Tutorials/DeviceTwins in het voorbeeld Node.js project dat u hebt gedownload. Open vervolgens het SimulatedDevice.js-bestand in een teksteditor.

In de volgende secties wordt de code beschreven die wordt uitgevoerd op het gesimuleerde apparaat dat reageert op wijzigingen in de gewenste eigenschap die vanuit de back-endtoepassing worden verzonden.

Het apparaat-twinobject ophalen

Wanneer u uw apparaat hebt geregistreerd bij de IoT-hub, hebt u een apparaatverbindingsreeks als uitvoer. Een apparaatverbindingsreeks wordt door het apparaat gebruikt om te verifiëren met de geregistreerde identiteit in de cloud. De volgende code maakt verbinding met uw IoT-hub met behulp van een apparaatverbindingsreeks:

// Get the device connection string from a command line argument
var connectionString = process.argv[2];

Met de volgende code wordt een tweeling opgehaald uit het clientobject:

// Get the device twin
client.getTwin(function(err, twin) {
  if (err) {
    console.error(chalk.red('Could not get device twin'));
  } else {
    console.log(chalk.green('Device twin created'));

Handlers maken

U kunt handlers maken voor gewenste eigenschapsupdates die reageren op updates op verschillende niveaus in de JSON-hiërarchie. Deze handler ziet bijvoorbeeld alle gewenste eigenschapswijzigingen die vanuit een back-endtoepassing naar het apparaat worden verzonden. De deltavariabele bevat de gewenste eigenschappen die worden verzonden vanuit de back-end van de oplossing:

// Handle all desired property updates
twin.on('properties.desired', function(delta) {
    console.log(chalk.yellow('\nNew desired properties received in patch:'));

De volgende handler reageert alleen op wijzigingen die zijn aangebracht in de gewenste eigenschap fanOn :

// Handle changes to the fanOn desired property
twin.on('properties.desired.fanOn', function(fanOn) {
    console.log(chalk.green('\nSetting fan state to ' + fanOn));

    // Update the reported property after processing the desired property
    reportedPropertiesPatch.fanOn = fanOn ? fanOn : '{unknown}';
});

Handlers voor meerdere eigenschappen

In de JSON-voorbeeldeigenschappen voor deze zelfstudie bevat het klimaatknooppunt onder onderdelen twee eigenschappen, minTemperature en maxTemperature.

Het lokale dubbelobject van een apparaat slaat een volledige set gewenste en gerapporteerde eigenschappen op. De delta die vanaf de back-end wordt verzonden, kan slechts een subset van de gewenste eigenschappen bijwerken. Als in het volgende codefragment het gesimuleerde apparaat een update ontvangt naar slechts één van minTemperature en maxTemperature, wordt de waarde in de lokale dubbel gebruikt voor de andere waarde om het apparaat te configureren:

// Handle desired properties updates to the climate component
twin.on('properties.desired.components.climate', function(delta) {
    if (delta.minTemperature || delta.maxTemperature) {
      console.log(chalk.green('\nUpdating desired tempertures in climate component:'));
      console.log('Configuring minimum temperature: ' + twin.properties.desired.components.climate.minTemperature);
      console.log('Configuring maximum temperture: ' + twin.properties.desired.components.climate.maxTemperature);

      // Update the reported properties and send them to the hub
      reportedPropertiesPatch.minTemperature = twin.properties.desired.components.climate.minTemperature;
      reportedPropertiesPatch.maxTemperature = twin.properties.desired.components.climate.maxTemperature;
      sendReportedProperties();
    }
});

Verwerk bewerkingen voor invoegen, bijwerken en verwijderen

De gewenste eigenschappen die vanaf de back-end worden verzonden, geven niet aan welke bewerking wordt uitgevoerd op een bepaalde gewenste eigenschap. Uw code moet de bewerking afleiden uit de huidige set gewenste eigenschappen die lokaal zijn opgeslagen en de wijzigingen die vanuit de hub worden verzonden.

Het volgende codefragment laat zien hoe het gesimuleerde apparaat invoeg-, update- en verwijderbewerkingen verwerkt in de lijst met onderdelen in de gewenste eigenschappen. U kunt zien hoe u null-waarden gebruikt om aan te geven dat een onderdeel moet worden verwijderd:

// Keep track of all the components the device knows about
var componentList = {};

// Use this componentList list and compare it to the delta to infer
// if anything was added, deleted, or updated.
twin.on('properties.desired.components', function(delta) {
  if (delta === null) {
    componentList = {};
  }
  else {
    Object.keys(delta).forEach(function(key) {

      if (delta[key] === null && componentList[key]) {
        // The delta contains a null value, and the
        // device has a record of this component.
        // Must be a delete operation.
        console.log(chalk.green('\nDeleting component ' + key));
        delete componentList[key];

      } else if (delta[key]) {
        if (componentList[key]) {
          // The delta contains a component, and the
          // device has a record of it.
          // Must be an update operation.
          console.log(chalk.green('\nUpdating component ' + key + ':'));
          console.log(JSON.stringify(delta[key]));
          // Store the complete object instead of just the delta
          componentList[key] = twin.properties.desired.components[key];

        } else {
          // The delta contains a component, and the
          // device has no record of it.
          // Must be an add operation.
          console.log(chalk.green('\nAdding component ' + key + ':'));
          console.log(JSON.stringify(delta[key]));
          // Store the complete object instead of just the delta
          componentList[key] = twin.properties.desired.components[key];
        }
      }
    });
  }
});

Gewenste eigenschappen verzenden vanuit een back-endtoepassing

U hebt gezien hoe een apparaat handlers implementeert voor het ontvangen van gewenste eigenschapsupdates. In deze sectie ziet u hoe u wijzigingen van gewenste eigenschappen naar een apparaat verzendt vanuit een back-endtoepassing.

Als u de voorbeeldcode van het gesimuleerde apparaat wilt weergeven die de gewenste eigenschappen ontvangt, gaat u naar de map iot-hub/Tutorials/DeviceTwins in het voorbeeld Node.js project dat u hebt gedownload. Open vervolgens het ServiceClient.js-bestand in een teksteditor.

In het volgende codefragment ziet u hoe u verbinding maakt met het apparaatidentiteitsregister en toegang krijgt tot de tweeling voor een specifiek apparaat.

// Create a device identity registry object
var registry = Registry.fromConnectionString(connectionString);

// Get the device twin and send desired property update patches at intervals.
// Print the reported properties after some of the desired property updates.
registry.getTwin(deviceId, async (err, twin) => {
  if (err) {
    console.error(err.message);
  } else {
    console.log('Got device twin');

In het volgende fragment ziet u verschillende gewenste eigenschapspatches die de back-end toepassing naar het apparaat verzendt:

// Turn the fan on
var twinPatchFanOn = {
  properties: {
    desired: {
      patchId: "Switch fan on",
      fanOn: "false",
    }
  }
};

// Set the maximum temperature for the climate component
var twinPatchSetMaxTemperature = {
  properties: {
    desired: {
      patchId: "Set maximum temperature",
      components: {
        climate: {
          maxTemperature: "92"
        }
      }
    }
  }
};

// Add a new component
var twinPatchAddWifiComponent = {
  properties: {
    desired: {
      patchId: "Add WiFi component",
      components: {
        wifi: { 
          channel: "6",
          ssid: "my_network"
        }
      }
    }
  }
};

// Update the WiFi component
var twinPatchUpdateWifiComponent = {
  properties: {
    desired: {
      patchId: "Update WiFi component",
      components: {
        wifi: { 
          channel: "13",
          ssid: "my_other_network"
        }
      }
    }
  }
};

// Delete the WiFi component
var twinPatchDeleteWifiComponent = {
  properties: {
    desired: {
      patchId: "Delete WiFi component",
      components: {
        wifi: null
      }
    }
  }
};

In het volgende fragment ziet u hoe de back-endtoepassing een gewenste eigenschapsupdate naar een apparaat verzendt:

// Send a desired property update patch
async function sendDesiredProperties(twin, patch) {
  twin.update(patch, (err, twin) => {
    if (err) {
      console.error(err.message);
    } else {
      console.log(chalk.green(`\nSent ${twin.properties.desired.patchId} patch:`));
      console.log(JSON.stringify(patch, null, 2));
    }
  });
}

Statusinformatie ontvangen van een apparaat

Uw back-endtoepassing ontvangt statusgegevens van een apparaat als gerapporteerde eigenschappen. Een apparaat stelt de gerapporteerde eigenschappen in en verzendt deze naar uw hub. Een back-endtoepassing kan de huidige waarden van de gerapporteerde eigenschappen van de device twin die in uw hub is opgeslagen, lezen.

Gerapporteerde eigenschappen verzenden vanaf een apparaat

U kunt updates naar gerapporteerde eigenschapswaarden verzenden als een patch. In het volgende fragment ziet u een sjabloon voor de patch die het gesimuleerde apparaat verzendt. Het gesimuleerde apparaat werkt de velden in de patch bij voordat het naar de hub wordt verzonden:

// Create a patch to send to the hub
var reportedPropertiesPatch = {
  firmwareVersion:'1.2.1',
  lastPatchReceivedId: '',
  fanOn:'',
  minTemperature:'',
  maxTemperature:''
};

Het gesimuleerde apparaat gebruikt de volgende functie om de patch met de gerapporteerde eigenschappen naar de hub te verzenden:

// Send the reported properties patch to the hub
function sendReportedProperties() {
  twin.properties.reported.update(reportedPropertiesPatch, function(err) {
    if (err) throw err;
    console.log(chalk.blue('\nTwin state reported'));
    console.log(JSON.stringify(reportedPropertiesPatch, null, 2));
  });
}

Gerapporteerde eigenschappen verwerken

Een back-endtoepassing heeft toegang tot de huidige gerapporteerde waarden van de eigenschappen van een apparaat via de device twin. In het volgende fragment ziet u hoe de back-endtoepassing de gerapporteerde eigenschapswaarden voor het gesimuleerde apparaat leest:

// Display the reported properties from the device
function printReportedProperties(twin) {
  console.log("Last received patch: " + twin.properties.reported.lastPatchReceivedId);
  console.log("Firmware version: " + twin.properties.reported.firmwareVersion);
  console.log("Fan status: " + twin.properties.reported.fanOn);
  console.log("Min temperature set: " + twin.properties.reported.minTemperature);
  console.log("Max temperature set: " + twin.properties.reported.maxTemperature);
}

De toepassingen uitvoeren

In deze sectie voert u de twee voorbeeldtoepassingen uit om te zien wanneer een back-endtoepassing gewenste eigenschapsupdates verzendt naar een gesimuleerde apparaattoepassing.

Als u het gesimuleerde apparaat en de back-endtoepassingen wilt uitvoeren, hebt u de verbindingsreeksen voor het apparaat en de service nodig. U hebt de verbindingsreeksen genoteerd toen u de resources aan het begin van deze zelfstudie maakte.

Als u de gesimuleerde apparaattoepassing wilt uitvoeren, opent u een shell- of opdrachtpromptvenster en gaat u naar de map iot-hub/Tutorials/DeviceTwins in het Node.js project dat u hebt gedownload. Voer vervolgens de volgende opdrachten uit:

npm install
node SimulatedDevice.js "{your device connection string}"

Als u de back-endtoepassing wilt uitvoeren, opent u een andere shell of een opdrachtpromptvenster. Navigeer vervolgens naar de map iot-hub/Tutorials/DeviceTwins in het Node.js project dat u hebt gedownload. Voer vervolgens de volgende opdrachten uit:

npm install
node ServiceClient.js "{your service connection string}"

De gewenste updates van eigenschappen bekijken

In de volgende schermopname ziet u de uitvoer van de gesimuleerde apparaattoepassing en wordt gemarkeerd hoe een update naar de gewenste eigenschap maxTemperature wordt verwerkt. U kunt zien hoe zowel de handler op het hoogste niveau als de handlers voor klimaatonderdelen worden uitgevoerd:

In de volgende schermopname ziet u de uitvoer van de back-endtoepassing en wordt gemarkeerd hoe er een update wordt verzonden naar de gewenste eigenschap maxTemperature :

Gerapporteerde eigenschapsupdates bekijken

In de volgende schermopname ziet u de uitvoer van de toepassing voor het gesimuleerde apparaat en wordt gemarkeerd hoe deze een gerapporteerde eigenschapsupdate naar uw hub verzendt:

In de volgende schermopname ziet u de uitvoer van de back-endtoepassing en ziet u hoe deze een gerapporteerde eigenschapsupdate van een apparaat ontvangt en verwerkt:

Hulpmiddelen opruimen

Als je van plan bent de volgende zelfstudie te voltooien, laat dan de resourcegroep en de IoT-hub staan om ze later opnieuw te gebruiken.

Als u de IoT-hub niet langer nodig hebt, verwijdert u deze en de resourcegroep in de portal. Hiervoor selecteert u de resourcegroep tutorial-iot-hub-rg die uw IoT-hub bevat en selecteert u Verwijderen.

U kunt ook de CLI gebruiken:

# Delete your resource group and its contents
az group delete --name tutorial-iot-hub-rg

Volgende stappen

In deze zelfstudie hebt u geleerd hoe u statusinformatie synchroniseert tussen uw apparaten en uw IoT-hub. Ga naar de volgende handleiding om te leren hoe je apparaat-tweelingen kunt gebruiken om het updateproces van apparaten te implementeren.