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