• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..--

.github/11-Mar-2024-252189

.gitlab/11-Mar-2024-4,4283,664

components/11-Mar-2024-1,677,0761,104,643

docs/11-Mar-2024-95,84465,978

examples/11-Mar-2024-324,746258,313

include/dt-bindings/pinctrl/11-Mar-2024-37,03224,440

make/11-Mar-2024-1,485846

tools/11-Mar-2024-854,706830,931

west/11-Mar-2024-196136

zephyr/11-Mar-2024-22,16816,518

.editorconfigD11-Mar-2024742 4433

.flake8D11-Mar-20248.9 KiB171160

.gitignoreD11-Mar-20241.6 KiB10377

.gitlab-ci.ymlD11-Mar-20245.4 KiB14298

.mypy.iniD11-Mar-2024985 2719

.pre-commit-config.yamlD11-Mar-20244 KiB113103

.pylintrcD11-Mar-202418.5 KiB607457

.readthedocs.ymlD11-Mar-2024538 2210

CMakeLists.txtD11-Mar-20248.1 KiB208179

CONTRIBUTING.rstD11-Mar-20242.5 KiB6237

KconfigD11-Mar-202418.4 KiB447353

LICENSED11-Mar-202411.1 KiB203169

README.mdD11-Mar-20247.6 KiB11967

README_CN.mdD11-Mar-20247.6 KiB11966

SUPPORT_POLICY.mdD11-Mar-20243.6 KiB8764

SUPPORT_POLICY_CN.mdD11-Mar-20243.2 KiB5635

add_path.shD11-Mar-2024721 1910

export.batD11-Mar-20243.2 KiB9782

export.fishD11-Mar-20242.4 KiB7964

export.ps1D11-Mar-20243 KiB8154

export.shD11-Mar-20246.1 KiB189142

install.batD11-Mar-20241.4 KiB4838

install.fishD11-Mar-2024570 2618

install.ps1D11-Mar-2024628 2317

install.shD11-Mar-2024563 2820

requirements.txtD11-Mar-20242 KiB4941

sdkconfig.renameD11-Mar-20241.9 KiB2926

sonar-project.propertiesD11-Mar-2024568 2719

README.md

1# Espressif IoT Development Framework
2
3* [中文版](./README_CN.md)
4
5ESP-IDF is the development framework for Espressif SoCs supported on Windows, Linux and macOS.
6
7# ESP-IDF Release and SoC Compatibility
8
9The following table shows ESP-IDF support of Espressif SoCs where ![alt text][preview] and ![alt text][supported] denote preview status and support, respectively. In preview status the build is not yet enabled and some crucial parts could be missing (like documentation, datasheet). Please use an ESP-IDF release where the desired SoC is already supported.
10
11|Chip         |         v3.3           |          v4.0          |           v4.1         |          v4.2          |         v4.3           |          v4.4          |                                                            |
12|:----------- |:---------------------: | :---------------------:| :---------------------:| :---------------------:| :---------------------:| :---------------------:|:---------------------------------------------------------- |
13|ESP32        | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] |                                                            |
14|ESP32-S2     |                        |                        |                        | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] |                                                            |
15|ESP32-C3     |                        |                        |                        |                        | ![alt text][supported] | ![alt text][supported] |                                                            |
16|ESP32-S3     |                        |                        |                        |                        | ![alt text][preview]   | ![alt text][supported] | [Announcement](https://www.espressif.com/en/news/ESP32_S3) |
17|ESP32-H2     |                        |                        |                        |                        |                        | ![alt text][preview]   | [Announcement](https://www.espressif.com/en/news/ESP32_H2) |
18
19[supported]: https://img.shields.io/badge/-supported-green "supported"
20[preview]: https://img.shields.io/badge/-preview-orange "preview"
21
22Espressif SoCs released before 2016 (ESP8266 and ESP8285) are supported by [RTOS SDK](https://github.com/espressif/ESP8266_RTOS_SDK) instead.
23
24# Developing With ESP-IDF
25
26## Setting Up ESP-IDF
27
28See https://idf.espressif.com/ for links to detailed instructions on how to set up the ESP-IDF depending on chip you use.
29
30**Note:** Each SoC series and each ESP-IDF release has its own documentation. Please see Section [Versions](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/versions.html) on how to find documentation and how to checkout specific release of ESP-IDF.
31
32### Non-GitHub forks
33
34ESP-IDF uses relative locations as its submodules URLs ([.gitmodules](.gitmodules)). So they link to GitHub.
35If ESP-IDF is forked to a Git repository which is not on GitHub, you will need to run the script
36[tools/set-submodules-to-github.sh](tools/set-submodules-to-github.sh) after git clone.
37The script sets absolute URLs for all submodules, allowing `git submodule update --init --recursive` to complete.
38If cloning ESP-IDF from GitHub, this step is not needed.
39
40## Finding a Project
41
42As well as the [esp-idf-template](https://github.com/espressif/esp-idf-template) project mentioned in Getting Started, ESP-IDF comes with some example projects in the [examples](examples) directory.
43
44Once you've found the project you want to work with, change to its directory and you can configure and build it.
45
46To start your own project based on an example, copy the example project directory outside of the ESP-IDF directory.
47
48# Quick Reference
49
50See the Getting Started guide links above for a detailed setup guide. This is a quick reference for common commands when working with ESP-IDF projects:
51
52## Setup Build Environment
53
54(See the Getting Started guide listed above for a full list of required steps with more details.)
55
56* Install host build dependencies mentioned in the Getting Started guide.
57* Run the install script to set up the build environment. The options include `install.bat` or `install.ps1` for Windows, and `install.sh` or `install.fish` for Unix shells.
58* Run the export script on Windows (`export.bat`) or source it on Unix (`source export.sh`) in every shell environment before using ESP-IDF.
59
60## Configuring the Project
61
62* `idf.py set-target <chip_name>` sets the target of the project to `<chip_name>`. Run `idf.py set-target` without any arguments to see a list of supported targets.
63* `idf.py menuconfig` opens a text-based configuration menu where you can configure the project.
64
65## Compiling the Project
66
67`idf.py build`
68
69... will compile app, bootloader and generate a partition table based on the config.
70
71## Flashing the Project
72
73When the build finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this automatically by running:
74
75`idf.py -p PORT flash`
76
77Replace PORT with the name of your serial port (like `COM3` on Windows, `/dev/ttyUSB0` on Linux, or `/dev/cu.usbserial-X` on MacOS. If the `-p` option is left out, `idf.py flash` will try to flash the first available serial port.
78
79This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `idf.py menuconfig`.
80
81You don't need to run `idf.py build` before running `idf.py flash`, `idf.py flash` will automatically rebuild anything which needs it.
82
83## Viewing Serial Output
84
85The `idf.py monitor` target uses the [idf_monitor tool](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html) to display serial output from Espressif SoCs. idf_monitor also has a range of features to decode crash output and interact with the device. [Check the documentation page for details](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html).
86
87Exit the monitor by typing Ctrl-].
88
89To build, flash and monitor output in one pass, you can run:
90
91`idf.py flash monitor`
92
93## Compiling & Flashing Only the App
94
95After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table:
96
97* `idf.py app` - build just the app.
98* `idf.py app-flash` - flash just the app.
99
100`idf.py app-flash` will automatically rebuild the app if any source files have changed.
101
102(In normal development there's no downside to reflashing the bootloader and partition table each time, if they haven't changed.)
103
104## Erasing Flash
105
106The `idf.py flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `idf.py erase-flash`.
107
108This can be combined with other targets, ie `idf.py -p PORT erase-flash flash` will erase everything and then re-flash the new app, bootloader and partition table.
109
110# Resources
111
112* Documentation for the latest version: https://docs.espressif.com/projects/esp-idf/. This documentation is built from the [docs directory](docs) of this repository.
113
114* The [esp32.com forum](https://esp32.com/) is a place to ask questions and find community resources.
115
116* [Check the Issues section on github](https://github.com/espressif/esp-idf/issues) if you find a bug or have a feature request. Please check existing Issues before opening a new one.
117
118* If you're interested in contributing to ESP-IDF, please check the [Contributions Guide](https://docs.espressif.com/projects/esp-idf/en/latest/contribute/index.html).
119

README_CN.md

1# Espressif 物联网开发框架
2
3* [English Version](./README.md)
4
5ESP-IDF 是乐鑫官方推出的物联网开发框架，支持 Windows、Linux 和 macOS 操作系统。
6
7# ESP-IDF 与乐鑫芯片
8
9下表总结了乐鑫芯片在 ESP-IDF 各版本中的支持状态，其中 ![alt text][supported] 代表已支持，![alt text][preview] 代表目前处于预览支持状态。在预览支持阶段，因为新芯片尚未完全添加到构建系统目录，所以一些重要的内容（如文档和技术规格书等）可能会缺失。请确保使用与芯片相匹配的 ESP-IDF 版本。
10
11|    芯片     |         v3.3           |          v4.0          |           v4.1         |          v4.2          |         v4.3           |          v4.4          |                                                            |
12|:----------- |:---------------------: | :---------------------:| :---------------------:| :---------------------:| :---------------------:| :---------------------:|:---------------------------------------------------------- |
13|ESP32        | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] |                                                            |
14|ESP32-S2     |                        |                        |                        | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] |                                                            |
15|ESP32-C3     |                        |                        |                        |                        | ![alt text][supported] | ![alt text][supported] |                                                            |
16|ESP32-S3     |                        |                        |                        |                        | ![alt text][preview]   | ![alt text][supported] | [芯片发布公告](https://www.espressif.com/en/news/ESP32_S3) |
17|ESP32-H2     |                        |                        |                        |                        |                        | ![alt text][preview]   | [芯片发布公告](https://www.espressif.com/en/news/ESP32_H2) |
18
19[supported]: https://img.shields.io/badge/-%E6%94%AF%E6%8C%81-green "supported"
20[preview]: https://img.shields.io/badge/-%E9%A2%84%E8%A7%88-orange "preview"
21
22对于 2016 年之前发布的乐鑫芯片（包括 ESP8266 和 ESP8285），请参考 [RTOS SDK](https://github.com/espressif/ESP8266_RTOS_SDK)。
23
24# 使用 ESP-IDF 进行开发
25
26## 搭建 ESP-IDF 开发环境
27
28关于不同芯片如何搭建 ESP-IDF 的开发环境，请参考 https://idf.espressif.com/ 。
29
30**注意：** 不同系列芯片和不同 ESP-IDF 版本都有其对应的文档。请参阅[版本](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/versions.html)部分，获得关于如何查找文档以及如何检出 ESP-IDF 的特定发行版的详细信息。
31
32### 非 GitHub 分叉的 ESP-IDF 项目
33
34ESP-IDF 中的子模块采用相对路径（[详见 .gitmodules 文件](.gitmodules)），所以它们会指向 GitHub。
35如果 ESP-IDF 被分叉到的仓库不在 GitHub 上，那么你需要在克隆结束后运行该脚本 [tools/set-submodules-to-github.sh](tools/set-submodules-to-github.sh)。
36
37这个脚本会为所有的子模块设置绝对路径，接着可以通过 `git submodule update --init --recursive` 完成子模块的更新。
38如果 ESP-IDF 是从 GitHub 上克隆得到，则不需要此步骤。
39
40## 寻找项目
41
42除了入门指南中提到的 [esp-idf 模板项目](https://github.com/espressif/esp-idf-template)，ESP-IDF 的 [examples](examples) 目录下还带有很多其它示例项目。
43
44一旦找到了需要的项目，便可以进入该目录，执行配置和构建操作。
45
46如果要基于示例工程开始你自己的项目，请将示例工程复制到 ESP-IDF 目录之外。
47
48# 快速参考
49
50详细的使用方法请参考上面入门指南的链接，这里仅仅列举一些 ESP-IDF 项目开发中常用的命令：
51
52## 设置构建环境
53
54请参考入门指南中列出的详细步骤。
55
56* 在主机中安装入门指南中提到的构建所依赖的工具。
57* 运行安装脚本来设置构建环境。可为 Windows shell 选择 `install.bat` 或 `install.ps1`，为 Unix shell 选择 `install.sh` 和 `install.fish`。
58* 在使用 ESP-IDF 之前，需要在 shell 中运行导出脚本。Windows 下可运行 `export.bat`，Unix 下可运行 `source export.sh`。
59
60## 配置项目
61
62* `idf.py set-target <chip_name>` 可将项目的目标芯片设置为 `<chip_name>`。运行 `idf.py set-target`，不用带任何参数，可查看所有支持的目标芯片列表。
63* `idf.py menuconfig` 可打开一个基于文本的配置菜单，可以用来对项目进行配置。
64
65## 编译项目
66
67`idf.py build`
68
69编译应用程序，引导程序，并根据配置生成分区表。
70
71## 烧写项目
72
73当构建结束，终端会打印出一条命令行，告知如何使用 esptool.py 工具烧写项目到芯片中。但你也可以运行下面这条命令来自动烧写：
74
75`idf.py -p PORT flash`
76
77将其中的 PORT 替换为系统中实际串口的名字（比如 Windows 下的 `COM3`，Linux 下的 `/dev/ttyUSB0`，或者 macOS 下的 `/dev/cu.usbserial-X`。如果省略 `-p` 选项，`idf.py flash` 会尝试使用第一个可用的串口进行烧写。
78
79这会烧写整个项目（包括应用程序，引导程序和分区表）到芯片中，此外还可以使用 `idf.py menuconfig` 来调整串口烧写相关的配置。
80
81不必先运行 `idf.py build` 再运行 `idf.py flash`，`idf.py flash` 会根据需要自动重新构建项目。
82
83## 观察串口输入
84
85`idf.py monitor` 会调用 [idf_monitor 工具](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html)来显示乐鑫芯片的串口输出。`idf_monitor` 还包含一系列的功能来解析程序崩溃后的输出结果并与设备进行交互。更多详细内容，请参阅[文档](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html).
86
87输入 `Ctrl-]` 可退出监视器。
88
89想要一次性执行构建、烧写和监视，可以运行如下命令：
90
91`idf.py flash monitor`
92
93## 仅编译并烧写应用程序
94
95在第一次烧写过后，你可能只想构建并烧写你的应用程序，不包括引导程序和分区表：
96
97* `idf.py app` - 仅构建应用程序。
98* `idf.py app-flash` - 仅烧写应用程序。
99
100`idf.py app-flash` 会自动判断是否有源文件发生了改变然后重新构建应用程序。
101
102（在正常的开发中，即使引导程序和分区表没有发生变化，每次都重新烧写它们并不会带来什么危害。）
103
104## 擦除 Flash
105
106`idf.py flash` 并不会擦除 flash 上所有的内容，但是有时候我们需要设备恢复到完全擦除的状态，尤其是分区表发生了变化或者 OTA 应用升级时。要擦除整块 flash 请运行 `idf.py erase-flash`。
107
108这条命令还可以和其余命令整合在一起，`idf.py -p PORT erase-flash flash` 会擦除一切然后重新烧写新的应用程序、引导程序和分区表。
109
110# 其它参考资源
111
112* 最新版的文档：https://docs.espressif.com/projects/esp-idf/ ，该文档是由本仓库 [docs 目录](docs) 构建得到。
113
114* 可以前往 [esp32.com 论坛](https://esp32.com/) 提问，挖掘社区资源。
115
116* 如果你在使用中发现了错误或者需要新的功能，请先[查看 GitHub Issues](https://github.com/espressif/esp-idf/issues)，确保该问题没有重复提交。
117
118* 如果你有兴趣为 ESP-IDF 作贡献，请先阅读[贡献指南](https://docs.espressif.com/projects/esp-idf/en/latest/contribute/index.html)。
119