Samouczek: tworzenie modułów języka C IoT Edge przy użyciu kontenerów systemu Windows
Dotyczy ikony:
IoT Edge 1.1
Ważne
IoT Edge 1.1 data zakończenia wsparcia technicznego wynosiła 13 grudnia 2022 r. Zapoznaj się z cyklem życia produktów firmy Microsoft, aby uzyskać informacje na temat sposobu obsługi tego produktu lub interfejsu API albo tej usługi lub technologii. Aby uzyskać więcej informacji na temat aktualizowania do najnowszej wersji IoT Edge, zobacz Update IoT Edge.
W tym artykule pokazano, jak za pomocą programu Visual Studio opracowywać kod języka C i wdrażać go na urządzeniu z systemem Windows z uruchomioną usługą Azure IoT Edge.
Uwaga
IoT Edge 1.1 LTS to ostatni kanał wersji obsługujący kontenery systemu Windows. Począwszy od wersji 1.2, kontenery systemu Windows nie są obsługiwane. Rozważ użycie lub przejście do IoT Edge dla systemu Linux w systemie Windows, aby uruchomić IoT Edge na urządzeniach z systemem Windows.
Moduły usługi Azure IoT Edge umożliwiają wdrażanie kodu, który implementuje logikę biznesową bezpośrednio na urządzeniach IoT Edge. W tym samouczku przedstawiono sposób tworzenia i wdrażania modułu usługi IoT Edge, w którym są filtrowane dane czujnika.
Ten samouczek zawiera informacje na temat wykonywania następujących czynności:
- Użyj programu Visual Studio, aby utworzyć moduł IoT Edge oparty na zestawie SDK języka C.
- Użyj programu Visual Studio i platformy Docker, aby utworzyć obraz platformy Docker i opublikować go w rejestrze.
- Wdrażanie modułu na urządzeniu usługi IoT Edge.
- Wyświetlanie wygenerowanych danych.
Utworzony w tym samouczku moduł usługi IoT Edge filtruje dane temperatury generowane przez urządzenie. Moduł wysyła komunikaty nadrzędne tylko wtedy, gdy temperatura przekroczy określony próg. Ten typ analizy brzegowej pomaga zmniejszyć ilość danych przekazywanych do chmury i w niej przechowywanych.
Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto platformy Azure.
Wymagania wstępne
W tym samouczku pokazano, jak opracować moduł w języku C przy użyciu programu Visual Studio 2019, a następnie wdrożyć go na urządzeniu z systemem Windows. Jeśli tworzysz moduły przy użyciu kontenerów systemu Linux, przejdź do tematu Opracowywanie modułów IoT Edge języka C przy użyciu kontenerów systemu Linux.
Aby poznać opcje tworzenia i wdrażania modułów języka C przy użyciu kontenerów systemu Windows, zapoznaj się z poniższą tabelą:
| C | Visual Studio Code | Visual Studio 2017 i 2019 |
|---|---|---|
| Windows AMD64 |  |
Przed rozpoczęciem tego samouczka skonfiguruj środowisko programistyczne, postępując zgodnie z instrukcjami w samouczku Programowanie modułów IoT Edge przy użyciu kontenerów systemu Windows. Po zakończeniu tego procesu środowisko będzie zawierać następujące wymagania wstępne:
- Bezpłatne lub standardowe centrum IoT Hub na platformie Azure.
- Urządzenie z systemem Windows z systemem Azure IoT Edge.
- Rejestr kontenerów, taki jak Azure Container Registry.
- Program Visual Studio 2019 skonfigurowany przy użyciu rozszerzenia Azure IoT Edge Tools.
- Program Docker Desktop skonfigurowany do uruchamiania kontenerów systemu Windows.
Zainstaluj zestaw SDK języka C usługi Azure IoT dla systemu Windows x64 za pomocą narzędzia vcpkg, uruchamiając następujące polecenia:
git clone https://github.com/Microsoft/vcpkg
cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg install azure-iot-sdk-c:x64-windows
.\vcpkg --triplet x64-windows integrate install
Porada
Jeśli używasz programu Visual Studio 2017 (w wersji 15.7 lub nowszej), pobierz i zainstaluj Azure IoT Edge Tools dla programu Visual Studio 2017 z witryny Visual Studio Marketplace.
Twórca projektu modułu
W tej sekcji utworzysz projekt modułu IoT Edge oparty na zestawie SDK języka C przy użyciu programu Visual Studio i rozszerzenia Azure IoT Edge Tools. Po utworzeniu szablonu projektu dodasz nowy kod, aby moduł filtrował komunikaty na podstawie ich zgłoszonych właściwości.
Tworzenie nowego projektu
Utwórz szablon rozwiązania języka C, który można dostosować przy użyciu własnego kodu.
Otwórz program Visual Studio 2019, a następnie wybierz pozycję Twórca Nowy projekt.
Na Twórca okienku nowego projektu wyszukaj IoT Edge, a następnie na liście wyników wybierz projekt Azure IoT Edge (Windows amd64).
Wybierz opcję Dalej.
Zostanie otwarte okienko Konfigurowanie nowego projektu .
W okienku Konfigurowanie nowego projektu zmień nazwę projektu i rozwiązania na bardziej opisowy, na przykład CTutorialApp.
Wybierz polecenie Create (Utwórz), aby utworzyć projekt.
Zostanie otwarte okienko Dodawanie modułu .
Na stronie Konfigurowanie nowego projektu wykonaj następujące czynności:
a. W okienku po lewej stronie wybierz szablon Moduł języka C .
b. W polu Nazwa modułu wprowadź wartość CModule.
c. W polu Adres URL repozytorium zastąp wartość localhost:5000 wartością serwera logowania z rejestru kontenerów platformy Azure w następującym formacie:<registry name>.azurecr.io/cmoduleUwaga
Repozytorium obrazów zawiera nazwę rejestru kontenerów oraz nazwę obrazu kontenera. Obraz kontenera jest wstępnie wypełniany na podstawie wartości nazwa projektu modułu. Serwer logowania można pobrać ze strony przeglądu rejestru kontenerów w Azure Portal.
Wybierz pozycję Dodaj , aby utworzyć projekt.
Dodawanie poświadczeń rejestru
Manifest wdrożenia udostępnia poświadczenia dla rejestru kontenerów za pomocą środowiska uruchomieniowego IoT Edge. Środowisko uruchomieniowe wymaga tych poświadczeń do ściągnięcia prywatnych obrazów na urządzenie usługi IoT Edge. Użyj poświadczeń z sekcji Klucze dostępu rejestru kontenerów platformy Azure.
W programie Visual Studio Eksplorator rozwiązań otwórz plik deployment.template.json.
Wyszukaj właściwość registryCredentials w żądanych właściwościach $edgeAgent. Adres rejestru właściwości powinien zostać wypełniony automatycznie przy użyciu informacji podanych podczas tworzenia projektu. Pola nazwy użytkownika i hasła powinny zawierać nazwy zmiennych. Na przykład:
"registryCredentials": { "<registry name>": { "username": "$CONTAINER_REGISTRY_USERNAME_<registry name>", "password": "$CONTAINER_REGISTRY_PASSWORD_<registry name>", "address": "<registry name>.azurecr.io" } }Otwórz plik środowiska (ENV) w rozwiązaniu modułu. Domyślnie plik jest ukryty w Eksplorator rozwiązań, więc może być konieczne wybranie przycisku Pokaż wszystkie pliki, aby go wyświetlić. Plik ENV powinien zawierać te same zmienne nazwy użytkownika i hasła, które są wyświetlane w pliku deployment.template.json .
Dodaj wartości Nazwa użytkownika i Hasło z rejestru kontenerów platformy Azure.
Zapisz zmiany w pliku ENV.
Aktualizowanie modułu przy użyciu kodu niestandardowego
Domyślny kod modułu odbiera komunikaty w kolejce wejściowej i przekazuje je przez kolejkę wyjściową. Dodajmy więcej kodu, aby moduł przetwarzał komunikaty na brzegu przed przekazaniem ich do centrum IoT. Zaktualizuj moduł, aby analizować dane temperatury w każdym komunikacie i wysyłać komunikat do centrum IoT tylko wtedy, gdy temperatura przekroczy określony próg.
Dane z czujnika w tym scenariuszu są dostępne w formacie JSON. Aby filtrować komunikaty w formacie JSON, należy zaimportować bibliotekę JSON dla języka C. W tym samouczku używana jest biblioteka Parson.
a. Pobierz repozytorium Parson GitHub.
b. Skopiuj pliki parson.c i parson.h do projektu CModule.
c. W programie Visual Studio otwórz plik CMakeLists.txt z folderu projektu CModule.
d. Na początku zaimportuj pliki biblioteki Parson jako bibliotekę o nazwie my_parson.add_library(my_parson parson.c parson.h )e. Dodaj
my_parsondo listy bibliotek w sekcji "target_link_libraries" pliku CMakeLists.txt .
f. Zapisz plik CMakeLists.txt.
g. Wybierz pozycję CModule>main.c. W dolnej części listy instrukcji include dodaj nową instrukcję do uwzględnieniaparson.hna potrzeby obsługi formatu JSON:#include "parson.h"W pliku main.c dodaj zmienną globalną o nazwie
temperatureThresholdobok zmiennejmessagesReceivedByInput1Queue. Ta zmienna ustawia wartość, która musi przekraczać mierzoną temperaturę, aby dane zostały wysłane do centrum IoT.static double temperatureThreshold = 25;CreateMessageInstanceZnajdź funkcję w pliku main.c. Zastąp wewnętrzną instrukcję if-else następującym kodem, który dodaje kilka wierszy funkcjonalności:if ((messageInstance->messageHandle = IoTHubMessage_Clone(message)) == NULL) { free(messageInstance); messageInstance = NULL; } else { messageInstance->messageTrackingId = messagesReceivedByInput1Queue; MAP_HANDLE propMap = IoTHubMessage_Properties(messageInstance->messageHandle); if (Map_AddOrUpdate(propMap, "MessageType", "Alert") != MAP_OK) { printf("ERROR: Map_AddOrUpdate Failed!\r\n"); } }Nowe wiersze kodu w instrukcji else dodają nową właściwość do komunikatu, która oznacza komunikat jako alert. Ten kod oznacza wszystkie komunikaty jako alerty, ponieważ dodamy funkcję, która wysyła komunikaty do centrum IoT tylko wtedy, gdy będą zgłaszać wysokie temperatury.
InputQueue1CallbackZnajdź funkcję i zastąp całą funkcję następującym kodem. Ta funkcja implementuje rzeczywisty filtr komunikatów. Po odebraniu komunikatu sprawdza, czy zgłoszona temperatura przekracza próg. Jeśli temperatura przekroczy próg, funkcja przekazuje komunikat za pośrednictwem kolejki wyjściowej. Jeśli nie przekroczy progu, funkcja ignoruje komunikat.static unsigned char *bytearray_to_str(const unsigned char *buffer, size_t len) { unsigned char *ret = (unsigned char *)malloc(len + 1); memcpy(ret, buffer, len); ret[len] = '\0'; return ret; } static IOTHUBMESSAGE_DISPOSITION_RESULT InputQueue1Callback(IOTHUB_MESSAGE_HANDLE message, void* userContextCallback) { IOTHUBMESSAGE_DISPOSITION_RESULT result; IOTHUB_CLIENT_RESULT clientResult; IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle = (IOTHUB_MODULE_CLIENT_LL_HANDLE)userContextCallback; unsigned const char* messageBody; size_t contentSize; if (IoTHubMessage_GetByteArray(message, &messageBody, &contentSize) == IOTHUB_MESSAGE_OK) { messageBody = bytearray_to_str(messageBody, contentSize); } else { messageBody = "<null>"; } printf("Received Message [%zu]\r\n Data: [%s]\r\n", messagesReceivedByInput1Queue, messageBody); // Check whether the message reports temperatures that exceed the threshold JSON_Value *root_value = json_parse_string(messageBody); JSON_Object *root_object = json_value_get_object(root_value); double temperature; // If temperature exceeds the threshold, send to output1 if (json_object_dotget_value(root_object, "machine.temperature") != NULL && (temperature = json_object_dotget_number(root_object, "machine.temperature")) > temperatureThreshold) { printf("Machine temperature %f exceeds threshold %f\r\n", temperature, temperatureThreshold); // This message should be sent to next stop in the pipeline, namely "output1". What happens at "outpu1" is determined // by the configuration of the Edge routing table setup. MESSAGE_INSTANCE *messageInstance = CreateMessageInstance(message); if (NULL == messageInstance) { result = IOTHUBMESSAGE_ABANDONED; } else { printf("Sending message (%zu) to the next stage in pipeline\n", messagesReceivedByInput1Queue); clientResult = IoTHubModuleClient_LL_SendEventToOutputAsync(iotHubModuleClientHandle, messageInstance->messageHandle, "output1", SendConfirmationCallback, (void *)messageInstance); if (clientResult != IOTHUB_CLIENT_OK) { IoTHubMessage_Destroy(messageInstance->messageHandle); free(messageInstance); printf("IoTHubModuleClient_LL_SendEventToOutputAsync failed on sending msg#=%zu, err=%d\n", messagesReceivedByInput1Queue, clientResult); result = IOTHUBMESSAGE_ABANDONED; } else { result = IOTHUBMESSAGE_ACCEPTED; } } } // If message does not exceed the threshold, do not forward else { printf("Not sending message (%zu) to the next stage in pipeline.\r\n", messagesReceivedByInput1Queue); result = IOTHUBMESSAGE_ACCEPTED; } messagesReceivedByInput1Queue++; return result; }Dodaj funkcję
moduleTwinCallback. Ta metoda odbiera aktualizacje odpowiednich właściwości z bliźniaczej reprezentacji modułu i aktualizuje zmienną temperatureThreshold, aby ją dopasować. Wszystkie moduły mają własną bliźniaczą reprezentację modułu, która umożliwia skonfigurowanie kodu uruchomionego wewnątrz modułu bezpośrednio z chmury.static void moduleTwinCallback(DEVICE_TWIN_UPDATE_STATE update_state, const unsigned char* payLoad, size_t size, void* userContextCallback) { printf("\r\nTwin callback called with (state=%s, size=%zu):\r\n%s\r\n", MU_ENUM_TO_STRING(DEVICE_TWIN_UPDATE_STATE, update_state), size, payLoad); JSON_Value *root_value = json_parse_string(payLoad); JSON_Object *root_object = json_value_get_object(root_value); if (json_object_dotget_value(root_object, "desired.TemperatureThreshold") != NULL) { temperatureThreshold = json_object_dotget_number(root_object, "desired.TemperatureThreshold"); } if (json_object_get_value(root_object, "TemperatureThreshold") != NULL) { temperatureThreshold = json_object_get_number(root_object, "TemperatureThreshold"); } }SetupCallbacksForModuleWyszukaj funkcję . Zastąp funkcję następującym kodem, który dodaje instrukcję else-if , aby sprawdzić, czy bliźniaczą reprezentację modułu została zaktualizowana.static int SetupCallbacksForModule(IOTHUB_MODULE_CLIENT_LL_HANDLE iotHubModuleClientHandle) { int ret; if (IoTHubModuleClient_LL_SetInputMessageCallback(iotHubModuleClientHandle, "input1", InputQueue1Callback, (void*)iotHubModuleClientHandle) != IOTHUB_CLIENT_OK) { printf("ERROR: IoTHubModuleClient_LL_SetInputMessageCallback(\"input1\")..........FAILED!\r\n"); ret = MU_FAILURE; } else if (IoTHubModuleClient_LL_SetModuleTwinCallback(iotHubModuleClientHandle, moduleTwinCallback, (void*)iotHubModuleClientHandle) != IOTHUB_CLIENT_OK) { printf("ERROR: IoTHubModuleClient_LL_SetModuleTwinCallback(default)..........FAILED!\r\n"); ret = MU_FAILURE; } else { ret = 0; } return ret; }Zapisz plik main.c .
Otwórz plik deployment.template.json .
Dodaj bliźniaczą reprezentację modułu CModule do manifestu wdrożenia. Wstaw następującą zawartość do pliku JSON na końcu sekcji
moduleContent, po bliźniaczej reprezentacji modułu$edgeHub:"CModule": { "properties.desired":{ "TemperatureThreshold":25 } }
Zapisz plik deployment.template.json.
Kompilowanie i wypychanie modułu
W poprzedniej sekcji utworzono rozwiązanie IoT Edge i dodano kod do modułu CModule, aby odfiltrować komunikaty, w których zgłoszona temperatura maszyny jest poniżej akceptowalnego progu. Teraz należy skompilować to rozwiązanie jako obraz kontenera i wypchnąć go do rejestru kontenerów.
Logowanie do platformy Docker
Podaj poświadczenia rejestru kontenerów do platformy Docker na komputerze deweloperskim, aby można było wypchnąć obraz kontenera do przechowywania w rejestrze.
Otwórz program PowerShell lub okno wiersza polecenia.
Zaloguj się do platformy Docker przy użyciu poświadczeń rejestru kontenerów platformy Azure zapisanych po utworzeniu rejestru.
docker login -u <ACR username> -p <ACR password> <ACR login server>Może zostać wyświetlone ostrzeżenie o zabezpieczeniach, które zaleca użycie elementu
--password-stdin. Mimo że zalecamy to jako najlepsze rozwiązanie dla scenariuszy produkcyjnych, wykracza poza zakres tego samouczka. Aby uzyskać więcej informacji, zobacz dokumentację logowania platformy Docker.
Kompilowanie i wypychanie
Komputer deweloperów ma teraz dostęp do rejestru kontenerów, a urządzenia IoT Edge również. Nadszedł czas, aby przekształcić kod projektu w obraz kontenera.
W programie Visual Studio Eksplorator rozwiązań kliknij prawym przyciskiem myszy nazwę projektu, który chcesz skompilować. Domyślna nazwa to AzureIotEdgeApp1. Na potrzeby tego samouczka wybraliśmy nazwę CTutorialApp i, ponieważ tworzysz moduł systemu Windows, rozszerzenie powinno mieć wartość Windows.Amd64.
Wybierz pozycję Kompiluj i wypychaj moduły IoT Edge.
Polecenie kompilacji i wypychania uruchamia trzy operacje:
- Najpierw tworzy nowy folder w rozwiązaniu o nazwie config, który zawiera pełny manifest wdrożenia. Jest on tworzony na podstawie informacji w szablonie wdrożenia i innych plikach rozwiązań.
- Po drugie uruchamia
docker buildpolecenie w celu skompilowania obrazu kontenera na podstawie odpowiedniego pliku Dockerfile dla architektury docelowej. - Na koniec zostanie uruchomione polecenie
docker push, aby wypchnąć repozytorium obrazów do rejestru kontenerów.
Ten proces może potrwać kilka minut po raz pierwszy, ale będzie działać szybciej przy następnym uruchomieniu poleceń.
Wdrażanie modułów na urządzeniu
Użyj programu Visual Studio Cloud Explorer i rozszerzenia Azure IoT Edge Tools, aby wdrożyć projekt modułu na urządzeniu IoT Edge. Masz już przygotowany manifest wdrożenia dla danego scenariusza— plik deployment.windows-amd64.json w folderze config . Teraz wystarczy wybrać urządzenie, które ma otrzymać wdrożenie.
Upewnij się, że urządzenie IoT Edge jest uruchomione.
W programie Visual Studio Cloud Explorer rozwiń zasoby, aby wyświetlić listę urządzeń IoT.
Kliknij prawym przyciskiem myszy nazwę urządzenia IoT Edge, które chcesz odebrać wdrożenie.
Wybierz pozycję Twórca Wdrożenie.
W programie Visual Studio Eksplorator plików wybierz plik deployment.windows-amd64.json w folderze konfiguracji rozwiązania.
Odśwież program Cloud Explorer, aby wyświetlić wdrożone moduły, które są wyświetlane na urządzeniu.
Wyświetlanie wygenerowanych danych
Po zastosowaniu manifestu wdrożenia na urządzeniu IoT Edge środowisko uruchomieniowe IoT Edge na urządzeniu zbiera nowe informacje o wdrożeniu i rozpoczyna jego wykonywanie. Wszystkie moduły uruchomione na urządzeniu, ale nieuwzględnione w manifeście wdrożenia, zostaną zatrzymane. Wszystkie moduły, których brakuje na urządzeniu, są uruchamiane.
Możesz użyć rozszerzenia IoT Edge Tools do wyświetlania komunikatów po nadejściu do centrum IoT.
W eksploratorze chmury programu Visual Studio wybierz nazwę urządzenia IoT Edge.
Na liście Akcje wybierz pozycję Rozpocznij monitorowanie wbudowanego punktu końcowego zdarzeń.
Wyświetlanie komunikatów przychodzących do centrum IoT Hub. Odebranie komunikatów może zająć trochę czasu, ponieważ urządzenie IoT Edge musi odebrać nowe wdrożenie i uruchomić wszystkie moduły. Zmiany w kodzie CModule muszą czekać, aż temperatura maszyny osiągnie 25 stopni przed wysłaniem komunikatów. Kod dodaje również typ komunikatu Alert do wszystkich komunikatów, które osiągną ten próg temperatury.
Edytowanie bliźniaczej reprezentacji modułu
Użyto bliźniaczej reprezentacji modułu CModule, aby ustawić próg temperatury na poziomie 25 stopni. Możesz użyć bliźniaczej reprezentacji modułu, aby zmienić funkcjonalność bez konieczności aktualizowania kodu modułu.
W programie Visual Studio otwórz plik deployment.windows-amd64.json .
Nie otwieraj pliku deployment.template. Jeśli manifest wdrożenia nie jest widoczny w pliku konfiguracji w Eksplorator rozwiązań, wybierz ikonę Pokaż wszystkie pliki na pasku narzędzi Eksplorator rozwiązań.
Poszukaj bliźniaczej reprezentacji CModule i zmień wartość parametru temperatureThreshold na nową temperaturę, która jest 5 do 10 stopni wyższa niż najnowsza zgłoszona temperatura.
Zapisz plik deployment.windows-amd64.json .
Ponownie postępuj zgodnie z instrukcjami wdrażania, aby zastosować zaktualizowany manifest wdrożenia do urządzenia.
Monitoruj przychodzące komunikaty z urządzenia do chmury. Komunikaty powinny zostać zatrzymane do momentu osiągnięcia nowego progu temperatury.
Czyszczenie zasobów
Jeśli planujesz przejść do następnego zalecanego artykułu, możesz zachować i ponownie użyć zasobów i konfiguracji utworzonych w tym samouczku. Możesz także nadal używać tego samego urządzenia usługi IoT Edge jako urządzenia testowego.
W przeciwnym razie, aby uniknąć naliczania opłat, możesz usunąć konfiguracje lokalne i zasoby platformy Azure użyte w tym miejscu.
Usuwanie zasobów platformy Azure
Usuwanie zasobów i grup zasobów platformy Azure jest nieodwracalne. Uważaj, aby nie usunąć przypadkowo niewłaściwych zasobów lub niewłaściwej grupy zasobów. Jeśli centrum IoT zostało utworzone w istniejącej grupie zasobów zawierającej zasoby, które chcesz zachować, usuń tylko sam zasób centrum IoT, a nie grupę zasobów.
Aby usunąć zasoby:
Zaloguj się do witryny Azure Portal, a następnie wybierz pozycję Grupy zasobów.
Wybierz nazwę grupy zasobów, która zawiera zasoby testowe usługi IoT Edge.
Przejrzyj listę zasobów, które znajdują się w grupie zasobów. Jeśli chcesz usunąć je wszystkie, możesz wybrać pozycję Usuń grupę zasobów. Jeśli chcesz usunąć tylko niektóre z nich, możesz kliknąć poszczególne zasoby, aby usunąć je pojedynczo.
Następne kroki
W tym samouczku został utworzony moduł usługi IoT Edge zawierający kod służący do filtrowania nieprzetworzonych danych wygenerowanych przez urządzenie usługi IoT Edge.
Aby dowiedzieć się, jak usługa Azure IoT Edge może ułatwić wdrażanie usług w chmurze platformy Azure w celu przetwarzania i analizowania danych na urządzeniach brzegowych, przejdź do następnych samouczków.