This topic describes how to port SDK for C 4.0 to an ESP8266 development board and use a demo 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. The host development operating system is macOS.
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

We recommend that you read ESP8266 RTOS Software Development Kit first to accelerate the setup of the development environment. Perform the following steps to set up the macOS environment:

  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 ESP-IDF official repository 
    cd ~
mkdir esp && cd esp
git clone git@github.com:espressif/ESP8266_RTOS_SDK.git -b release/v3.3

    After the download, run the export IDF_PATH=~/esp/ESP8266_RTOS_SDK script to configure the IoT Development Framework (IDF) SDK path.

    Note
    • This demo uses the release/v3.3 branch, and the corresponding commit ID is fd785ab0c50009ab93503ae785814136f6d1009b.
    • Espressif IoT Development Framework (ESP-IDF) has been used in ESP8266_RTOS_SDK V3.0 and later. You can modify ESP8266_RTOS_SDK of an earlier version than V3.0 and use it by referring to this topic.
  3. Install the toolchain and compilation tool

    Manually download the macOS toolchain package and decompress it 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 to the development board
    • Install the USB driver. You can obtain the serial port driver required by ESP-LAUNCHER USB driver from FTDI.
    • Obtain the serial port name. You can run the ls /dev/cu.* command to query the port name for macOS. The serial port name in this demo is /dev/cu.usbserial-AH06UHLH.
  5. Configure, compile, and flash the project, and monitor the serial port
    1. All configurations must be done in the project path. Therefore, first run the cd examples/wifi/simple_wifi/ script to go to the examples/wifi/simple_wifi/ directory.
    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.

    Now, you have set up the ESP8266 development environment and compiled and flashed the wifi station demo.

  6. Port SDK for C 4.0

    The process of porting the SDK for C 4.0 includes the import of SDK code and the configuration of the SDK port files and the compilation system.

    The portfiles directory of the SDK contains the portfile of ESP8266. Therefore, you only need to import the SDK source code and configure the compilation system to complete the SDK porting.

    We recommend that you read Build System of IDF to learn about the porting process. You must understand the following terms about IDF:

    • project: It is a directory that contains only all source files and configuration files used to build an app.
    • components: They are modular pieces of standalone code, which are compiled into .a static libraries and linked to the app. These modular components are stored in the components directory of IDF. You can add custom components.

    By default, the compilation system of ESP8266 SDK uses GUN Make. You only need to import the SDK for C code and write the corresponding .mk configuration file to compile the SDK for C.

Porting methods

The following two porting methods are available:

  • Method 1: Import the SDK for C into the project directory and compile the SDK source code 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 SDK for C as a custom component

    Download the SDK for C 4.0, copy the SDK to the $IDF_PATH/components directory, and add the following component.mk file to the SDK directory: 

    COMPONENT_ADD_INCLUDEDIRS := core core/sysdep core/utils components/ota

COMPONENT_SRCDIRS := core core/utils core/sysdep components/ota portfiles/freertos_port/ external
    Note

    The freertos_port.c file in the portfiles/freertos_port components directory is an SDK porting file for ESP-IDF. This file integrates the SDK for C with ESP-IDF and mbedtls.

  2. Port the demo program

    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 the project

    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 PSK as the TLS key exchange method, you must perform the following operations:

    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 the make all and make flash commands to complete the compilation and flashing.

  4. View logs

    Run the make monitor command to start the serial port monitor and 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
......

    Log description:

    • I (2342) simple wifi: Start linkkit main is the log information added to the demo for identifying that the SDK for C starts to work.
    • Logs that contain [LK-XXXX] are provided by the SDK for C. In the logs, [2.450][LK-0313] MQTT connect success in 460 ms indicates that the MQTT connection is established, and contains the time consumed.