Cara melakukan porting C-SDK 4.0 ke papan pengembangan ESP32 dan menghubungkannya ke IoT Platform - IoT Platform

Topik ini menjelaskan cara melakukan porting C-SDK 4.0 ke papan pengembangan ESP32 dan menggunakan demo MQTT untuk terhubung ke Alibaba Cloud IoT Platform.

Tutorial ini mencakup langkah-langkah berikut:

Siapkan lingkungan pengembangan ESP-IDF di macOS atau Linux.
Tambahkan C-SDK 4.0 sebagai komponen kustom ESP-IDF.
Ganti file entri demo dan selesaikan konflik mbedTLS.

Kompilasi, flash, dan verifikasi koneksi MQTT ke IoT Platform.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Papan pengembangan ESP32 (tutorial ini menggunakan ESP32 Core Board V2/ESP32 DevKitC dengan modul onboard ESP-WROOM-32, modul USB-to-serial CP2102, dan modul daya).
Kabel USB.
Komputer yang menjalankan Linux atau macOS.

Buat juga produk dan perangkat di IoT Platform sebelum memulai:

Login ke Konsol IoT Platform dan buat produk.
Buat perangkat di bawah produk tersebut dan catat ProductKey, DeviceName, dan DeviceSecret. Anda memerlukan kredensial ini saat mengompilasi firmware.

Catatan
Tutorial ini menggunakan macOS sebagai lingkungan pengembangan. Jika Anda menggunakan sistem operasi lain, lihat tutorial mulai resmi ESP32 untuk menyiapkan lingkungan pengembangan Anda.

Siapkan lingkungan pengembangan

Catatan

Bagian ini hanya sebagai referensi. Jika mengalami masalah, hubungi pemasok papan pengembangan Anda untuk bantuan. Untuk mempercepat proses penyiapan, lihat tutorial mulai resmi Espressif.

Instal paket yang diperlukan.
- Di macOS, gunakan Homebrew untuk menginstal pip, ninja, dan cmake. Lihat Penyiapan Standar Toolchain untuk Mac OS untuk detailnya.
- Di Linux, lihat Penyiapan Standar Toolchain untuk Linux.
Klon repositori esp-idf.

Tutorial ini menggunakan branch release/v4.2. Versi lain dapat menyebabkan masalah kompatibilitas.
```
cd ~
mkdir esp && cd esp
git clone --recursive -b release/v4.2 https://github.com/espressif/esp-idf.git
```
Instal toolchain dan alat kompilasi.
```
cd esp-idf
./install.sh
```
Konfigurasikan variabel lingkungan.
- Jalankan skrip export:
```
. $HOME/esp/esp-idf/export.sh
```
- Untuk menghindari menjalankan skrip ini setiap kali, tambahkan fungsi berikut ke $HOME/.bash_profile:
```
set_esp32 ()
{
    export IDF_PATH=$HOME/esp/esp-idf
    . $HOME/esp/esp-idf/export.sh
}
```

Salin contoh Wi-Fi station ke direktori kerja.

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

Sambungkan papan pengembangan.
- Instal driver USB. Lihat Membangun Koneksi Serial dengan ESP32 untuk detailnya.
- Identifikasi nama port USB. Dalam tutorial ini, port tersebut adalah /dev/cu.SLAB_USBtoUART.
Konfigurasikan proyek.

Jalankan idf.py menuconfig dan gunakan konfigurasi default.
Build, flash, dan pantau.
- Di direktori proyek station, jalankan idf.py build untuk mengompilasi.
- Setelah kompilasi selesai, jalankan idf.py -p PORT flash untuk melakukan flashing firmware. Ganti PORT dengan nama port USB aktual Anda.
- Setelah firmware di-flash, jalankan idf.py -p PORT monitor untuk membuka monitor port serial.
- Anda juga dapat menjalankan idf.py -p PORT flash monitor untuk melakukan flashing dan monitoring dalam satu perintah.
Lingkungan pengembangan ESP32 kini telah disiapkan, dan Anda telah memverifikasi bahwa contoh wifi station berhasil dikompilasi dan dijalankan. Bagian berikut menjelaskan cara melakukan porting C-SDK 4.0 dan menghubungkannya ke IoT Platform.

Porting C-SDK 4.0

Porting C-SDK 4.0 melibatkan tiga tugas: menambahkan SDK sebagai komponen idf, mengganti file port yang telah disesuaikan untuk ESP32, dan menyelesaikan konflik pustaka mbedTLS.

Direktori portfiles di C-SDK sudah berisi file port untuk ESP32, sehingga porting terutama berarti mengimpor kode sumber SDK dan mengonfigurasi sistem build.

Konsep utama

Baca pengantar sistem build ESP-IDF untuk latar belakangnya. Dua konsep berikut menjadi inti dari tutorial ini:

project: Folder yang berisi file sumber dan file konfigurasi untuk membangun app.
components: Unit kode yang dapat digunakan ulang dan mandiri, dikompilasi menjadi pustaka statis .a dan ditautkan ke app. Komponen kustom ditempatkan di direktori components dari idf.

Sistem build ESP-IDF menggunakan CMake dan ninja. Untuk mengintegrasikan C-SDK, pindahkan kode sumbernya ke direktori components dan tambahkan file CMakeLists.txt.

Metode porting

Metode 1: Impor C-SDK ke direktori project. Kompilasi kode sumber SDK bersama dengan kode sumber app lainnya.
Metode 2: Impor C-SDK sebagai komponen idf kustom ke direktori components dari idf.

Tutorial ini menggunakan Metode 2. Menggunakan C-SDK sebagai komponen independen membantu Anda menggunakannya kembali di berbagai proyek dan menjaganya tetap terpisah dari kode aplikasi Anda.

Tabel berikut menunjukkan direktori C-SDK yang relevan:

Direktori	Isi
`core/`	File sumber dan header inti SDK
`core/sysdep/`	Abstraksi dependensi sistem (termasuk `core_adapter.c`)
`core/utils/`	Fungsi utilitas
`portfiles/aiot_port/`	File port spesifik platform, termasuk `posix_port.c` yang telah disesuaikan untuk ESP32
`external/`	Pustaka pihak ketiga yang disertakan dalam SDK

Prosedur porting

Tambahkan C-SDK sebagai komponen kustom.

Unduh C-SDK 4.0 dan salin ke $IDF_PATH/components. Di direktori root C-SDK, buat file CMakeLists.txt dengan konten berikut:
```
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)
```
Catatan
- C-SDK bergantung pada pustaka mbedTLS. REQUIRES mbedtls mendeklarasikan dependensi komponen ini.
- C-SDK tidak memiliki item konfigurasi Kconfig. Tidak diperlukan pengaturan Kconfig komponen.
- Untuk menggunakan fitur SDK lanjutan seperti model Thing Specification Language (TSL) atau pembaruan Over-the-Air (OTA), tambahkan path file sumber dan header yang sesuai ke CMakeLists.txt ini.
Ganti file port dan nonaktifkan konflik mbedTLS.

Unduh posix_port.c, yang telah disesuaikan untuk ESP32. Ganti $IDF_PATH/components/C-SDK/portfiles/aiot_port/posix_port.c dengan file ini.

Baik LinkSDK maupun ESP-IDF menyertakan pustaka mbedTLS. Untuk menghindari konflik simbol saat linking, buka $IDF_PATH/components/C-SDK/core/sysdep/core_adapter.c dan nonaktifkan makro CORE_ADAPTER_MBEDTLS_ENABLED.
Ganti file entri demo.

Unduh station_example_main.c dan ganti station/main/station_example_main.c di contoh station Anda.
Catatan
- wifi_init_sta() mencoba koneksi Wi-Fi secara berulang hingga mencapai batas yang ditentukan oleh makro EXAMPLE_ESP_MAXIMUM_RETRY.
- Setelah koneksi Wi-Fi terbentuk, demo memanggil API C-SDK untuk membuka koneksi MQTT. Setelah terhubung, perangkat dapat bertukar data dengan IoT Platform.
- linkkit_main() berisi logika demo MQTT C-SDK asli.
Kompilasi dan flash.
- Di direktori proyek, jalankan idf.py menuconfig dan buka menu Example Configuration.
- Atur WiFi SSID, WiFi Password, dan Maximum retry, lalu simpan dan keluar.
- Jalankan idf.py build untuk mengompilasi.
- Setelah kompilasi berhasil, jalankan idf.py -p /dev/cu.SLAB_USBtoUART flash monitor untuk melakukan flashing firmware dan membuka monitor port serial.
Catatan
Jika perangkat menggunakan pertukaran kunci Pre-Shared Key (PSK), aktifkan dukungan PSK di mbedTLS dan atur panjang maksimum PSK menjadi 64:
- Di idf.py menuconfig, buka Component config > mbedTLS > TLS Key Exchange Methods.
- Aktifkan Enable pre-shared-key ciphersuites.
- Di CMakeLists.txt komponen mbedTLS, tambahkan set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DMBEDTLS_PSK_MAX_LEN=64").

Verifikasi koneksi.

Koneksi yang berhasil menghasilkan output serupa berikut:

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

Cari MQTT connect success dan AIOT_MQTTEVT_CONNECT dalam output. Baris heartbeat response yang berulang menunjukkan bahwa koneksi MQTT tetap terjaga.

Penting

Jika Anda melihat error aiot_mqtt_connect failed: -0x0F0F, ini merupakan masalah konektivitas jaringan. Periksa status jaringan Wi-Fi Anda dan pastikan papan berada dalam jangkauan titik akses. Jika perlu, lakukan flashing ulang firmware dan coba lagi.

Kode kesalahan -0x0F0F berkorespondensi dengan STATE_PORT_NETWORK_CONNECT_TIMEOUT, yang menunjukkan bahwa upaya koneksi mengalami timeout.

Pemecahan Masalah

Koneksi MQTT gagal dengan `aiot_mqtt_connect failed: -0x0F0F`

Kode kesalahan -0x0F0F dipetakan ke STATE_PORT_NETWORK_CONNECT_TIMEOUT, yang berarti papan tidak dapat mencapai server IoT Platform dalam periode timeout. Periksa hal berikut:

Pastikan papan berada dalam jangkauan sinyal Wi-Fi dan terhubung ke SSID yang benar.
Verifikasi nilai WiFi SSID dan WiFi Password yang Anda masukkan di idf.py menuconfig.
Jika masalah berlanjut, lakukan flashing ulang firmware dan coba lagi.

Build gagal karena simbol mbedTLS duplikat

Baik LinkSDK maupun ESP-IDF menyertakan mbedTLS. Jika Anda melihat error linker tentang simbol duplikat, pastikan Anda telah menonaktifkan CORE_ADAPTER_MBEDTLS_ENABLED di core_adapter.c seperti yang dijelaskan pada langkah 2 prosedur porting.

Perangkat terus-menerus reset setelah flashing

Coba hapus flash sebelum melakukan flashing ulang:

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

Port serial tidak dikenali di macOS

Pastikan driver USB CP2102 telah diinstal. Lihat Membangun Koneksi Serial dengan ESP32 untuk instruksi instalasi driver.