Tutorial: Mengonfigurasi perangkat Anda dari layanan back-end
Sebagai bagian dari siklus hidup perangkat, Anda mungkin perlu mengonfigurasi perangkat IoT dari layanan back-end Anda. Saat mengirim konfigurasi yang diinginkan ke perangkat, Anda juga ingin menerima pembaruan status dan kepatuhan dari perangkat tersebut. Misalnya, Anda dapat mengatur rentang suhu operasional target untuk perangkat atau mengumpulkan informasi versi firmware dari perangkat Anda.
Untuk menyinkronkan informasi status antara perangkat dan IoT Hub, Anda menggunakan perangkat ganda. Perangkat ganda adalah dokumen JSON, yang terkait dengan perangkat tertentu, dan disimpan oleh IoT Hub di cloud tempat Anda dapat mengkuerinya. Perangkat ganda berisi properti yang diinginkan, properti yang dilaporkan, dan tag.
- Properti yang diinginkan diatur oleh aplikasi back-end dan dibaca oleh perangkat.
- Properti yang dilaporkan diatur oleh perangkat dan dibaca oleh aplikasi back-end.
- Tag diatur oleh aplikasi back-end dan tidak pernah dikirim ke perangkat. Anda menggunakan tag untuk mengatur perangkat Anda.
Tutorial ini menunjukkan kepada Anda cara menggunakan properti yang diinginkan dan dilaporkan untuk menyinkronkan informasi status.
Dalam tutorial ini, Anda melakukan tugas berikut:
- Membuat IoT Hub dan menambahkan perangkat uji ke registri identitas.
- Menggunakan properti yang diinginkan untuk mengirim informasi status ke perangkat Anda yang disimulasikan.
- Menggunakan properti yang dilaporkan untuk menerima informasi status dari perangkat yang disimulasikan.
Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.
Prasyarat
Tutorial ini menggunakan Azure CLI untuk membuat sumber daya cloud. Jika Anda sudah memiliki hub IoT dengan perangkat yang terdaftar di dalamnya, Anda dapat melewati langkah-langkah tersebut. Ada dua cara untuk menjalankan perintah CLI:
Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai Cepat Azure Cloud Shell - Bash.
Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.
- Masuk ke Azure CLI dengan perintah az login.
- Saat diminta, pasang ekstensi saat pertama kali menggunakan Azure CLI. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan ekstensi dengan Azure CLI.
- Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan peningkatan az.
Dua aplikasi sampel yang Anda jalankan dalam tutorial ini ditulis menggunakan Node.js. Anda perlu Node.js v10.x.x atau lebih baru di komputer pengembangan Anda.
Anda dapat mengunduh Node.js untuk beberapa platform dari nodejs.org.
Anda dapat memverifikasi versi Node.js saat ini di komputer pengembangan Anda menggunakan perintah berikut:
node --version
Kloning atau unduh sampel proyek Node.js dari sampel Azure IoT untuk Node.js.
Pastikan port 8883 terbuka di firewall Anda. Sampel perangkat dalam tutorial ini menggunakan protokol MQTT, yang berkomunikasi melalui port 8883. Port ini dapat diblokir di beberapa lingkungan jaringan perusahaan dan pendidikan. Untuk informasi selengkapnya dan cara mengatasi masalah ini, lihat Menyambungkan ke Azure IoT Hub (MQTT).
Menyiapkan sumber daya Azure
Untuk menyelesaikan tutorial ini, langganan Azure Anda harus berisi IoT Hub dengan perangkat yang ditambahkan ke registri identitas perangkat. Entri dalam registri identitas perangkat memungkinkan perangkat simulasi yang Anda jalankan dalam tutorial ini untuk terhubung ke hub Anda.
Jika belum menyiapkan IoT Hub di langganan, Anda bisa menyiapkannya dengan skrip CLI berikut ini. Skrip ini menggunakan nama tutorial-iot-hub dengan angka acak yang ditambahkan untuk nama hub IoT. Anda dapat mengganti nama ini dengan nama unik global Anda sendiri saat menjalankannya. Skrip membuat grup sumber daya dan hub di wilayah US Tengah, yang dapat Anda ubah ke wilayah yang lebih dekat dengan Anda. Skrip mengambil string koneksi layanan IoT Hub Anda, yang Anda gunakan dalam sampel back-end untuk menyambungkan ke IoT Hub Anda:
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
Tutorial ini menggunakan perangkat simulasi yang disebut MyTwinDevice. Skrip berikut ini menambahkan perangkat ini ke registri identitas Anda dan mengambil string koneksinya:
# 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
Mengirim informasi status ke perangkat
Anda menggunakan properti yang diinginkan untuk mengirim informasi status dari aplikasi back-end ke perangkat. Di bagian ini, Anda akan melihat cara:
- Konfigurasikan perangkat untuk menerima dan memproses properti yang diinginkan.
- Kirim properti yang diinginkan dari aplikasi back-end ke perangkat.
Sampel properti yang diinginkan
Anda dapat menyusun properti yang Anda inginkan dengan cara apa pun yang nyaman untuk aplikasi Anda. Contoh ini menggunakan satu properti tingkat atas yang disebut fanOn dan mengelompokkan properti yang tersisa ke dalam komponen terpisah. Cuplikan JSON berikut menunjukkan struktur properti yang diinginkan yang digunakan tutorial ini. JSON berada di file desired.json.
{
"fanOn": "true",
"components": {
"system": {
"id": "17",
"units": "farenheit",
"firmwareVersion": "9.75"
},
"wifi" : {
"channel" : "6",
"ssid": "my_network"
},
"climate" : {
"minTemperature": "68",
"maxTemperature": "76"
}
}
}
Menerima properti yang diinginkan dalam aplikasi perangkat
Untuk melihat kode sampel perangkat yang disimulasikan yang menerima properti yang diinginkan, buka folder iot-hub/Tutorials/DeviceTwins dalam sampel Node.js yang Anda unduh. Kemudian, buka file SimulatedDevice.js di editor teks.
Bagian berikut menjelaskan kode yang berjalan pada perangkat simulasi yang merespons perubahan properti yang diinginkan yang dikirim dari aplikasi back end.
Mengambil objek perangkat ganda
Saat mendaftarkan perangkat dengan hub IoT, Anda mendapatkan perangkat string koneksi sebagai output. Perangkat string koneksi digunakan oleh perangkat untuk mengautentikasi dengan identitas terdaftarnya di cloud. Kode berikut terhubung ke IoT Hub Anda menggunakan string koneksi perangkat:
// Get the device connection string from a command line argument
var connectionString = process.argv[2];
Kode berikut mendapatkan penggandaan dari objek klien:
// 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'));
Membuat penangan
Anda dapat membuat penangan untuk pembaruan properti yang diinginkan yang merespons pembaruan pada tingkat yang berbeda dalam hierarki JSON. Misalnya, penangan ini melihat semua perubahan properti yang diinginkan yang dikirim ke perangkat dari aplikasi back-end. Variabel delta berisi properti yang diinginkan yang dikirim dari back end solusi:
// Handle all desired property updates
twin.on('properties.desired', function(delta) {
console.log(chalk.yellow('\nNew desired properties received in patch:'));
Penangan berikut hanya bereaksi terhadap perubahan yang dilakukan pada properti yang diinginkan 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}';
});
Penangan untuk beberapa properti
Dalam sampel properti yang diinginkan JSON untuk tutorial ini, node iklim di bawah komponen berisi dua properti, minTemperature dan maxTemperature.
Objek ganda lokal perangkat menyimpan sekumpulan properti yang diinginkan dan dilaporkan. Delta yang dikirim dari back end mungkin hanya memperbarui subkumpulan properti yang diinginkan. Dalam cuplikan kode berikut, jika perangkat yang disimulasikan menerima pembaruan hanya untuk salah satu minTemperature dan maxTemperature, perangkat akan menggunakan nilai dalam ganda lokal agar nilai lain mengonfigurasi perangkat:
// 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();
}
});
Menangani operasi penyisipan, pembaruan, dan penghapusan
Properti yang diinginkan dikirim dari back end tidak menunjukkan operasi apa yang dilakukan pada properti tertentu yang diinginkan. Kode Anda perlu menyimpulkan operasi dari kumpulan properti yang diinginkan saat ini yang disimpan secara lokal dan perubahan yang dikirim dari hub.
Cuplikan berikut menunjukkan bagaimana perangkat yang disimulasikan menangani operasi penyisipan, pembaruan, dan penghapusan pada daftar komponen dalam properti yang diinginkan. Anda dapat melihat cara menggunakan nilai null untuk menunjukkan bahwa komponen harus dihapus:
// 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];
}
}
});
}
});
Mengirim properti yang diinginkan dari aplikasi back end
Anda telah melihat bagaimana perangkat mengimplementasikan penangan untuk menerima pembaruan properti yang diinginkan. Bagian ini menunjukkan cara mengirim perubahan properti yang diinginkan ke perangkat dari aplikasi back-end.
Untuk melihat kode sampel perangkat yang disimulasikan yang menerima properti yang diinginkan, buka folder iot-hub/Tutorials/DeviceTwins dalam sampel Node.js yang Anda unduh. Kemudian, buka file ServiceClient.js di editor teks.
Cuplikan kode berikut menunjukkan cara terhubung ke registri identitas perangkat dan mengakses ganda untuk perangkat tertentu:
// 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');
Cuplikan berikut menunjukkan patch properti berbeda yang diinginkan yang dikirim aplikasi back end ke perangkat:
// 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
}
}
}
};
Cuplikan berikut menunjukkan bagaimana aplikasi back-end mengirimkan pembaruan properti yang diinginkan ke perangkat:
// 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));
}
});
}
Menerima informasi status dari perangkat
Aplikasi back-end Anda menerima informasi status dari perangkat sebagai properti yang dilaporkan. Perangkat mengatur properti yang dilaporkan, dan mengirimkannya ke hub Anda. Aplikasi back-end dapat membaca nilai saat ini dari properti yang dilaporkan dari perangkat ganda yang disimpan di hub Anda.
Mengirim properti yang dilaporkan dari perangkat
Anda dapat mengirim pembaruan ke nilai properti yang dilaporkan sebagai patch. Cuplikan berikut menunjukkan templat untuk patch yang dikirim perangkat yang disimulasikan. Perangkat yang disimulasikan memperbarui bidang di patch sebelum mengirimkannya ke hub:
// Create a patch to send to the hub
var reportedPropertiesPatch = {
firmwareVersion:'1.2.1',
lastPatchReceivedId: '',
fanOn:'',
minTemperature:'',
maxTemperature:''
};
Perangkat yang disimulasikan menggunakan fungsi berikut untuk mengirim patch yang berisi properti yang dilaporkan ke hub:
// 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));
});
}
Memproses properti yang dilaporkan
Aplikasi back-end mengakses nilai properti yang dilaporkan saat ini untuk perangkat melalui perangkat ganda. Cuplikan berikut menunjukkan bagaimana aplikasi back-end membaca nilai properti yang dilaporkan untuk perangkat yang disimulasikan:
// 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);
}
Menjalankan aplikasi
Di bagian ini, Anda menjalankan dua aplikasi sampel untuk diamati sebagai aplikasi back-end mengirimkan pembaruan properti yang diinginkan ke aplikasi perangkat yang disimulasikan.
Untuk menjalankan perangkat yang disimulasikan dan aplikasi back-end, Anda perlu string koneksi perangkat dan layanan. Anda membuat catatan string koneksi ketika membuat sumber daya di awal tutorial ini.
Untuk menjalankan aplikasi perangkat yang disimulasikan, buka jendela wantian perintah atau shell dan buka folder iot-hub/Tutorials/DeviceTwins di proyek Node.js yang Anda unduh. Kemudian jalankan perintah berikut:
npm install
node SimulatedDevice.js "{your device connection string}"
Untuk menjalankan aplikasi back-end, buka jendela shell atau prompt perintah lain. Kemudian, buka folder iot-hub/Tutorials/DeviceTwins di proyek Node.js yang Anda unduh. Kemudian jalankan perintah berikut:
npm install
node ServiceClient.js "{your service connection string}"
Amati pembaruan properti yang diinginkan
Cuplikan layar berikut menunjukkan output dari aplikasi perangkat yang disimulasikan dan menyoroti caranya menangani pembaruan ke properti maxTemperature yang diinginkan. Anda dapat melihat bagaimana penangan tingkat atas dan penangan komponen iklim berjalan:
Cuplikan layar berikut menunjukkan output dari aplikasi back-end dan menyoroti bagaimana caranya mengirim pembaruan ke properti maxTemperature yang diinginkan:
Amati pembaruan properti yang dilaporkan
Cuplikan layar berikut menunjukkan output dari aplikasi perangkat yang disimulasikan dan menyoroti cara mengirim pembaruan properti yang dilaporkan ke hub Anda:
Cuplikan layar berikut menunjukkan output dari aplikasi back-end dan menyoroti bagaimana caranya menerima dan memproses pembaruan properti yang dilaporkan dari perangkat:
Membersihkan sumber daya
Jika Anda berencana untuk menyelesaikan tutorial berikutnya, tinggalkan grup sumber daya dan hub IoT untuk menggunakannya kembali nanti.
Jika Anda tidak memerlukan IoT hub lagi, hapus lot hub dan grup sumber daya di portal. Untuk melakukannya, pilih grup sumber daya tutorial-iot-hub-rg yang berisi hub IoT Anda dan pilih Hapus.
Atau, gunakan CLI:
# Delete your resource group and its contents
az group delete --name tutorial-iot-hub-rg
Langkah berikutnya
Dalam tutorial ini, Anda mempelajari cara menyinkronkan informasi status antara perangkat dan IoT Hub Anda. Lanjutkan ke tutorial berikutnya untuk mempelajari cara menggunakan perangkat kembar guna mengimplementasikan proses pembaruan perangkat.