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. Előfordulhat például, hogy működési hőmérsékletre vonatkozó céltartományt szeretne beállítani egy eszközhöz, vagy össze szeretné gyűjteni az eszközök belső vezérlőprogramjainak verzióadatait.
Az állapotinformációk eszköz és IoT-központ közötti szinkronizálásához használjon ikereszközöket. Az ikereszköz egy adott eszközzel társított JSON-dokumentum, melyet az IoT Hub a felhőben tárol, és onnan le is kérdezhető. Az ikereszköz kívánt tulajdonságokból, jelentett tulajdonságokból és címkékből áll.
- A kívánt tulajdonságot egy háttéralkalmazás állítja be, és egy eszköz olvassa be.
- A jelentett tulajdonságot 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. A címkék az eszközök rendszerezésére szolgálnak.
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:
- Létrehoz egy IoT-központot, és hozzáad egy teszteszközt az identitásjegyzékhez.
- A kívánt tulajdonságok használatával állapotinformációt küld a szimulált eszközre.
- A jelentett tulajdonságok használatával állapotinformációt fogad 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 rendszert használ, 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 paranccsal.
- 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 az az upgrade paranccsal frissíthet.
Az oktatóanyagban futtatott két mintaalkalmazás Node.js haszná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 tekintse meg az IoT Hubra (MQTT) való Csatlakozás.
Az Azure-erőforrások beállítása
Az oktatóanyag teljesítéséhez az Azure-előfizetésnek rendelkeznie kell egy olyan IoT-központtal, amelyhez tartoznia kell egy, az eszköz identitásjegyzékéhez hozzáadott eszköznek. Az eszköz identitásjegyzékében található bejegyzés teszi lehetővé az oktatóanyagban futtatott szimulált eszköz csatlakozását 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 az erőforráscsoportot és a központot az USA középső régiójában hozza létre, de ez módosítható egy Önhöz közelebb eső régióra. A szkript lekéri az IoT Hub szolgáltatás kapcsolati sztringjét, amellyel a mintául szolgáló háttérrendszerben csatlakozhat az IoT-központhoz:
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 elnevezésű szimulált eszközt használ. A következő szkript hozzáadja ezt az eszközt az identitásjegyzékhez, és lekéri a kapcsolati sztringet:
# 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 állapotinformációkat küldhet a háttéralkalmazásból az eszközre. Ez a szakasz a következőket ismerteti:
- 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.
Mintául szolgáló kívánt tulajdonságok
A kívánt tulajdonságokat bármilyen módon rendezheti, ahogyan az alkalmazásnak megfelel. Ez a példa egy fanOn elnevezésű legfelső szintű tulajdonságot használ, a többi tulajdonságot pedig külön components (összetevők) elemekbe 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öz mintakódjának megtekintéséhez keresse meg az iot-hub/Tutorials/DeviceTwins mappát a letöltött Node.js mintaprojektben. 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 kapcsolati sztring eszközt. Az eszköz egy kapcsolati sztring használ a regisztrált identitással való hitelesítéshez a felhőben. A következő kód egy eszközkapcsolati sztringgel csatlakozik az Ön IoT-központjához:
// Get the device connection string from a command line argument
var connectionString = process.argv[2];
A következő kód lekér egy ikereszközt 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
A kívánt tulajdonságok frissítéséhez kezelőket hozhat lére, amelyek válaszolnak a JSON-hierarchia különböző szintjeinek frissítéseire. Ez a kezelő például látja a háttéralkalmazásból az eszközre küldött kívánt tulajdonság összes módosítását. A delta változó a megoldás háttérrendszeréből küldött kívánt tulajdonságokból áll:
// Handle all desired property updates
twin.on('properties.desired', function(delta) {
console.log(chalk.yellow('\nNew desired properties received in patch:'));
Az alábbi kezelő csak a fanOn kívánt tulajdonságon végrehajtott módosításokra 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 való 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.
Egy eszköz helyi ikerobjektuma tárolja a kívánt és jelentett tulajdonságok teljes készletét. Előfordulhat, hogy a háttérrendszerből küldött delta változó a kívánt tulajdonságoknak csak egy részét frissíti. A következő kódrészlet, ha a szimulált eszköz frissítést kap a minTemperature és a maxTemperature tulajdonság egyikéhez, akkor az eszköz konfigurálásához a helyi ikerobjektumban szereplő értéket adja meg a másik tulajdonsághoz:
// 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űvelet végrehajtására kerül sor egy adott kívánt tulajdonságon. A kódnak a kívánt tulajdonságok helyben, adott pillanatban tárolt készletéből és a központból küldött módosításokból kell következtetnie a műveletre.
A következő 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 components (összetevők) listáján a kívánt tulajdonságokban. Láthatja, hogyan használja a rendszer a null értéket annak jelzésére, ha egy összetevő törölhető:
// 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áttuk, hogyan implementál egy eszköz kezelőket a kívánt tulajdonságok frissítésének fogadására. Ez a szakasz azt mutatja be, hogyan lehet kívánttulajdonság-módosításokat küldeni egy eszközre egy háttéralkalmazásból.
A kívánt tulajdonságokat fogadó szimulált eszköz mintakódjának megtekintéséhez keresse meg az iot-hub/Tutorials/DeviceTwins mappát a letöltött Node.js mintaprojektben. Ezután nyissa meg a ServiceClient.js fájlt egy szövegszerkesztőben.
A következő kódrészlet azt illusztrálja, hogyan kapcsolódhat az eszköz identitásjegyzékhez és férhet hozzá egy adott eszköz ikereszközéhez:
// 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');
A következő kódrészlet olyan különböző, kívánt tulajdonságokra vonatkozó javításokat mutat be, amelyeket a háttéralkalmazás küld az eszközre:
// 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
}
}
}
};
A következő kódrészlet azt mutatja meg, hogyan küld a háttéralkalmazás kívánt tulajdonságokat egy eszközre:
// 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
A háttéralkalmazás jelentett tulajdonságok formájában fogadja az eszközök állapotinformációit. Az eszköz beállítja a jelentett tulajdonságokat, és elküldi őket a központnak. A háttéralkalmazás a központban tárolt ikereszközről le tudja olvasni a jelentett tulajdonságok aktuális értékét.
Jelentett tulajdonságok küldése egy eszközről
Jelentett tulajdonságokra frissítéseket javítások formájában küldhet. A következő kódrészlet egy szimulált eszköz által küldött javítássablont mutat be. A szimulált eszköz frissíti a javítás mezőit, mielőtt elküldi 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ény segítségével küldi el a jelentett tulajdonságokból álló 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
Egy háttéralkalmazás a jelentett tulajdonságok aktuális értékéhez az ikereszközön keresztül fér hozzá. A következő kódrészlet bemutatja, hogyan olvassa be a háttéralkalmazás szimulált eszköz jelentett tulajdonságait:
// 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 lesz az eszköz és a szolgáltatás kapcsolati sztringjére. Ezt a sztringet az oktatóanyag elején, az erőforrások létrehozásánál jegyezte fel.
A szimulálteszköz-alkalmazás futtatásához nyisson meg egy kezelőfelületet vagy parancssori ablakot, és keresse meg a letöltött Node.js-projektben az iot-hub/Tutorials/DeviceTwins mappát. Ezután futtassa le a következő parancsokat:
npm install
node SimulatedDevice.js "{your device connection string}"
A háttéralkalmazás futtatásához nyisson meg egy újabb kezelőfelületet vagy parancssori ablakot. Keresse meg a letöltött Node.js-projektben az iot-hub/Tutorials/DeviceTwins mappát. Ezután futtassa le a következő parancsokat:
npm install
node ServiceClient.js "{your service connection string}"
A kívánt tulajdonságfrissítések megfigyelése
A következő képernyőkép bemutatja a szimulálteszköz-alkalmazás kimenetét, a kiemelt rész pedig arra vonatkozik, hogyan frissíti a maxTemperature kívánt tulajdonságot. Látható, hogy a legfelső szintű kezelő és az időjárási összetevő (climate component) egyaránt fut:
A következő képernyőkép bemutatja a háttéralkalmazás kimenetét, a kiemelt rész pedig arra vonatkozik, hogyan küld frissítést a maxTemperature kívánt tulajdonságnak:
Jelentett tulajdonságfrissítések megfigyelése
A következő képernyőkép bemutatja a szimulált eszközalkalmazás kimenetét, a kiemelt rész pedig arra vonatkozik, hogyan küld a központnak jelentett tulajdonságra vonatkozó frissítést:
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:
Az erőforrások eltávolí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, az erőforráscsoporttal együtt törölje a Portalon. 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.
Ha szeretné, a CLI-t is használhatja:
# Delete your resource group and its contents
az group delete --name tutorial-iot-hub-rg
Következő lépések
Ez az oktatóanyag azt ismertette, 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.