Tous les produits
Search

Ce produit

    IoT Platform:Porting to an Espressif ESP32 development board

    Centre de documentation

    IoT Platform:Porting to an Espressif ESP32 development board

    Dernière mise à jour :Aug 10, 2026

    Cette rubrique explique comment porter le C-SDK 4.0 sur une carte de développement ESP32 et utiliser la démonstration MQTT pour se connecter à Alibaba Cloud IoT Platform.

    Ce tutoriel couvre les étapes suivantes :

    1. Configurez l'environnement de développement ESP-IDF sous macOS ou Linux.

    2. Ajoutez le C-SDK 4.0 en tant que composant ESP-IDF personnalisé.

    3. Remplacez le fichier d'entrée de la démonstration et résolvez le conflit mbedTLS.

    4. Compilez, flashez et vérifiez la connexion MQTT à IoT Platform.

      Prérequis

      Avant de commencer, assurez-vous de disposer des éléments suivants :

      • Une carte de développement ESP32 (ce tutoriel utilise une ESP32 Core Board V2/ESP32 DevKitC avec un module ESP-WROOM-32 intégré, un module USB-série CP2102 et un module d'alimentation).

      • Un câble USB.

      • Un ordinateur fonctionnant sous Linux ou macOS.

      Créez également un produit et un dispositif dans IoT Platform avant de démarrer :

      1. Connectez-vous à la console IoT Platform et créez un produit.

      2. Créez un dispositif sous le produit et notez les valeurs ProductKey, DeviceName et DeviceSecret. Vous aurez besoin de ces identifiants lors de la compilation du micrologiciel.

        Remarque

        Ce tutoriel utilise macOS comme environnement de développement. Si vous utilisez un autre système d'exploitation, consultez le tutoriel de démarrage officiel ESP32 pour configurer votre environnement de développement.

      Configuration de l'environnement de développement

      Remarque

      Cette section est fournie à titre de référence uniquement. En cas de problème, contactez le fournisseur de votre carte de développement pour obtenir de l'aide. Pour accélérer le processus de configuration, consultez le tutoriel de démarrage officiel d'Espressif.

      1. Installez les packages requis.

      2. Clonez le dépôt esp-idf.

        Ce tutoriel utilise la branche release/v4.2. D'autres versions peuvent entraîner des problèmes de compatibilité.

        cd ~
mkdir esp && cd esp
git clone --recursive -b release/v4.2 https://github.com/espressif/esp-idf.git

      3. Installez la chaîne d'outils et les outils de compilation.

        cd esp-idf
./install.sh

      4. Configurez les variables d'environnement.

        • Exécutez le script d'exportation :

          . $HOME/esp/esp-idf/export.sh

        • Pour éviter d'exécuter ce script à chaque fois, ajoutez la fonction suivante au fichier $HOME/.bash_profile :

          set_esp32 ()
{
    export IDF_PATH=$HOME/esp/esp-idf
    . $HOME/esp/esp-idf/export.sh
}

      5. Copiez l'exemple de station Wi-Fi dans un répertoire de travail.

        cd ~/esp
cp -r $IDF_PATH/examples/wifi/getting_started/station .

      6. Connectez la carte de développement.

        • Installez le pilote USB. Consultez la page Establish Serial Connection with ESP32 pour plus de détails.

        • Identifiez le nom du port USB. Dans ce tutoriel, le port est /dev/cu.SLAB_USBtoUART.

      7. Configurez le projet.

        Exécutez idf.py menuconfig et utilisez la configuration par défaut.

      8. Compilez, flashez et surveillez l'exécution.

        • Dans le répertoire du projet station, exécutez idf.py build pour compiler.

        • Une fois la compilation terminée, exécutez idf.py -p PORT flash pour flasher le micrologiciel. Remplacez PORT par le nom réel de votre port USB.

        • Après le flashage du micrologiciel, exécutez idf.py -p PORT monitor pour ouvrir le moniteur de port série.

        • Vous pouvez également exécuter idf.py -p PORT flash monitor pour flasher et lancer la surveillance en une seule commande.

        L'environnement de développement ESP32 est désormais configuré et vous avez vérifié que l'exemple wifi station se compile et s'exécute correctement. Les sections suivantes expliquent comment porter le C-SDK 4.0 et se connecter à IoT Platform.

      Portage du C-SDK 4.0

      Le portage du C-SDK 4.0 implique trois tâches : ajouter le SDK en tant que composant idf, remplacer le fichier de port adapté à l'ESP32 et résoudre le conflit de bibliothèque mbedTLS.

      Le répertoire portfiles du C-SDK contient déjà le fichier de port pour l'ESP32 ; le portage consiste donc principalement à importer le code source du SDK et à configurer le système de build.

      Concepts clés

      Consultez l'introduction au système de build ESP-IDF pour acquérir les bases nécessaires. Deux concepts sont essentiels pour ce tutoriel :

      • project : dossier contenant les fichiers source et de configuration pour la construction de l'app.

      • components : unités de code réutilisables et autonomes, compilées en bibliothèques statiques .a et liées à l'app. Les composants personnalisés sont placés dans le répertoire components de l'idf.

      Le système de build ESP-IDF utilise CMake et ninja. Pour intégrer le C-SDK, déplacez son code source dans le répertoire des composants et ajoutez un fichier CMakeLists.txt.

      Méthodes de portage

      • Méthode 1 : Importez le C-SDK dans le répertoire project. Compilez le code source du SDK conjointement avec les autres sources de votre app.

      • Méthode 2 : Importez le C-SDK en tant que composant idf personnalisé dans le répertoire components de l'idf.

      Ce tutoriel utilise la méthode 2. L'utilisation du C-SDK en tant que composant indépendant facilite sa réutilisation dans plusieurs projets et maintient un découplage avec le code de votre application.

      Le tableau suivant présente les répertoires pertinents du C-SDK :

      Répertoire

      Contenu

      core/

      Fichiers source et en-têtes principaux du SDK

      core/sysdep/

      Abstractions des dépendances système (inclut core_adapter.c)

      core/utils/

      Fonctions utilitaires

      portfiles/aiot_port/

      Fichiers de port spécifiques à la plateforme, y compris le fichier posix_port.c adapté à l'ESP32

      external/

      Bibliothèques tierces incluses avec le SDK

      Procédure de portage

      1. Ajoutez le C-SDK en tant que composant personnalisé.

        Téléchargez le C-SDK 4.0 et copiez-le dans $IDF_PATH/components. Dans le répertoire racine du C-SDK, créez un fichier CMakeLists.txt avec le contenu suivant :

        set(include_dirs core core/sysdep core/utils)
file(GLOB c_sdk_srcs
    "core/*.c"
    "core/utils/*.c"
    "core/sysdep/*.c"
    "portfiles/aiot_port/*.c"
    "external/*.c")
idf_component_register(SRCS ${c_sdk_srcs}
                       INCLUDE_DIRS "${include_dirs}"
                       REQUIRES mbedtls)
        Remarque

        • Le C-SDK dépend de la bibliothèque mbedTLS. La directive REQUIRES mbedtls déclare cette dépendance de composant.

        • Le C-SDK ne possède aucun élément de configuration Kconfig. Aucune configuration Kconfig de composant n'est nécessaire.

        • Pour utiliser des fonctionnalités avancées du SDK telles que le modèle TSL (Thing Specification Language) ou les mises à jour OTA (Over-the-Air), ajoutez les chemins des fichiers source et d'en-tête correspondants à ce fichier CMakeLists.txt.

      2. Remplacez le fichier de port et désactivez le conflit mbedTLS.

        Téléchargez le fichier posix_port.c, qui a été adapté pour l'ESP32. Remplacez le fichier $IDF_PATH/components/C-SDK/portfiles/aiot_port/posix_port.c par ce fichier.

        LinkSDK et ESP-IDF incluent tous deux la bibliothèque mbedTLS. Pour éviter les conflits de symboles lors de l'édition des liens, ouvrez le fichier $IDF_PATH/components/C-SDK/core/sysdep/core_adapter.c et désactivez la macro CORE_ADAPTER_MBEDTLS_ENABLED.

      3. Remplacez le fichier d'entrée de la démonstration.

        Téléchargez le fichier station_example_main.c et remplacez le fichier station/main/station_example_main.c dans votre exemple de station.

        Remarque

        • La fonction wifi_init_sta() tente de se reconnecter au Wi-Fi jusqu'à atteindre la limite définie par la macro EXAMPLE_ESP_MAXIMUM_RETRY.

        • Une fois la connexion Wi-Fi établie, la démonstration appelle l'API du C-SDK pour ouvrir une connexion MQTT. Une fois connecté, le dispositif peut échanger des données avec IoT Platform.

        • La fonction linkkit_main() contient la logique originale de la démonstration MQTT du C-SDK.

      4. Compilez et flashez.

        • Dans le répertoire du projet, exécutez idf.py menuconfig et ouvrez le menu Example Configuration.

        • Définissez les valeurs WiFi SSID, WiFi Password et Maximum retry, puis enregistrez et quittez.

        • Exécutez idf.py build pour compiler.

        • Une fois la compilation réussie, exécutez idf.py -p /dev/cu.SLAB_USBtoUART flash monitor pour flasher le micrologiciel et ouvrir le moniteur de port série.

        Remarque

        Si le dispositif utilise l'échange de clés Pre-Shared Key (PSK), activez la prise en charge PSK dans mbedTLS et définissez la longueur maximale PSK sur 64 :

        • Dans idf.py menuconfig, accédez à Component config > mbedTLS > TLS Key Exchange Methods.

        • Activez l'option Enable pre-shared-key ciphersuites.

        • Dans le fichier CMakeLists.txt du composant mbedTLS, ajoutez la ligne set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DMBEDTLS_PSK_MAX_LEN=64").

      5. Vérifiez la connexion.

        Une connexion réussie génère une sortie similaire à la suivante :

        ......
I (829) phy: phy_version: 4180, cb3948e, Sep 12 2019, 16:39:13, 0, 0
I (829) wifi: mode : sta (30:ae:a4:04:81:84)
I (829) wifi station: wifi_init_sta finished.
I (949) wifi: new:<11,0>, old:<1,0>, ap:<255,255>, sta:<11,0>, prof:1
I (949) wifi: state: init -> auth (b0)
I (969) wifi: state: auth -> assoc (0)
I (969) wifi: state: assoc -> run (10)
I (1129) wifi: connected with C_SDK_Test, aid = 1, channel 11, BW20, bssid = ec:26:ca:4b:68:cc
I (1129) wifi: security type: 3, phy: bgn, rssi: -37
I (1139) wifi: pm start, type: 1
I (1219) wifi: AP's beacon interval = 102400 us, DTIM period = 1
I (2129) esp_netif_handlers: sta ip: 192.168.0.100, mask: 255.255.255.0, gw: 192.168.0.1
I (2129) wifi station: got ip:192.168.0.100
I (2129) wifi station: connected to ap SSID:C_SDK_Test password:1234abcd
I (2139) wifi station: Start linkkit mqtt
[1.583][LK-0313] MQTT user calls aiot_mqtt_connect api, connect
[1.587][LK-0317] mqtt_basic_demo&a13FNXXXXXX
[1.590][LK-0318] 4780A5F17990D8DC4CCAD392683ED80160C4C2A1FFA649425CD0E2666A8593EB
[1.598][LK-0319] a13FN5TplKq.mqtt_basic_demo|timestamp=2524608000000,_ss=1,_v=sdk-c-4.0.0,securemode=2,signmethod=hmacsha256,ext=1,|
establish mbedtls connection with server(host='a13FN5TplKq.iot-as-mqtt.cn-shanghai.aliyuncs.com', port=[443])
success to establish mbedtls connection, fd = 54(cost 29739 bytes in total, max used 44007 bytes)
[3.493][LK-0313] MQTT connect success in 1910 ms
AIOT_MQTTEVT_CONNECT
[3.494][LK-0309] sub: /sys/a13FN5TplKq/mqtt_basic_demo/thing/event/+/post_reply
[3.499][LK-0309] pub: /sys/a13FN5TplKq/mqtt_basic_demo/thing/event/property/post
[LK-030A] > 7B 22 69 64 22 3A 22 31  22 2C 22 76 65 72 73 69 | {"id":"1","versi
[LK-030A] > 6F 6E 22 3A 22 31 2E 30  22 2C 22 70 61 72 61 6D | on":"1.0","param
[LK-030A] > 73 22 3A 7B 22 4C 69 67  68 74 53 77 69 74 63 68 | s":{"LightSwitch
[LK-030A] > 22 3A 30 7D 7D                                   | ":0}}
suback, res: -0x0000, packet id: 1, max qos: 1
[3.573][LK-0309] pub: /sys/a13FN5TplKq/mqtt_basic_demo/thing/event/property/post_reply
[LK-030A] < 7B 22 63 6F 64 65 22 3A  32 30 30 2C 22 64 61 74 | {"code":200,"dat
[LK-030A] < 61 22 3A 7B 7D 2C 22 69  64 22 3A 22 31 22 2C 22 | a":{},"id":"1","
[LK-030A] < 6D 65 73 73 61 67 65 22  3A 22 73 75 63 63 65 73 | message":"succes
[LK-030A] < 73 22 2C 22 6D 65 74 68  6F 64 22 3A 22 74 68 69 | s","method":"thi
[LK-030A] < 6E 67 2E 65 76 65 6E 74  2E 70 72 6F 70 65 72 74 | ng.event.propert
[LK-030A] < 79 2E 70 6F 73 74 22 2C  22 76 65 72 73 69 6F 6E | y.post","version
[LK-030A] < 22 3A 22 31 2E 30 22 7D                          | ":"1.0"}
pub, qos: 0, topic: /sys/a13FNXXXXXX/mqtt_basic_demo/thing/event/property/post_reply
pub, payload: {"code":200,"data":{},"id":"1","message":"success","method":"thing.event.property.post","version":"1.0"}
heartbeat response
heartbeat response
heartbeat response
......

        Recherchez les messages MQTT connect success et AIOT_MQTTEVT_CONNECT dans la sortie. La présence récurrente de lignes heartbeat response confirme que la connexion MQTT est maintenue.

        Important

        Si vous rencontrez l'erreur aiot_mqtt_connect failed: -0x0F0F, il s'agit d'un problème de connectivité réseau. Vérifiez l'état de votre réseau Wi-Fi et assurez-vous que la carte se trouve à portée du point d'accès. Si nécessaire, reflashez le micrologiciel et réessayez.

        Le code d'erreur -0x0F0F correspond à STATE_PORT_NETWORK_CONNECT_TIMEOUT, indiquant que la tentative de connexion a expiré.

    Dépannage

    Échec de la connexion MQTT avec l'erreur aiot_mqtt_connect failed: -0x0F0F

    Le code d'erreur -0x0F0F correspond à STATE_PORT_NETWORK_CONNECT_TIMEOUT, ce qui signifie que la carte n'a pas pu atteindre le serveur IoT Platform dans le délai imparti. Vérifiez les points suivants :

    • Confirmez que la carte se trouve dans la zone de couverture du signal Wi-Fi et qu'elle est connectée au bon SSID.

    • Vérifiez les valeurs WiFi SSID et WiFi Password saisies dans idf.py menuconfig.

    • Si le problème persiste, reflashez le micrologiciel et réessayez.

    Échec de la compilation avec des symboles mbedTLS en double

    LinkSDK et ESP-IDF incluent tous deux mbedTLS. Si vous observez des erreurs de l'éditeur de liens concernant des symboles dupliqués, assurez-vous d'avoir désactivé CORE_ADAPTER_MBEDTLS_ENABLED dans le fichier core_adapter.c comme décrit à l'étape 2 de la procédure de portage.

    Redémarrages continus du dispositif après le flashage

    Essayez d'effacer la mémoire flash avant de reflasher :

    idf.py -p PORT erase_flash
idf.py -p PORT flash monitor

    Port série non reconnu sous macOS

    Assurez-vous que le pilote USB CP2102 est installé. Consultez la page Establish Serial Connection with ESP32 pour obtenir les instructions d'installation du pilote.