Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Démos de CoreMQTT **Important** Cette démo est hébergée sur le référentiel Amazon-FreeRTOS qui est obsolète. Nous vous recommandons de [commencer ici](freertos-getting-started-modular.md) lorsque vous créez un nouveau projet. Si vous possédez déjà un projet FreeRTOS basé sur le référentiel Amazon-FreeRTOS, désormais obsolète, consultez le. [Guide de migration du référentiel Github d'Amazon-FreeRTOS](github-repo-migration.md) Ces démos peuvent vous aider à apprendre à utiliser la bibliothèque CoreMQTT. **Topics** + [Démo de l'authentification mutuelle CoreMQTT](mqtt-demo-ma.md) + [Démonstration du partage de connexion avec l'agent CoreMQTT](mqtt-demo-cs.md) # Démo de l'authentification mutuelle CoreMQTT **Important** Cette démo est hébergée sur le référentiel Amazon-FreeRTOS qui est obsolète. Nous vous recommandons de [commencer ici](freertos-getting-started-modular.md) lorsque vous créez un nouveau projet. Si vous possédez déjà un projet FreeRTOS basé sur le référentiel Amazon-FreeRTOS, désormais obsolète, consultez le. [Guide de migration du référentiel Github d'Amazon-FreeRTOS](github-repo-migration.md) ## Introduction Le projet de démonstration d'authentification mutuelle CoreMQTT vous montre comment établir une connexion avec un courtier MQTT à l'aide du protocole TLS avec authentification mutuelle entre le client et le serveur. [Cette démonstration utilise une implémentation d'interface de transport basée sur MBEDTLS pour établir une connexion TLS authentifiée par le serveur et le client, et illustre le flux de travail d'abonnement/publication de MQTT au niveau QoS 1.](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Toc442180914) Il s'abonne à un filtre de rubrique, puis publie dans les rubriques correspondant au filtre et attend la réception de ces messages du serveur au niveau QoS 1. Ce cycle de publication auprès du courtier et de réception du même message de la part du courtier se répète indéfiniment. Les messages de cette démo sont envoyés à QoS 1, ce qui garantit au moins une livraison conformément à la spécification MQTT. **Note** Pour configurer et exécuter les démos de FreeRTOS, suivez les étapes décrites dans. [Commencez avec FreeRTOS](freertos-getting-started.md) ## Code source Le fichier source de démonstration est nommé `mqtt_demo_mutual_auth.c` et se trouve dans le `freertos/demos/coreMQTT/` répertoire et [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c)sur le site Web. ## Fonctionnalité La démo crée une tâche d'application unique qui passe en revue un ensemble d'exemples illustrant comment se connecter au courtier, s'abonner à une rubrique sur le courtier, publier dans une rubrique sur le courtier, puis enfin, se déconnecter du courtier. L'application de démonstration s'abonne et publie sur le même sujet. Chaque fois que la démo publie un message au broker MQTT, celui-ci renvoie le même message à l'application de démonstration. Une démonstration réussie générera un résultat similaire à l'image suivante. ![\[Sortie du terminal de démonstration MQTT en cas de réussite\]](http://docs.aws.amazon.com/fr_fr/freertos/latest/userguide/images/coremqtt-mad-output.png) La AWS IoT console générera une sortie similaire à l'image suivante. ![\[Sortie de la console de démonstration MQTT en cas de réussite\]](http://docs.aws.amazon.com/fr_fr/freertos/latest/userguide/images/coremqtt-mad-console.png) ## Réessayez la logique avec un recul et une instabilité exponentiels La fonction [ prvBackoffForRetry](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L671-L717) montre comment les opérations réseau ayant échoué avec le serveur, par exemple les connexions TLS ou les demandes d'abonnement MQTT, peuvent être réessayées avec un retard et une instabilité exponentiels. La fonction calcule la période d'attente pour la prochaine tentative et effectue le délai d'annulation si les tentatives n'ont pas été épuisées. Comme le calcul de la période d'attente nécessite la génération d'un nombre aléatoire, la fonction utilise le PKCS11 module pour générer le nombre aléatoire. L'utilisation du PKCS11 module permet d'accéder à un véritable générateur de nombres aléatoires (TRNG) si la plateforme du fournisseur le prend en charge. Nous vous recommandons d'amorcer le générateur de nombres aléatoires avec une source d'entropie spécifique à l'appareil afin de réduire la probabilité de collisions avec des appareils lors de nouvelles tentatives de connexion. ## Connexion au courtier MQTT La [ prvConnectToServerWithBackoffRetries](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L721-L782)fonction tente d'établir une connexion TLS mutuellement authentifiée avec le broker MQTT. Si la connexion échoue, elle réessaie après une période d'attente. La période d'attente augmentera de façon exponentielle jusqu'à ce que le nombre maximum de tentatives soit atteint ou que la période d'interruption maximale soit atteinte. La `BackoffAlgorithm_GetNextBackoff` fonction fournit une valeur de retard qui augmente de façon exponentielle et revient `RetryUtilsRetriesExhausted` lorsque le nombre maximum de tentatives a été atteint. La `prvConnectToServerWithBackoffRetries` fonction renvoie un état d'échec si la connexion TLS au broker ne peut pas être établie après le nombre de tentatives configuré. La MQTTConnection WithBroker fonction [PrvCreate](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L785-L848) montre comment établir une connexion MQTT avec un broker MQTT avec une session propre. Il utilise l'interface de transport TLS, qui est implémentée dans le `FreeRTOS-Plus/Source/Application-Protocols/platform/freertos/transport/src/tls_freertos.c` fichier. N'oubliez pas que nous définissons les secondes pendant lesquelles le courtier doit rester actif. `xConnectInfo` La fonction suivante montre comment l'interface de transport TLS et la fonction de temps sont définies dans un contexte MQTT à l'aide de la `MQTT_Init` fonction. Il montre également comment une fonction de rappel d'événement pointer (`prvEventCallback`) est définie. Ce rappel est utilisé pour signaler les messages entrants. ## Abonnement à un sujet MQTT La MQTTSubscribe WithBackoffRetries fonction [prv](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L871-L969) montre comment s'abonner à un filtre de sujet sur le broker MQTT. L'exemple montre comment s'abonner à un filtre de sujet, mais il est possible de transmettre une liste de filtres de sujets dans le même appel d'API d'abonnement pour s'abonner à plusieurs filtres de sujets. De plus, si le courtier MQTT rejette la demande d'abonnement, l'abonnement réessaiera, avec un retard exponentiel, pour. `RETRY_MAX_ATTEMPTS` ## Publication dans une rubrique La MQTTPublish ToTopic fonction [prv](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L972-L1004) montre comment publier sur un sujet sur le broker MQTT. ## Réception de messages entrants L'application enregistre une fonction de rappel d'événement avant de se connecter au broker, comme décrit précédemment. La `prvMQTTDemoTask` fonction appelle la `MQTT_ProcessLoop` fonction pour recevoir les messages entrants. Lorsqu'un message MQTT entrant est reçu, il appelle la fonction de rappel d'événements enregistrée par l'application. La [ prvEventCallback](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L1139-L1154)fonction est un exemple d'une telle fonction de rappel d'événements. `prvEventCallback`examine le type de paquet entrant et appelle le gestionnaire approprié. Dans l'exemple ci-dessous, la fonction appelle soit à gérer `prvMQTTProcessIncomingPublish()` les messages de publication entrants, soit `prvMQTTProcessResponse()` à gérer les accusés de réception (ACK). ## Traitement des paquets de publication MQTT entrants La MQTTProcess IncomingPublish fonction [prv](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L1108-L1135) montre comment traiter un paquet de publication à partir du broker MQTT. ## Se désabonner d'un sujet La dernière étape du flux de travail consiste à se désabonner du sujet afin que le courtier n'envoie aucun message publié depuis`mqttexampleTOPIC`. Voici la définition de la fonction [prv MQTTUnsubscribe FromTopic](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT/mqtt_demo_mutual_auth.c#L1007-L1043). ## Modification de l'autorité de certification racine utilisée dans la démo Par défaut, les démos FreeRTOS utilisent le certificat Amazon Root CA 1 (clé RSA 2048 bits) pour s'authentifier auprès du serveur. AWS IoT Core Il est possible d'utiliser d'autres [certificats CA pour l'authentification du serveur](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs), notamment le certificat Amazon Root CA 3 (clé ECC 256 bits). Pour modifier l'autorité de certification racine pour la démonstration d'authentification mutuelle CoreMQTT : 1. Dans un éditeur de texte, ouvrez le fichier `freertos/vendors/vendor/boards/board/aws_demos/config_files/mqtt_demo_mutual_auth_config.h`. 1. Dans le fichier, repérez la ligne suivante. ``` * #define democonfigROOT_CA_PEM "...insert here..." ``` Décommentez cette ligne et, si nécessaire, déplacez-la au-delà de la fin ` */` du bloc de commentaires. 1. Copiez le certificat CA que vous souhaitez utiliser, puis collez-le dans le `"...insert here..."` texte. Le résultat doit ressembler à l'exemple suivant : ``` #define democonfigROOT_CA_PEM "-----BEGIN CERTIFICATE-----\n"\ "MIIBtjCCAVugAwIBAgITBmyf1XSXNmY/Owua2eiedgPySjAKBggqhkjOPQQDAjA5\n"\ "MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6b24g\n"\ "Um9vdCBDQSAzMB4XDTE1MDUyNjAwMDAwMFoXDTQwMDUyNjAwMDAwMFowOTELMAkG\n"\ "A1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEZMBcGA1UEAxMQQW1hem9uIFJvb3Qg\n"\ "Q0EgMzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABCmXp8ZBf8ANm+gBG1bG8lKl\n"\ "ui2yEujSLtf6ycXYqm0fc4E7O5hrOXwzpcVOho6AF2hiRVd9RFgdszflZwjrZt6j\n"\ "QjBAMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdDgQWBBSr\n"\ "ttvXBp43rDCGB5Fwx5zEGbF4wDAKBggqhkjOPQQDAgNJADBGAiEA4IWSoxe3jfkr\n"\ "BqWTrBqYaGFy+uGh0PsceGCmQ5nFuMQCIQCcAu/xlJyzlvnrxir4tiz+OpAUFteM\n"\ "YyRIHN8wfdVoOw==\n"\ "-----END CERTIFICATE-----\n" ``` 1. (Facultatif) Vous pouvez modifier l'autorité de certification racine pour les autres démos. Répétez les étapes 1 à 3 pour chaque `freertos/vendors/vendor/boards/board/aws_demos/config_files/demo-name_config.h` fichier. # Démonstration du partage de connexion avec l'agent CoreMQTT **Important** Cette démo est hébergée sur le référentiel Amazon-FreeRTOS qui est obsolète. Nous vous recommandons de [commencer ici](freertos-getting-started-modular.md) lorsque vous créez un nouveau projet. Si vous possédez déjà un projet FreeRTOS basé sur le référentiel Amazon-FreeRTOS, désormais obsolète, consultez le. [Guide de migration du référentiel Github d'Amazon-FreeRTOS](github-repo-migration.md) ## Introduction Le projet de démonstration du partage de connexion CoreMQTT vous montre comment utiliser une application multithread pour établir une connexion au broker AWS MQTT à l'aide du protocole TLS avec authentification mutuelle entre le client et le serveur. [Cette démonstration utilise une implémentation d'interface de transport basée sur MBEDTLS pour établir une connexion TLS authentifiée par le serveur et le client, et illustre le flux de travail d'abonnement/publication de MQTT au niveau QoS 1.](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Toc442180914) La démo s'abonne à un filtre de rubrique, publie les rubriques correspondant au filtre, puis attend de recevoir ces messages du serveur au niveau QoS 1. Ce cycle de publication auprès du courtier et de réception du même message de la part du courtier est répété plusieurs fois pour chaque tâche créée. Les messages de cette démo sont envoyés à QoS 1, ce qui garantit au moins une livraison conformément à la spécification MQTT. **Note** Pour configurer et exécuter les démos de FreeRTOS, suivez les étapes décrites dans. [Commencez avec FreeRTOS](freertos-getting-started.md) Cette démonstration utilise une file d'attente sécurisée par thread pour contenir les commandes permettant d'interagir avec l'API MQTT. Il y a deux tâches à prendre en compte dans cette démonstration. + Une tâche (principale) de l'agent MQTT traite les commandes de la file de commandes tandis que les autres tâches les mettent en file d'attente. Cette tâche entre dans une boucle au cours de laquelle elle traite les commandes de la file de commandes. Si une commande de fin est reçue, cette tâche sera interrompue. + Une tâche de sous-publication de démonstration crée un abonnement à un sujet MQTT, puis crée des opérations de publication et les place dans la file de commandes. Ces opérations de publication sont ensuite exécutées par la tâche de l'agent MQTT. La tâche de sous-publication de démonstration attend la fin de la publication, ce qui est indiqué par l'exécution du rappel de fin de commande, puis entre dans un court délai avant de commencer la publication suivante. Cette tâche montre des exemples de la manière dont les tâches d'application utiliseraient l'API de l'agent CoreMQTT. Pour les messages de publication entrants, l'agent CoreMQTT invoque une seule fonction de rappel. Cette démo inclut également un gestionnaire d'abonnements qui permet aux tâches de spécifier un rappel à invoquer pour les messages de publication entrants sur les sujets auxquels elles sont abonnées. Dans le cadre de cette démonstration, le rappel de publication entrant de l'agent appelle le gestionnaire d'abonnements pour répartir les publications sur toute tâche ayant enregistré un abonnement. Cette démonstration utilise une connexion TLS avec authentification mutuelle pour se connecter AWS. Si le réseau se déconnecte de façon inattendue pendant la démonstration, le client tente de se reconnecter en utilisant une logique d'interruption exponentielle. Si le client se reconnecte avec succès, mais que le courtier ne peut pas reprendre la session précédente, le client se réabonnera aux mêmes sujets que lors de la session précédente. ### Monothread ou multithread Il existe deux modèles d'utilisation de CoreMQTT, monothread et multithread (multitâche). Le modèle à thread unique utilise la bibliothèque CoreMQTT uniquement à partir d'un thread et vous oblige à effectuer des appels explicites répétés dans la bibliothèque MQTT. Les cas d'utilisation multithread peuvent à la place exécuter le protocole MQTT en arrière-plan dans une tâche d'agent (ou de démon), comme le montre la démonstration documentée ici. Lorsque vous exécutez le protocole MQTT dans une tâche d'agent, vous n'avez pas besoin de gérer explicitement un état MQTT ni d'appeler la fonction `MQTT_ProcessLoop` API. En outre, lorsque vous utilisez une tâche d'agent, plusieurs tâches d'application peuvent partager une seule connexion MQTT sans avoir besoin de primitives de synchronisation telles que des mutex. ## Code source Les fichiers source de démonstration sont nommés `mqtt_agent_task.c` `simple_sub_pub_demo.c` et se trouvent dans le `freertos/demos/coreMQTT_Agent/` répertoire et sur le [GitHub](https://github.com/aws/amazon-freertos/tree/main/demos/coreMQTT_Agent/)site Web. ## Fonctionnalité Cette démonstration crée au moins deux tâches : une tâche principale qui traite les demandes d'appels d'API MQTT, et un nombre configurable de sous-tâches qui créent ces demandes. Dans cette démonstration, la tâche principale crée les sous-tâches, appelle la boucle de traitement et effectue ensuite le nettoyage. La tâche principale crée une connexion MQTT unique avec le broker, qui est partagée entre les sous-tâches. Les sous-tâches créent un abonnement MQTT auprès du courtier, puis y publient des messages. Chaque sous-tâche utilise un sujet unique pour ses publications. ## Tâche principale La tâche principale de l'application, [ RunCoreMQTTAgentDemo](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT_Agent/mqtt_agent_task.c#L435-L480), établit une session MQTT, crée les sous-tâches et exécute la boucle de traitement [ MQTTAgent\$1 CommandLoop](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT_Agent/mqtt_agent_task.c#L856) jusqu'à ce qu'une commande de fin soit reçue. Si le réseau se déconnecte de façon inattendue, la démo se reconnecte au courtier en arrière-plan et rétablit les abonnements auprès du courtier. Une fois la boucle de traitement terminée, elle se déconnecte du broker. ### Commandes Lorsque vous appelez une API d'agent CoreMQTT, elle crée une commande qui est envoyée à la file d'attente de la tâche de l'agent, qui est traitée dans. `MQTTAgent_CommandLoop()` Au moment de la création de la commande, le rappel de fin facultatif et les paramètres de contexte peuvent être transmis. Une fois la commande correspondante terminée, le rappel d'achèvement sera invoqué avec le contexte transmis et toutes les valeurs de retour créées à la suite de la commande. La signature du rappel de fin est la suivante : ``` typedef void (* MQTTAgentCommandCallback_t )( void * pCmdCallbackContext, MQTTAgentReturnInfo_t * pReturnInfo ); ``` Le contexte d'exécution des commandes est défini par l'utilisateur ; pour cette démo, il s'agit de : [ MQTTAgentCommandContextstruct](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT_Agent/simple_sub_pub_demo.c#L105-L115). Les commandes sont considérées comme terminées lorsque : + S'abonne, se désabonne et publie avec QoS > 0 : une fois que le paquet d'accusé de réception correspondant a été reçu. + Toutes les autres opérations : une fois que l'API CoreMQTT correspondante a été invoquée. Toutes les structures utilisées par la commande, y compris les informations de publication, les informations d'abonnement et les contextes d'achèvement, doivent rester dans le champ d'application jusqu'à ce que la commande soit terminée. Une tâche appelante ne doit réutiliser aucune des structures d'une commande avant l'invocation du rappel de fin. Notez que puisque le rappel d'achèvement est invoqué par l'agent MQTT, il s'exécutera avec le contexte de thread de la tâche de l'agent, et non avec la tâche qui a créé la commande. Les mécanismes de communication entre processus, tels que les notifications de tâches ou les files d'attente, peuvent être utilisés pour signaler à la tâche appelante que la commande est terminée. ### Exécution de la boucle de commande Les commandes sont traitées en continu dans`MQTTAgent_CommandLoop()`. S'il n'y a aucune commande à traiter, la boucle attendra au maximum qu'une commande soit ajoutée à la file d'attente et, si aucune commande n'est ajoutée, elle exécutera une seule itération de`MQTT_ProcessLoop()`. `MQTT_AGENT_MAX_EVENT_QUEUE_WAIT_TIME` Cela garantit à la fois que MQTT Keep-Alive est géré et que toutes les publications entrantes sont reçues même s'il n'y a aucune commande dans la file d'attente. La fonction de boucle de commande sera renvoyée pour les raisons suivantes : + Une commande renvoie tout autre code d'état`MQTTSuccess`. L'état de l'erreur est renvoyé par la boucle de commande, vous pouvez donc décider comment le gérer. Dans cette démonstration, la connexion TCP est rétablie et une tentative de reconnexion est effectuée. En cas d'erreur, une reconnexion peut se produire en arrière-plan sans aucune intervention de la part d'autres tâches utilisant MQTT. + Une commande de déconnexion (de`MQTTAgent_Disconnect`) est traitée. La boucle de commande se termine afin que le protocole TCP puisse être déconnecté. + Une commande de fin (depuis`MQTTAgent_Terminate`) est traitée. Cette commande marque également comme une erreur toute commande encore dans la file d'attente ou en attente d'un paquet d'accusé de réception, avec un code de retour de. `MQTTRecvFailed` ### Gestionnaire d'abonnements Comme la démo utilise plusieurs sujets, un gestionnaire d'abonnements est un moyen pratique d'associer les sujets souscrits à des rappels ou à des tâches uniques. Le gestionnaire d'abonnement de cette démo est mono-thread, il ne doit donc pas être utilisé par plusieurs tâches simultanément. Dans cette démo, les fonctions du gestionnaire d'abonnements sont uniquement appelées à partir des fonctions de rappel transmises à l'agent MQTT et exécutées uniquement avec le contexte du thread de la tâche de l'agent. ## Tâche simple d'abonnement/de publication Chaque instance de [ prvSimpleSubscribePublishTask](https://github.com/aws/amazon-freertos/blob/main/demos/coreMQTT_Agent/simple_sub_pub_demo.c#L447-L569)crée un abonnement à un sujet MQTT et crée des opérations de publication pour ce sujet. Pour illustrer plusieurs types de publication, les tâches à numéro pair utilisent QoS 0 (qui sont terminées une fois le paquet de publication envoyé) et les tâches impaires utilisent QoS 1 (qui sont terminées à la réception d'un paquet PUBACK).