Skip to content

Commit 78ed80f

Browse files
leeeboleeebo
committed
docs(readme): update readme and getting started
1 parent 44e1e0a commit 78ed80f

File tree

4 files changed

+267
-202
lines changed

4 files changed

+267
-202
lines changed

‎README_CN.md‎

Lines changed: 20 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ ESP-IoT-Solution 包含物联网系统开发中常用的外设驱动和代码框
1212

1313
ESP-IoT-Solution 包含的内容如下:
1414

15-
* 传感器、显示屏、音频设备、输入设备、执行机构等设备驱动；
15+
* 传感器、显示屏、音频设备、输入设备、电机控制等设备驱动；
1616
* 低功耗、安全加密、存储方案等代码框架或说明文档；
1717
* 从实际应用的角度出发，为乐鑫开源解决方案提供了入口指引。
1818

@@ -21,35 +21,38 @@ ESP-IoT-Solution 包含的内容如下:
2121
- 中文：https://docs.espressif.com/projects/esp-iot-solution/zh_CN
2222
- English: https://docs.espressif.com/projects/esp-iot-solution/en
2323

24-
## 快速参考
25-
26-
### 硬件准备
27-
28-
您可以选择任意 ESP 系列开发板使用 ESP-IoT-Solution，或者选择[板级支持组件](./examples/common_components/boards)中支持的开发板快速开始。
29-
30-
ESP 系列 SoC 采用 40nm 工艺制成，具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性，适用于各种应用场景和不同功耗需求。
24+
## 版本说明
3125

32-
### 环境搭建
26+
自 `release/v2.0` 起，ESP-IoT-Solution 采用组件化管理，各组件与示例独立迭代，不再绑定仓库分支。具体依赖的 ESP-IDF 版本请查阅组件 `idf_component.yml` 文件中的声明。Release 分支仅用于维护组件的历史大版本，例如 `button` `v3.x` 版本在 `release/v2.0` 分支中维护，`master` 分支中维护最新的 `button` 版本（例如 `v4.x`）。
3327

34-
#### 搭建 ESP-IDF 开发环境
35-
36-
由于 ESP-IoT-Solution 依赖 ESP-IDF 的基础功能和编译工具，因此首先需要参考 [ESP-IDF 详细安装步骤](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/index.html#get-started-step-by-step) 完成 ESP-IDF 开发环境的搭建。
37-
38-
请注意，不同 ESP-IoT-Solution 版本 依赖的 ESP-IDF 版本可能不同，请参考下表进行选择。
3928

4029
| ESP-IoT-Solution | 依赖的 ESP-IDF | 主要变更 | 文档 | 支持状态 |
4130
| :--------------: | :--------------: | :----------------------------------------: | :----------------------------------------------------------------------------------------------------------: | ---------------------------- |
4231
| master | >= v5.3 | 新芯片支持 | [Docs online](https://docs.espressif.com/projects/esp-iot-solution/zh_CN) | 新功能开发分支 |
43-
| release/v2.0 | <= v5.3, >= v4.4 | 支持组件管理器 | [Docs online](https://docs.espressif.com/projects/esp-iot-solution/zh_CN/release-v2.0/index.html) | 仅限 Bugfix，维护到 v5.3 EOL |
32+
| release/v2.0 | <= v5.3, >= v4.4 | 支持组件管理器 | [Docs online](https://docs.espressif.com/projects/esp-iot-solution/zh_CN/release-v2.0/index.html) | 仅限组件历史版本 Bugfix，维护到 v5.3 EOL |
4433
| release/v1.1 | v4.0.1 | IDF 版本更新，删除已经移动到其它仓库的代码 | [v1.1 Overview](https://github.com/espressif/esp-iot-solution/tree/release/v1.1#esp32-iot-solution-overview) | 备份，停止维护 |
4534
| release/v1.0 | v3.2.2 | 历史版本 | [v1.0 Overview](https://github.com/espressif/esp-iot-solution/tree/release/v1.0#esp32-iot-solution-overview) | 备份，停止维护 |
4635

47-
> `release/v2.0` `master` 分支使用 `ESP 组件管理器` 来管理组件，因此每个组件都是一个单独的软件包，每个包可能支持不同版本的 ESP-idf，这些版本将在组件的 `idf_component.yml` 文件中声明。
36+
## 快速参考
37+
38+
### 硬件准备
39+
40+
您可以选择任意 ESP 系列开发板使用 ESP-IoT-Solution，或者选择[esp-bsp](https://github.com/espressif/esp-bsp)中支持的开发板快速开始。
41+
42+
ESP 系列 SoC 采用先进工艺制程，提供业界领先的射频性能、低功耗特性和稳定可靠性，适用于物联网、工业控制、智能家居、可穿戴设备等多种应用场景。各系列芯片的具体规格和功能请参考 [ESP 产品选型工具](https://products.espressif.com/)。
43+
44+
### 组件使用或二次开发
45+
46+
请参考 [ESP-IDF 详细安装步骤](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/index.html#get-started-step-by-step) 先完成 ESP-IDF 开发环境的搭建。
4847

4948
#### 从 ESP 组件注册表获取组件
5049

5150
如果您只想使用 ESP-IoT-Solution 中的组件，我们建议您从 ESP 组件注册表 [ESP Component Registry](https://components.espressif.com/) 中使用它。
5251

52+
可以在项目根目录下使用 `idf.py add-dependency` 命令直接将组件从 Component Registry 添加到项目中。例如，执行 `idf.py add-dependency "espressif/button"` 命令添加 `button`，该组件将在 `CMake` 步骤中自动下载。
53+
54+
> 请参考 [IDF Component Manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html) 查看更多关于组件管理器的细节.
55+
5356
ESP-IoT-Solution 中注册的组件如下:
5457

5558
<center>
@@ -153,10 +156,6 @@ ESP-IoT-Solution 中注册的组件如下:
153156

154157
</center>
155158

156-
可以在项目根目录下使用 `idf.py add-dependency` 命令直接将组件从 Component Registry 添加到项目中。例如，执行 `idf.py add-dependency "espressif/usb_stream"` 命令添加 `usb_stream`，该组件将在 `CMake` 步骤中自动下载。
157-
158-
> 请参考 [IDF Component Manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html) 查看更多关于组件管理器的细节.
159-
160159
#### 从 ESP-IoT-Solution 仓库获取组件
161160

162161
如果您想为 `ESP-IoT-Solution` 中的组件或示例[贡献代码](https://docs.espressif.com/projects/esp-iot-solution/zh_CN/latest/contribute/index.html)，或者想基于 `ESP-IoT-Solution` 中的示例开发项目，您可以通过以下步骤下载 ESP-IoT-Solution 代码仓库:
@@ -173,7 +172,7 @@ ESP-IoT-Solution 中注册的组件如下:
173172
git clone -b release/v2.0 --recursive https://github.com/espressif/esp-iot-solution
174173
```
175174
176-
#### 编译和下载示例
175+
### 构建和烧录示例
177176
178177
**我们强烈建议**您 [构建您的第一个项目](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#build-your-first-project) 以熟悉 ESP-IDF 并确保环境已经设置正确。
179178

‎docs/zh_CN/gettingstarted.rst‎

Lines changed: 82 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -1,186 +1,143 @@
1+
12
快速入门
23
=================
34

45
:link_to_translation:`en:[English]`
56

6-
本文档旨在指导用户搭建 ESP-IoT-Solution (Espressif IoT Solution) 开发环境，通过一个简单的示例展示如何使用 ESP-IoT-Solution 搭建环境、创建工程、编译和下载固件至 ESP 系列开发板等步骤。
7-
8-
ESP-IoT-Solution 简介
9-
~~~~~~~~~~~~~~~~~~~~~~~~~~~
10-
11-
ESP-IoT-Solution 包含物联网系统开发中常用的外设驱动和代码框架，可提供 ESP-IDF 的补充组件，方便用户实现更简单的开发，其中包含的内容如下：
7+
本文档简要介绍如何获取和使用 ESP-IoT-Solution 内的组件，如何编译和运行示例，帮助初学者快速上手。
128

13-
- 传感器、显示屏、音频设备、输入设备、执行机构等设备驱动；
14-
- 低功耗、安全加密、存储方案等代码框架或说明文档；
15-
- 从实际应用的角度出发，为乐鑫开源解决方案提供了入口指引。
9+
ESP-IoT-Solution 版本说明
10+
--------------------------
1611

17-
ESP-IoT-Solution 版本
18-
**************************
12+
ESP-IoT-Solution 自 ``release/v2.0`` 起采用组件化管理，各组件与示例独立迭代，依赖的 ESP-IDF 版本请查阅组件 ``idf_component.yml`` 文件。release 分支仅维护历史大版本，master 分支持续集成新特性。建议新项目通过组件注册表获取所需组件。
1913

20-
不同版本的 ESP-IoT-Solution 说明如下：
14+
不同版本说明如下，详情及组件列表请见 `README_CN.md <https://github.com/espressif/esp-iot-solution/blob/master/README_CN.md>`_：
2115

22-
+-----------------------+---------------------+--------------------------------------------+----------------+
23-
| ESP-IoT-Solution 版本 | 对应的 ESP-IDF 版本 | 主要变更 | 支持状态 |
24-
+=======================+=====================+============================================+================+
25-
| master | >=v4.4 | 支持组件管理器，增加支持新的芯片支持 | 新功能开发分支 |
26-
+-----------------------+---------------------+--------------------------------------------+----------------+
27-
| release/v1.1 | v4.0.1 | IDF 版本更新，删除已经移动到其它仓库的代码 | 停止维护 |
28-
+-----------------------+---------------------+--------------------------------------------+----------------+
29-
| release/v1.0 | v3.2.2 | 历史版本 | 停止维护 |
30-
+-----------------------+---------------------+--------------------------------------------+----------------+
16+
+------------------+------------------+------------------------+----------------+
17+
| ESP-IoT-Solution | 依赖的 ESP-IDF | 主要变更 | 支持状态 |
18+
+==================+==================+========================+================+
19+
| master | >= v5.3 | 新芯片支持 | 新功能开发分支 |
20+
+------------------+------------------+------------------------+----------------+
21+
| release/v2.0 | <= v5.3, >= v4.4 | 支持组件管理器 | 历史版本维护 |
22+
+------------------+------------------+------------------------+----------------+
23+
| release/v1.1 | v4.0.1 | IDF 版本更新，代码迁移 | 备份，停止维护 |
24+
+------------------+------------------+------------------------+----------------+
25+
| release/v1.0 | v3.2.2 | 历史版本 | 备份，停止维护 |
26+
+------------------+------------------+------------------------+----------------+
3127

32-
``master`` 分支使用 ``ESP 组件管理器`` 来管理组件，因此每个组件都是一个单独的软件包，每个包可能支持不同版本的 ESP-idf，这些版本将在组件的 ``idf_component.yml`` 文件中声明。
3328

34-
ESP-IDF 简介
35-
~~~~~~~~~~~~~~~~~~~~~~~
29+
开发环境搭建
30+
--------------------------
3631

3732
ESP-IDF 是乐鑫为 ESP 系列芯片提供的物联网开发框架：
3833

39-
- ESP-IDF 包含一系列库及头文件，提供了基于 ESP SoC 构建软件项目所需的核心组件;
34+
- ESP-IDF 包含一系列库及头文件，提供了基于 ESP SoC 构建软件项目所需的核心组件；
4035
- ESP-IDF 还提供了开发和量产过程中最常用的工具及功能，例如：构建、烧录、调试和测量等。
4136

42-
.. Note::
37+
.. note::
4338

44-
详情请查阅：`ESP-IDF 编程指南 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/index.html>`__。
39+
请参考：`ESP-IDF 编程指南 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/index.html>`__ 完成 ESP-IDF 开发环境的搭建。
4540

41+
硬件准备
42+
--------------------------
4643

47-
ESP 系列 SoC 简介
48-
~~~~~~~~~~~~~~~~~~~~~~~~~
49-
50-
您可以选择任意 ESP 系列开发板使用 ESP-IoT-Solution，或者选择 `板级支持组件 <./basic/boards.html>`_ 中支持的开发板快速开始。
44+
您可以选择任意 ESP 系列开发板，或参考 `esp-bsp <https://github.com/espressif/esp-bsp>`__ 中支持的开发板快速开始。各系列芯片规格请见 `ESP 产品选型工具 <https://products.espressif.com/>`__。
5145

5246
ESP 系列 SoC 支持以下功能：
5347

54-
- 2.4 GHz Wi-Fi
55-
- 蓝牙
56-
- 高性能单核、双核处理器，运行频率可达 240 MHz
57-
- 超低功耗协处理器
58-
- 多种外设，包括 GPIO、I2C、I2S、SPI、UART、SDIO、RMT、LEDC PWM、Ethernet、TWAI、Touch、USB OTG 等
59-
- 丰富的内存资源，内部 RAM 可达 520 KB，同时支持扩展 PSRAM
60-
- 支持硬件加密等安全功能
61-
62-
ESP 系列 SoC 采用 40nm 工艺制成，具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性，适用于各种应用场景和不同功耗需求。
63-
64-
.. Note::
65-
66-
不同系列 SoC 配置不同，详情请查阅 `ESP 产品选型工具 <http://products.espressif.com:8000/#/product-selector>`_。
67-
68-
配置开发环境
69-
~~~~~~~~~~~~~~~~
70-
71-
1. 安装 ESP-IDF
72-
*******************
73-
74-
由于 ESP-IoT-Solution 依赖 ESP-IDF 的基础功能和编译工具，因此首先需要参考 `ESP-IDF 详细安装步骤 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/index.html#get-started-get-prerequisites>`_ 完成 ESP-IDF 开发环境的搭建。请注意，不同版本的 ESP-IoT-Solution 依赖的 ESP-IDF 版本可能不同，请参考 `ESP-IoT-Solution 版本`_ 进行选择。
75-
76-
2. 获取 ESP-IoT-Solution
77-
*****************************
78-
79-
若选择 ``master`` 版本，可使用以下指令获取代码：
80-
81-
.. code:: shell
82-
83-
git clone --recursive https://github.com/espressif/esp-iot-solution
84-
85-
对于 ``release/v1.1`` 版本，可使用以下指令获取代码：
86-
87-
.. code:: shell
88-
89-
git clone -b release/v1.1 --recursive https://github.com/espressif/esp-iot-solution
90-
91-
对于其它版本，请将 ``release/v1.1`` 替换成目标分支名。
92-
93-
使用 ESP-IoT-Solution 组件
94-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
95-
96-
如果您只想使用 ESP-IoT-Solution 中的组件，我们建议您从 ESP 组件注册表 `ESP Component Registry <https://components.espressif.com/>`_ 中使用它。
97-
98-
ESP-IoT-Solution 中注册的组件可在 :project_file:`README_CN.md` 中查阅，您可以在项目根目录下使用 ``idf.py add-dependency`` 命令直接将组件从 Component Registry 添加到项目中。例如，执行 ``idf.py add-dependency "espressif/usb_stream"`` 命令添加 ``usb_stream``，该组件将在 ``CMake`` 步骤中自动下载。
99-
100-
请参考 `IDF Component Manager <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html>`_ 查看更多关于组件管理器的细节.
48+
- Wi-Fi (2.4 GHz/5 GHz 双频)
49+
- 蓝牙 5.x (BLE/Mesh)
50+
- 高性能多核处理器，主频最高可达 400 MHz
51+
- 超低功耗协处理器和深度睡眠模式
52+
- 丰富的外设接口：
53+
- 通用接口：GPIO、UART、I2C、I2S、SPI、SDIO、USB OTG 等
54+
- 专用接口：LCD、摄像头、以太网、CAN、Touch、LED PWM、温度传感器等
55+
- 大容量内存：
56+
- 内部 RAM 最大可达 768 KB
57+
- 支持外部 PSRAM 扩展
58+
- 支持外部 Flash 存储
59+
- 增强的安全特性：
60+
- 硬件加密引擎
61+
- 安全启动
62+
- Flash 加密
63+
- 数字签名
10164

102-
编译和下载
103-
~~~~~~~~~~~~~~~~
65+
ESP 系列 SoC 采用先进工艺制程，提供业界领先的射频性能、低功耗特性和稳定可靠性，适用于物联网、工业控制、智能家居、可穿戴设备等多种应用场景。
10466

105-
1. 设置环境变量
106-
********************
67+
.. note::
10768

108-
以上步骤安装的代码和工具尚未添加至 PATH 环境变量，无法通过终端窗口使用这些工具。添加环境变量的步骤如下：
69+
各系列芯片的具体规格和功能请参考 `ESP 产品选型工具 <https://products.espressif.com/>`__。
10970

110-
* 添加 ESP-IDF 环境变量：
11171

112-
Windows 在 CMD 窗口运行：
72+
如何获取和使用组件
73+
--------------------------
11374

114-
.. code:: shell
75+
推荐通过 `ESP Component Registry <https://components.espressif.com/>`__ 获取 ESP-IoT-Solution 组件。
11576

116-
%userprofile%\esp\esp-idf\export.bat
77+
以 button 组件为例，添加依赖的步骤如下：
11778

118-
Linux 和 macOS 在终端运行：
79+
1. 在项目根目录下执行：
11980

120-
.. code:: shell
81+
.. code-block:: bash
12182
122-
. $HOME/esp/esp-idf/export.sh
83+
idf.py add-dependency "espressif/button"
12384
124-
请将以上指令中的路径，替换成实际安装路径。
85+
2. 在代码中引用头文件并调用 API，例如：
12586

126-
* 添加 IOT_SOLUTION_PATH 环境变量：
87+
.. code-block:: c
12788
128-
Windows 在 CMD 窗口运行：
89+
#include "iot_button.h"
90+
// 具体 API 使用请参考组件文档
12991
130-
.. code:: shell
92+
更多组件管理器的使用方法请参考 `ESP Registry Docs <https://docs.espressif.com/projects/idf-component-manager/en/latest/>`__。
13193

132-
set IOT_SOLUTION_PATH=C:\esp\esp-iot-solution
94+
如何使用示例程序
95+
--------------------------
13396

134-
Linux 和 macOS 在终端运行：
97+
ESP-IoT-Solution 提供了丰富的示例程序，帮助用户快速上手。以 ``button_power_save`` 示例为例：
13598

136-
.. code:: shell
99+
1. 确保已经完成 ESP-IDF 开发环境的搭建，并成功配置了环境变量
137100

138-
export IOT_SOLUTION_PATH=~/esp/esp-iot-solution
101+
2. 下载 ESP-IoT-Solution 代码仓库：
139102

140-
.. Note::
103+
.. code-block:: bash
141104
142-
以上方法设置的环境变量，仅对当前终端有效，如果打开新终端，请重新执行以上步骤。
105+
git clone https://github.com/espressif/esp-iot-solution.git
143106
144-
2. 设置编译目标
145-
********************
107+
3. 进入示例目录或将其复制到您的工作目录：
146108

147-
ESP-IDF 同时支持 ``esp32``、``esp32s2`` 等多款芯片，因此需要在编译代码之前设置的编译目标芯片（默认编译目标为 ``esp32``），例如设置编译目标为 ``esp32s2``：
109+
.. code-block:: bash
148110
149-
.. code:: shell
111+
cd examples/get-started/button_power_save
150112
151-
idf.py set-target esp32s2
113+
.. note::
152114

153-
对于 ESP-IoT-Solution 中基于 `板级支持组件 <./basic/boards.html>`_ 开发的 example，还可以使用 ``menuconfig`` 在 ``Board Options -> Choose Target Board`` 中选择一个目标开发板：
115+
如果您将示例复制到其他目录，由于文件路径发生变更，请删除 ``main/idf_component.yml`` 中所有 ``override_path`` 的配置。
154116

155-
.. code:: shell
117+
4. 选择目标芯片（如 ESP32，首次使用或切换芯片时需执行）：
156118

157-
idf.py menuconfig
119+
.. code-block:: bash
158120
159-
3. 编译、下载程序
160-
**********************
121+
idf.py set-target esp32
161122
162-
使用 ``idf.py`` 工具编译、下载程序，指令为：
123+
5. 配置项目（可选）：
163124

164-
.. code:: shell
125+
.. code-block:: bash
165126
166-
idf.py -p PORT build flash
127+
idf.py menuconfig
167128
168-
请将 PORT 替换为当前使用的端口号，Windows 系统串口号一般为 ``COMx``，Linux 系统串口号一般为 ``/dev/ttyUSBx``，macOS 串口号一般为 ``/dev/cu.``。
129+
6. 编译并烧录到开发板：
169130

170-
4. 串口打印 log
171-
*******************
131+
.. code-block:: bash
172132
173-
使用 ``idf.py`` 工具查看 log，指令为：
133+
idf.py build
134+
idf.py -p <PORT> flash
174135
175-
.. code:: shell
136+
7. 通过串口监视输出：
176137

177-
idf.py -p PORT monitor
138+
.. code-block:: bash
178139
179-
请将 ``PORT`` 替换为当前使用的端口号，Windows 系统串口号一般为 ``COMx``，Linux 系统串口号一般为 ``/dev/ttyUSBx``，macOS 串口号一般为 ``/dev/cu.``。
140+
idf.py -p <PORT> monitor
180141
181-
相关文档
182-
~~~~~~~~~~~~~~~~
142+
更多示例请见 ``examples/`` 目录，具体使用方法请参考各示例下的 README 文件。
183143

184-
- `ESP-IDF 详细安装步骤 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/index.html#get-started-get-prerequisites>`_
185-
- `ESP-IDF 编程指南 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/index.html>`__
186-
- `ESP 产品选型工具 <http://products.espressif.com:8000/#/product-selector>`_

0 commit comments

Comments
 (0)