Samouczek: konfigurowanie urządzeń z poziomu usługi zaplecza

W ramach cyklu życia urządzenia może być konieczne skonfigurowanie urządzeń IoT z poziomu usługi zaplecza. Po wysłaniu żądanej konfiguracji do urządzeń chcesz również otrzymywać aktualizacje stanu i zgodności z tych urządzeń. Można na przykład ustawić docelowy zakres temperatury operacyjnej dla urządzenia lub zebrać informacje o wersji oprogramowania układowego z urządzeń.

Aby zsynchronizować informacje o stanie między urządzeniem a centrum IoT, należy użyć bliźniaczych urządzeń. Bliźniak urządzenia to dokument JSON skojarzony z określonym urządzeniem i przechowywany w IoT Hub w chmurze, na które można wykonywać zapytania. Bliźniacze reprezentacje urządzenia zawierają żądane właściwości, zgłoszone właściwości i tagi.

• Żądana właściwość jest ustawiana przez aplikację zaplecza i odczytywana przez urządzenie.
• zgłoszona właściwość jest ustawiana przez urządzenie i odczytywana przez aplikację serwerową.
• Tag jest ustawiany przez aplikację zaplecza i nigdy nie jest wysyłany do urządzenia. Tagi służą do organizowania urządzeń.

Ten samouczek pokazuje, jak używać właściwości żądanych i zgłoszonych do synchronizowania informacji o stanie.

Ten samouczek obejmuje wykonanie następujących zadań:

• Utwórz centrum IoT i dodaj urządzenie testowe do rejestru tożsamości.
• Użyj żądanych właściwości, aby wysyłać informacje o stanie do symulowanego urządzenia.
• Użyj zgłoszonych właściwości, aby odbierać informacje o stanie z urządzenia symulowanego.

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

Wymagania wstępne

• W tym samouczku do tworzenia zasobów w chmurze jest używany interfejs wiersza polecenia platformy Azure. Jeśli masz już centrum IoT z zarejestrowanym w nim urządzeniem, możesz pominąć te kroki. Istnieją dwa sposoby uruchamiania poleceń linii komend:

  • Użyj środowiska Bash w Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Przewodnik Szybki start usługi Azure Cloud Shell — Bash.

  • Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj Azure CLI. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze platformy Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić interfejs wiersza polecenia platformy Azure w kontenerze platformy Docker.

    • Zaloguj się do Azure CLI, używając polecenia az login.
    • Gdy zostaniesz poproszony, przy pierwszym użyciu zainstaluj rozszerzenia Azure CLI. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Korzystanie z rozszerzeń w interfejsie wiersza polecenia platformy Azure.
    • Uruchom az version, aby sprawdzić zainstalowaną wersję i biblioteki zależne. Aby przeprowadzić uaktualnienie do najnowszej wersji, uruchom polecenie az upgrade.

• Dwie przykładowe aplikacje uruchamiane w tym samouczku zostały napisane przy użyciu Node.js. Potrzebujesz Node.js wersji 10.x.x lub nowszej na komputerze deweloperskim.

  • Możesz pobrać środowisko Node.js dla wielu platform ze strony nodejs.org.

  • Możesz sprawdzić bieżącą wersję środowiska Node.js na komputerze deweloperskim przy użyciu następującego polecenia:

    node --version
    

• Sklonuj lub pobierz przykładowy projekt Node.js z przykładów usługi Azure IoT dla Node.js.

• Upewnij się, że port 8883 jest otwarty w twojej zaporze. Przykład urządzenia w tym samouczku używa protokołu MQTT, który przesyła dane za pośrednictwem portu 8883. Ten port może zostać zablokowany w niektórych środowiskach sieci firmowych i edukacyjnych. Aby uzyskać więcej informacji i sposobów obejścia tego problemu, zobacz Nawiązywanie połączenia z usługą IoT Hub (MQTT).

Konfigurowanie zasobów platformy Azure

Aby ukończyć ten samouczek, subskrypcja platformy Azure musi zawierać centrum IoT z urządzeniem dodanym do rejestru tożsamości urządzeń. Wpis w rejestrze tożsamości urządzeń umożliwia symulowanemu urządzeniu uruchomionemu w tym samouczku połączenie się z twoim centrum.

Jeśli nie masz jeszcze skonfigurowanego centrum IoT w ramach subskrypcji, możesz skonfigurować go za pomocą następującego skryptu interfejsu wiersza polecenia. Ten skrypt używa nazwy tutorial-iot-hub z numerem losowym dołączonym do nazwy centrum IoT. Możesz zastąpić tę nazwę własną globalnie unikatową nazwą podczas jej uruchamiania. Skrypt tworzy grupę zasobów i punkt centralny w regionie Centralny region USA, który można zmienić do regionu bliżej ciebie. Skrypt pobiera parametry połączenia usługi IoT Hub, które są używane w przykładzie zaplecza w celu nawiązania połączenia z centrum 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

W tym samouczku używamy symulowanego urządzenia o nazwie MyTwinDevice. Poniższy skrypt dodaje to urządzenie do rejestru tożsamości i pobiera jego parametry połączenia:

# 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

Wysyłanie informacji o stanie do urządzenia

Żądane właściwości służą do wysyłania informacji o stanie z aplikacji zaplecza do urządzenia. W tej sekcji zobaczysz, jak wykonać następujące działania:

• Skonfiguruj urządzenie do odbierania i przetwarzania żądanych właściwości.
• Wysyłanie żądanych właściwości z aplikacji zaplecza do urządzenia.

Przykładowe żądane właściwości

Możesz ustawić pożądane właściwości w dowolny sposób, który jest najwygodniejszy dla Twojej aplikacji. W tym przykładzie użyto jednej właściwości najwyższego poziomu o nazwie fanOn i grupuje pozostałe właściwości w osobnych składnikach. Poniższy fragment kodu JSON przedstawia strukturę żądanych właściwości używanych w tym samouczku. Plik JSON znajduje się w pliku desired.json.

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

Odbieranie żądanych właściwości w aplikacji urządzenia

Aby wyświetlić przykładowy kod urządzenia symulowanego, który odbiera żądane właściwości, przejdź do folderu iot-hub/Tutorials/DeviceTwins w przykładowym projekcie Node.js pobranym. Następnie otwórz plik SimulatedDevice.js w edytorze tekstów.

W poniższych sekcjach opisano kod uruchamiany na symulowanym urządzeniu, który odpowiada na żądane zmiany właściwości wysyłane z aplikacji zaplecza.

Pobierz obiekt bliźniaka urządzenia

Po zarejestrowaniu urządzenia w centrum IoT otrzymasz parametry połączenia urządzenia jako dane wyjściowe. Parametry połączenia urządzenia są używane przez urządzenie do uwierzytelniania za pomocą zarejestrowanej tożsamości w chmurze. Poniższy kod łączy się z twoim IoT Hub za pomocą łańcucha połączenia urządzenia:

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

Poniższy kod pobiera bliźniaka z obiektu 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'));

Tworzenie programów obsługi

Możesz utworzyć obsługujące dla żądanych aktualizacji właściwości, które reagują na aktualizacje na różnych poziomach hierarchii JSON. Na przykład ten obsługujący widzi wszystkie pożądane zmiany właściwości wysyłane do urządzenia z aplikacji zaplecza. Zmienna delta zawiera pożądane właściwości otrzymane z zaplecza rozwiązania.

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

Następująca procedura obsługi reaguje tylko na zmiany wprowadzone w żądanej właściwości 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}';
});

Programy obsługi dla wielu właściwości

W przykładowym pliku JSON pożądanych właściwości dla tego samouczka, węzeł klimat w sekcji komponenty zawiera dwie właściwości: minTemperature i maxTemperature.

Lokalny obiekt bliźniaczy urządzenia przechowuje kompletny zestaw żądanych i raportowanych właściwości. Delta wysłana z zaplecza może zaktualizować tylko podzbiór żądanych właściwości. W poniższym fragmencie kodu, jeśli symulowane urządzenie otrzyma aktualizację tylko jednej z wartości minTemperature lub maxTemperature, używa wartości z lokalnej kopii bliźniaczej dla drugiej wartości, aby skonfigurować urządzenie.

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

Obsługa operacji wstawiania, aktualizowania i usuwania

Oczekiwane właściwości wysyłane z zaplecza systemowego nie wskazują, jaka operacja jest wykonywana na określonej oczekiwanej właściwości. Kod musi wywnioskować operację z bieżącego zestawu pożądanych właściwości przechowywanych lokalnie i zmian wysyłanych z centralnego systemu.

Poniższy fragment kodu pokazuje, jak symulowane urządzenie obsługuje operacje wstawiania, aktualizowania i usuwania na liście składników we żądanych właściwościach. Zobaczysz, jak używać wartości null , aby wskazać, że składnik powinien zostać usunięty:

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

Wysyłanie żądanych właściwości z aplikacji zaplecza

Wiesz już, jak urządzenie implementuje programy obsługi do odbierania żądanych aktualizacji właściwości. W tej sekcji pokazano, jak wysyłać zmiany żądanej właściwości do urządzenia z aplikacji zaplecza.

Aby wyświetlić przykładowy kod urządzenia symulowanego, który odbiera żądane właściwości, przejdź do folderu iot-hub/Tutorials/DeviceTwins w przykładowym projekcie Node.js pobranym. Następnie otwórz plik ServiceClient.js w edytorze tekstów.

Poniższy fragment kodu pokazuje, jak nawiązać połączenie z rejestrem tożsamości urządzenia i uzyskać dostęp do bliźniaczej reprezentacji dla określonego urządzenia:

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

Poniższy fragment kodu przedstawia różne poprawki żądanej właściwości wysyłane do urządzenia przez aplikację zaplecza:

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

Poniższy fragment kodu pokazuje, jak aplikacja zaplecza wysyła żądaną aktualizację właściwości do urządzenia:

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

Odbieranie informacji o stanie z urządzenia

Aplikacja typu back-end odbiera informacje o stanie z urządzenia jako raportowane właściwości. Urządzenie ustawia zgłoszone właściwości i przesyła je do huba. Aplikacja back-endowa może odczytywać bieżące wartości raportowanych właściwości z bliźniaka urządzenia przechowywanego w Twoim hubie.

Wysyłanie zgłoszonych właściwości z urządzenia

Aktualizacje raportowanych wartości właściwości można wysyłać jako poprawkę. Poniższy fragment kodu przedstawia szablon poprawki wysyłanej przez symulowane urządzenie. Symulowane urządzenie aktualizuje pola w poprawce przed wysłaniem ich do centrum:

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

Urządzenie symulowane używa następującej funkcji do wysyłania poprawki zawierającej zgłoszone właściwości do centrum:

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

Przetwarzanie zgłoszonych właściwości

Aplikacja back-end uzyskuje dostęp do bieżących zgłoszonych wartości właściwości dla urządzenia za pośrednictwem bliźniaka urządzenia. Poniższy fragment kodu pokazuje, jak aplikacja zaplecza odczytuje zgłaszane wartości właściwości dla symulowanego urządzenia:

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

Uruchamianie aplikacji

W tej sekcji uruchomisz dwie przykładowe aplikacje, aby obserwować, jak aplikacja zaplecza wysyła żądane aktualizacje właściwości do aplikacji symulowanego urządzenia.

Aby uruchomić symulowane urządzenia i aplikacje zaplecza, potrzebne są parametry połączenia urządzenia i usługi. Podczas tworzenia zasobów na początku tego samouczka zanotowałeś parametry połączenia.

Aby uruchomić aplikację urządzenia symulowanego, otwórz okno terminala lub wiersza polecenia i przejdź do folderu iot-hub/Tutorials/DeviceTwins w pobranym projekcie Node.js. Następnie uruchom następujące polecenia:

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

Aby uruchomić aplikację zaplecza, otwórz inną powłokę lub okno wiersza polecenia. Następnie przejdź do folderu iot-hub/Tutorials/DeviceTwins w pobranym projekcie Node.js. Następnie uruchom następujące polecenia:

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

Obserwowanie aktualizacji żądanych właściwości

Poniższy zrzut ekranu przedstawia dane wyjściowe z aplikacji symulowanego urządzenia i przedstawia sposób obsługi aktualizacji żądanej właściwości maxTemperature . Zobaczysz, jak działa program obsługi najwyższego poziomu i programy obsługi składników klimatu:

Poniższy zrzut ekranu przedstawia dane wyjściowe z aplikacji zaplecza i przedstawia sposób wysyłania aktualizacji do żądanej właściwości maxTemperature :

Obserwuj zgłoszone aktualizacje nieruchomości

Poniższy zrzut ekranu przedstawia dane wyjściowe z aplikacji urządzenia symulowanego i przedstawia sposób wysyłania aktualizacji zgłaszanej właściwości do centrum:

Poniższy zrzut ekranu przedstawia dane wyjściowe z aplikacji zaplecza i wyróżnia sposób, w jaki odbiera i przetwarza zgłoszoną aktualizację właściwości z urządzenia:

Czyszczenie zasobów

Jeśli planujesz ukończyć następny samouczek, pozostaw grupę zasobów i centrum IoT, aby móc je ponownie wykorzystać później.

Jeśli nie potrzebujesz już tego centrum IoT, usuń je oraz grupę zasobów z poziomu portalu. W tym celu wybierz grupę zasobów tutorial-iot-hub-rg zawierającą centrum IoT, a następnie wybierz pozycję Usuń.

Alternatywnie, użyj CLI:

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

Następne kroki

W tym samouczku nauczyłeś się, jak synchronizować informacje o stanie między swoimi urządzeniami a IoT Hub. Przejdź do następnego samouczka, aby dowiedzieć się, jak za pomocą device twins wprowadzić proces aktualizacji urządzeń.

Zaimplementuj aktualizację urządzenia dla usługi Azure IoT Hub , korzystając z obrazu referencyjnego urządzenia Raspberry Pi 3 B+.