<img alt="ESP-IDF development diagram" src="../../hardware-dev/images/idf/esp-idf.png" loading="lazy" />

## ESP-IDF Introduction

**ESP-IDF (Espressif IoT Development Framework) is Espressif's official IoT development framework for its ESP32 series chips, designed to help users quickly develop IoT applications**. The following is a detailed introduction to ESP-IDF:

1. **Product overview**: ESP-IDF is designed for the ESP32, ESP32-S, ESP32-C, and ESP32-H series SoCs and provides a complete software development toolchain. The framework is based on the C/C++ language and provides a self-sufficient SDK, enabling developers to easily build general-purpose applications on these platforms.

2. **Core features**: ESP-IDF supports multiple network protocols, including TCP/UDP, MQTT, HTTP, and more, meeting the needs of different application scenarios. It also supports low-power modes, reducing standby power consumption through optimized power management and extending device battery life. In addition, ESP-IDF provides rich peripheral pins, such as USB, UART, SPI, I2C, PWM, and GPIO, making it easy to connect various sensors and controllers.

3. **Development environment**: ESP-IDF supports Windows, Linux, and macOS. Users can choose to set up the development environment via the manual command-line method or by using the VSCode plugin. For beginners, the VSCode plugin is recommended because it is simple, convenient, and easy to get started with.

4. **Remote upgrade**: ESP-IDF supports FOTA (Firmware Over-The-Air) remote upgrades. Users can upgrade firmware through the Hezhou IOT platform or a self-built server without on-site operations, greatly reducing maintenance costs.

5. **Application areas**: ESP-IDF is widely used in smart cities, smart homes, industrial automation, intelligent transportation, and many other fields. Its high performance, low power consumption, and rich features make it an ideal choice for IoT applications.

In summary, as Espressif's official IoT development framework, ESP-IDF has become one of the preferred tools for IoT developers thanks to its powerful features and wide range of application areas.

## Connecting Devices to the FastBee IoT Cloud Platform

::: tip Source Code
[ Connecting an ESP device to the FastBee IoT Cloud Platform, for reference only](https://gitee.com/beecue/fastbee-sdk/tree/master/ESP-IDF/esp_fastbee_aliyun)
:::

### Contents

* [1. Purpose](#aim)
* [2. Hardware Preparation](#hardwareprepare)
* [3. Cloud Platform Preparation](#compileprepare)
* [4. Environment Setup](#envprepare)
* [5. SDK Preparation](#sdkprepare)
* [6. Compile & Flash & Run](#makeflash)

### <span id = "aim">1. Purpose</span>

This project is modified based on the esp-aliyun SDK and introduces the specific process of connecting an ESP device to the FastBee IoT Cloud Platform and the Alibaba Cloud platform.
Main features implemented:

* Support for \<FastBee IoT Cloud Platform> network provisioning, access, and control
* Support for one-touch network provisioning via the \<Cloud Intelligence> app
* Support for device control via the \<Cloud Intelligence> app
* Support for device control via the \<Tmall Genie smart speaker>
* Support for network provisioning and device control via the \<Tmall Genie smart speaker>
* Support for LED control (on/off, color, etc.)
* Support for OTA upgrades

### <span id = "hardwareprepare">2. Hardware Preparation</span>

* **Linux environment**\
  A mandatory environment for compiling, flashing, running, and other operations.

> Windows users can install a virtual machine and install Linux inside it.

* **ESP device**\
  ESP devices include [ESP chips](https://www.espressif.com/zh-hans/products/hardware/socs), [ESP modules](https://www.espressif.com/zh-hans/products/hardware/modules), [ESP development boards](https://www.espressif.com/zh-hans/products/hardware/development-boards), and more.

* **USB cable**\
  Connects the PC and the ESP device, used for flashing/downloading programs, viewing logs, and more.

### <span id = "compileprepare">3. Cloud Platform Preparation</span>

### <span id = "envprepare">4. Environment Setup</span>

**If you are familiar with the ESP development environment, you can easily understand the steps below; if you are not familiar with a certain part, such as compilation or flashing, you will need to refer to the relevant official documentation, such as the [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/index.html).**

#### 4.1 Setting Up the Compiler Environment

* ESP8266 platform: get the toolchain via **Get toolchain** in the [official link](https://github.com/espressif/ESP8266_RTOS_SDK)
* ESP32 & ESP32S2 platforms: download the toolchain via **Setting up the toolchain** in the [official link](https://github.com/espressif/esp-idf/blob/master/docs/zh_CN/get-started/linux-setup.rst)

For toolchain setup, refer to the [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/get-started/index.html#get-started-setup-toolchain).

#### 4.2 Getting the Flashing/Download Tool

* ESP8266 platform: the flashing tool is located under [ESP8266\_RTOS\_SDK](https://github.com/espressif/ESP8266_RTOS_SDK) at `./components/esptool_py/esptool/esptool.py`
* ESP32 & ESP32S2 platforms: the flashing tool is located under [esp-idf](https://github.com/espressif/esp-idf) at `./components/esptool_py/esptool/esptool.py`

For esptool features, refer to:

```js
$ ./components/esptool_py/esptool/esptool.py --help
```

### <span id = "sdkprepare">5. SDK Preparation</span>

* [esp-aliyun SDK](https://github.com/espressif/esp-aliyun): this SDK enables ESP devices to connect to Alibaba Cloud using the MQTT protocol.
* Espressif SDK
  * ESP32 & ESP32S2 platforms: [ESP-IDF](https://github.com/espressif/esp-idf)
  * ESP8266 platform: [ESP8266\_RTOS\_SDK](https://github.com/espressif/ESP8266_RTOS_SDK)

> After downloading the Espressif SDK:\
> ESP-IDF: switch to the v4.2 branch: `git checkout v4.2`
> If you need to use the ESP32S2 module, switch to version v4.2: `git checkout v4.2`
> ESP8266\_RTOS\_SDK: switch to the v3.3 branch: `git checkout v3.3`

### <span id = "makeflash">6. Compile & Flash & Run</span>

#### 6.1 Compile

**6.1.1 Export the Compiler**
Refer to [Setting up the toolchain](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/get-started/linux-setup.html)

**6.1.2 Compile the Demo Example**
**Since esp32 and esp8266 use different sdkconfig.defaults and corresponding partitions.csv files, the corresponding chip option is added to the make command, such as chip=esp32 or chip=esp8266.**

When chip=esp32, sdkconfig\_esp32.defaults and partitions\_esp32.csv are used by default.

When chip=esp8266, sdkconfig\_esp8266.defaults and partitions\_esp8266.csv are used by default.

When using esp32s2, sdkconfig.defaults, sdkconfig.defaults.esp32s2, and partitions\_esp32s2.csv are used by default. The compilation method is different from both 8266 & 32 and requires cmake.

Pay special attention to the above.

Execute in the esp-aliyun directory:

```shell
cd fastbee\sdk\ESP-IDF\esp-aliyun
make chip=esp32 defconfig
make menuconfig
```

If you need to compile the esp32s2 version, compile it as follows:

Execute in the esp-aliyun directory:

```shell
cd fastbee\sdk\ESP-IDF\esp-aliyun
idf.py set-target esp32s2
idf.py menuconfig
```

* Configure the flashing serial port
* Configure `WIFI_SSID`, `WIFI_PASSWORD`

If you need to compile the esp32s3 version, compile it as follows:

Execute in the esp-aliyun directory:

```shell
cd fastbee\sdk\ESP-IDF\esp-aliyun
idf.py set-target esp32s3
idf.py menuconfig
```

2. Generate the Final bin

```shell
make -j8
```

Generate the bin with esp32s2/esp32s3

```shell
idf.py build
```

#### 6.2 Erase & Compile/Flash & Download the Firmware & View Logs

Connect the ESP device and the PC with the USB cable, and make sure the flashing port is correct.

**6.2.1 \[Optional] Erase Flash**

```sh
make erase_flash
```

> Note: there is no need to erase every time; after erasing, you need to redo 6.2.3.

**6.2.2 Flash the Program**

```sh
make flash
```

Erase flash with esp32s2/esp32s3

```sh
idf.py -p (PORT) erase_flash
```

**6.2.3 Flash the Triplet Information**
Refer to the mass-production instructions in `aliyunsdk/config/mass_mfg/README.md` in the SDK to flash the triplet NVS partition.

#### 6.2.4 Run

```sh
make monitor
```

> You can also run `make flash monitor` to compile, flash, and view logs in one go.
