Todos los productos
Search

Este producto

    IoT Platform:Porting to an Espressif ESP32 development board

    Centro de documentos

    IoT Platform:Porting to an Espressif ESP32 development board

    Última actualización: Sep 03, 2026

    Este tema describe cómo portar C-SDK 4.0 a una placa de desarrollo ESP32 y utilizar la demostración MQTT para conectarse a Alibaba Cloud IoT Platform.

    Este tutorial abarca los siguientes pasos:

    1. Configure el entorno de desarrollo ESP-IDF en macOS o Linux.

    2. Agregue C-SDK 4.0 como un componente personalizado de ESP-IDF.

    3. Reemplace el archivo de entrada de la demostración y resuelva el conflicto de mbedTLS.

    4. Compile, programe y verifique la conexión MQTT con IoT Platform.

      Requisitos previos

      Antes de empezar, asegúrese de contar con lo siguiente:

      • Una placa de desarrollo ESP32 (este tutorial utiliza una ESP32 Core Board V2/ESP32 DevKitC con un módulo ESP-WROOM-32 integrado, un módulo USB a serial CP2102 y un módulo de alimentación).

      • Un cable USB.

      • Una computadora con Linux o macOS.

      Además, cree un producto y un dispositivo en IoT Platform antes de comenzar:

      1. Inicie sesión en la consola de IoT Platform y cree un producto.

      2. Cree un dispositivo bajo el producto y anote ProductKey, DeviceName y DeviceSecret. Estas credenciales son necesarias al compilar el firmware.

        Nota

        Este tutorial utiliza macOS como entorno de desarrollo. Si usa un sistema operativo diferente, consulte la getting started tutorial oficial de ESP32 para configurar su entorno de desarrollo.

      Configuración del entorno de desarrollo

      Nota

      Esta sección es solo de referencia. Si encuentra problemas, contacte al proveedor de su placa de desarrollo para obtener ayuda. Para acelerar el proceso de configuración, consulte la official getting started tutorial de Espressif.

      1. Instale los paquetes obligatorios.

      2. Clone el repositorio esp-idf.

        Este tutorial utiliza la rama release/v4.2. Otras versiones pueden causar problemas de compatibilidad.

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

      3. Instale la cadena de herramientas y las utilidades de compilación.

        cd esp-idf
./install.sh

      4. Configure las variables de entorno.

        • Ejecute el script de exportación:

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

        • Para evitar ejecutar este script cada vez, agregue la siguiente función a $HOME/.bash_profile:

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

      5. Copie el ejemplo de estación Wi-Fi a un directorio de trabajo.

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

      6. Conecte la placa de desarrollo.

        • Instale el controlador USB. Consulte Establish Serial Connection with ESP32 para más detalles.

        • Identifique el nombre del puerto USB. En este tutorial, el puerto es /dev/cu.SLAB_USBtoUART.

      7. Configure el proyecto.

        Ejecute idf.py menuconfig y utilice la configuración predeterminada.

      8. Compile, programe y monitoree.

        • En el directorio del proyecto station, ejecute idf.py build para compilar.

        • Una vez finalizada la compilación, ejecute idf.py -p PORT flash para programar el firmware. Reemplace PORT con el nombre real de su puerto USB.

        • Después de programar el firmware, ejecute idf.py -p PORT monitor para abrir el monitor de puerto serial.

        • También puede ejecutar idf.py -p PORT flash monitor para programar y monitorear con un solo comando.

        El entorno de desarrollo ESP32 ya está configurado y se ha verificado que el ejemplo wifi station compila y se ejecuta correctamente. Las siguientes secciones explican cómo portar C-SDK 4.0 y conectarse a IoT Platform.

      Portar C-SDK 4.0

      Portar C-SDK 4.0 implica tres tareas: agregar el SDK como componente idf, reemplazar el archivo de adaptación para ESP32 y resolver el conflicto de la biblioteca mbedTLS.

      El directorio portfiles en C-SDK ya contiene el archivo de adaptación para ESP32, por lo que la portabilidad consiste principalmente en importar el código fuente del SDK y configurar el sistema de compilación.

      Conceptos clave

      Consulte la build system introduction de ESP-IDF para obtener contexto. Dos conceptos son fundamentales en este tutorial:

      • project: La carpeta que contiene los archivos fuente y de configuración para compilar la app.

      • components: Unidades de código reutilizables y autónomas que se compilan en bibliotecas estáticas .a y se vinculan a la app. Los componentes personalizados se colocan en el directorio components de idf.

      El sistema de compilación de ESP-IDF utiliza CMake y ninja. Para integrar C-SDK, mueva su código fuente al directorio de componentes y agregue un archivo CMakeLists.txt.

      Métodos de portabilidad

      • Método 1: Importe C-SDK al directorio project. Compile el código fuente del SDK junto con el resto del código fuente de su app.

      • Método 2: Importe C-SDK como un componente idf personalizado en el directorio components de idf.

      Este tutorial utiliza el Método 2. Usar C-SDK como componente independiente facilita su reutilización en varios proyectos y lo mantiene desacoplado del código de su aplicación.

      La siguiente tabla muestra los directorios relevantes de C-SDK:

      Directorio

      Contenido

      core/

      Archivos fuente y encabezados principales del SDK

      core/sysdep/

      Abstracciones de dependencias del sistema (incluye core_adapter.c)

      core/utils/

      Funciones de utilidad

      portfiles/aiot_port/

      Archivos de adaptación específicos de plataforma, incluido posix_port.c adaptado para ESP32

      external/

      Bibliotecas de terceros incluidas con el SDK

      Procedimiento de portabilidad

      1. Agregue C-SDK como componente personalizado.

        Download C-SDK 4.0 y cópielo a $IDF_PATH/components. En el directorio raíz de C-SDK, cree un archivo CMakeLists.txt con el siguiente contenido:

        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)
        Nota

        • C-SDK depende de la biblioteca mbedTLS. REQUIRES mbedtls declara esta dependencia del componente.

        • C-SDK no tiene elementos de configuración Kconfig. No se requiere configuración Kconfig para el componente.

        • Para usar funciones avanzadas del SDK, como el modelo Thing Specification Language (TSL) o actualizaciones Over-the-Air (OTA), agregue las rutas correspondientes de archivos fuente y de encabezado a este CMakeLists.txt.

      2. Reemplace el archivo de adaptación y deshabilite el conflicto de mbedTLS.

        Descargue posix_port.c, que ha sido adaptado para ESP32. Reemplace $IDF_PATH/components/C-SDK/portfiles/aiot_port/posix_port.c con este archivo.

        Tanto LinkSDK como ESP-IDF incluyen la biblioteca mbedTLS. Para evitar conflictos de símbolos durante la vinculación, abra $IDF_PATH/components/C-SDK/core/sysdep/core_adapter.c y deshabilite la macro CORE_ADAPTER_MBEDTLS_ENABLED.

      3. Reemplace el archivo de entrada de la demostración.

        Descargue station_example_main.c y reemplace station/main/station_example_main.c en su ejemplo de estación.

        Nota

        • wifi_init_sta() reintenta la conexión Wi-Fi hasta alcanzar el límite definido por la macro EXAMPLE_ESP_MAXIMUM_RETRY.

        • Una vez establecida la conexión Wi-Fi, la demostración llama a la API de C-SDK para abrir una conexión MQTT. Al conectarse, el dispositivo puede intercambiar datos con IoT Platform.

        • linkkit_main() contiene la lógica original de la demostración MQTT de C-SDK.

      4. Compile y programe.

        • En el directorio del proyecto, ejecute idf.py menuconfig y abra el menú Example Configuration.

        • Establezca WiFi SSID, WiFi Password y Maximum retry, luego guarde y salga.

        • Ejecute idf.py build para compilar.

        • Si la compilación es exitosa, ejecute idf.py -p /dev/cu.SLAB_USBtoUART flash monitor para programar el firmware y abrir el monitor de puerto serial.

        Nota

        Si el dispositivo utiliza intercambio de claves Pre-Shared Key (PSK), habilite la compatibilidad con PSK en mbedTLS y establezca la longitud máxima de PSK en 64:

        • En idf.py menuconfig, vaya a Component config > mbedTLS > TLS Key Exchange Methods.

        • Habilite Enable pre-shared-key ciphersuites.

        • En el CMakeLists.txt del componente mbedTLS, agregue set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DMBEDTLS_PSK_MAX_LEN=64").

      5. Verifique la conexión.

        Una conexión exitosa genera una salida similar a la siguiente:

        ......
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
......

        Busque MQTT connect success y AIOT_MQTTEVT_CONNECT en la salida. Las líneas recurrentes de heartbeat response confirman que la conexión MQTT se mantiene activa.

        Importante

        Si observa el error aiot_mqtt_connect failed: -0x0F0F, se trata de un problema de conectividad de red. Compruebe el estado de su red Wi-Fi y asegúrese de que la placa esté dentro del alcance del punto de acceso. Si es necesario, vuelva a programar el firmware e inténtelo de nuevo.

        El código de error -0x0F0F corresponde a STATE_PORT_NETWORK_CONNECT_TIMEOUT, lo que indica que el intento de conexión agotó el tiempo de espera.

    Solución de problemas

    La conexión MQTT falla con aiot_mqtt_connect failed: -0x0F0F

    El código de error -0x0F0F corresponde a STATE_PORT_NETWORK_CONNECT_TIMEOUT, lo que significa que la placa no pudo comunicarse con el servidor de IoT Platform dentro del período de tiempo de espera. Compruebe lo siguiente:

    • Confirme que la placa esté dentro del alcance de la señal Wi-Fi y conectada al SSID correcto.

    • Verifique los valores de WiFi SSID y WiFi Password que ingresó en idf.py menuconfig.

    • Si el problema persiste, vuelva a programar el firmware e inténtelo de nuevo.

    La compilación falla con símbolos duplicados de mbedTLS

    Tanto LinkSDK como ESP-IDF incluyen mbedTLS. Si observa errores del vinculador sobre símbolos duplicados, asegúrese de haber deshabilitado CORE_ADAPTER_MBEDTLS_ENABLED en core_adapter.c como se describe en el paso 2 del procedimiento de portabilidad.

    El dispositivo se reinicia continuamente después de la programación

    Intente borrar la memoria flash antes de volver a programar:

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

    Puerto serial no reconocido en macOS

    Asegúrese de que el controlador USB CP2102 esté instalado. Consulte Establish Serial Connection with ESP32 para obtener instrucciones sobre la instalación del controlador.