All Products
Search

This Product

    IoT Platform:Port the SDK to ESP8266

    Document Center

    IoT Platform:Port the SDK to ESP8266

    Last Updated:Jun 20, 2026

    This guide explains how to port the SDK for C 4.0 to an ESP8266 development board and use a demo application to connect to Alibaba Cloud IoT Platform.

    Preparations

    To port the SDK, you must prepare the following items:

    • A development board. The development board used in this topic is ESP-LAUNCHER, which is the official ESP8266EX_Demo_Board.
    • A USB cable.
    • A computer that runs Windows, Linux, or macOS. This guide uses macOS as the host development platform.
    Note For more information about how to set up a development environment on other operating systems, see Get started in ESP8266_RTOS_SDK.

    Set up a development environment

    Note The following instructions for setting up the development environment and verifying that the ESP8266 works as expected are for reference only. If you encounter any issues, contact your development board supplier.

    To speed up the environment setup, read the ESP8266 RTOS SDK Readme. The following steps describe how to set up the environment on macOS:

    1. Install required software

      Run the sudo easy_install pip command to install the pip system.

      Run the sudo pip install pyserial command to install the pySerial module.

    2. Clone the official ESP-IDF repository
      cd ~
mkdir esp && cd esp
git clone https://github.com/espressif/ESP8266_RTOS_SDK.git -b release/v3.3
      Run these commands to clone the official ESP-IDF repository:

      After the download is complete, you need to run the command export IDF_PATH=~/esp/ESP8266_RTOS_SDK to configure the IDF SDK path.

      Note
      • release/v3.3fd785ab0c50009ab93503ae785814136f6d1009bThis demonstration uses the branch. The corresponding commit ID is .
      • For versions earlier than v3.0 that do not use the ESP-IDF framework, you can adjust the process accordingly to complete the integration.
    3. Install the toolchain and compilation tool

      Manually download the macOS toolchain, and extract the toolchain to the ~/esp directory:

      mkdir -p ~/esp
cd ~/esp
tar -xzf ~/Downloads/xtensa-lx106-elf-macos-1.22.0-100-ge567ec7-5.2.0.tar.gz

      You can obtain the toolchains of other operating systems on the ESP8266_RTOS_SDK page on GitHub.

      Configure the system path for the toolchain.

      export PATH=$PATH:$HOME/esp/xtensa-lx106-elf/bin

      Run the following script to add configurations of all environment variables to the $HOME/.bash_profile file:

      set_esp8266 ()
{
    exprot IDF_PATH=$HOME/esp/ESP8266_RTOS_SDK
    export PATH=$PATH: $HOME/esp/xtensa-lx106-elf/bin
}

    4. Connect the development board

      To find the serial port name on macOS, run the ls /dev/cu.* command. The serial port name in this demonstration is /dev/cu.usbserial-AH06UHLH.

    5. Configure, compile, flash, and monitor

      1. cd examples/wifi/simple_wifi/examples/wifi/simple_wifi/All configurations must be performed in the project's path. First, navigate to the directory by running .
      2. In ESP-IDF, run make menuconfig to configure the project. For more information, see the following porting methods.
      3. After the configuration is complete, run the make all command to compile the firmware.
      4. After the compilation is complete, run the make flash command to flash the firmware. Ensure that the development board is in download mode.
      5. After the project is flashed, run the make monitor command to monitor the serial port. Ensure that the development board is in work mode.

      You have now set up the ESP8266 development environment and successfully compiled and flashed the Wi-Fi station example.

      Note Before you proceed, ensure that the development board is working correctly.

    6. Port the C SDK 4.0

      The porting process involves importing the SDK source code, configuring the SDK porting layer files, and setting up the build system.

      The SDK's portfiles directory already contains the portfile for the ESP8266, so you only need to import the SDK source code and configure the build system to complete the porting.

      To better understand the porting process, we recommend that you read the ESP-IDF Build System documentation. You should first familiarize yourself with some basic ESP-IDF concepts:

      • Project: A directory that contains all the source files and configuration files required to build your app.
      • components: Modular pieces of standalone code, compiled into static libraries and linked to the app. These modular components are stored in the ESP-IDF directory. You can also add your own custom components.

      Because the ESP8266-sdk build system uses GNU make by default, you can add the SDK for C to the build by adding its code and creating a corresponding .mk build configuration file.

    Porting approaches

    The following two porting methods are available:

    • Method 1: Add the SDK for C to the project directory and compile the SDK source code together with your app source code.
    • Method 2: Introduce the SDK for C into the components directory of IDF as a custom IDF component.

    We recommend that you use the second method. Using the SDK for C as a separate component helps you reuse it in different projects and decouple the SDK code from your app code. Perform the following steps:

    1. Add the C SDK as a custom component

      • Get the C Link SDK.
        Note device OSFreeRTOSAdvanced featuresWhen you customize the SDK, you can select for the and leave other parameters at their defaults. Select as needed. For more information, see Get C Link SDK.
      • Download the attached posix_port.c file, which is adapted for the ESP8266. Use this file to replace portfiles/aiot_port/posix_port.c in the C Link SDK.
      • Both the C Link SDK and ESP-IDF contain an mbedtls library. To avoid library conflicts, modify the $IDF_PATH/components/C-SDK/core/sysdep/core_adapter.c file and disable the CORE_ADAPTER_MBEDTLS_ENABLED macro.
      • Copy the SDK to the $IDF_PATH/components directory. Then, create a build file named component.mk in the SDK directory with the following content:
        COMPONENT_ADD_INCLUDEDIRS := core core/sysdep core/utils components/ota
COMPONENT_SRCDIRS := core core/utils core/sysdep components/ota portfiles/aiot_port/ external

    2. Port the demo application

      You can modify the example in examples/wifi/simple_wifi/ to demonstrate the Message Queuing Telemetry Transport (MQTT)-based cloud migration.

      The native demo demonstrates how to access a specific Wi-Fi hotspot in wifi station mode, which allows you to download the source file of the attachment to overwrite the simple_wifi.c file.

    3. Configure, compile, and flash

      Run the make menuconfig command in the examples/wifi/simple_wifi/ project directory to configure the project.

      1. On the SDK tool configuration menu, ensure that Compiler toolchain path/prefix is set to xtensa-lx106-elf-.
      2. On the Serial flasher config menu, change the default serial port name of the ESP8266 development board.
      3. On the Example Configuration menu, select the Station mode, and configure the WiFi SSID, WiFi Password, and the Maximum retry parameters.
      4. Choose Component config > ESP8266-specific. On the page that appears, set Main task stack size to 4096, save the modification, and then exit.

      mbedTLS configuration

      To use a pre-shared key (PSK) for the TLS key exchange method, follow these steps:

      1. Choose Component config > mbedTLS. On the page that appears, click TLS Key Exchange Methods.
      2. Turn on the Enable pre-shared-key ciphersuites switch.
      3. Add CFLAGS += -DMBEDTLS_PSK_MAX_LEN=64 to the component.mk file of the mbedtls component.

      The following information specifies the configurations:

      COMPONENT_ADD_INCLUDEDIRS := port/include mbedtls/include port/esp8266/include
COMPONENT_SRCDIRS := mbedtls/library port port/esp8266
COMPONENT_OBJEXCLUDE := mbedtls/library/net_sockets.o
COMPONENT_SUBMODULES += mbedtls
CFLAGS += -DMBEDTLS_PSK_MAX_LEN=64

      After the configuration is complete, run make all and make flash to compile and flash.

    4. Run the application and view logs

      Run make monitor to open the serial port monitor. Restart the device to view the following logs:

      ......
I (274) esp_image: segment 1: paddr=0x00073818 vaddr=0x40273810 size=0x0e5fc ( 58876) map
I (300) esp_image: segment 2: paddr=0x00081e1c vaddr=0x3ffe8000 size=0x00a3c (  2620) load
I (301) esp_image: segment 3: paddr=0x00082860 vaddr=0x40100000 size=0x00a50 (  2640) load
I (308) esp_image: segment 4: paddr=0x000832b8 vaddr=0x40100a50 size=0x05854 ( 22612) load
I (325) boot: Loaded app from partition at offset 0x10000
I (349) system_api: Base MAC address is not set, read default base MAC address from EFUSE
I (359) system_api: Base MAC address is not set, read default base MAC address from EFUSE
phy_version: 1155.0, 6cb3053, Nov 11 2019, 17:31:08, RTOS new
I (413) phy_init: phy ver: 1155_0
I (418) reset_reason: RTC reset 1 wakeup 0 store 0, reason is 1
I (425) simple wifi: ESP_WIFI_MODE_STA
I (473) simple wifi: wifi_init_sta finished.
I (479) simple wifi: connect to ap SSID:C_SDK_Test password:1234abcd
I (614) wifi: state: 0 -> 2 (b0)
I (659) wifi: state: 2 -> 3 (0)
I (671) wifi: state: 3 -> 5 (10)
I (676) wifi: pm start, type: 2
I (2320) event: sta ip: 192.168.0.101, mask: 255.255.255.0, gw: 192.168.0.1
I (2329) simple wifi: got ip:192.168.0.101
I (2334) simple wifi: connected to ap SSID:C_SDK_Test password:1234abcd
I (2342) simple wifi: Start linkkit main
[1.990][LK-0313] MQTT user calls aiot_mqtt_connect api, connect
[2.000][LK-0317] mqtt_basic_demo&a13FNXXXXXX
[2.000][LK-0318] 4780A5F17990D8DC4CCAD392683ED80160C4C2A1FFA649425CD0E2666A8593EB
[2.010][LK-0319] a13FNXXXXXX.mqtt_basic_demo|timestamp=2524608000000,_ss=1,_v=sdk-c-4.0.0,securemode=2,signmethod=hmacsha256,ext=1,|
[2.020][LK-031A] devicename|hmacsha256|a13FNXXXXXX&mqtt_basic_demo|2524608000000
[2.020][LK-031A] 3A27B38E1BAB95462F8EA659C15EE26319286EB1CB7B372451EE82A30A9E7FDF
establish mbedtls connection with server(host='a13FNXXXXXX.itls.cn-shanghai.aliyuncs.com', port=[1883])
[2.450][LK-0313] MQTT connect success in 460 ms
AIOT_MQTTEVT_CONNECT
[2.450][LK-0309] sub: /sys/a13FNXXXXXX/mqtt_basic_demo/thing/event/+/post_reply
[2.460][LK-0309] pub: /sys/a13FNXXXXXX/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
[2.530][LK-0309] pub: /sys/a13FNXXXXXX/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
......

      Logs

      • I (2342) simple wifi: Start linkkit mainThe message in the demo indicates that the SDK for C has started.
      • [LK-XXXX][2.450][LK-0313] MQTT connect success in 460 msThe SDK for C generates logs that contain . The message indicates a successful MQTT connection and shows the time it took to connect.