1# ESP32-C3 BSP Introduction 2 3[中文](README_ZH.md) | English 4 5This document records the execution instruction of the BSP (board support package) for the [ESP32-C3](http://luatos.com/t/esp32c3) development board. 6 7The document is covered in two parts: 8 9- Board Resources Introduction 10- Quickly Get Started 11 12## Resources Introduction 13 14We tested 2 development boards, it all works, but due to the different LED pins of the two development boards, so we'll need to select the corresponding development board in the menuconfig. 15 16- [LUATOS_ESP32C3](https://wiki.luatos.com/chips/esp32c3/board.html) 17 18 19 20- [HX-DK-商](https://docs.wireless-tech.cn/doc/7/) 21 22 23 24The mainly-used resources of LUATOS_ESP32C3 are shown as follows: 25 26- MCU: [esp32-c3](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf)，Main Frequency 160MHz, 407.22 CoreMark; 2.55 CoreMark/MHz 27- Built-in Chip: 384KB ROM, 400KB SRAM 28- Peripherals 29 - Red LED: 2, LED: D4 (IO12), D5（IO13） 30 - Button: 2, K1（BOOT） K2(RST) 31 - SPI FLASH: 4M 32- Common-used interfaces: USB, UART, etc. 33 34### For more details about this board, please refer to [Here](https://wiki.luatos.com/chips/esp32c3/board.html). 35 36## **Peripheral Condition** 37 38Each peripheral supporting condition for this BSP is as follows: 39 40| **On-board Peripherals** | ****Support**** | ****Remark**** | 41| ------------------------ | --------------- | ------------------------------------------------------------ | 42| GPIO | Support | | 43| UART | Support | Using LUATOS_ESP32C3 development board requires connecting serial port to USB chip UART0_TX and UART0_RX (such as CP2102) | 44| I2C | Supported | Hardware I2C may encounter transmission errors. Software I2C is recommended, but it occupies a general hardware system timer. | 45| SPI | Supported | Supports custom configuration | 46| JTAG debug | Support | ESP32C3 usb-linked development boards can be debugged | 47| WIFI | Partial support | There are currently some problems, such as `rt_mq_recive` cannot be used in ISR, etc. | 48| BLE | Partially supported | There are currently some problems, such as `NimBLE` running errors after starting for a while | 49| GDBStub | Support | You can use the GDB provided by ESP-IDF by turning on the `BSP_ENABLE_GDBSTUB` switch, which will enter GDB mode after a chip error | 50| HWTIMER | Support | 51Note: 52 531. WIFI and BLE cannot be enabled at the same time. When using the BLE driver, be sure to turn off the `RT_USING_WIFI` and `LWIP` switches in `menuconfig`. In addition, due to limited capabilities and lack of debugging equipment, there are problems with WIFI and BLE driver operation. If it can be solved, please contact [timwcx@qq.com](mailto:timwcx@qq.com). 54 552. The BLE driver only supports `NimBLE` and is provided by the `bluetooth` component in `esp-idf`. To use the BLE driver, please refer to `bsp/ESP32_C3/packages/ESP-IDF-latest/examples/bluetooth/nimble` Sample program, please note that the `esp_timer_init()` function must be called to initialize the clock driver before calling the `NimBLE` related interface. 56 57One way to run the BLE sample is to add the sample program to `scons` compilation and call the clock initialization program and sample program entry in `bsp/ESP32_C3/main/main.c`. 58 59```c 60int main(void) { 61 ... 62#ifdef BSP_USING_BLE 63 esp_timer_init(); //Call clock initialization program 64 app_main(); //Call the BLE sample program entry 65#endif 66 ... 67} 68``` 69 703、 Regarding the use of the GDBStub component, please see [ESP-IDF official documentation on GDBStub](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32c3/api-guides/tools/idf- monitor.html?#gdbstub-gdb), currently I have provided a debugging script `esp32c3.gdb`, the specific usage method is as follows. 71 72```sh 73wcx@tim ~/rt-thread/bsp/ESP32_C3 esp32 ± sudo riscv32-esp-elf-gdb # Enter gdb debugging 74GNU gdb (crosstool-NG esp-2022r1-RC1) 9.2.90.20200913-git 75Copyright (C) 2020 Free Software Foundation, Inc. 76License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> 77This is free software: you are free to change and redistribute it. 78There is NO WARRANTY, to the extent permitted by law. 79Type "show copying" and "show warranty" for details. 80This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=riscv32-esp-elf". 81Type "show configuration" for configuration details. 82For bug reporting instructions, please see: 83<http://www.gnu.org/software/gdb/bugs/>. 84Find the GDB manual and other documentation resources online at: 85 <http://www.gnu.org/software/gdb/documentation/>. 86 87For help, type "help". 88Type "apropos word" to search for commands related to "word". 89(gdb) source esp32c3.gpb # Load gdb script 900x3fca8c30 in __stack_start__ () 91(gdb) 92``` 93 94## Environment construction and compilation 95 96### Docker deploy 97 98If you want to lightly experiment with the ESP32-C3, it is recommended to quickly set up the environment using Docker. Otherwise, use a native environment setup. 99 100 1. Ensure Docker is installed and the inner network environment is properly configured. You can obtain the Docker image either via a pre-built docker image or by building it from a Dockerfile. Note that the docker image may not always be up-to-date, while the Dockerfile allows you to fetch the latest main branch. Below are the setup commands: 101 * Setting up the development environment using a Dockerfile: 102 103 ```sh 104 cd docker 105 sudo docker build --build-arg HTTP_PROXY=http://ip:port --build-arg HTTPS_PROXY=http://ip:port -t image_name . 106 ``` 107 Replace ip:port with your proxy server's IP and port. Otherwise, network issues may occur when pulling repositories. 108 109 * Setting up the development environment using a pre-built Docker image: 110 111 ```sh 112 sudo docker pull 1078249029/rtthread_esp32c3:latest 113 ``` 114 115 2. Enter the Docker container: 116 117 ```sh 118 sudo docker run -it --device=/dev/ttyUSB* image_name 119 ``` 120 121 The --device parameter is used for debugging and flashing code. You can obtain the corresponding port by running ls /dev/ttyUSB* on the host machine. If you used the pre-built Docker image, replace image_name with 1078249029/rtthread_esp32c3. 122 123 3. Using the Environment: 124 125 Flashing firmware: 126 127 ```sh 128 sudo esptool.py -b 115200 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 80m 0x0 path/to/your/bootloader.bin 0x08000 path/to/your/partition-table.bin 0x010000 path/to/your/rtthread.bin 129 ``` 130 131 Debugging: 132 133 ```sh 134 sudo minicom -c on -D /dev/ttyUSB* 135 ``` 136### Native setup 137 1381. Download the RISC-V toolchain: 139 140 ```sh 141 wget https://github.com/espressif/crosstool-NG/releases/download/esp-2022r1-RC1/riscv32-esp-elf-gcc11_2_0-esp-2022r1-RC1-linux-amd64.tar.xz 142 tar xf riscv32-esp-elf-gcc11_2_0-esp-2022r1-RC1-linux-amd64.tar.xz 143 ``` 144 1452. Configure the path of the toolchain: 146 147 Add the local path of the `RISC-V` toolchain to the `EXEC_PATH` variable in the `rtconfig.py` file, or specify the path by setting the `RTT_EXEC_PATH` environment variable, for example: 148 149 ```sh 150 export RTT_EXEC_PATH=/opt/riscv32-esp-elf/bin 151 ``` 152 1533. Compile 154 155 Install esptool to convert ELF files to binary flash files: 156 157 ```sh 158 pip install esptool 159 ``` 160 161 Execute the following command on the Linux platform to configure: 162 163 ``` 164 scons --menuconfig 165 ``` 166 167 It will automatically download env-related scripts to the `~/.env` directory, and then execute: 168 169 ```sh 170 source ~/.env/env.sh 171 172 cd bsp/ESP32_C3/ 173 pkgs --update 174 ``` 175 176 It will automatically download `RT-Thread-packages/esp-idf` and `RT-Thread-packages/FreeRTOS-Wrapper`, after updating the software packages, execute `scons` to compile the board support package. 177 178 If the compilation is successful, `rtthread.elf`, `rtthread.bin` files will be generated. 179 180## Download and program 181 182In Windows, we can use *flash* supported by ESPRESSIF. 183 184In Linux, we can use the esptool, which we have downloaded serval steps 185 186### Windows 187 1881. Programming tool download 189 190 The current bsp test uses the [Flash Download Tools](https://www.espressif.com.cn/sites/default/files/tools/flash_download_tool_3.9.4_0.zip) tool to program without errors. 191 1922. Programming tool configuration 193 194 Chip model selection `ESP32-C3` 195 196 Configure the binary file and offset address as follows: 197 198 | binary file | offset address | 199 | ------------------- | -------- | 200 | bootloader.bin | 0x0 | 201 | partition-table.bin | 0x8000 | 202 | rtthread.bin | 0x10000 | 203 204 Among them, `bootloader.bin` and `partition-table.bin` can be found in the `bsp/ESP32_C3/builtin_imgs` folder. After the configuration is completed, the screenshot is as follows, and then click `START` to download. 205 206  207 208### Linux 209 210```sh 211esptool.py -b 115200 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size detect --flash_freq 80m 0x0 path/to/your/bootloader.bin 0x08000 path/to/your/partition-table.bin 0x010000 path/to/your/rtthread.bin 212``` 213if you have more than one ESP device connected, you can use -p to choose which device to use. 214 215if the command failed, check whether user ave enough privilige to access the serials. 216 217or we can check ESPRESSIF's [Troubleshooting](https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html) to get more help. 218 219## Notes 220 221- The basic functions are now supported, but it needs more, welcome any contributions and feedback. 222 223 224Maintainer: 225 226- [supperthomas](https://github.com/supperthomas) email address: [78900636@qq.com](mailto:78900636@qq.com) 227- [tangzz98](https://github.com/tangzz98) email address: [tangz98@outlook.com](tangz98@outlook.com) 228- [wumingzi](https://github.com/1078249029) email address: [1078249029@qq.com](1078249029@qq.com) 229 230Special thanks to [chenyingchun0312](https://github.com/chenyingchun0312) for providing support on the RISC-V part working. 231 232
