Didacticiel : connecter un kit ESPRESSIF ESP32-Azure IoT à IoT Hub

Article
06/11/2024

Dans ce didacticiel, vous utilisez le middleware Azure pour FreeRTOS afin de connecter le kit ESPRESSIF ESP32-Azure IoT (que nous allons désormais appelé le DevKit ESP32) à Azure IoT.

Effectuez les tâches suivantes :

Installer un ensemble d’outils de développement intégrés pour la programmation d’un DevKit ESP32
Générer une image et la flasher sur le DevKit ESP32
Utiliser Azure CLI pour créer et gérer un Azure IoT Hub auquel le DevKit ESP32 se connectera
Utiliser Azure IoT Explorer pour inscrire un appareil auprès de votre IoT Hub, afficher les propriétés de l’appareil, afficher la télémétrie de l’appareil, et appeler des commandes directes sur l’appareil

Prérequis

un PC exécutant Windows 10 ou Windows 11
Git pour cloner le référentiel
Matériel
- ESPRESSIF ESP32-Azure IoT Kit
- USB 2.0, câble mâle-mâle micro USB
- Wi-Fi 2,4 GHz
Un abonnement Azure actif. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

Préparer l’environnement de développement

Installer les outils

Pour configurer votre environnement de développement, vous devez d’abord installer l’environnement de génération ESPRESSIF ESP-IDF. Le programme d’installation comprend tous les outils nécessaires pour cloner, générer, flasher et monitorer votre appareil.

Pour installer les outils ESP-IDF :

Téléchargez et lancez le programme d’installation hors connexion ESP-IDF v5.0.
Lorsque le programme d’installation répertorie les composants à installer, sélectionnez tous les composants et terminez l’installation.

Cloner le référentiel

Clonez le référentiel suivant pour télécharger tous les exemples de code d’appareil, les scripts d’installation et la documentation du kit de développement logiciel (SDK). Si vous avez précédemment cloné ce référentiel, il n’est pas nécessaire de recommencer.

Pour cloner le référentiel, exécutez la commande suivante :

git clone --recursive  https://github.com/Azure-Samples/iot-middleware-freertos-samples.git

Pour Windows 10 et 11, assurez-vous que les chemins longs sont activés.

Pour activer les chemins longs, consultez Activer les chemins longs dans Windows 10.
Dans Git, exécutez la commande suivante dans un terminal avec des autorisations d’administrateur :
```
git config --system core.longpaths true
```

Créer les composants cloud

Créer un hub IoT

Vous pouvez utiliser Azure CLI pour créer un hub IoT qui gère les événements et la messagerie pour votre appareil.

Pour créer un hub IoT :

Lancez votre application CLI. Pour exécuter les commandes CLI dans le reste de ce guide de démarrage rapide, copiez la syntaxe de la commande, collez-la dans votre application CLI, modifiez les valeurs des variables et appuyez sur Entrée.
- Si vous utilisez Cloud Shell, cliquez avec le bouton droit sur le lien Cloud Shell, puis sélectionnez l’option pour ouvrir sous un nouvel onglet.
- Si vous utilisez Azure CLI localement, démarrez votre application console CLI et connectez-vous à Azure CLI.
Exécutez la commande az extension add pour installer ou mettre à niveau l’extension azure-iot vers la version actuelle.
```
az extension add --upgrade --name azure-iot
```
Exécutez la commande az group create pour créer un groupe de ressources. La commande suivante crée un groupe de ressources nommé MyResourceGroup dans la région centralus.

Notes

Vous pouvez éventuellement définir un autre location. Pour afficher les emplacements disponibles, exécutez la commande az account list-locations.
```
az group create --name MyResourceGroup --location centralus
```
Exécutez la commande az iot hub create pour créer un hub IoT. La création de votre hub IoT peut prendre plusieurs minutes.

YourIotHubName. Remplacez l’espace réservé dans le code par le nom que vous avez choisi pour votre hub IoT. Le nom du hub IoT doit être globalement unique dans Azure. Cet espace réservé est utilisé dans le reste de ce démarrage rapide pour représenter votre nom de hub IoT unique.

Le paramètre --sku F1 crée le hub IoT de niveau gratuit. Les hubs de niveau gratuit disposent d’un ensemble limité de fonctionnalités, et sont utilisés pour des applications de preuve de concept. Pour plus d’informations sur les niveaux les fonctionnalités et la tarification d’IoT Hub, consultez Tarification d’Azure IoT Hub.
```
az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName} --sku F1 --partition-count 2
```
Une fois le hub IoT créé, affichez la sortie JSON dans la console, puis copiez la valeur hostName que vous allez utiliser dans une étape ultérieure. La valeur hostName ressemble à l’exemple suivant :

{Your IoT hub name}.azure-devices.net

Configurer IoT Explorer

Dans le reste de ce guide de démarrage rapide, vous allez utiliser l’explorateur IoT pour inscrire un appareil auprès de votre hub IoT, afficher les propriétés et la télémétrie de l’appareil, et envoyer des commandes à celui-ci. Dans cette section, vous allez configurer IoT Explorer pour qu’il se connecte au hub IoT que vous avez créé et lise les modèles Plug-and-Play à partir du référentiel de modèle public.

Pour ajouter une connexion à votre hub IoT :

Installez l’Explorateur Azure IoT. Cet outil est un utilitaire multiplateforme destiné à superviser et gérer les ressources Azure IoT.
Dans votre application CLI, exécutez la commande az iot hub connection-string show pour obtenir la chaîne de connexion à votre hub IoT.
```
az iot hub connection-string  show --hub-name {YourIoTHubName}
```
Copiez la chaîne de connexion sans les guillemets qui l’entourent.
Dans Azure IoT Explorer, sélectionnez Hubs IoT dans le menu de gauche.
Cliquez sur + Ajouter une connexion.
Collez la chaîne de connexion dans la zone Chaîne de connexion.
Sélectionnez Enregistrer.

Si la connexion aboutit, IoT Explorer bascule vers l’affichage Appareils.

Pour ajouter le référentiel de modèle public :

Dans IoT Explorer, sélectionnez Accueil pour revenir à la vue d’accueil.
Dans le menu de gauche, sélectionnez Paramètres IoT Plug-and-Play.
Vérifiez qu’il existe une entrée de référentiel public existante grâce à un point de terminaison https://devicemodels.azure.com.

Remarque

S’il n’existe pas d’entrée dans le référentiel public, sélectionnez +Ajouter, sélectionnez Référentiel public dans le menu déroulant, spécifiez la https://devicemodels.azure.comvaleur du point de terminaison, puis sélectionnez Enregistrer.

L’entrée complète du référentiel public ressemble à la capture d’écran suivante :

Inscrire un appareil

Dans cette section, vous allez créer une instance d’appareil et l’inscrire auprès du hub IoT que vous avez créé. Vous allez utiliser les informations de connexion de l’appareil que vous venez d’inscrire pour connecter votre appareil physique de manière sécurisée dans une section ultérieure.

Pour inscrire un appareil :

À partir de la vue d’accueil dans IoT Explorer, sélectionnez Hubs IoT.
La connexion que vous avez ajoutée précédemment devrait apparaître. Sous les propriétés de connexion, sélectionnez Afficher les appareils dans ce hub.
Sélectionnez + Nouveau, puis entrez un ID d’appareil pour votre appareil, par exemple, mydevice. Conservez toutes les autres propriétés en l’état.
Sélectionnez Create (Créer).
Utilisez les boutons de copie pour copier les champs ID de l’appareil et Clé primaire.

Avant de passer à la section suivante, enregistrez dans un emplacement sécurisé chacune des valeurs suivantes récupérées lors des étapes précédentes. Vous utiliserez ces valeurs dans la section suivante pour configurer votre appareil.

hostName
deviceId
primaryKey

Préparer l’appareil

Pour connecter le DevKit ESP32 à Azure, vous allez modifier les paramètres de configuration, générer l’image et flasher l’image sur l’appareil.

Configurer l’environnement

Pour lancer l’environnement ESP-IDF :

Sélectionnez Démarrer Windows, recherchez ESP-IDF 5.0 CMD et exécutez-le.
Dans ESP-IDF 5.0 CMD, accédez au répertoire iot-middleware-freertos-samples que vous avez cloné précédemment.
Accédez au répertoire de projets demos\projects\ESPRESSIF\aziotkit d’ESP32-Azure IoT Kit.
Exécutez la commande suivante pour lancer le menu de configuration :
```
idf.py menuconfig
```

Ajouter une configuration

Pour ajouter une configuration réseau sans fil :

Dans ESP-IDF 5.0 CMD, sélectionnez Azure IoT middleware for FreeRTOS Sample Configuration --->, puis appuyez sur Entrée.
Définissez les paramètres de configuration suivants avec les informations d’identification du réseau sans fil local.

Paramètre Valeur

WiFi SSID {Votre SSID Wi-Fi}

WiFi Password {Votre mot de passe Wi-Fi}
Appuyez sur Échap pour revenir au menu précédent.

Paramètre	Valeur
WiFi SSID	{Votre SSID Wi-Fi}
WiFi Password	{Votre mot de passe Wi-Fi}

Pour ajouter une configuration pour se connecter à Azure IoT Hub :

Sélectionnez Azure IoT middleware for FreeRTOS Main Task Configuration --->, puis appuyez sur Entrée.
Définissez les paramètres de configuration Azure IoT suivants avec les valeurs que vous avez enregistrées après la création des ressources Azure.

Paramètre Valeur

Azure IoT Hub FQDN {Votre nom d’hôte}

ID de l’appareil Azure IoT {ID de votre appareil}

Azure IoT Device Symmetric Key {Votre clé primaire}

Notes

Dans le paramètre Méthode d’authentification Azure IoT, vérifiez que la valeur par défaut de la Clé symétrique est sélectionnée.
Appuyez sur Échap pour revenir au menu précédent.

Paramètre	Valeur
Azure IoT Hub FQDN	{Votre nom d’hôte}
ID de l’appareil Azure IoT	{ID de votre appareil}
Azure IoT Device Symmetric Key	{Votre clé primaire}

Pour enregistrer la configuration :

Sélectionnez Maj+S pour ouvrir les options d’enregistrement. Ce menu vous permet d’enregistrer la configuration dans un fichier nommé skconfig dans le répertoire .\aziotkit actuel.
Cliquez sur Entrée pour enregistrer la configuration.
Sélectionnez Entrée pour ignorer le message d’accusé de réception.
SélectionnezQ pour quitter le menu de configuration.

Générer et flasher l’image

Dans cette section, vous allez utiliser les outils ESP-IDF pour générer le DevKit ESP32, le flasher et le monitorer quand il se connecte à Azure IoT.

Notes

Dans les commandes suivantes de cette section, utilisez un chemin de sortie de build court à proximité de votre répertoire racine. Spécifiez le chemin de build après le paramètre -B dans chaque commande qui l’exige. Un chemin de build court permet d’éviter les erreurs générées par les outils ESPRESSIF ESP-IDF lors de l’utilisation de chemins longs. Les commandes suivantes utilisent un chemin local C:\espbuild comme exemple.

Pour générer l’image :

Dans ESP-IDF 5.0 CMD, dans le répertoire iot-middleware-freertos-samples\demos\projects\ESPRESSIF\aziotkit, exécutez la commande suivante pour générer l’image.
```
idf.py --no-ccache -B "C:\espbuild" build 
```
Une fois la génération terminée, vérifiez que le fichier image binaire a été créé dans le chemin de build spécifié précédemment.

C:\espbuild\azure_iot_freertos_esp32.bin

Pour flasher l’image :

Sur le DevKit ESP32, recherchez le port Micro USB qui est mis en évidence dans l’image suivante :
Branchez le câble Micro USB au port Micro USB du DevKit ESP32, puis branchez-le à votre ordinateur.
Ouvrez le Gestionnaire de périphériques Windows. Sous Ports, déterminez le port COM auquel le DevKit ESP32 est connecté.
Dans ESP-IDF 5.0 CMD, exécutez la commande suivante, en remplaçant l’espace réservé <Your-COM-port> et les crochets par le port COM identifié à l’étape précédente. Par exemple, remplacez l’espace réservé par COM3.
```
idf.py --no-ccache -B "C:\espbuild" -p <Your-COM-port> flash
```
Vérifiez que la sortie génère le texte suivant qui confirme un flashage réussi :
```
Hash of data verified

Leaving...
Hard resetting via RTS pin...
Done
```

Pour confirmer que l’appareil se connecte à Azure IoT Central :

Dans ESP-IDF 5.0 CMD, exécutez la commande suivante pour démarrer l’outil de monitoring. Comme vous l’avez fait dans une commande précédente, remplacez l’espace réservé <Your-COM-port> et les crochets par le port COM auquel l’appareil est connecté.
```
idf.py -B "C:\espbuild" -p <Your-COM-port> monitor
```

Recherchez les blocs de sortie répétés similaires à ceux de l’exemple suivant. Cette sortie confirme que l’appareil se connecte à Azure IoT et envoie des données de télémétrie.

I (50807) AZ IOT: Successfully sent telemetry message
I (50807) AZ IOT: Attempt to receive publish message from IoT Hub.

I (51057) MQTT: Packet received. ReceivedBytes=2.
I (51057) MQTT: Ack packet deserialized with result: MQTTSuccess.
I (51057) MQTT: State record updated. New state=MQTTPublishDone.
I (51067) AZ IOT: Puback received for packet id: 0x00000008
I (53067) AZ IOT: Keeping Connection Idle...

Voir les propriétés de l’appareil

Vous pouvez utiliser Azure IoT Explorer pour afficher et gérer les propriétés de vos appareils. Dans les sections suivantes, vous utiliserez les fonctionnalités Plug and Play visibles dans IoT Explorer pour gérer et interagir avec le DevKit ESP32. Ces fonctionnalités s’appuient sur le modèle d’appareil publié pour le DevKit ESP32 dans le référentiel de modèle public. Plus tôt dans ce didacticiel, vous avez configuré IoT Explorer pour rechercher des modèles d’appareil dans ce référentiel. Dans de nombreux cas, vous pouvez effectuer la même action sans utiliser le les fonctionnalités Plug and Play en sélectionnant les options du menu d'IoT Explorer. Toutefois, l’utilisation de la technologie Plug-and-Play offre souvent une expérience améliorée. IoT Explorer peut lire le modèle d’appareil spécifié par un appareil Plug-and-Play et présenter des informations spécifiques de celui-ci.

Pour accéder aux composants IoT Plug-and-Play pour l’appareil dans IoT Explorer :

À partir de la vue d’accueil dans IoT Explorer, sélectionnez Hubs IoT, puis Afficher les appareils dans ce hub.
Sélectionnez votre appareil.
Sélectionnez Composants IoT Plug-and-Play.
Sélectionnez le composant par défaut. IoT Explorer affiche les composants IoT Plug-and-Play implémentés sur votre appareil.

Sous l’onglet interface, affichez le contenu JSON dans la Description du modèle d’appareil. Le JSON contient les détails de configuration de chaque composant IoT Plug-and-Play dans le modèle d’appareil.

Chaque onglet dans IoT Explorer correspond à l’un des composants IoT Plug-and-Play dans le modèle d’appareil.

Onglet	Type	Nom	Description
Interface	Interface	`Espressif ESP32 Azure IoT Kit`	Exemple de modèle d’appareil pour le DevKit ESP32
Propriétés (accessibles en écriture)	Propriété	`telemetryFrequencySecs`	Intervalle pendant lequel l’appareil envoie de la télémétrie
Commandes	Commande	`ToggleLed1`	Activer ou désactiver la LED
Commandes	Commande	`ToggleLed2`	Activer ou désactiver la LED
Commandes	Commande	`DisplayText`	Affiche le texte envoyé sur l’écran de l’appareil

Pour afficher et modifier les propriétés d’un appareil à l’aide d’Azure IoT Explorer :

Sélectionnez l’onglet Propriétés (accessibles en écriture) . Celui-ci affiche l’intervalle d’envoi de la télémétrie.
Remplacez la valeur de telemetryFrequencySecs par 5, puis sélectionnez Mettre à jour la valeur souhaitée. Votre appareil utilise désormais cet intervalle pour envoyer la télémétrie.
IoT Explorer répond avec une notification.

Pour utiliser Azure CLI pour afficher les propriétés de l’appareil :

Exécutez la commande az iot hub device-twin show.

az iot hub device-twin show --device-id mydevice --hub-name {YourIoTHubName}

Examinez les propriétés de votre appareil dans la sortie de la console.

Conseil

Vous pouvez également utiliser Azure IoT Explorer pour afficher les propriétés de l’appareil. Dans le volet de navigation gauche, sélectionnez Jumeau d’appareil.

Afficher les données de télémétrie

Avec IoT Central, vous pouvez afficher le flux de télémétrie de votre appareil vers le cloud. Si vous le souhaitez, vous pouvez effectuer la même tâche à l’aide d’Azure CLI.

Pour afficher la télémétrie dans Azure IoT Explorer :

Dans le volet Composants IoT Plug-and-Play (composant par défaut) de votre appareil dans IoT Explorer, sélectionnez l’onglet Télémétrie. Vérifiez que l’option Utiliser l’Event Hub intégré est définie sur Oui.
Sélectionnez Démarrer.
Affichez la télémétrie à mesure que l’appareil envoie des messages au cloud.
Activez la case à cocher Afficher les événements modélisés pour voir les événements dans le format de données spécifié par le modèle d’appareil.
Sélectionnez Arrêter pour cesser de recevoir des événements.

Pour utiliser Azure CLI pour afficher la télémétrie d’un appareil :

Exécutez la commande az iot hub monitor-events. Utilisez les noms que vous avez créés précédemment dans Azure IoT pour votre appareil et le hub IoT.
```
az iot hub monitor-events --device-id mydevice --hub-name {YourIoTHubName}
```

Affichez la sortie JSON dans la console

{
    "event": {
        "origin": "mydevice",
        "module": "",
        "interface": "dtmi:azureiot:devkit:freertos:Esp32AzureIotKit;1",
        "component": "",
        "payload": "{\"temperature\":28.6,\"humidity\":25.1,\"light\":116.66,\"pressure\":-33.69,\"altitude\":8764.9,\"magnetometerX\":1627,\"magnetometerY\":28373,\"magnetometerZ\":4232,\"pitch\":6,\"roll\":0,\"accelerometerX\":-1,\"accelerometerY\":0,\"accelerometerZ\":9}"
    }
}

Sélectionnez CTRL+C pour cesser la surveillance.

Appeler une méthode directe sur l’appareil

Vous pouvez également utiliser Azure IoT Explorer pour appeler une méthode directe que vous avez mise en œuvre sur votre appareil. Les méthodes directes portent un nom et peuvent éventuellement avoir une charge utile JSON, une connexion configurable et un délai d’expiration de méthode. Dans cette section, vous appelez une méthode qui allume ou éteint une LED. Si vous le souhaitez, vous pouvez effectuer la même tâche à l’aide d’Azure CLI.

Pour appeler une méthode dans Azure IoT Explorer :

Dans le volet Composants IoT Plug-and-Play (composant par défaut) de votre appareil dans IoT Explorer, sélectionnez l’onglet Commandes.
Pour la commande ToggleLed1, sélectionnez Envoyer la commande. La LED du DevKit ESP32 s’active ou se désactive. Vous devriez également voir une notification dans IoT Explorer.
Pour la commande DisplayText , entrez du texte dans le champ de contenu.
Sélectionnez Envoyer la commande. Le texte s’affiche sur l’écran DevKit ESP32.

Pour utiliser Azure CLI pour appeler une méthode :

Exécutez la commande az iot hub invoke-device-method et spécifiez le nom et la charge utile de la méthode. Pour cette méthode, la définition de method-payload sur true signifie que la LED bascule à l’opposé de son état actuel.
```
az iot hub invoke-device-method --device-id mydevice --method-name ToggleLed2 --method-payload true --hub-name {YourIoTHubName}
```
La console CLI affiche l’état de votre appel de méthode sur l’appareil, où 200 indique la réussite.
```
{
  "payload": {},
  "status": 200
} 
```
Examiner votre appareil pour vérifier l’état de la LED.

Résoudre les problèmes et déboguer

Si vous rencontrez des problèmes pour générer le code d’appareil, flasher l’appareil ou le connecter, consultez Résolution des problèmes.

Pour déboguer l’application, consultez Débogage avec Visual Studio Code.

Nettoyer les ressources

Si vous n’avez plus besoin des ressources Azure créées dans ce démarrage rapide, vous pouvez utiliser Azure CLI pour supprimer le groupe de ressources.

Important

La suppression d’un groupe de ressources est irréversible. Le groupe de ressources et toutes les ressources qu’il contient sont supprimés définitivement. Veillez à ne pas supprimer accidentellement des ressources ou un groupe de ressources incorrects.

Pour supprimer un groupe de ressources par nom :

Exécutez la commande az group delete. Cette commande supprime le groupe de ressources, le hub IoT et l’inscription de l’appareil que vous avez créés.
```
az group delete --name MyResourceGroup
```
Exécutez la commande az group list pour confirmer la suppression du groupe de ressources.
```
az group list
```

Étapes suivantes

Dans ce didacticiel, vous avez généré une image personnalisée qui contient un exemple de code pour le middleware Azure IoT pour FreeRTOS, puis vous avez flashé l’image sur l’appareil DevKit ESP32. Vous avez connecté le DevKit ESP32 à Azure IoT Hub et effectué des tâches comme voir les données de télémétrie et appeler des méthodes sur l’appareil.

La prochaine étape est d’explorer l’article qui suit pour en savoir plus sur les options de développement incorporées.

En savoir plus sur la connexion d’appareils incorporés à l’aide du SDK C et du SDK C incorporé

Partager via