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 například nastavit cílový rozsah provozních teplot pro zařízení nebo shromažďovat informace o verzi firmwaru ze zařízení.

K synchronizaci informací o stavu mezi zařízením a centrem IoT použijte 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, kde je můžete dotazovat. Dvojče zařízení obsahuje požadované vlastnosti, nahlášené vlastnosti a značky.

• Požadovaná vlastnost je nastavena back-endovou aplikací a přečtena zařízením.
• Ohlášená vlastnost je nastavená zařízením a přečtená back-endovou aplikací.
• Značka je nastavena back-end aplikací a nikdy se neodesílá do zařízení. Používáte značky k uspořádání svých zařízení.

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

Diagram digitálních dvojčat zařízení v zařízení a v cloudovém prostředí.

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

• Vytvořte centrum IoT a přidejte testovací zařízení do registru identit.
• K odeslání informací o stavu do simulovaného zařízení použijte požadované vlastnosti.
• Pomocí ohlášených vlastností můžete přijímat informace o stavu ze simulovaného zařízení.

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. Pro více informací si přečtěte Průvodce rychlým startem 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 Dockeru. 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.
    • Spusťte az version a zjistěte verzi a nainstalované závislé knihovny. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

• Dvě ukázkové aplikace, které spustíte v tomto kurzu, se zapisují 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 ve firewallu 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 řešení tohoto problému najdete v tématu Připojení ke službě IoT Hub (MQTT).

Nastavení prostředků Azure

K dokončení tohoto kurzu musí vaše předplatné Azure obsahovat centrum IoT s zařízením přidaným do registru identit zařízení. Položka v registru identit zařízení umožňuje simulovanému zařízení, které jste spustili v tomto kurzu, připojit se k centru.

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 oblast blíže k vám. Skript načte připojovací řetězec služby IoT Hub, který použijete v back-endové ukázce pro připojení k centru 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 odesílání informací o stavu z back-endové aplikace do zařízení. V této části se dozvíte, jak:

• 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ázkové požadované vlastnosti

Požadované vlastnosti můžete strukturovat jakýmkoli způsobem, který je pro vaši aplikaci vhodný. Tento příklad používá jednu vlastnost nejvyšší úrovně s názvem fanOn a seskupuje zbývající vlastnosti do samostatných komponent. 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í

Pokud chcete zobrazit ukázkový kód simulovaného zařízení, který přijímá požadované vlastnosti, přejděte do složky iot-hub/Tutorials/DeviceTwins v ukázkovém Node.js projektu, který jste stáhli. Potom otevřete soubor SimulatedDevice.js v 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, jako výstup jste získali připojovací řetězec zařízení. Připojovací řetězec zařízení používá zařízení ke svému ověření pomocí registrované identity v cloudu. Následující kód se připojí ke službě IoT Hub pomocí připojovacího řetězce zařízení:

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

Následující kód získá dvojče z objektu klienta:

// 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řit obslužné rutiny

Můžete vytvořit obslužné rutiny pro aktualizace požadovaných vlastností, které reagují na aktualizace na různých úrovních v hierarchii JSON. Tato obslužná rutina například zobrazí všechny požadované změny vlastností odeslané do zařízení z back-endové aplikace. Delta proměnná obsahuje požadované vlastnosti odeslané z backendu ř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.

Objekt lokálního dvojčete zařízení ukládá úplnou sadu požadovaných a ohlášených vlastností. Delta odeslaná z backendu může aktualizovat pouze podmnožinu požadovaných vlastností. V následujícím fragmentu kódu, pokud simulované zařízení obdrží aktualizaci pouze na jednu z minTemperature a maxTemperature, použije hodnotu 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();
    }
});

Zpracujte operace vložení, aktualizace a odstranění

Požadované vlastnosti odeslané z back-endu neudávají, jaká operace se provádí u konkrétní požadované vlastnosti. Váš kód musí operaci odvodit z aktuální sady požadovaných vlastností uložených místně a změny odeslané z centra.

Následující fragment kódu ukazuje, jak simulované zařízení zpracovává operace vložení, aktualizace a odstranění v seznamu součástí v požadovaných vlastnostech. Zjistíte, jak pomocí hodnot null označit, že se má komponenta 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

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

Pokud chcete zobrazit ukázkový kód simulovaného zařízení, který přijímá požadované vlastnosti, přejděte do složky iot-hub/Tutorials/DeviceTwins v ukázkovém Node.js projektu, který jste stáhli. Potom otevřete soubor ServiceClient.js v 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 pro konkrétní 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 kódu ukazuje různé opravy 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 kódu ukazuje, jak back-endová aplikace odešle aktualizaci požadované vlastnosti do zařízení:

// 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řijímá informace o stavu ze zařízení jako ohlášené vlastnosti. Zařízení nastaví ohlášené vlastnosti a odešle je do centra. Back-endová aplikace může číst aktuální hodnoty ohlášených vlastností z dvojčete zařízení uloženého ve vašem centru.

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

Aktualizace hlášených hodnot vlastností můžete odesílat jako opravu. Následující fragment kódu ukazuje šablonu opravy, která simulované zařízení odesílá. Simulované zařízení před odesláním do centra aktualizuje pole v opravě:

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

Simulované zařízení používá následující funkci k odeslání opravy obsahující ohlášené vlastnosti do centra:

// 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 přistupuje k aktuálním hodnotám ohlášených vlastností zařízení prostřednictvím dvojčete zařízení. Následující fragment kódu ukazuje, jak back-endová aplikace čte hlášené hodnoty vlastností simulovaného 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í simulovaných zařízení a back-endových aplikací potřebujete připojovací řetězce zařízení a služeb. Při vytváření prostředků jste si na začátku tohoto kurzu poznamenali připojovací řetězce.

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

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

Pokud chcete spustit back-endovou aplikaci, otevřete jiné prostředí nebo okno příkazového řádku. Potom přejděte do složky iot-hub/Tutorials/DeviceTwins v projektu Node.js, který jste stáhli. Pak 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í a zvýrazní, jak zpracovává aktualizaci na požadovanou vlastnost maxTemperature . Můžete vidět, jak obslužná rutina nejvyšší úrovně i obslužné rutiny klimatických komponent běží:

Následující snímek obrazovky ukazuje výstup z back-endové aplikace a zvýrazní, jak odesílá aktualizaci do požadované vlastnosti maxTemperature :

Sledujte aktualizace nahlášených vlastností

Následující snímek obrazovky ukazuje výstup z aplikace pro simulované zařízení a zvýrazňuje, jak odesílá ohlášenou aktualizaci vlastnosti do hlavního uzlu.

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í:

Upravte zdroje

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

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

Případně použijte 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 zjistili, jak 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í.

Implementujte kurz aktualizace zařízení pro Azure IoT Hub pomocí referenční image Raspberry Pi 3 B+.