Tutoriel : utiliser Eclipse ThreadX pour connecter un devkit MXCHIP AZ3166 à IoT Hub

Article
11/11/2024

Dans ce tutoriel, vous utilisez Eclipse ThreadX pour connecter un DevKit MXCHIP AZ3166 IoT (à partir de maintenant, MXCHIP DevKit) à Azure IoT.

Effectuez les tâches suivantes :

Installer un ensemble d’outils de développement intégrés pour la programmation du DevKit MXChip en C
Créer une image et la flasher sur le DevKit MXCHIP
Utiliser Azure CLI pour créer et gérer un hub Azure IoT auquel le DevKit MXCHIP se connecte de manière sécurisée
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
Un abonnement Azure actif. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.
Git pour cloner le référentiel
Azure CLI. Vous avez le choix entre deux options pour exécuter les commandes Azure CLI dans cet tutoriel :
- Utilisez Azure Cloud Shell, un interpréteur de commandes interactif qui exécute des commandes CLI dans votre navigateur. Cette option est recommandée, car vous n’avez pas besoin d’installer quoi que ce soit. Si vous utilisez Cloud Shell pour la première fois, connectez-vous au portail Azure. Suivez les étapes décrites dans Démarrage rapide de Cloud Shell pour démarrer Cloud Shell et sélectionner l’environnement Bash.
- Si vous le souhaitez, exécutez Azure CLI sur votre ordinateur local. Si l’interface de ligne de commande Azure est déjà installée, exécutez az upgrade pour la mettre à niveau, ainsi que les extensions, vers la version actuelle. Pour installer l’interface de ligne de commande Azure, consultez Installer l’interface de ligne de commande Azure.
Matériel
- DevKit IoT MXCHIP AZ3166 (DevKit MXCHIP)
- Wi-Fi 2,4 GHz
- USB 2.0, câble mâle-mâle micro USB

Préparer l’environnement de développement

Avant de configurer votre environnement de développement, vous devez cloner un référentiel GitHub qui contient toutes les ressources dont vous avez besoin pour le didacticiel. Ensuite, vous installez un ensemble d’outils de programmation.

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 les versions hors connexion de la documentation. Si vous avez précédemment cloné ce référentiel dans un autre didacticiel, 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/eclipse-threadx/getting-started.git

Installer les outils

Le référentiel cloné contient un script d’installation qui installe et configure les outils requis. Si vous avez installé ces outils dans le cadre d’un autre tutoriel d’appareil intégré, il n’est pas nécessaire de recommencer.

Remarque

Le script d’installation installe les outils suivants :

CMake : générer
ARM GCC : compiler
Termite : surveiller la sortie du port série pour les ressources d’appareils connectés

Pour installer les outils :

Accédez au chemin d’accès suivant dans le référentiel et exécutez le script d’installation nommé get-toolchain.bat :

getting-started\tools\get-toolchain.bat
Ouvrez une nouvelle fenêtre de console pour identifier les modifications de configuration apportées par le script d’installation. Utilisez cette console pour effectuer les tâches de programmation restantes dans le didacticiel. Vous pouvez utiliser Windows CMD, PowerShell ou Git Bash pour Windows.
Exécutez le code suivant pour vérifier que CMake version 3.14 ou ultérieure est installé.
```
cmake --version
```

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.
Confirmez l’existence d’une entrée Référentiel public avec un point de terminaison de https://devicemodels.azure.com.

Remarque

Si le référentiel public ne contient pas d’entrée, sélectionnez +Ajouter, sélectionnez Référentiel public dans le menu déroulant, spécifiez la valeur de point de terminaison https://devicemodels.azure.com, puis sélectionnez Enregistrer.

La capture d’écran suivante montre l’entrée terminée pour le référentiel public :

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 MXCHIP à Azure, vous allez modifier un fichier de configuration pour les paramètres Wi-Fi et Azure IoT, regénérer l’image et flasher celle-ci sur l’appareil.

Ajouter une configuration

Ouvrez le fichier suivant dans un éditeur de texte :

getting-started\MXChip\AZ3166\app\azure_config.h
Commentez la ligne suivante en haut du fichier, comme illustré :
```
// #define ENABLE_DPS
```
Affectez aux constantes Wi-Fi les valeurs suivantes à partir de votre environnement local.

Nom de la constante Valeur

WIFI_SSID {Votre SSID Wi-Fi}

WIFI_PASSWORD {Votre mot de passe Wi-Fi}

WIFI_MODE {Une des valeurs de mode de Wi-Fi énumérées dans le fichier}
Définissez les constantes d’informations de l’appareil Azure IoT sur les valeurs que vous avez enregistrées après avoir créé les ressources Azure.

Nom de la constante Valeur

IOT_HUB_HOSTNAME {Valeur de votre nom d’hôte}

IOT_HUB_DEVICE_ID {Valeur d’ID de votre appareil}

IOT_DEVICE_SAS_KEY {Valeur de votre clé primaire}
Enregistrez et fermez le fichier.

Nom de la constante	Valeur
`WIFI_SSID`	{Votre SSID Wi-Fi}
`WIFI_PASSWORD`	{Votre mot de passe Wi-Fi}
`WIFI_MODE`	{Une des valeurs de mode de Wi-Fi énumérées dans le fichier}

Nom de la constante	Valeur
`IOT_HUB_HOSTNAME`	{Valeur de votre nom d’hôte}
`IOT_HUB_DEVICE_ID`	{Valeur d’ID de votre appareil}
`IOT_DEVICE_SAS_KEY`	{Valeur de votre clé primaire}

Créer l’image

Dans votre console ou dans l’Explorateur de fichiers, exécutez le script rebuild.bat à l’emplacement suivant pour générer l’image :

getting-started\MXChip\AZ3166\tools\rebuild.bat
Une fois la génération terminée, vérifiez que le fichier binaire a été créé dans le chemin d’accès suivant :

getting-started\MXChip\AZ3166\build\app\mxchip_azure_iot.bin

Flasher l’image

Dans le DevKit MXCHIP, recherchez le bouton Réinitialiser et le port micro USB. Vous pouvez utiliser ces composants dans les étapes suivantes. Les deux sont mis en surbrillance dans l’image suivante :
Branchez le câble micro USB au port micro USB du DevKit MXCHIP, puis branchez-le à votre ordinateur.
Dans l’Explorateur de fichiers, recherchez le fichier binaire que vous avez créé dans la section précédente.
Copiez le fichier binaire mxchip_azure_iot. bin.
Dans l’Explorateur de fichiers, recherchez l’appareil DevKit MXCHIP connecté à votre ordinateur. L’appareil apparaît en tant que lecteur sur votre système avec l’intitulé de lecteur AZ3166.
Collez le fichier binaire dans le dossier racine du DevKit MXCHIP. Le processus de flash démarre automatiquement et se termine en quelques secondes.

Notes

Au cours de ce processus, un voyant vert s’allume pour le DevKit MXCHIP.

Vérifier les détails de connexion de l’appareil

Vous pouvez utiliser l’application Termite pour surveiller la communication et vérifier que votre appareil est correctement configuré.

Démarrez Termite.

Conseil

Si vous ne parvenez pas à connecter Termite à votre devkit, installez le pilote ST-LINK, puis réessayez. Vous pouvez consulter des étapes supplémentaires dans Résolution des problèmes.
Sélectionnez Paramètres.
Dans la boîte de dialogue Paramètres du port série, vérifiez les paramètres suivants et mettez à jour si nécessaire :
- Vitesse (en bauds) : 115 200
- Port : port auquel votre DevKit MXCHIP est connecté. Si plusieurs options de port sont disponibles dans la liste déroulante, vous pouvez trouver le port approprié à utiliser. Ouvrez le Gestionnaire d'appareils Windows et affichez les Ports pour identifier le port à utiliser.
Sélectionnez OK.
Appuyez sur le bouton Réinitialiser de l’appareil. Le bouton est étiqueté sur l’appareil et situé près du connecteur micro USB.

Dans l’application Termite, vérifiez les valeurs de point de contrôle suivantes pour confirmer que l’appareil est initialisé et connecté à Azure IoT.

 Starting Azure thread


 Initializing WiFi
     MAC address: ******************
 SUCCESS: WiFi initialized

 Connecting WiFi
     Connecting to SSID 'iot'
     Attempt 1...
 SUCCESS: WiFi connected

 Initializing DHCP
     IP address: 192.168.0.49
     Mask: 255.255.255.0
     Gateway: 192.168.0.1
 SUCCESS: DHCP initialized

 Initializing DNS client
     DNS address: 192.168.0.1
 SUCCESS: DNS client initialized

 Initializing SNTP time sync
     SNTP server 0.pool.ntp.org
     SNTP time update: Jan 4, 2023 22:57:32.658 UTC
 SUCCESS: SNTP initialized

 Initializing Azure IoT Hub client
     Hub hostname: ***.azure-devices.net
     Device id: mydevice
     Model id: dtmi:eclipsethreadx:devkit:gsgmxchip;2
 SUCCESS: Connected to IoT Hub

 Receive properties: {"desired":{"$version":1},"reported":{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128},"ledState":false,"telemetryInterval":{"ac":200,"av":1,"value":10},"$version":4}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=3{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=5{"ledState":false}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=7{"telemetryInterval":{"ac":200,"av":1,"value":10}}

 Starting Main loop
 Telemetry message sent: {"humidity":31.01,"temperature":25.62,"pressure":927.3}.
 Telemetry message sent: {"magnetometerX":177,"magnetometerY":-36,"magnetometerZ":-346.5}.
 Telemetry message sent: {"accelerometerX":-22.5,"accelerometerY":0.54,"accelerometerZ":1049.01}.
 Telemetry message sent: {"gyroscopeX":0,"gyroscopeY":0,"gyroscopeZ":0}.

Laissez Termite ouvert pour surveiller la sortie de l’appareil dans les étapes suivantes.

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 cette section et les suivantes, vous allez utiliser les fonctionnalités Plug-and-Play proposées dans IoT Explorer pour gérer le DevKit MXCHIP et interagir avec celui-ci. Ces fonctionnalités s’appuient sur le modèle d’appareil publié pour le DevKit MXCHIP 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. Vous pouvez effectuer de nombreuses actions sans utiliser la technologie Plug-and-Play en sélectionnant l’action dans le menu de gauche du volet de votre appareil dans 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	`MXCHIP Getting Started Guide`	Exemple de modèle pour le DevKit MXCHIP
Propriétés (lecture seule)	Propriété	`ledState`	État actuel de la LED
Propriétés (accessibles en écriture)	Propriété	`telemetryInterval`	Intervalle pendant lequel l’appareil envoie de la télémétrie
Commandes	Commande	`setLedState`	Activer ou désactiver la LED

Pour afficher 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 telemetryInterval 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. Vous pouvez également observer la mise à jour dans Termite.
Réaffectez la valeur 10 à l’intervalle de télémétrie.

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.

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.

Notes

Vous pouvez également surveiller la télémétrie à partir de l’appareil à l’aide de l’application Termite.
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:eclipsethreadx:devkit:gsgmxchip;1",
         "component": "",
         "payload": "{\"humidity\":41.21,\"temperature\":31.37,\"pressure\":1005.18}"
     }
 }

Sélectionnez CTRL+C pour cesser la surveillance.

Appeler une méthode directe sur l’appareil

Vous pouvez également utiliser l’Explorateur Azure IoT pour appeler une méthode directe que vous avez implémentée 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 setLedState, définissez state sur true.
Sélectionnez Envoyer la commande. Une notification devrait s’afficher dans IoT Explorer et le témoin LED USER de couleur jaune devrait s’allumer sur l’appareil.
Définissez l’état sur false, puis sélectionnez Envoyer la commande. Le témoin LED USER de couleur jaune devrait s’éteindre.
Si vous le souhaitez, vous pouvez afficher la sortie dans Termite pour surveiller l’état des méthodes.

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 a pour effet d’allumer la LED, et sa définition sur false de l’éteindre.
```
az iot hub invoke-device-method --device-id mydevice --method-name setLedState --method-payload true --hub-name {YourIoTHubName}
```
La console CLI affiche l’état de votre appel de méthode sur l’appareil, où 204 indique la réussite.
```
{
  "payload": {},
  "status": 200
}
```
Examiner votre appareil pour vérifier l’état de la LED.

Affichez le terminal Termite pour vérifier les messages de sortie :

 Receive direct method: setLedState
     Payload: true
 LED is turned ON
 Device twin property sent: {"ledState":true}

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 créé une image personnalisée qui contient un exemple de code Azure RTOS, puis vous avez flashé l’image sur l’appareil DevKit MXCHIP. Vous avez également utilisé Azure CLI et/ou IoT Explorer pour créer des ressources Azure, connecter le DevKit MXCHIP en toute sécurité à Azure, afficher la télémétrie et envoyer des messages.

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é

Eclipse ThreadX fournit aux fabricants OEM les composants permettant de sécuriser la communication et de créer du code et l’isolation des données à l’aide des mécanismes sous-jacents de protection matérielle MCU/MPU. Toutefois, chaque fabricant OEM est tenu de garantir que son appareil répond aux exigences de sécurité en constante évolution.

Partager via