Port the SDK to an ESP32 development board - IoT Platform

This topic describes how to port SDK for C 4.0 to an ESP32 development board and use a Message Queuing Telemetry Transport (MQTT) demo to connect to Alibaba Cloud IoT Platform.

Development environment

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

An ESP32 development board.
A USB cable.
A computer that runs Windows, Linux, or macOS.

The development board used in the demo is ESP32 Core Board V2/ESP32 DevKitC, which is equipped with the official ESP-WROOM-322 module, the onboard USB-to-serial module CP2102, and a power supply module.

Note

In this demo, we use macOS to set up the development environment. For more information about how to set up a development environment on other operating systems, see Get Started.

Set up a development environment

Note

We recommend that you read Get Started first to accelerate the setup of the development environment.

Perform the following steps to set up a macOS environment:

Install required software.
- To install required software, macOS users can view Standard Setup of Toolchain for Mac OS. We recommend that you use the Homebrew package management tool. The required packages include pip, Ninja, and CMake.
- To install required software, Windows users can view Standard Setup of Toolchain for Windows.
- To install required software, Linux users can view Standard Setup of Toolchain for Linux.
Clone the ESP-IDF official repository.
This demo uses the release/v4.2 branch of the Espressif IoT Development Framework (ESP-IDF) repository.
```
cd ~
mkdir esp && cd esp
git clone --recursive -b release/v4.2 https://github.com/espressif/esp-idf.git
```
Install the toolchain and compilation tool.
```
cd esp-idf
./install.sh
```
Configure environment variables.
- Run the following script:
```
. $HOME/esp/esp-idf/export.sh
```
- Alternatively, run the following script to add configurations of all environment variables to the $HOME/.bash_profile file:
```
set_esp32 ()
{
    export IDF_PATH=$HOME/esp/esp-idf
    . $HOME/esp/esp-idf/export.sh
}
```

Copy the wifi station demo to a separate directory.

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

Connect to the development board.
- Install the USB driver. For more information, see Establish Serial Connection with ESP32.
- Check the device port name. The USB port name in the demo is /dev/cu.SLAB_USBtoUART.
Configure a project.
Run idf.py menuconfig to configure a project. In this demo, the default configurations are retained.
Compile and flash the project, and monitor the serial port.
- Go to the station project path and run idf.py build to compile the project.
- After the compilation is complete, run the idf.py -p PORT flash command to flash the firmware. Replace PORT with the actual USB port name.
- After the flashing is complete, run the idf.py -p PORT monitor command to monitor the serial port.
- You can also run the idf.py -p PORT flash monitor command to flash the firmware and monitor the printed information of the serial port.
Now, you have set up the ESP32 development environment and compiled and flashed the wifi station demo. The following section describes how to port SDK for C 4.0 and connect it to Alibaba Cloud IoT Platform.

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 ESP32. Therefore, you only need to import the SDK source code and configure the compilation system to complete the porting.

Terms

We recommend that you read Build System of IoT Development Framework (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 IDF uses Ninja and CMake together. You only need to import the SDK code and write the corresponding CMakeList.txt file to compile the SDK.

Porting methods

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.

Procedure

Add the SDK for C as a custom component.
Download SDK for C 4.0, copy the SDK to the $IDF_PATH/components directory, and add the following CMakeLists.txt file to the SDK for C directory:
```
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)
```
Note
- The esp32_port.c file is an SDK porting file for ESP32.
- The SDK for C depends on the mbedtls library. Therefore, REQUIRES mbedtls must be used to introduce component dependencies.
- The SDK for C has no configuration items. Therefore, you do not need to configure the Kconfig component.
Port the demo program.
IDF is compatible with the Portable Operating System Interface (POSIX) standard. Therefore, you only need to copy the content of the LinkSDK/core/demos/mqtt_basic_demo.c file to the station/main/station_example_main.c file and modify it slightly.
You can download the modified demo.c file to replace the original station_example_main.c file.
Note
- The wifi_init_sta() function waits for the Wi-Fi connection until the number of reconnections reaches the value specified by EXAMPLE_ESP_MAXIMUM_RETRY.
- After the Wi-Fi connection succeeds, you can call the API operations of the SDK for C to establish an MQTT connection. After the MQTT connection succeeds, data can be transmitted between the device and IoT Platform.
- The linkkit_main() function contains the MQTT demo of the original SDK for C.
Compile and flash the project.
- Run the idf.py menuconfig command in the project directory. You can view the Example Configuration menu.
- Modify the WiFi SSID, WiFi Password, and Maximum retry (specifying the maximum number of reconnections) parameters, save the modification, and exit.
- Run the idf.py build command to compile the project.
- After the compilation succeeds, run the idf.py -p /dev/cu.SLAB_USBtoUART flash monitor command to flash the project and monitor the serial port.

View logs.

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