Oktatóanyag: Eszközök konfigurálása háttérszolgáltatásból

Előfordulhat, hogy az eszköz életciklusának részeként konfigurálnia kell az IoT-eszközöket a háttérszolgáltatásból. Amikor a kívánt konfigurációt elküldi az eszközöknek, állapot- és megfelelőségi frissítéseket is szeretne kapni ezektől az eszközöktől. Beállíthatja például egy eszköz működési hőmérsékleti tartományát, vagy adatokat gyűjthet a belső vezérlőprogram verzióadatairól az eszközeiről.

Az állapotadatok egy eszköz és egy IoT Hub közötti szinkronizálásához eszköz ikreket használ. Az eszköz-ikerpéldány egy adott eszközhöz kapcsolódó JSON-dokumentum, amelyet az IoT Hub tárol a felhőben, ahol lekérdezheti őket. Az ikereszköz kívánt tulajdonságokat, jelentett tulajdonságokat és címkéket tartalmaz.

• A kívánt tulajdonságot egy háttéralkalmazás állítja be, és egy eszköz olvassa be.
• A jelentett tulajdonság egy eszköz állítja be, és egy háttéralkalmazás olvassa be.
• A címkéket egy háttéralkalmazás állítja be, és soha nem küldi el az eszközre. Címkékkel rendszerezheti az eszközöket.

Ez az oktatóanyag bemutatja, hogyan használhatja a kívánt és jelentett tulajdonságokat az állapotadatok szinkronizálásához.

Az oktatóanyagban az alábbi feladatokat fogja végrehajtani:

• Hozzon létre egy IoT Hubot, és vegyen fel egy teszteszközt az identitásjegyzékbe.
• A kívánt tulajdonságok használatával állapotinformációkat küldhet a szimulált eszközre.
• A jelentett tulajdonságok használatával állapotinformációkat kaphat a szimulált eszközről.

Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.

Előfeltételek

• Ez az oktatóanyag az Azure CLI használatával hoz létre felhőerőforrásokat. Ha már van egy IoT Hubja, amelyen regisztrálva van egy eszköz, kihagyhatja ezeket a lépéseket. A parancssori felületi parancsok kétféleképpen futtathatók:

  • Használja a Bash-környezetet az Azure Cloud Shellben. További információ: Azure Cloud Shell – Bash rövid útmutató.

  • Ha inkább helyi cli-referenciaparancsokat szeretne futtatni, telepítse az Azure CLI-t. Ha Windows vagy macOS rendszeren fut, fontolja meg az Azure CLI docker-tárolóban való futtatását. További információ: Az Azure CLI futtatása Docker-tárolóban.

    • Jelentkezzen be az Azure CLI-be az az login parancs használatával.
    • Ha a rendszer kéri, az első használatkor telepítse az Azure CLI-bővítményeket. További információ a bővítményekről: Bővítmények használata az Azure CLI-vel.
    • Futtassa az az version parancsot a telepített verzió és a függő kódtárak megkereséséhez. A legújabb verzióra való frissítéshez futtassa a az upgrade parancsot.

• Az oktatóanyagban futtatott két mintaalkalmazás Node.jshasználatával íródik. A fejlesztői gépen Node.js v10.x.x vagy újabb verzióra van szüksége.

  • A Node.js-t a nodejs.org oldalról töltheti le többféle platformra.

  • A Node.js aktuális verzióját a következő paranccsal ellenőrizheti a fejlesztői gépen:

    node --version
    

• Klónozza vagy töltse le a minta Node.js projektet az Azure IoT-mintákból Node.js.

• Győződjön meg arról, hogy a 8883-as port nyitva van a tűzfalon. Az oktatóanyagban szereplő eszközminta MQTT protokollt használ, amely a 8883-es porton keresztül kommunikál. Ez a port néhány vállalati és oktatási hálózati környezetben blokkolható. További információkért és a probléma megoldásának módjaiért lásd: Csatlakozás az IoT Hubhoz (MQTT).

Azure-erőforrások beállítása

Az oktatóanyag elvégzéséhez az Azure-előfizetésnek tartalmaznia kell egy IoT Hubot az eszközidentitás-beállításjegyzékhez hozzáadott eszközzel. Az eszközidentitás-beállításjegyzék bejegyzése lehetővé teszi, hogy az oktatóanyagban futtatott szimulált eszköz csatlakozzon a központhoz.

Ha még nem állította be az IoT Hubot az előfizetésében, az alábbi CLI-szkripttel állíthat be egyet. Ez a szkript a tutorial-iot-hub nevet használja az IoT Hub nevéhez hozzáfűzött véletlenszerű számmal. Ezt a nevet a futtatáskor a saját globálisan egyedi nevére cserélheti. A szkript létrehozza az erőforráscsoportot és a központot az USA középső régiójában, amelyet önhöz közelebbi régióra válthat. A szkript lekéri az IoT Hub szolgáltatás kapcsolati karakterláncot, amelyet a példaprogramban használ az IoT Hubhoz való csatlakozáshoz.

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

Ez az oktatóanyag egy MyTwinDevice nevű szimulált eszközt használ. A következő szkript hozzáadja ezt az eszközt az identitásjegyzékhez, és lekéri annak kapcsolati sztringjét:

# 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

Állapotinformációk küldése eszközre

A kívánt tulajdonságok használatával állapotadatokat küldhet egy háttéralkalmazásból egy eszközre. Ebben a szakaszban a következő lépéseket láthatja:

• Konfiguráljon egy eszközt a kívánt tulajdonságok fogadásához és feldolgozásához.
• A kívánt tulajdonságok elküldése háttéralkalmazásból egy eszközre.

Minta kívánt tulajdonságok

A kívánt tulajdonságokat bármilyen, az alkalmazásnak megfelelő módon strukturálhatja. Ez a példa egy fanOn nevű legfelső szintű tulajdonságot használ, és a fennmaradó tulajdonságokat külön összetevőkbe csoportosítja. Az alábbi JSON-kódrészlet az oktatóanyag által használt kívánt tulajdonságok struktúráját mutatja be. A JSON a desired.json fájlban található.

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

Kívánt tulajdonságok fogadása egy eszközalkalmazásban

A kívánt tulajdonságokat fogadó szimulált eszközmintakód megtekintéséhez keresse meg az iot-hub/Tutorials/DeviceTwins mappát a letöltött minta Node.js projektben. Ezután nyissa meg a SimulatedDevice.js fájlt egy szövegszerkesztőben.

A következő szakaszok a szimulált eszközön futó kódot ismertetik, amely a háttéralkalmazásból küldött kívánt tulajdonságmódosításokra reagál.

Az ikereszköz-objektum lekérése

Amikor regisztrálta az eszközt az IoT Hubon, kimenetként kapott egy eszközkapcsolati sztringet. Az eszköz egy eszközkapcsolati sztringet használ a regisztrált identitással való hitelesítéshez a felhőben. Az alábbi kód egy eszközkapcsolati sztring használatával csatlakozik az IoT Hubhoz:

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

Az alábbi kód lekéri az ikerpéldányt az ügyfélobjektumból:

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

Kezelők létrehozása

Létrehozhat kezelőket a kívánt tulajdonságfrissítésekhez, amelyek a JSON-hierarchia különböző szintjein reagálnak a frissítésekre. Ez a kezelő például egy háttéralkalmazásból az eszközre küldött összes kívánt tulajdonságmódosítást látja. A delta változó a megoldás háttérrendszeréből küldött kívánt tulajdonságokat tartalmazza:

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

A következő kezelő csak a fanOn kívánt tulajdonság módosításaira reagál:

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

Több tulajdonsághoz tartozó kezelők

Az oktatóanyaghoz tartozó JSON-minta kívánt tulajdonságai között az összetevők alatti klímacsomópont két tulajdonságot, a minTemperature és a maxTemperature tulajdonságot tartalmazza.

Az eszköz helyi ikerobjektuma a kívánt és jelentett tulajdonságok teljes készletét tárolja. Előfordulhat, hogy a háttérrendszerből küldött különbözet csak a kívánt tulajdonságok egy részhalmazát frissíti. A következő kódrészletben, ha a szimulált eszköz csak a minTemperature és a maxTemperature egyikére kap frissítést, a helyi ikerpéldány értékét használja a másik értékhez az eszköz konfigurálásához:

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

Beszúrási, frissítési és törlési műveletek kezelése

A háttérrendszerből küldött kívánt tulajdonságok nem jelzik, hogy milyen műveletet hajtanak végre egy adott kívánt tulajdonságon. A kódnak a helyileg tárolt kívánt tulajdonságok aktuális készletéből és a központból küldött módosításokból kell következtetnie a műveletre.

Az alábbi kódrészlet bemutatja, hogyan kezeli a szimulált eszköz a beszúrási, frissítési és törlési műveleteket a kívánt tulajdonságok összetevőinek listájában. Láthatja, hogyan használhat null értékeket egy összetevő törlésének jelzésére:

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

Kívánt tulajdonságok küldése háttéralkalmazásból

Láthatta, hogyan valósítja meg egy eszköz a kívánt tulajdonságfrissítések fogadásához szükséges kezelőket. Ez a szakasz bemutatja, hogyan küldhet el kívánt tulajdonságmódosításokat egy eszközre egy háttéralkalmazásból.

A kívánt tulajdonságokat fogadó szimulált eszközmintakód megtekintéséhez keresse meg az iot-hub/Tutorials/DeviceTwins mappát a letöltött minta Node.js projektben. Ezután nyissa meg a ServiceClient.js fájlt egy szövegszerkesztőben.

Az alábbi kódrészlet bemutatja, hogyan csatlakozhat az eszközidentitás-beállításjegyzékhez, és hogyan férhet hozzá az ikerpéldányhoz egy adott eszközhöz:

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

Az alábbi kódrészlet a háttéralkalmazás által az eszköznek küldött különböző kívánt tulajdonságjavításokat jeleníti meg:

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

Az alábbi kódrészlet bemutatja, hogy a háttéralkalmazás hogyan küldi el a kívánt tulajdonságfrissítést az eszköznek:

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

Állapotinformációk fogadása eszközről

Az alkalmazás háttérmodulja állapotinformációkat kap egy eszközről jelentett tulajdonságokként. Az eszköz beállítja a jelentett tulajdonságokat, és elküldi őket a központnak. A háttéralkalmazások a hubon tárolt ikereszközről beolvashatják a jelentett tulajdonságok aktuális értékeit.

Jelentett tulajdonságok küldése eszközről

Javításként frissítéseket küldhet a jelentett tulajdonságértékek számára. Az alábbi kódrészlet egy sablont jelenít meg a szimulált eszköz által küldött javításhoz. A szimulált eszköz frissíti a javítás mezőit, mielőtt elküldené a központnak:

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

A szimulált eszköz a következő függvénnyel küldi el a jelentett tulajdonságokat tartalmazó javítást a központnak:

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

Jelentett tulajdonságok feldolgozása

A háttéralkalmazás az ikereszközön keresztül éri el az eszköz aktuális jelentett tulajdonságértékeit. Az alábbi kódrészlet bemutatja, hogyan olvassa be a háttéralkalmazás a szimulált eszköz jelentett tulajdonságértékeit:

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

Az alkalmazások futtatása

Ebben a szakaszban futtatja a két mintaalkalmazást, hogy megfigyelje, ahogy egy háttéralkalmazás a kívánt tulajdonságfrissítéseket küldi egy szimulált eszközalkalmazásnak.

A szimulált eszköz és a háttéralkalmazások futtatásához szükség van az eszköz- és szolgáltatáskapcsolati sztringekre. Az oktatóanyag elején jegyezte fel a kapcsolati sztringeket, amikor létrehozta az erőforrásokat.

A szimulált eszközalkalmazás futtatásához nyisson meg egy felületi vagy parancssori ablakot, és keresse meg az iot-hub/Tutorials/DeviceTwins mappát a letöltött Node.js projektben. Ezután futtassa a következő parancsokat:

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

A háttéralkalmazás futtatásához nyisson meg egy másik rendszerhéjat vagy parancssori ablakot. Ezután keresse meg az iot-hub/Tutorials/DeviceTwins mappát a letöltött Node.js projektben. Ezután futtassa a következő parancsokat:

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

A kívánt tulajdonságfrissítések megfigyelése

Az alábbi képernyőképen a szimulált eszközalkalmazás kimenete látható, és kiemeli, hogyan kezeli a maxTemperature kívánt tulajdonság frissítését. Láthatja, hogyan futnak a legfelső szintű kezelők és a klímaösszetevő-kezelők is:

Az alábbi képernyőképen a háttéralkalmazás kimenete látható, és kiemeli, hogyan küld frissítést a maxTemperature kívánt tulajdonságnak:

Jelentett tulajdonságfrissítések megfigyelése

Az alábbi képernyőképen a szimulált eszközalkalmazás kimenete látható, és kiemeli, hogyan küldi el a jelentett tulajdonságfrissítést a központnak:

Az alábbi képernyőképen a háttéralkalmazás kimenete látható, és kiemeli, hogyan fogadja és dolgozza fel a jelentett tulajdonságfrissítéseket egy eszközről:

Erőforrások tisztítása

Ha a következő oktatóanyag elvégzését tervezi, hagyja meg az erőforráscsoportot és az IoT Hubot, hogy később újra felhasználja őket.

Ha már nincs szüksége az IoT Hubra, törölje azt és az erőforráscsoportot is a portálon. Ehhez válassza ki az IoT Hubot tartalmazó tutorial-iot-hub-rg erőforráscsoportot, és válassza a Törlés lehetőséget.

Másik lehetőségként használja a parancssori felületet:

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

Következő lépések

Ebben az oktatóanyagban megtanulta, hogyan szinkronizálhatja az állapotinformációkat az eszközök és az IoT Hub között. Lépjen tovább a következő oktatóanyagra, amelyből megtudhatja, hogyan használhatja az ikereszközöket az eszközfrissítési folyamat implementálásához.

Eszközfrissítés implementálása az Azure IoT Hubhoz oktatóanyag a Raspberry Pi 3 B+ referenciarendszerkép használatával.