Kurz: Konfigurace zařízení z back-endové služby

V rámci životního cyklu zařízení možná budete muset nakonfigurovat zařízení IoT z back-endové služby. Když do zařízení odešlete požadovanou konfiguraci, chcete z těchto zařízení také dostávat aktualizace stavu a dodržování předpisů. Můžete tak například pro zařízení nastavit cílový rozsah provozní teploty nebo z nich shromáždit informace o verzi firmwaru.

K synchronizaci informací o stavu mezi zařízením a centrem IoT slouží dvojčata zařízení. Dvojče zařízení je dokument JSON přidružený ke konkrétnímu zařízení a uložený službou IoT Hub v cloudu, kam na něj můžete odeslat dotaz. Dvojče zařízení obsahuje požadované vlastnosti, ohlášené vlastnosti a značky.

• Požadovaná vlastnost je nastavena back-endovou aplikací a přečteno zařízením.
• Ohlášená vlastnost je nastavená zařízením a přečtená back-endovou aplikací.
• Značka je nastavena back-endovou aplikací a nikdy se neodesílají do zařízení. Značky slouží k uspořádání zařízení.

V tomto kurzu se dozvíte, jak pomocí požadovaných a ohlášených vlastností synchronizovat informace o stavu.

V tomto kurzu provedete následující úlohy:

Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.

Požadavky

• V tomto kurzu se k vytváření cloudových prostředků používá Azure CLI. Pokud už máte centrum IoT s zaregistrovaným zařízením, můžete tyto kroky přeskočit. Příkazy rozhraní příkazového řádku můžete spustit dvěma způsoby:

  • Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v rychlém startu pro Azure Cloud Shell – Bash.

  • Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.

    • Přihlaste se k Azure CLI pomocí příkazu az login .
    • Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.
    • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

• Dvě ukázkové aplikace, které spustíte v tomto kurzu, jsou napsané pomocí Node.js. Na vývojovém počítači potřebujete Node.js v10.x.x nebo novější.

  • Node.js pro různé platformy si můžete stáhnout z webu nodejs.org.

  • Aktuální verzi Node.js na počítači používaném pro vývoj můžete ověřit pomocí následujícího příkazu:

    node --version
    

• Naklonujte nebo stáhněte ukázkový projekt Node.js z ukázek Azure IoT pro Node.js.

• Ujistěte se, že je v bráně firewall otevřený port 8883. Ukázka zařízení v tomto kurzu používá protokol MQTT, který komunikuje přes port 8883. Tento port může být blokovaný v některých podnikových a vzdělávacích síťových prostředích. Další informace a způsoby, jak tento problém obejít, najdete v tématu Připojení pro IoT Hub (MQTT).

Nastavení prostředků Azure

Abyste mohli dokončit tento kurz, musí vaše předplatné Azure obsahovat centrum IoT se zařízením přidaným do registru identit zařízení. Záznam v registru identit zařízení umožňuje připojení simulovaného zařízení, které v tomto kurzu spustíte, do vašeho centra.

Pokud ještě nemáte ve svém předplatném nastavené centrum IoT, můžete si ho nastavit pomocí následujícího skriptu rozhraní příkazového řádku. Tento skript používá název tutorial-iot-hub s náhodným číslem připojeným pro název centra IoT. Tento název můžete po spuštění nahradit vlastním globálně jedinečným názvem. Skript vytvoří skupinu prostředků a centrum v oblasti USA – střed, kterou můžete změnit na bližší zeměpisnou oblast. Skript načte připojovací řetězec služby IoT Hub, který použijete v ukázkové back-endové aplikaci k připojení do centra IoT:

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

V tomto kurzu se používá simulované zařízení s názvem MyTwinDevice. Následující skript přidá toto zařízení do registru identit a načte jeho připojovací řetězec:

# 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

Odeslání informací o stavu do zařízení

Požadované vlastnosti slouží k odeslání informací o stavu z back-endové aplikace do zařízení. V této části najdete postup následujících úloh:

• Nakonfigurujte zařízení pro příjem a zpracování požadovaných vlastností.
• Odeslání požadovaných vlastností z back-endové aplikace do zařízení

Ukázka požadovaných vlastností

U požadovaných vlastnosti můžete použít jakoukoli strukturu, která vyhovuje potřebám vaší aplikace. V tomto příkladu používáme jednu vlastnost nejvyšší úrovně s názvem fanOn a ostatní vlastnosti seskupené do samostatných součástí. Následující fragment kódu JSON ukazuje strukturu požadovaných vlastností, které tento kurz používá. JSON je v souboru desired.json.

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

Příjem požadovaných vlastností v aplikaci zařízení

Ukázkový kód simulovaného zařízení, které přijímá požadované vlastnosti, zobrazíte ve složce iot-hub/Tutorials/DeviceTwins v ukázkovém projektu Node.js, který jste si stáhli. Poté otevřete soubor SimulatedDevice.js v libovolném textovém editoru.

Následující části popisují kód, který běží na simulovaném zařízení, který reaguje na změny požadovaných vlastností odeslaných z back-endové aplikace.

Načtení objektu dvojčete zařízení

Když jste zařízení zaregistrovali ve službě IoT Hub, získali jste jako výstup připojovací řetězec zařízení. Zařízení připojovací řetězec používá zařízení k ověření pomocí své registrované identity v cloudu. Následující kód se pomocí připojovacího řetězce zařízení připojí k centru IoT:

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

Následující kód získá z klientského objektu dvojče:

// 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'));

Vytvoření obslužných rutin

K aktualizaci požadovaných vlastností můžete vytvořit obslužné rutiny, které budou odpovídat na aktualizace na různých úrovních hierarchie JSON. Tato obslužná rutina například sleduje všechny změny požadovaných vlastností odeslané z back-endové aplikace do zařízení. Proměnná delta obsahuje požadované vlastnosti odeslané z back-endu řešení:

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

Následující obslužná rutina reaguje pouze na změny provedené v požadované vlastnosti 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}';
});

Obslužné rutiny pro více vlastností

V ukázkovém formátu JSON požadovaných vlastností pro tento kurz obsahuje klimatický uzel pod komponentami dvě vlastnosti: minTemperature a maxTemperature.

V místním objektu dvojčete zařízení se ukládá kompletní sada požadovaných a ohlášených vlastností. Proměnná delta odeslaná z back-endu může aktualizovat jen dílčí sadu požadovaných vlastností. Pokud simulované zařízení obdrží aktualizaci jen jedné z vlastností minTemperature a maxTemperature, následující fragment kódu zajistí, že se její hodnota použije v místním dvojčeti pro druhou hodnotu ke konfiguraci zařízení:

// 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();
    }
});

Zpracování operací vložení, aktualizace a odstranění

Požadované vlastnosti odeslané z back-endu neuvádějí, jaká operace se s konkrétní požadovanou vlastností provádí. Kód musí typ operace vyvodit z aktuální sady požadovaných vlastností uložených místně a ze změn odeslaných z centra.

Následující fragment kódu ukazuje, jak simulované zařízení zpracovává operace vložení, aktualizace a odstranění u seznamu components v požadovaných vlastnostech. Zjistíte v něm, jak použít hodnoty null k označení, že se určitá součást má odstranit:

// 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];
        }
      }
    });
  }
});

Odeslání požadovaných vlastností z back-endové aplikace

Už víte, jak zařízení implementuje obslužné rutiny pro příjem aktualizací požadovaných vlastností. V této části se dozvíte, jak do zařízení z back-endové aplikace odeslat změny požadovaných vlastností.

Ukázkový kód simulovaného zařízení, které přijímá požadované vlastnosti, zobrazíte ve složce iot-hub/Tutorials/DeviceTwins v ukázkovém projektu Node.js, který jste si stáhli. Poté otevřete soubor ServiceClient.js v libovolném textovém editoru.

Následující fragment kódu ukazuje, jak se připojit k registru identit zařízení a získat přístup k dvojčeti konkrétního zařízení:

// 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');

Následující fragment obsahuje opravy různých požadovaných vlastností, které back-endová aplikace odesílá do zařízení:

// 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
      }
    }
  }
};

Následující fragment ukazuje, jak back-endová aplikace odesílá do zařízení aktualizaci požadované vlastnosti:

// 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));
    }
  });
}

Příjem informací o stavu ze zařízení

Back-endová aplikace přijme ze zařízení informace o stavu jako ohlášené vlastnosti. Zařízení nastaví ohlášené vlastnosti a odešle je do centra IoT. Back-endová aplikace může číst aktuální hodnoty ohlášených vlastností z dvojčete zařízení, které je uloženo v centru.

Odeslání ohlášených vlastností ze zařízení

Aktualizace hodnot ohlášených vlastností můžete odesílat jako opravy. Následující fragment kódu obsahuje šablonu opravy, kterou simulované zařízení odesílá. Před odesláním do centra aktualizuje simulované zařízení pole opravy:

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

K odeslání opravy, která obsahuje ohlášené vlastnosti, do centra používá simulované zařízení následující funkce:

// 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));
  });
}

Zpracování ohlášených vlastností

Back-endová aplikace má k aktuálním hodnotám ohlášených vlastností zařízení přístup prostřednictvím dvojčete zařízení. Následující fragment kódu ukazuje, jak back-endová aplikace načte hodnoty ohlášených vlastností pro simulované zařízení:

// 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);
}

Spuštění aplikací

V této části spustíte dvě ukázkové aplikace, abyste mohli sledovat, jak back-endová aplikace odesílá aktualizace požadovaných vlastností do aplikace simulovaného zařízení.

Ke spuštění aplikace simulovaného zařízení a back-endové aplikace potřebujete připojovací řetězce zařízení a služby. Tyto řetězce jste si poznamenali, když jste na začátku tohoto kurzu vytvářeli příslušné prostředky.

Spusťte aplikaci simulovaného zařízení tak, že otevřete okno prostředí nebo příkazového řádku a přejdete v projektu Node.js, který jste si stáhli, do složky iot-hub/Tutorials/DeviceTwins. Potom spusťte následující příkazy:

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

Back-endovou aplikaci spusťte tak, že otevřete další okno prostředí nebo příkazového řádku. Pak přejděte v projektu Node.js, který jste si stáhli, do složky iot-hub/Tutorials/DeviceTwins. Potom spusťte následující příkazy:

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

Sledování aktualizací požadovaných vlastností

Následující snímek obrazovky ukazuje výstup z aplikace simulovaného zařízení, je na něm zvýrazněno zpracování aktualizace požadované vlastnosti maxTemperature. Vidíte zde, jak se spouští obslužná rutina nejvyšší úrovně a obslužná rutina součásti climate:

Následující snímek obrazovky ukazuje výstup z back-endové aplikace, je na něm zvýrazněno odeslání aktualizace požadované vlastnosti maxTemperature:

Sledování aktualizací ohlášených vlastností

Následující snímek obrazovky ukazuje výstup z aplikace simulovaného zařízení, je na něm zvýrazněno odeslání aktualizace ohlášené vlastnosti do centra IoT:

Následující snímek obrazovky ukazuje výstup z back-endové aplikace a zvýrazní, jak přijímá a zpracovává aktualizaci ohlášené vlastnosti ze zařízení:

Vyčištění prostředků

Pokud plánujete dokončit další kurz, ponechte skupinu prostředků a centrum IoT, abyste je mohli později znovu použít.

Pokud už centrum IoT nepotřebujete, odstraňte ho společně se skupinou prostředků na portálu. Uděláte to tak, že vyberete skupinu prostředků tutorial-iot-hub-rg , která obsahuje centrum IoT, a vyberete Odstranit.

Můžete použít také rozhraní příkazového řádku:

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

Další kroky

V tomto kurzu jste se naučili synchronizovat informace o stavu mezi zařízeními a centrem IoT. V dalším kurzu se dozvíte, jak pomocí dvojčat zařízení implementovat proces aktualizace zařízení.