diff --git a/README.md b/README.md index 55f9f453e..af05edb06 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,65 @@ # ESP-AT -[![Documentation Version](./docs/_static/at_doc_latest.svg)](https://docs.espressif.com/projects/esp-at/en/latest/) +[![alt text][doc-latest]](https://docs.espressif.com/projects/esp-at/en/latest/) -- [中文版](#esp-at-项目) +[doc-latest]: https://img.shields.io/badge/docs-latest-blue -esp-at project was started and powered by Espressif Systems (@[espressif](https://github.com/espressif/)) as an official project, for the **ESP32-C2**, **ESP32-C3**, **ESP32-C6**, **ESP32**, and **ESP8266** Series SoCs provided for Windows, Linux, and macOS. +- [中文版](./README_CN.md) + +esp-at project was started and powered by Espressif Systems (@[espressif](https://github.com/espressif/)) as an official project, for the **ESP32-C2**, **ESP32-C3**, **ESP32-C6**, **ESP32**, and **ESP32-S2** Series SoCs provided for Windows, Linux, and macOS. It is now supported and maintained by Espressif esp-at team (@[esp-at](https://github.com/espressif/esp-at)). # Introduction -Espressif Wi-Fi and Bluetooth® chipsets are often used as add-on modules to seamlessly integrate wireless connectivity features into new and existing products. -In an effort to facilitate this and cut down on engineering costs, Espressif Systems has developed a set of AT commands that can be used to interface with Espressif products. - -"AT" means 'attention'. Each command string is prefixed with "AT", and a number of discrete commands can be concatenated after the "AT". +Espressif SoC chipsets are often used as add-on modules to seamlessly integrate wireless connectivity features into new and existing products. In an effort to facilitate this and cut down on engineering costs, Espressif Systems has developed a set of [AT commands](https://docs.espressif.com/projects/esp-at/en/latest/esp32/AT_Command_Set/index.html) (Please select your target chip from the dropdown menu in the top left corner of the page) that can be used to interface with Espressif products. -The AT command firmware allows for rapid integration by providing: +The AT solution provided by Espressif allows for rapid integration by providing: -- In-built TCP/IP stack and data buffering +- In-built a large number of AT commands - Easy integration with resource-constrained host platforms - Easy-to-parse command-response protocols - Customized, user-defined AT commands -# Resources -- There are several guides for esp-at developers and users. These guides can be rendered in a number of formats, like HTML and PDF. - Documentation for the latest version: [https://docs.espressif.com/projects/esp-at/en/latest/index.html](https://docs.espressif.com/projects/esp-at/en/latest/index.html). This documentation is built from the [docs directory](https://github.com/espressif/esp-at/tree/master/docs) of this repository. - -- The Changelogs of historic released versions: https://github.com/espressif/esp-at/releases - -- [Check the Issues section on GitHub](https://github.com/espressif/esp-at/issues) if you find a bug or have a feature request. Please check existing Issues before opening a new one. - -- The [esp-at forum](https://www.esp32.com/viewforum.php?f=42) is a place to ask questions and find community resources. - -- The [ESP Product Selector](https://products.espressif.com/#/product-selector?language=en&names=) is a tool to help you compare different chips or modules. - -# ESP-AT Support Policy for ESP Chip Series - -- ESP32-C2 Series - - **Preferred recommended chip for using ESP-AT on** - - Recommended released version: [v3.3.0.0](https://github.com/espressif/esp-at/releases/tag/v3.3.0.0) +# ESP-AT Release and SoC Compatibility +The following table shows ESP-AT support status of Espressif SoCs. -- ESP32-C3 Series - - **Preferred recommended chip for using ESP-AT on** - - Recommended released version: [v3.3.0.0](https://github.com/espressif/esp-at/releases/tag/v3.3.0.0) +| Chip | v3.2.0.0 | v3.3.0.0 | v3.4.0.0 | v4.0.0.0 | master | +|:- |:-:| :-:| :-:| :-:| :-:| +| ESP32 | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.2.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.3.0.0) | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.4.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v4.0.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/master) | +|ESP32-C3 | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.2.0.0) | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.3.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.4.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v4.0.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/master) | +|ESP32-C2 | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.2.0.0) | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.3.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.4.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v4.0.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/master) | +|ESP32-C6 | | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.3.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.4.0.0) | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v4.0.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/master) | +|ESP32-S2 | | | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.4.0.0) | | [![alt text][supported]](https://github.com/espressif/esp-at/tree/master) | -- ESP32-C6 Series - - **Preferred recommended chip for using ESP-AT on** - - Recommended released version: [v4.0.0.0](https://github.com/espressif/esp-at/releases/tag/v4.0.0.0) +- ![alt text][released]: Released versions, you can click ![alt text][released] to go to the corresponding release page and download the AT firmware. +- ![alt text][supported]: Rupported versions, you can click ![alt text][supported] to go to the corresponding branch and develop your own AT firmware. +- ![alt text][pre-release]: Pre-release versions, expected to release AT firmware for the corresponding chip soon. -- ESP32 Series - - Recommended released version: [v3.2.0.0](https://github.com/espressif/esp-at/releases/tag/v3.2.0.0) +Please choose one of the following options based on your needs: +- **The default AT firmware meets your requirements**: It is recommended to use the latest released version of the firmware corresponding to the chip. +- **The default AT firmware does not meet your requirements and stability is a priority**: It is recommended to develop your AT firmware based on the latest released version of the firmware corresponding to the chip. +- **The default AT firmware does not meet your requirements and you want more new features**: It is recommended to develop your AT firmware based on the [master branch](https://github.com/espressif/esp-at/tree/master). -- ESP8266 Series - - **ESP32-C2 is recommended to use instead** - - ESP-AT will not release the major version for ESP8266. - - ESP-AT no longer adds new features to ESP8266. - - [v2.2.1.0_esp8266](https://github.com/espressif/esp-at/releases/tag/v2.2.1.0_esp8266) is the last version of ESP-AT for ESP8266, corresponding to branch [release/v2.2.0.0_esp8266](https://github.com/espressif/esp-at/tree/release/v2.2.0.0_esp8266), corresponding to documentation [https://docs.espressif.com/projects/esp-at/en/release-v2.2.0.0_esp8266](https://docs.espressif.com/projects/esp-at/en/release-v2.2.0.0_esp8266/). - - ESP-AT will regularly update [release/v2.2.0.0_esp8266](https://github.com/espressif/esp-at/tree/release/v2.2.0.0_esp8266) branch for ESP8266. Update includes vital bugfix and security repair. +[released]: https://img.shields.io/badge/-released-4CBB17 +[supported]: https://img.shields.io/badge/-supported-1F51FF +[pre-release]: https://img.shields.io/badge/-pre--release-FFC000 -- Other Series - - ESP-AT will support ESP32-C5 series of chips. - - ESP-AT will not support ESP32-S and ESP32-H series of chips. +**Other series of chips:** +- ESP-AT will support ESP32-C5 series of chips. +- ESP-AT will not support ESP32-S3 and ESP32-H series of chips. -# ESP-AT 项目 -esp-at 作为由 Espressif Systems (@[espressif](https://github.com/espressif/)) 发起和提供技术支持的官方项目，适用于 Windows、Linux、macOS 上的 **ESP32-C2**、**ESP32-C3**、**ESP32-C6**、**ESP32**、和 **ESP8266** 系列芯片。 -当前该项目由 Espressif esp-at 团队 (@[esp-at](https://github.com/espressif/esp-at)) 负责技术支持和维护。 +# Support Periods of ESP-AT -# 简介 -乐鑫 Wi-Fi 和蓝牙芯片可以用作附加模块，完美集成在其他现有产品上，提供无线通讯功能。 -为降低客户开发成本，乐鑫开发了一套 AT 指令集，方便客户简单快速地使用 AT 指令来控制芯片。 +![support periods](docs/_static/at-support-periods.png) -乐鑫提供的 AT 指令固件具有以下特色，利于芯片集成到应用中： +- Please refer to [ESP-AT Versions](https://docs.espressif.com/projects/esp-at/en/latest/esp32/versions.html) for more details。 -- 内置 TCP/IP 堆栈和数据缓冲 -- 能便捷地集成到资源受限的主机平台中 -- 主机对指令的回应易于解析 -- 用户可自定义 AT 指令 - -# 资源 -- 这里为开发者和用户提供了一些指南，这些指南可以以多种格式呈现，比如 HTML 和 PDF。 - 最新文档见：[https://docs.espressif.com/projects/esp-at/zh_CN/latest/index.html](https://docs.espressif.com/projects/esp-at/zh_CN/latest/index.html)。该文档是由本仓库 [docs 目录](https://github.com/espressif/esp-at/tree/master/docs) 自动编译构建的。 - -- 已发布版本的修改记录见：https://github.com/espressif/esp-at/releases - -- 如果你有 bug 上报或者功能需求，可以在 [GitHub Issues](https://github.com/espressif/esp-at/issues) 里提交。请在提交前检索下是否有相同的 Issue。 - -- [esp-at 社区](https://www.esp32.com/viewforum.php?f=34) 可以用来询问问题或寻找一些社区资源。 - -- [产品选型工具](https://products.espressif.com/#/product-selector?language=zh&names=) 可以帮助你对比不同的芯片或模组。 - -# ESP-AT 对不同芯片系列支持策略 - -- ESP32-C2 系列 - - **ESP-AT 首选推荐芯片** - - 推荐使用的发布版本：[v3.3.0.0](https://github.com/espressif/esp-at/releases/tag/v3.3.0.0) - -- ESP32-C3 系列 - - **ESP-AT 首选推荐芯片** - - 推荐使用的发布版本：[v3.3.0.0](https://github.com/espressif/esp-at/releases/tag/v3.3.0.0) +# Resources +- There are several guides for esp-at developers and users. These guides can be rendered in a number of formats, like HTML and PDF. + Documentation for the latest version: [https://docs.espressif.com/projects/esp-at/en/latest/index.html](https://docs.espressif.com/projects/esp-at/en/latest/index.html). This documentation is built from the [docs directory](https://github.com/espressif/esp-at/tree/master/docs) of this repository. -- ESP32-C6 系列 - - **ESP-AT 首选推荐芯片** - - 推荐使用的发布版本：[v4.0.0.0](https://github.com/espressif/esp-at/releases/tag/v4.0.0.0) +- The Changelogs of historic released versions: https://github.com/espressif/esp-at/releases -- ESP32 系列 - - 推荐使用的发布版本：[v3.2.0.0](https://github.com/espressif/esp-at/releases/tag/v3.2.0.0) +- [Check the Issues section on GitHub](https://github.com/espressif/esp-at/issues) if you find a bug or have a feature request. Please check existing Issues before opening a new one. -- ESP8266 系列 - - **推荐使用 ESP32-C2 芯片** - - ESP-AT 不再为 ESP8266 添加新功能 - - ESP-AT 不再为 ESP8266 发布大版本 - - [v2.2.1.0_esp8266](https://github.com/espressif/esp-at/releases/tag/v2.2.1.0_esp8266) 是 ESP-AT 为 ESP8266 发布的最后一个版本，对应分支为 [release/v2.2.0.0_esp8266](https://github.com/espressif/esp-at/tree/release/v2.2.0.0_esp8266)，对应文档为 [https://docs.espressif.com/projects/esp-at/zh_CN/release-v2.2.0.0_esp8266](https://docs.espressif.com/projects/esp-at/zh_CN/release-v2.2.0.0_esp8266/) - - ESP-AT 将定期在 [release/v2.2.0.0_esp8266](https://github.com/espressif/esp-at/tree/release/v2.2.0.0_esp8266) 分支为 ESP8266 进行重要 bug 修复，安全修补等更新 +- The [esp-at forum](https://www.esp32.com/viewforum.php?f=42) is a place to ask questions and find community resources. -- 其它系列 - - ESP-AT 将计划支持 ESP32-C5 系列芯片 - - ESP-AT 无计划支持 ESP32-S、ESP32-H 系列芯片 +- The [ESP Product Selector](https://products.espressif.com/#/product-selector?language=en&names=) is a tool to help you compare different chips or modules. diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 000000000..c3c1a6010 --- /dev/null +++ b/README_CN.md @@ -0,0 +1,65 @@ +# ESP-AT +[![alt text][doc-latest]](https://docs.espressif.com/projects/esp-at/en/latest/) + +[doc-latest]: https://img.shields.io/badge/docs-latest-blue + +- [English Version](./README.md) + +esp-at 作为由 Espressif Systems (@[espressif](https://github.com/espressif/)) 发起和提供技术支持的官方项目，适用于 Windows、Linux、macOS 上的 **ESP32-C2**、**ESP32-C3**、**ESP32-C6**、**ESP32**、和 **ESP32-S2** 系列芯片。 +当前该项目由 Espressif esp-at 团队 (@[esp-at](https://github.com/espressif/esp-at)) 负责技术支持和维护。 + +# 简介 +乐鑫 SoC 芯片可以用作附加模块，完美集成在其他现有产品上，提供丰富的无线功能。为降低客户开发成本，乐鑫开发了一套 [AT 命令集](https://docs.espressif.com/projects/esp-at/zh_CN/latest/esp32/AT_Command_Set/index.html)（请在页面左上方的下拉菜单中选择您的目标芯片），方便客户简单快速地使用 AT 命令来控制芯片。 + +乐鑫提供的 AT 方案具有以下特色，利于芯片集成到应用中： + +- 内置丰富的 AT 命令集 +- 能便捷地集成到资源受限的主机平台中 +- 主机对命令的回应易于解析 +- 用户可自定义 AT 命令 + +# ESP-AT 与乐鑫芯片 +下表总结了乐鑫芯片在 ESP-AT 主要版本中的支持状态。 + +| 芯片 | v3.2.0.0 | v3.3.0.0 | v3.4.0.0 | v4.0.0.0 | master | +|:- |:-:| :-:| :-:| :-:| :-:| +| ESP32 | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.2.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.3.0.0) | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.4.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v4.0.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/master) | +|ESP32-C3 | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.2.0.0) | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.3.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.4.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v4.0.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/master) | +|ESP32-C2 | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.2.0.0) | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.3.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.4.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v4.0.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/master) | +|ESP32-C6 | | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.3.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/release/v3.4.0.0) | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v4.0.0.0) | [![alt text][supported]](https://github.com/espressif/esp-at/tree/master) | +|ESP32-S2 | | | [![alt text][released]](https://github.com/espressif/esp-at/releases/tag/v3.4.0.0) | | [![alt text][supported]](https://github.com/espressif/esp-at/tree/master) | + +- ![alt text][released]：已发布的版本，您可以点击 ![alt text][released] 前往对应的发布页下载 AT 固件。 +- ![alt text][supported]：已支持的版本，您可以点击 ![alt text][supported] 前往对应的分支开发您自己的 AT 固件。 +- ![alt text][pre-release]：在测试的版本，预计近期发布对应芯片的 AT 固件。 + +请根据您的需求，从以下选项中任选其一： +- **默认 AT 固件已满足您的需求**：推荐选用该芯片最新已发布的版本对应的 AT 固件。 +- **默认 AT 固件不满足您的需求且希望稳定性优先**：推荐基于该芯片最新已发布的版本对应的分支开发您的 AT 固件。 +- **默认 AT 固件不满足您的需求且希望更多新功能**：推荐基于 [master 分支](https://github.com/espressif/esp-at/tree/master) 开发您的 AT 固件。 + +[released]: https://img.shields.io/badge/-已发布-4CBB17 +[supported]: https://img.shields.io/badge/-已支持-1F51FF +[pre-release]: https://img.shields.io/badge/-待发布-FFC000 + +**其它系列芯片：** +- ESP-AT 将计划支持 ESP32-C5 芯片。 +- ESP-AT 无计划支持 ESP32-S3、ESP32-H 系列芯片。 + +# ESP-AT 版本支持期限 + +![support periods](docs/_static/at-support-periods.png) + +- 请参考 [ESP-AT 版本简介](https://docs.espressif.com/projects/esp-at/zh_CN/latest/esp32/versions.html) 了解更多关于 ESP-AT 版本的信息。 + +# 资源 +- 这里为开发者和用户提供了一些指南，这些指南可以以多种格式呈现，比如 HTML 和 PDF。 + 最新文档见：[https://docs.espressif.com/projects/esp-at/zh_CN/latest/index.html](https://docs.espressif.com/projects/esp-at/zh_CN/latest/index.html)。该文档是由本仓库 [docs 目录](https://github.com/espressif/esp-at/tree/master/docs) 自动编译构建的。 + +- 已发布版本的修改记录见：https://github.com/espressif/esp-at/releases + +- 如果你有 bug 上报或者功能需求，可以在 [GitHub Issues](https://github.com/espressif/esp-at/issues) 里提交。请在提交前检索下是否有相同的 Issue。 + +- [esp-at 社区](https://www.esp32.com/viewforum.php?f=34) 可以用来询问问题或寻找一些社区资源。 + +- [产品选型工具](https://products.espressif.com/#/product-selector?language=zh&names=) 可以帮助你对比不同的芯片或模组。 diff --git a/docs/_static/at-sub-release-apply.png b/docs/_static/at-sub-release-apply.png new file mode 100644 index 000000000..9b44b10b9 Binary files /dev/null and b/docs/_static/at-sub-release-apply.png differ diff --git a/docs/_static/at-sub-release-custom.png b/docs/_static/at-sub-release-custom.png new file mode 100644 index 000000000..62648ab5b Binary files /dev/null and b/docs/_static/at-sub-release-custom.png differ diff --git a/docs/_static/at-support-periods.png b/docs/_static/at-support-periods.png new file mode 100644 index 000000000..a07fa3677 Binary files /dev/null and b/docs/_static/at-support-periods.png differ diff --git a/docs/_static/at_doc_latest.svg b/docs/_static/at_doc_latest.svg deleted file mode 100644 index 56e560956..000000000 --- a/docs/_static/at_doc_latest.svg +++ /dev/null @@ -1,2 +0,0 @@ -docs: latestdocslatest - diff --git a/docs/_static/js/at_versions.js b/docs/_static/js/at_versions.js index 514ed3f4c..0d5b0bbc9 100644 --- a/docs/_static/js/at_versions.js +++ b/docs/_static/js/at_versions.js @@ -9,6 +9,9 @@ var DOCUMENTATION_VERSIONS = { // v4.0.0.0 { name: "release-v4.0.0.0", has_targets: true, supported_targets: [ "esp32", "esp32c2", "esp32c3", "esp32c6" ] }, + // v3.4.0.0 + { name: "release-v3.4.0.0", has_targets: true, supported_targets: [ "esp32", "esp32c2", "esp32c3", "esp32c6", "esp32s2" ] }, + // v3.3.0.0 { name: "release-v3.3.0.0", has_targets: true, supported_targets: [ "esp32", "esp32c2", "esp32c3", "esp32c6" ] }, diff --git a/docs/en/AT_Binary_Lists/esp_at_binaries.rst b/docs/en/AT_Binary_Lists/esp_at_binaries.rst index 8de199ae3..e86be2f48 100644 --- a/docs/en/AT_Binary_Lists/esp_at_binaries.rst +++ b/docs/en/AT_Binary_Lists/esp_at_binaries.rst @@ -25,7 +25,8 @@ It is recommended to use the lastest version of firmware. Currently, Espressif r ESP32-WROOM-32 Series ^^^^^^^^^^^^^^^^^^^^^^ - - v3.2.0.0 `ESP32-WROOM-32-AT-V3.2.0.0.zip `__ (Recommended) + - v3.4.0.0 `ESP32-WROOM-32-AT-V3.4.0.0.zip `__ (Recommended) + - v3.2.0.0 `ESP32-WROOM-32-AT-V3.2.0.0.zip `__ - v2.4.0.0 `ESP32-WROOM-32-AT-V2.4.0.0.zip `__ - v2.2.0.0 `ESP32-WROOM-32-AT-V2.2.0.0.zip `__ - v2.1.0.0 `ESP32-WROOM-32-AT-V2.1.0.0.zip `__ @@ -39,7 +40,8 @@ It is recommended to use the lastest version of firmware. Currently, Espressif r ESP32-MINI-1 Series ^^^^^^^^^^^^^^^^^^^ - - v3.2.0.0 `ESP32-MINI-1-AT-V3.2.0.0.zip `__ (Recommended) + - v3.4.0.0 `ESP32-MINI-1-AT-V3.4.0.0.zip `__ (Recommended) + - v3.2.0.0 `ESP32-MINI-1-AT-V3.2.0.0.zip `__ - v2.4.0.0 `ESP32-MINI-1-AT-V2.4.0.0.zip `__ - v2.2.0.0 `ESP32-MINI-1-AT-V2.2.0.0.zip `__ @@ -58,8 +60,9 @@ It is recommended to use the lastest version of firmware. Currently, Espressif r ESP32-PICO Series ^^^^^^^^^^^^^^^^^ - - - v3.2.0.0 `ESP32-PICO-D4-AT-V3.2.0.0.zip `__ (Recommended) + + - v3.4.0.0 `ESP32-PICO-D4-AT-V3.4.0.0.zip `__ (Recommended) + - v3.2.0.0 `ESP32-PICO-D4-AT-V3.2.0.0.zip `__ - v2.4.0.0 `ESP32-PICO-D4-AT-V2.4.0.0.zip `__ - v2.2.0.0 `ESP32-PICO-D4-AT-V2.2.0.0.zip `__ - v2.1.0.0 `ESP32-PICO-D4-AT-V2.1.0.0.zip `__ @@ -68,7 +71,8 @@ It is recommended to use the lastest version of firmware. Currently, Espressif r ESP32-SOLO Series ^^^^^^^^^^^^^^^^^ - - v3.2.0.0 `ESP32-SOLO-AT-V3.2.0.0.zip `__ (Recommended) + - v3.4.0.0 `ESP32-SOLO-AT-V3.4.0.0.zip `__ (Recommended) + - v3.2.0.0 `ESP32-SOLO-AT-V3.2.0.0.zip `__ - v2.4.0.0 `ESP32-SOLO-AT-V2.4.0.0.zip `__ - v2.2.0.0 `ESP32-SOLO-AT-V2.2.0.0.zip `__ - v2.1.0.0 `ESP32-SOLO-AT-V2.1.0.0.zip `__ @@ -115,4 +119,9 @@ It is recommended to use the lastest version of firmware. Currently, Espressif r ESP32-S2-MINI Series ^^^^^^^^^^^^^^^^^^^^ - - The first version of ESP-AT firmware (v3.4.0.0) is planned to be released in July 2024. + - v3.4.0.0 `ESP32-S2-MINI-AT-V3.4.0.0.zip `__ (Recommended) + +Subscribe to AT Releases +^^^^^^^^^^^^^^^^^^^^^^^^ + +Please refer to the :ref:`sub-at-release` documentation to subscribe to our version release notifications and stay updated on the latest releases. diff --git a/docs/en/AT_Binary_Lists/index.rst b/docs/en/AT_Binary_Lists/index.rst index 647c55922..59619369a 100644 --- a/docs/en/AT_Binary_Lists/index.rst +++ b/docs/en/AT_Binary_Lists/index.rst @@ -15,8 +15,6 @@ This document covers the following sections: - :doc:`Download {IDF_TARGET_NAME} AT Released Firmware ` - :ref:`brief-intro-firmware`: What binary files the AT firmware contains and their functions - - :ref:`firmware-selection`: Types of AT firmware, ways to access them, their application scenarios, pros, cons, etc. - - :ref:`what-next-after-you-get-firmware` .. note:: To download AT firmware for other chip series, please go to the drop-down list on the upper left corner of this page and select a chip series to navigate to the documentation of that chip for downloading. @@ -42,90 +40,3 @@ The ESP-AT firmware package contains several binary files for specific functiona ├── partition_table │ └── partition-table.bin // Primary partition table (system partition table) └── ota_data_initial.bin // OTA data initialization file - -.. _firmware-selection: - -Which Type of Firmware Shall I Choose? --------------------------------------- - -ESP-AT firmware has the following types. Among them, the workload of downloading or preparing firmware increases from top to bottom, and so does the number of supported module types. - -.. contents:: - :local: - :depth: 1 - -.. _official-released-firmware: - -Officially Released Firmware (Recommended) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Officially released firmware**, also known as "released firmware", "official firmware" or "default firmware", is tested and periodically released by Espressif's official team according to the internal development plan. It can be upgraded directly based on the Espressif OTA server. If it fully matches your project needs, it is recommended to choose it over the other types of firmware. If it does not support your module, you can select a firmware that has a similar hardware configuration to your module according to :doc:`Hardware Differences <../Compile_and_Develop/esp-at_firmware_differences>` for testing and verification. - -.. list:: - - - How to obtain firmware: :doc:`{IDF_TARGET_NAME} AT firmware ` - - Pros: - - - Stable - - Reliable - - Small workload of obtaining firmware - - - Cons: - - - Long update cycle - - A limited number of supported modules - - - Reference documentation: - - - :doc:`Hardware connection <../Get_Started/Hardware_connection>` - - :doc:`Firmware Downloading and Flash <../Get_Started/Downloading_guide>` - - For which chip series are supported and unsupported by ESP-AT firmware, please refer to ESP-AT GitHub home page `readme.md `_ - -.. _github-temporary-firmware: - -GitHub Temporary Firmware -^^^^^^^^^^^^^^^^^^^^^^^^^ - -**GitHub temporary firmware** is compiled by GitHub whenever code is pushed to GitHub and yet does not reach the firmware release cycle. In other words, it is the firmware in development, including the temporary versions of **officially released firmware** and supported firmware that is not planned for release. The former can be upgraded directly based on the Espressif OTA server. - -- How to obtain firmware: Please refer to :doc:`../Compile_and_Develop/How_to_download_the_latest_temporary_version_of_AT_from_github`. -- Pros: - - - Real-time integration of new features and bug fixes. - - Covering some unofficially released firmware, such as firmware based on SDIO communication and firmware based on SPI communication. - - Small workload of obtaining firmware. - -- Cons: As the firmware compiled based on commits that are not for official release has not been thoroughly tested, there may be some risks. You need to do a complete test by yourself. - -.. _firmware-modify-paras-not-source-code: - -Firmware with Updated Parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The **firmware with updated parameters** is generated by updating the parameter area and you do not need to compile the firmware. It is suitable for the case where the firmware function meets the project requirements, but only some parameters do not, such as the factory baud rate and UART IO pins. This type of firmware can be directly upgraded based on the Espressif OTA server. - -- For how to modify those parameters, please refer to :doc:`../Compile_and_Develop/tools_at_py`. -- Pros: - - - No need to recompile the firmware. - - The firmware is stable and reliable. - -- Cons: Requiring modification to released firmware, long update cycle, and a limited number of supported modules. - -.. _self-compiled-firmware: - -Self-Compiled Firmware -^^^^^^^^^^^^^^^^^^^^^^ - -When you need to conduct secondary development, you can compile the firmware by yourself. To support the OTA function, you need to deploy your own OTA server. - -- For how to compile the firmware by yourself, please refer to :doc:`../Compile_and_Develop/How_to_clone_project_and_compile_it`. -- Pros: You can control functions and cycles. -- Cons: You need to set up the compilation environment. - -.. _what-next-after-you-get-firmware: - -After Getting Firmware, What Next? ----------------------------------- - -After you get the firmware, please refer to :doc:`Hardware Connection <../Get_Started/Hardware_connection>` and :doc:`Firmware Downloading and Flashing Guide <../Get_Started/Downloading_guide>` to connect the PC and ESP device and flash the firmware to the device. diff --git a/docs/en/Compile_and_Develop/tools_at_py.rst b/docs/en/Compile_and_Develop/tools_at_py.rst index cb0d50317..dd0b90bfb 100644 --- a/docs/en/Compile_and_Develop/tools_at_py.rst +++ b/docs/en/Compile_and_Develop/tools_at_py.rst @@ -87,13 +87,13 @@ The currently modifiable Wi-Fi parameter configurations are shown in the followi - See `{IDF_TARGET_NAME} Maximum transmission power `_ for more details. * - \--country_code - Wi-Fi country code - - See the ``cc`` field of `Wi-Fi Country Code `_ + - See the ``cc`` field of `Wi-Fi Country Code `_ * - \--start_channel - Wi-Fi starting channel - - See the ``schan`` field of `Wi-Fi Country Code `_ + - See the ``schan`` field of `Wi-Fi Country Code `_ * - \--channel_number - Total number of Wi-Fi channels - - See the ``nchan`` field of `Wi-Fi Country Code `_ + - See the ``nchan`` field of `Wi-Fi Country Code `_ For example, you can use the following command to modify the maximum transmission power of Wi-Fi to 18 dBm, set the country code to US, starting channel to 1, and total channel number to 11: diff --git a/docs/en/Get_Started/Technology_selection.rst b/docs/en/Get_Started/Technology_selection.rst new file mode 100644 index 000000000..522feac55 --- /dev/null +++ b/docs/en/Get_Started/Technology_selection.rst @@ -0,0 +1,158 @@ +Technology Selection +==================== + +:link_to_translation:`zh_CN:[中文]` + +This document mainly introduces how to choose the right Espressif hardware product, AT software solution, and the initial preparation for your project. + +.. important:: + If you have any questions regarding the selection of Espressif hardware products or AT software solutions, please contact `Espressif Sales `_ or `Technical Support `_. + +Hardware Selection +------------------ + +Before using ESP-AT, you need to select a suitable Espressif chip to integrate into your product, empowering it with wireless capabilities. Hardware selection is a complex process that requires consideration of various factors such as functionality, power consumption, cost, size, etc. Please read the following content to help you choose the hardware. + +.. list:: + + - `Product Selector Tool `_ can help you understand the hardware differences of different Espressif products. + - `Datasheets `_ can help you understand the hardware capabilities supported by the chip/module. + - `Board Selection Guide `_ can help you compare the differences between chips, modules, and development boards and provide selection guidance. + +.. note:: + **The datasheets indicate the maximum hardware capabilities and do not represent the capabilities of the AT software**. For example, the ESP32-C6 chip supports Zigbee 3.0 and Thread 1.3, but the existing AT software solutions do not support these two wireless protocols. + +.. _at-solution-selection: + +AT Software Solution Selection +------------------------------ + +AT software solution is the AT firmwares provided by Espressif for different chips, which can help you quickly implement wireless functionality. + +- If you want to know the detailed AT software capabilities of {IDF_TARGET_NAME} chip, please refer to the :doc:`AT Command Set <../AT_Command_Set/index>`. +- If you want to compare the different AT firmware functionalities of {IDF_TARGET_NAME} chip, please refer to the :doc:`ESP-AT Firmware Differences <../Compile_and_Develop/esp-at_firmware_differences>`. + +The table below shows a brief comparison of the AT firmware for different chips. + +.. list-table:: + :header-rows: 1 + + * - Chip + - Wireless + - AT Firmware + - Description + * - ESP32-C6 + - **Wi-Fi 6** + BLE 5.0 + - `v4.0.0.0 `_ + - + * - ESP32-C3 + - Wi-Fi 4 + BLE 5.0 + - `v3.3.0.0 `_ + - + * - ESP32-C2 + - Wi-Fi 4 (or BLE 5.0) + - `v3.3.0.0 `_ + - + * - ESP32 + - Wi-Fi 4 + BLE v4.2 (+ **BT**) + - `v3.4.0.0 `_ + - + * - ESP32-S2 + - Wi-Fi 4 + - `v3.4.0.0 `_ + - It is recommended to use the more cost-effective ESP32-C series. + +- ``(or BLE 5.0)`` indicates that Bluetooth LE functionality is supported in the AT software solution, but it is not included in the released firmware. +- ``(+ BT)`` indicates that Classic Bluetooth functionality is supported in the AT software solution, but it is not included in the released firmware. + +.. note:: + The modules or chips from the factory are not preloaded with AT firmware. If you have mass production requirements, please contact the corresponding business personnel or sales@espressif.com in a timely manner, and we will provide customized production. + +.. _firmware-selection: + +Which Type of AT Firmware Shall I Choose? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ESP-AT firmware has the following types. Among them, the workload of downloading or preparing firmware increases from top to bottom, and so does the number of supported module types. + +.. contents:: + :local: + :depth: 1 + +.. _official-released-firmware: + +Officially Released Firmware (Recommended) +"""""""""""""""""""""""""""""""""""""""""" + +**Officially released firmware**, also known as "released firmware", "official firmware" or "default firmware", has passed testing and periodically released by Espressif's official team according to the internal development plan. It can be upgraded directly based on the Espressif OTA server. If it fully matches your project needs, it is recommended to choose it over the other types of firmware. If it does not support your module, you can select a firmware that has a similar hardware configuration to your module according to :doc:`Hardware Differences <../Compile_and_Develop/esp-at_firmware_differences>` for testing and verification. + +.. list:: + + - How to obtain firmware: :doc:`{IDF_TARGET_NAME} AT firmware <../AT_Binary_Lists/esp_at_binaries>` + - Pros: + + - Stable + - Reliable + - Small workload of obtaining firmware + + - Cons: + + - Long update cycle + - A limited number of supported modules + + - Reference documentation: + + - :doc:`Hardware connection <../Get_Started/Hardware_connection>` + - :doc:`Firmware Downloading and Flash <../Get_Started/Downloading_guide>` + - For which chip series are supported and unsupported by ESP-AT firmware, please refer to ESP-AT GitHub home page `readme.md `_ + +.. _github-temporary-firmware: + +GitHub Temporary Firmware +""""""""""""""""""""""""" + +**GitHub temporary firmware** is compiled by GitHub whenever code is pushed to GitHub and yet does not reach the firmware release cycle. In other words, it is the firmware in development, including the temporary versions of **officially released firmware** and supported firmware that is not planned for release. The former can be upgraded directly based on the Espressif OTA server. + +- How to obtain firmware: Please refer to :doc:`../Compile_and_Develop/How_to_download_the_latest_temporary_version_of_AT_from_github`. +- Pros: + + - Real-time integration of new features and bug fixes. + - Covering some unofficially released firmware, such as firmware based on SDIO communication and firmware based on SPI communication. + - Small workload of obtaining firmware. + +- Cons: As the firmware compiled based on commits that are not for official release has not been thoroughly tested, there may be some risks. You need to do a complete test by yourself. + +.. _firmware-modify-paras-not-source-code: + +Firmware with Updated Parameters +"""""""""""""""""""""""""""""""" + +The **firmware with updated parameters** is generated by updating the parameter area and you do not need to compile the firmware. It is suitable for the case where the firmware function meets the project requirements, but only some parameters do not, such as the UART baud rate and UART GPIO pins. This type of firmware can be directly upgraded based on the Espressif OTA server. + +- For how to modify those parameters, please refer to :doc:`../Compile_and_Develop/tools_at_py`. +- Pros: + + - No need to recompile the firmware. + - The firmware is stable and reliable. + +- Cons: Requiring modification to released firmware, long update cycle, and a limited number of supported modules. + +.. _self-compiled-firmware: + +Self-Compiled Firmware +"""""""""""""""""""""" + +When you need to conduct secondary development, you can compile the firmware by yourself. To support the OTA function, you need to deploy your own OTA server. + +- For how to compile the firmware by yourself, please refer to :doc:`../Compile_and_Develop/How_to_clone_project_and_compile_it`. +- Pros: You can control functions and cycles. +- Cons: You need to set up the compilation environment. + +If stability is your priority, it is recommended to develop your AT firmware based on the latest released version corresponding to the chip. If you want more new features, it is recommended to develop your AT firmware based on the `master branch `_. + +Initial Project Preparation +--------------------------- + +During the initial project preparation phase, it is **strongly recommended** that you choose `Espressif development boards `_ to start your project. In the early stages of the project, it can help you quickly validate prototypes, evaluate hardware and software capabilities, and reduce project risks. In the middle stages of the project, it can help you quickly integrate and verify functions, optimize performance, and improve development efficiency. In the later stages of the project, it can help you quickly simulate and locate issues, and achieve rapid product iteration. + +If you are using :ref:`self-compiled-firmware`, it is recommended to prioritize using Linux as the development environment. diff --git a/docs/en/Get_Started/index.rst b/docs/en/Get_Started/index.rst index 17982c2b9..879c7bb3d 100644 --- a/docs/en/Get_Started/index.rst +++ b/docs/en/Get_Started/index.rst @@ -4,15 +4,18 @@ Get Started :link_to_translation:`zh_CN:[中文]` -This Get Started guide provides users with detailed information on what is ESP-AT, how to connect hardware, and how to download and flash AT firmware. It consists of the following parts: +This Get Started guide provides users with detailed information on what is ESP-AT, technology selection, how to connect hardware, and how to download and flash AT firmware. It consists of the following parts: .. toctree:: :maxdepth: 1 What is ESP-AT + Technology Selection Hardware Connection Downloading Guide To learn more about ESP-AT, please read :doc:`What_is_ESP-AT`. -To get started with ESP-AT, please read :doc:`Hardware_connection` first to learn what hardware to prepare and how to connect them. Then, you can download and flash AT firmware into your device according to :doc:`Downloading_guide`. +Help you select hardware and software + +To get started with ESP-AT, please read :doc:`Technology_selection` first to help you select hardware and software, and then read :doc:`Hardware_connection` to learn what hardware to prepare and how to connect them. Then, you can download and flash AT firmware into your device according to :doc:`Downloading_guide`. diff --git a/docs/en/index.rst b/docs/en/index.rst index 6cbc1a1cb..55e524d2b 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -3,7 +3,7 @@ ESP-AT User Guide :link_to_translation:`zh_CN:[中文]` -This is the documentation for `ESP-AT `_ Development Framework. ESP-AT project was started and powered by `Espressif Systems `_ as an official project, for the `ESP32, ESP32-C2, ESP32-C3, ESP32-C6, ESP32-S2, and ESP8266 Series SoCs `_ provided for Windows, Linux, and macOS. +This is the documentation for `ESP-AT `_ Development Framework. ESP-AT project was started and powered by `Espressif Systems `_ as an official project, for the `ESP32, ESP32-C2, ESP32-C3, ESP32-C6, and ESP32-S2 Series SoCs `_ provided for Windows, Linux, and macOS. .. only:: html @@ -48,6 +48,7 @@ This is the documentation for `ESP-AT `_ De AT Binary Lists AT Command Set AT Command Examples + ESP-AT Versions Compile and Develop Customized AT Commands and Firmware FAQ diff --git a/docs/en/versions.rst b/docs/en/versions.rst new file mode 100644 index 000000000..0fda7a6f9 --- /dev/null +++ b/docs/en/versions.rst @@ -0,0 +1,183 @@ +ESP-AT Versions +=============== + +:link_to_translation:`zh_CN:[中文]` + +This document mainly introduces ESP-AT versions, how to select a version, versioning scheme, support periods, viewing versions, and subscribing to AT releases. + +Releases +-------- + +The full history of ESP-AT releases can be found on the GitHub repository `Release page `_. There you can find the AT firmwares, release notes, links to each version of the documentation, and instructions for obtaining each version. + +Which Version Should I Start With? +---------------------------------- + +Please read :ref:`AT software solution selection `. + +.. _versioning-scheme: + +Versioning Scheme +----------------- + +ESP-AT Firmware Release Management +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ESP-AT release is specific to a chip and usually refers to the release of one or more AT firmwares for that chip. The AT command set supported by the released AT firmware is usually backward compatible. This means that you can update the new version of the AT firmware to devices with older versions. + +The firmware released by ESP-AT follows a similar version management method as `Semantic Versioning `_. You can understand the differences of each version from the literal meaning. For example, ``v3.3.0.0``, ``v`` represents version, followed by the version number in the following format: + +:: + + ... + +Where: + +- is the major version. For example, ``v4.0.0.0`` represents a major update, usually including the introduction of new chip support, new features, and bug fixes. +- is the minor version. For example, ``v3.3.0.0`` represents an important update, usually including new features, ESP-IDF version upgrade, and bug fixes. +- is the patch version, also known as the bugfix version. For example, ``v2.4.2.0`` represents only bug fixes without adding any new features. +- is the custom version. It is usually used for downstream distributors or customized project versions. + +ESP-AT Branch Release Management +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When ESP-AT releases AT firmware, if there are major or minor version updates, a new `release branch `_ will be created. + +The release branches of ESP-AT follow a similar version management method as `Semantic Versioning `_. You can understand the differences of each version from the literal meaning. For example, ``release/v3.3.0.0``, ``release`` represents the release branch, ``v`` represents the version of the release branch, followed by the version number in the following format: + +:: + + ..0.0 + +Where: + +- is the major version. For example, ``release/v4.0.0.0`` represents a major update, usually including the introduction of new chip support, new features, and bug fixes. +- is the minor version. For example, ``release/v3.3.0.0`` represents an important update, usually including new features, ESP-IDF version upgrade, and bug fixes. + +In general, the AT firmware to be released will undergo multiple rounds of testing on the release branch until there are no major issues. Then, the AT firmware will be released, and the release branch will be synchronized to GitHub. + +- New feature development usually takes place on the master branch and is not merged into the release branch. +- Bug fixes usually take place on the master branch and, if the issue is severe, will be merged into the release branch. + +Support Periods +--------------- + +Each ESP-IDF major and minor release version has an associated support period. After this period, the release is End of Life and no longer supported. Since ESP-AT is a project based on ESP-IDF, the support period of ESP-AT is limited by the support period of ESP-IDF. The current information of each version of ESP-AT is as follows: + +.. list-table:: + :header-rows: 1 + :width: 100% + + * - AT Version (Release Date) + - Supported Chips + - IDF Version + - IDF EOL Date + - AT New Version Plan + * - **v4.0.0.0** (2023.12.29) + - ESP32-C6 + - `v5.1.2 `_ + - 2025.12.30 + - 2025.7.30 - 2025.9.30 + * - **v3.4.0.0** (2024.6.7) + - + * ESP32 + * ESP32-S2 + - `v5.0.6 `_ + - 2025.5.29 + - 2024.12.29 - 2025.2.28 + * - **v3.3.0.0** (2024.5.9) + - + * ESP32-C2 + * ESP32-C3 + - `v5.0.6 `_ + - 2025.5.29 + - 2024.12.29 - 2025.2.28 + * - **v3.2.0.0** (2023.7.28) + - + * ESP32 + * ESP32-C3 + - ~v5.0.3 (`24b9d38 `_) + - 2025.5.29 + - + * New version v3.4.0.0 released for ESP32 + * New version v3.3.0.0 released for ESP32-C3 + +**Support periods for each released version of ESP-AT are as follows:** + +.. figure:: ../_static/at-support-periods.png + :align: center + :alt: ESP-AT Version Support Periods + :figclass: align-center + + ESP-AT Version Support Periods + +- Service Period of Support Period + + Usually, it starts from the release of the AT firmware for the chip and lasts until the planned release of the next AT version for that chip. The release time of the next AT version is usually a few months before the end of the corresponding `ESP-IDF support period `_ (the AT release notes provide information about the ESP-IDF version corresponding to the chip). + +- Maintenance Period of Support Period + + Usually, it starts after the service period ends and lasts until the end of the corresponding `ESP-IDF support period `_ for the chip (the AT release notes provide information about the ESP-IDF version corresponding to the chip). For example, if the support period of ESP-IDF v5.0 is until May 29, 2025, then the maintenance period for ESP-AT v3.0 ~ v3.3 will also be until May 29, 2025. + +In general: + +- Once a new version of AT is released, the service period of the support period for the old version ends and enters the maintenance period of the support period. + + For example, when AT releases version v3.3.0.0 (for ESP32-C2 and ESP32-C3 chips), the service period of the support period for version v3.2.0.0 of ESP32-C3 ends and enters the maintenance period of the support period; the service period of the support period for version v3.1.0.0 of ESP32-C2 ends and enters the maintenance period of the support period. + +- If you have a GitHub account, please :ref:`Subscribe to AT releases `. GitHub will notify you when a new version is released. When a bugfix version of the AT firmware you are using is released, please plan to upgrade to that bugfix version. +- Please make sure to plan the upgrade to a new version before the version you are using stops receiving updates and support. +- Being within the support period means that the ESP-AT team will continue to perform important bug fixes, security fixes, etc. on the release branch on GitHub, and periodically release new bugfix versions as needed. + +Check the Current AT Firmware Version +------------------------------------- + +Please send the :ref:`AT+GMR ` command to check the AT firmware version information. Refer to the parameter description under the :ref:`AT+GMR ` command for more information. + +.. _sub-at-release: + +Subscribe to AT Releases +------------------------ + +* :ref:`at-sr-github-login` +* :ref:`at-sr-watch-custom` +* :ref:`at-sr-release-apply` + +.. _at-sr-github-login: + +Step 1: Log in to Your GitHub Account +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before you start, please `sign in your GitHub account `_, as you need login permission to subscribe to AT releases. + +.. _at-sr-watch-custom: + +Step 2: Choose Customized Notifications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Visit the `ESP-AT repository `_, click on ``Watch`` in the upper right corner of the page, and then click on ``Custom``. + + .. figure:: ../_static/at-sub-release-custom.png + :align: center + :alt: + :figclass: align-center + :scale: 70% + + Customized Notifications (click to enlarge) + +.. _at-sr-release-apply: + +Step 3: Apply for Release Notifications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Check ``Releases`` and click on ``Apply``. + + .. figure:: ../_static/at-sub-release-apply.png + :align: center + :alt: + :figclass: align-center + :scale: 70% + + Apply for Release Notifications (click to enlarge) + +This completes the process of subscribing to AT releases. You will receive notifications from GitHub when a new AT version is released. diff --git a/docs/zh_CN/AT_Binary_Lists/esp_at_binaries.rst b/docs/zh_CN/AT_Binary_Lists/esp_at_binaries.rst index 4ba69d1ec..4a209f618 100644 --- a/docs/zh_CN/AT_Binary_Lists/esp_at_binaries.rst +++ b/docs/zh_CN/AT_Binary_Lists/esp_at_binaries.rst @@ -25,7 +25,8 @@ ESP32-WROOM-32 系列 ^^^^^^^^^^^^^^^^^^^^^^ - - v3.2.0.0 `ESP32-WROOM-32-AT-V3.2.0.0.zip `__ （推荐） + - v3.4.0.0 `ESP32-WROOM-32-AT-V3.4.0.0.zip `__ （推荐） + - v3.2.0.0 `ESP32-WROOM-32-AT-V3.2.0.0.zip `__ - v2.4.0.0 `ESP32-WROOM-32-AT-V2.4.0.0.zip `__ - v2.2.0.0 `ESP32-WROOM-32-AT-V2.2.0.0.zip `__ - v2.1.0.0 `ESP32-WROOM-32-AT-V2.1.0.0.zip `__ @@ -39,7 +40,8 @@ ESP32-MINI-1 系列 ^^^^^^^^^^^^^^^^^^^ - - v3.2.0.0 `ESP32-MINI-1-AT-V3.2.0.0.zip `__ （推荐） + - v3.4.0.0 `ESP32-MINI-1-AT-V3.4.0.0.zip `__ （推荐） + - v3.2.0.0 `ESP32-MINI-1-AT-V3.2.0.0.zip `__ - v2.4.0.0 `ESP32-MINI-1-AT-V2.4.0.0.zip `__ - v2.2.0.0 `ESP32-MINI-1-AT-V2.2.0.0.zip `__ @@ -59,7 +61,8 @@ ESP32-PICO 系列 ^^^^^^^^^^^^^^^^^ - - v3.2.0.0 `ESP32-PICO-D4-AT-V3.2.0.0.zip `__ （推荐） + - v3.4.0.0 `ESP32-PICO-D4-AT-V3.4.0.0.zip `__ （推荐） + - v3.2.0.0 `ESP32-PICO-D4-AT-V3.2.0.0.zip `__ - v2.4.0.0 `ESP32-PICO-D4-AT-V2.4.0.0.zip `__ - v2.2.0.0 `ESP32-PICO-D4-AT-V2.2.0.0.zip `__ - v2.1.0.0 `ESP32-PICO-D4-AT-V2.1.0.0.zip `__ @@ -68,7 +71,8 @@ ESP32-SOLO 系列 ^^^^^^^^^^^^^^^^^ - - v3.2.0.0 `ESP32-SOLO-AT-V3.2.0.0.zip `__ （推荐） + - v3.4.0.0 `ESP32-SOLO-AT-V3.4.0.0.zip `__ （推荐） + - v3.2.0.0 `ESP32-SOLO-AT-V3.2.0.0.zip `__ - v2.4.0.0 `ESP32-SOLO-AT-V2.4.0.0.zip `__ - v2.2.0.0 `ESP32-SOLO-AT-V2.2.0.0.zip `__ - v2.1.0.0 `ESP32-SOLO-AT-V2.1.0.0.zip `__ @@ -115,4 +119,9 @@ ESP32-S2-MINI 系列 ^^^^^^^^^^^^^^^^^^^^^^ - - 计划在 2024 年 7 月发布首版 ESP-AT 固件（v3.4.0.0） + - v3.4.0.0 `ESP32-S2-MINI-AT-V3.4.0.0.zip `__ （推荐） + +订阅 AT 版本发布 +^^^^^^^^^^^^^^^^^^^^^^ + +请参考 :ref:`sub-at-release` 文档订阅我们的版本发布通知，及时获取最新版本的发布情况。 diff --git a/docs/zh_CN/AT_Binary_Lists/index.rst b/docs/zh_CN/AT_Binary_Lists/index.rst index 8a9b007c5..afa42073a 100644 --- a/docs/zh_CN/AT_Binary_Lists/index.rst +++ b/docs/zh_CN/AT_Binary_Lists/index.rst @@ -15,8 +15,6 @@ AT 固件 - :doc:`下载 {IDF_TARGET_NAME} AT 发布版固件 ` - :ref:`brief-intro-firmware`：AT 固件包含哪些二进制文件及其作用 - - :ref:`firmware-selection`：不同类型的 AT 固件及其获取方式、适用情况、优缺点等 - - :ref:`what-next-after-you-get-firmware` .. note:: 若需下载其他芯片系列的发布版固件，请在页面左上方的下拉菜单栏选择相应的芯片，即可跳转至该芯片的文档进行下载。 @@ -42,90 +40,3 @@ ESP-AT 固件包含了若干个特定功能的二进制文件： ├── partition_table │ └── partition-table.bin // 一级分区表（系统分区表） └── ota_data_initial.bin // OTA 数据初始化文件 - -.. _firmware-selection: - -我该选哪种类型的固件？ ------------------------ - -ESP-AT 固件有以下几种类型，其中下载或准备固件的工作量自上而下依次递增，支持的模组类型也自上而下依次递增。 - -.. contents:: - :local: - :depth: 1 - -.. _official-released-firmware: - -官方发布版固件（推荐） -^^^^^^^^^^^^^^^^^^^^^^^^ - -**官方发布版固件** 又称“发布版固件”、“官方固件”、“默认固件”，为乐鑫官方团队测试并发布的固件，固件会根据内部开发计划周期性发布，此种固件可直接基于乐鑫 OTA 服务器升级固件。如果 **官方发布版固件** 完全满足您的项目需求，建议您优先选择 **官方发布版固件**。如果官方固件不支持您的模组，您可以根据 :doc:`硬件差异 <../Compile_and_Develop/esp-at_firmware_differences>`，选择和您的模组硬件配置相近的固件进行测试验证。 - -.. list:: - - - 获取途径：:doc:`{IDF_TARGET_NAME} AT 固件 ` - - 优点： - - - 稳定 - - 可靠 - - 获取固件工作量小 - - - 缺点： - - - 更新周期长 - - 覆盖的模组有限 - - - 参考文档： - - - :doc:`硬件连接 <../Get_Started/Hardware_connection>` - - :doc:`固件下载及烧录指南 <../Get_Started/Downloading_guide>` - - 有关 ESP-AT 固件支持/不支持哪些芯片系列，请参考 ESP-AT GitHub 首页 `readme.md `_ - -.. _github-temporary-firmware: - -GitHub 临时固件 -^^^^^^^^^^^^^^^^^^^^^^ - -**GitHub 临时固件** 为每次将代码推送到 GiHub 时都会生成但并未达到固件发布周期条件的固件，或者说是开发中的固件，包括 **官方发布版固件** 的临时版本和适配过但是不计划正式发布的固件，其中前者可直接基于乐鑫 OTA 服务器升级固件。 - -- 获取途径：请参考 :doc:`../Compile_and_Develop/How_to_download_the_latest_temporary_version_of_AT_from_github`。 -- 优点： - - - 实时性强，新的特性和漏洞修补都会实时同步出来。 - - 包含一些非正式发布的固件，如基于 SDIO 通讯的固件、基于 SPI 通讯的固件。 - - 获取固件工作量小。 - -- 缺点：基于非正式发布的 commit 生成的固件未经过完整的测试，可能会存在一些风险，需要您自己做完整的测试。 - -.. _firmware-modify-paras-not-source-code: - -修改参数的固件 -^^^^^^^^^^^^^^^^^^^^^^ - -**修改参数的固件** 指的是只修改参数区域而并不需要重新编译的固件，适用于固件功能满足项目要求、但只有某些参数不满足的情况下，如出厂波特率、UART IO 管脚的等参数的变更，此种固件可直接基于乐鑫 OTA 服务器升级固件。 - -- 关于如何修改参数文件，请参考 :doc:`../Compile_and_Develop/tools_at_py`。 -- 优点： - - - 不需要重新编译固件。 - - 固件稳定、可靠。 - -- 缺点：需要基于发布版的固件修改，更新周期长，覆盖的模组有限。 - -.. _self-compiled-firmware: - -自行编译的固件 -^^^^^^^^^^^^^^^^^ - -当您需要进行二次开发时可采用此种方式。需要自己部署 OTA 服务器以支持 OTA 功能。 - -- 关于如何自行编译固件，请参考 :doc:`../Compile_and_Develop/How_to_clone_project_and_compile_it`。 -- 优点：功能、周期自己可控。 -- 缺点：需要自己搭建环境编译。 - -.. _what-next-after-you-get-firmware: - -获取固件后，接来下做什么？ ----------------------------------- - -当您获取到固件后，请参考 :doc:`硬件连接 <../Get_Started/Hardware_connection>` 与 :doc:`固件下载及烧录指南 <../Get_Started/Downloading_guide>` 连接 PC 和 ESP 设备、并将固件烧录至设备。 diff --git a/docs/zh_CN/AT_Command_Examples/Ethernet_AT_Examples.rst b/docs/zh_CN/AT_Command_Examples/Ethernet_AT_Examples.rst index 35f36d359..39ce466d5 100644 --- a/docs/zh_CN/AT_Command_Examples/Ethernet_AT_Examples.rst +++ b/docs/zh_CN/AT_Command_Examples/Ethernet_AT_Examples.rst @@ -10,7 +10,7 @@ :depth: 1 .. Important:: - - 在使用 Ethernet AT 指令之前，请先阅读 :ref:`准备工作 `。 + - 在使用 Ethernet AT 命令之前，请先阅读 :ref:`准备工作 `。 - 文档中所描述的例子均是基于网线已经插入的情况下。 基于以太网创建 TCP 连接 @@ -93,7 +93,7 @@ 说明： - - 若输入的字节数目超过了 ``AT+CIPSEND`` 指令设定的长度 (n)，则会响应 ``busy p...``，并发送数据的前 n 个字节，发送完成后响应 ``SEND OK``。 + - 若输入的字节数目超过了 ``AT+CIPSEND`` 命令设定的长度 (n)，则会响应 ``busy p...``，并发送数据的前 n 个字节，发送完成后响应 ``SEND OK``。 #. 采用 :term:`普通传输模式` 从网络连接 ID 为 0 的链路上接收 4 字节数据。 @@ -135,5 +135,5 @@ 说明： - - 指令 ``AT+CIPSERVER=0`` 只会关闭服务器，但会保留现有客户端连接。如果您想同时关闭所有的客户端连接，请执行指令 ``AT+CIPSERVER=0,1``。 + - 命令 ``AT+CIPSERVER=0`` 只会关闭服务器，但会保留现有客户端连接。如果您想同时关闭所有的客户端连接，请执行命令 ``AT+CIPSERVER=0,1``。 \ No newline at end of file diff --git a/docs/zh_CN/AT_Command_Examples/MQTT_AT_Examples.rst b/docs/zh_CN/AT_Command_Examples/MQTT_AT_Examples.rst index 43195ff86..e0b81f3c5 100644 --- a/docs/zh_CN/AT_Command_Examples/MQTT_AT_Examples.rst +++ b/docs/zh_CN/AT_Command_Examples/MQTT_AT_Examples.rst @@ -133,7 +133,7 @@ MQTT AT 示例 示例介绍了如何基于 TCP 创建 MQTT 连接。首先您需要创建一个本地 MQTT 代理，假设 MQTT 代理的 IP 地址为 ``192.168.3.102``，端口为 ``8883``。 -如果您发布消息的数据量相对较多，已经超过了单条 AT 指令的长度阈值 ``256``，则您可以使用 :ref:`AT+MQTTPUBRAW ` 命令。 +如果您发布消息的数据量相对较多，已经超过了单条 AT 命令的长度阈值 ``256``，则您可以使用 :ref:`AT+MQTTPUBRAW ` 命令。 .. Important:: 步骤中以 ``{IDF_TARGET_NAME} MQTT 发布者`` 开头的操作只需要在 {IDF_TARGET_NAME} MQTT 发布者端执行即可，以 ``{IDF_TARGET_NAME} MQTT 订阅者`` 开头的操作只需要在 {IDF_TARGET_NAME} MQTT 订阅者端执行即可。如果操作没有特别指明在哪端操作，则需要在发布者端和订阅者端都执行。 diff --git a/docs/zh_CN/AT_Command_Examples/http_at_examples.rst b/docs/zh_CN/AT_Command_Examples/http_at_examples.rst index b1bb3c1d5..a5361bc11 100644 --- a/docs/zh_CN/AT_Command_Examples/http_at_examples.rst +++ b/docs/zh_CN/AT_Command_Examples/http_at_examples.rst @@ -272,7 +272,7 @@ HTTP 客户端 POST 请求方法（适用于 POST 少量数据） HTTP 客户端 POST 请求方法（推荐方式） ------------------------------------------------------------------------------------- -如果您 POST 的数据量相对较多，已经超过了单条 AT 指令的长度阈值 ``256``，则建议您可以使用 :ref:`AT+HTTPCPOST ` 命令。 +如果您 POST 的数据量相对较多，已经超过了单条 AT 命令的长度阈值 ``256``，则建议您可以使用 :ref:`AT+HTTPCPOST ` 命令。 该示例以 http://httpbin.org 作为 HTTP 服务器，数据类型为 ``application/json``。 diff --git a/docs/zh_CN/AT_Command_Examples/mqtt-at-examples-for-cloud.rst b/docs/zh_CN/AT_Command_Examples/mqtt-at-examples-for-cloud.rst index 1a52f606d..e7dff9459 100644 --- a/docs/zh_CN/AT_Command_Examples/mqtt-at-examples-for-cloud.rst +++ b/docs/zh_CN/AT_Command_Examples/mqtt-at-examples-for-cloud.rst @@ -3,7 +3,7 @@ MQTT AT 连接云示例 :link_to_translation:`en:[English]` -本文档主要介绍您的设备如何通过 AT 指令对接 AWS IoT。 +本文档主要介绍您的设备如何通过 AT 命令对接 AWS IoT。 .. Important:: 有关如何使用 MQTT AT 命令的详细信息，请参阅 :doc:`../AT_Command_Set/MQTT_AT_Commands`。 diff --git a/docs/zh_CN/AT_Command_Set/BLE_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/BLE_AT_Commands.rst index cc0827923..d2621d129 100644 --- a/docs/zh_CN/AT_Command_Set/BLE_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/BLE_AT_Commands.rst @@ -479,7 +479,7 @@ Bluetooth® Low Energy AT 命令集 ^^^^ - 响应中的 ``OK`` 和 ``+BLESCAN:,,,,`` 在输出顺序上没有严格意义上的先后顺序。``OK`` 可能在 ``+BLESCAN:,,,,`` 之前输出，也有可能在 ``+BLESCAN:,,,,`` 之后输出。 - - 如果您想要获得扫描响应数据，需要使用 :ref:`AT+BLESCANPARAM ` 指令设置扫描方式为 ``active scan (AT+BLESCANPARAM=1,0,0,100,50)``，并且对端设备需要设置 ``scan rsp data``，才能获得扫描响应数据。 + - 如果您想要获得扫描响应数据，需要使用 :ref:`AT+BLESCANPARAM ` 命令设置扫描方式为 ``active scan (AT+BLESCANPARAM=1,0,0,100,50)``，并且对端设备需要设置 ``scan rsp data``，才能获得扫描响应数据。 示例 ^^^^ @@ -615,7 +615,7 @@ Bluetooth® Low Energy AT 命令集 - 5: ADV_TYPE_EXT_NOSCANNABLE_IND - 6: ADV_TYPE_EXT_CONNECTABLE_IND - 7: ADV_TYPE_EXT_SCANNABLE_IND - - 当设置广播类型为 0-4，则使用 :ref:`AT+BLEADVDATA ` 命令设置广播参数最多只能设置 31 字节，如果需要设置更长的广播参数，请调用 :ref:`AT+BLESCANRSPDATA ` 指令来设置。 + - 当设置广播类型为 0-4，则使用 :ref:`AT+BLEADVDATA ` 命令设置广播参数最多只能设置 31 字节，如果需要设置更长的广播参数，请调用 :ref:`AT+BLESCANRSPDATA ` 命令来设置。 - 当设置广播类型为 5-7，则使用 :ref:`AT+BLEADVDATA ` 命令设置广播参数最多只能设置 119 字节。 - ****：Bluetooth LE 地址类型 @@ -753,12 +753,12 @@ Bluetooth® Low Energy AT 命令集 .. only:: esp32 - - 如果需要设置更长的广播数据，请调用 :ref:`AT+BLESCANRSPDATA ` 指令来设置。 + - 如果需要设置更长的广播数据，请调用 :ref:`AT+BLESCANRSPDATA ` 命令来设置。 .. only:: esp32c3 or esp32c6 or esp32c2 - 在使用 :ref:`AT+BLEADVDATA ` 命令之前，必须先通过 :ref:`AT+BLEADVPARAM ` 命令设置广播参数。 - - 当调用 :ref:`AT+BLEADVPARAM ` 命令设置广播类型为 0-4，则使用 :ref:`AT+BLEADVDATA ` 命令设置广播数据最多只能设置 31 字节，如果需要设置更长的广播数据，请调用 :ref:`AT+BLESCANRSPDATA ` 指令来设置。 + - 当调用 :ref:`AT+BLEADVPARAM ` 命令设置广播类型为 0-4，则使用 :ref:`AT+BLEADVDATA ` 命令设置广播数据最多只能设置 31 字节，如果需要设置更长的广播数据，请调用 :ref:`AT+BLESCANRSPDATA ` 命令来设置。 - 当调用 :ref:`AT+BLEADVPARAM ` 命令设置广播类型为 5-7，则使用 :ref:`AT+BLEADVDATA ` 命令设置广播数据最多只能设置 119 字节。 示例 diff --git a/docs/zh_CN/AT_Command_Set/Basic_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/Basic_AT_Commands.rst index 75bb3581d..58c4b9868 100644 --- a/docs/zh_CN/AT_Command_Set/Basic_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/Basic_AT_Commands.rst @@ -1296,7 +1296,7 @@ ^^^^ - 使用本命令需烧录 at_customize.bin，详细信息可参考 :doc:`../Compile_and_Develop/How_to_customize_partitions`。 -- 擦除分区时，请完整擦除该目标分区。这可以通过省略 ```` 和 ```` 参数来完成。例如，指令 ``AT+SYSFLASH=0,"mfg_nvs"`` 可擦除整个 "mfg_nvs" 区域。 +- 擦除分区时，请完整擦除该目标分区。这可以通过省略 ```` 和 ```` 参数来完成。例如，命令 ``AT+SYSFLASH=0,"mfg_nvs"`` 可擦除整个 "mfg_nvs" 区域。 - 关于分区的定义可参考 `ESP-IDF 分区表 `_。 - 当 ```` 为 ``write`` 时，系统收到此命令后先换行返回 ``>``，此时您可以输入要写的数据，数据长度应与 ```` 一致。 - 写分区前，请先擦除该分区。 diff --git a/docs/zh_CN/AT_Command_Set/Driver_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/Driver_AT_Commands.rst index 8260e5d66..0bc4450b2 100644 --- a/docs/zh_CN/AT_Command_Set/Driver_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/Driver_AT_Commands.rst @@ -304,7 +304,7 @@ 说明 ^^^^ -- 本指令只支持 I2C 主机。 +- 本命令只支持 I2C 主机。 示例 ^^^^ diff --git a/docs/zh_CN/AT_Command_Set/HTTP_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/HTTP_AT_Commands.rst index 92b52105b..365ed4be3 100644 --- a/docs/zh_CN/AT_Command_Set/HTTP_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/HTTP_AT_Commands.rst @@ -90,7 +90,7 @@ HTTP AT 命令集 - 如果包含 URL 的整条命令的长度超过了 256 字节，请先使用 :ref:`AT+HTTPURLCFG ` 命令预配置 URL，然后本命令里的 ``<"url">`` 参数需要设置为 ``""``。 - 如果 ``url`` 参数不为空，HTTP 客户端将使用它并忽略 ``host`` 参数和 ``path`` 参数；如果 ``url`` 参数被省略或字符串为空，HTTP 客户端将使用 ``host`` 参数和 ``path`` 参数。 - 某些已发布的固件默认不支持 HTTP 客户端命令（详情请见 :doc:`../Compile_and_Develop/esp-at_firmware_differences`），但是可通过以下方式使其支持该命令：``./build.py menuconfig`` > ``Component config`` > ``AT`` > ``AT http command support``，然后编译项目（详情请见 :doc:`../Compile_and_Develop/How_to_clone_project_and_compile_it`）。 -- 该指令不支持 URL 重定向，在获取到服务器返回的状态码 301（永久性重定向）或者 302（临时性重定向）后不会自动跳转到新的 URL 地址。您可以使用某些工具获取要访问的实际 URL，然后通过该命令访问它。 +- 该命令不支持 URL 重定向，在获取到服务器返回的状态码 301（永久性重定向）或者 302（临时性重定向）后不会自动跳转到新的 URL 地址。您可以使用某些工具获取要访问的实际 URL，然后通过该命令访问它。 - 如果包含 ``<"data">`` 参数的整条命令的长度超过了 256 字节，请使用 :ref:`AT+HTTPCPOST ` 命令。 - 要设置更多的 HTTP 请求头，请使用 :ref:`AT+HTTPCHEAD ` 命令。 diff --git a/docs/zh_CN/AT_Command_Set/MQTT_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/MQTT_AT_Commands.rst index 11d6c592f..b2f32c6a2 100644 --- a/docs/zh_CN/AT_Command_Set/MQTT_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/MQTT_AT_Commands.rst @@ -455,7 +455,7 @@ MQTT AT 命令集 **功能：** -通过 topic 发布 MQTT **字符串** 消息。如果您发布消息的数据量相对较多，已经超过了单条 AT 指令的长度阈值 ``256`` 字节，请使用 :ref:`AT+MQTTPUBRAW ` 命令。 +通过 topic 发布 MQTT **字符串** 消息。如果您发布消息的数据量相对较多，已经超过了单条 AT 命令的长度阈值 ``256`` 字节，请使用 :ref:`AT+MQTTPUBRAW ` 命令。 **命令：** @@ -505,7 +505,7 @@ MQTT AT 命令集 **功能：** -通过 topic 发布长 MQTT 消息。如果您发布消息的数据量相对较少，不大于单条 AT 指令的长度阈值 ``256`` 字节，也可以使用 :ref:`AT+MQTTPUB ` 命令。 +通过 topic 发布长 MQTT 消息。如果您发布消息的数据量相对较少，不大于单条 AT 命令的长度阈值 ``256`` 字节，也可以使用 :ref:`AT+MQTTPUB ` 命令。 **命令：** diff --git a/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst b/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst index 8684941ca..4f801ac6a 100644 --- a/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst +++ b/docs/zh_CN/AT_Command_Set/Wi-Fi_AT_Commands.rst @@ -732,7 +732,7 @@ Wi-Fi AT 命令集 说明 ^^^^ -- 本指令只有当 :ref:`AT+CWMODE=2 ` 或者 :ref:`AT+CWMODE=3 ` 时才有效 +- 本命令只有当 :ref:`AT+CWMODE=2 ` 或者 :ref:`AT+CWMODE=3 ` 时才有效 - 若 :ref:`AT+SYSSTORE=1 `，配置更改将保存在 NVS 分区 - 默认 SSID 因设备而异，因为它由设备的 MAC 地址组成。 您可以使用 :ref:`AT+CWSAP? ` 查询默认的SSID。 @@ -774,7 +774,7 @@ Wi-Fi AT 命令集 说明 ^^^^ -- 本指令无法查询静态 IP，仅支持在 {IDF_TARGET_NAME} SoftAP 和连入的 station DHCP 均使能的情况下有效 +- 本命令无法查询静态 IP，仅支持在 {IDF_TARGET_NAME} SoftAP 和连入的 station DHCP 均使能的情况下有效 .. _cmd-QIF: diff --git a/docs/zh_CN/Compile_and_Develop/How_to_implement_SPI_AT.rst b/docs/zh_CN/Compile_and_Develop/How_to_implement_SPI_AT.rst index 563339bb8..b8a567376 100644 --- a/docs/zh_CN/Compile_and_Develop/How_to_implement_SPI_AT.rst +++ b/docs/zh_CN/Compile_and_Develop/How_to_implement_SPI_AT.rst @@ -223,7 +223,7 @@ SPI AT 数据交互流程 ^^^^^^^^^^^^^^^^^^^^^^ SPI AT 数据交互流程主要分为两个方面： -- SPI master 向 slave 发送 AT 指令 ： +- SPI master 向 slave 发送 AT 命令 ： .. code-block:: none diff --git a/docs/zh_CN/Get_Started/Technology_selection.rst b/docs/zh_CN/Get_Started/Technology_selection.rst new file mode 100644 index 000000000..81d09e560 --- /dev/null +++ b/docs/zh_CN/Get_Started/Technology_selection.rst @@ -0,0 +1,158 @@ +技术选型 +======== + +:link_to_translation:`en:[English]` + +本文档主要介绍如何选择合适的乐鑫硬件产品、AT 软件方案、以及项目初期的准备。 + +.. important:: + 如果您在选择乐鑫硬件产品、AT 软件方案中有任何问题，请联系 `乐鑫商务 `_ 或者 `技术支持 `_。 + +硬件选型 +------------ + +在开始使用 ESP-AT 之前，您需要选择一款合适的乐鑫芯片集成到您的产品中，为您的产品赋能无线功能。硬件选型是一个复杂的过程，需要考虑多方面的因素，如功能、功耗、成本、尺寸等。请阅读下面内容帮助您选型硬件。 + +.. list:: + + - `产品选型工具 `_ 可以帮助您了解不同乐鑫产品的硬件区别。 + - `技术规格书 `_ 可以帮助您了解该芯片/模组所支持的硬件能力。 + - `硬件选型入门指导 `_ 可以帮助您简要对比芯片差别，了解芯片、模组、和开发板的差别以及选择指南。 + +.. note:: + **技术规格书中载明的是硬件最大能力，不代表 AT 软件能力**。例如，ESP32-C6 芯片支持 Zigbee 3.0 及 Thread 1.3，但是现有的 AT 软件方案暂未支持这两种无线协议。 + +.. _at-solution-selection: + +AT 软件方案选型 +-------------------- + +AT 软件方案是乐鑫针对不同芯片提供的 AT 固件，可以帮助您快速实现无线功能。 + +- 如果您想了解 {IDF_TARGET_NAME} 芯片详细的 AT 软件能力，请参考 :doc:`AT 命令集 <../AT_Command_Set/index>`。 +- 如果您想对比 {IDF_TARGET_NAME} 芯片不同的 AT 固件功能，请参考 :doc:`ESP-AT 固件差异 <../Compile_and_Develop/esp-at_firmware_differences>`。 + +下表列出了不同芯片对应的 AT 固件简要对比图。 + +.. list-table:: + :header-rows: 1 + + * - 芯片 + - 无线功能 + - 推荐的 AT 固件 + - 说明 + * - ESP32-C6 + - **Wi-Fi 6** + BLE 5.0 + - `v4.0.0.0 `_ + - + * - ESP32-C3 + - Wi-Fi 4 + BLE 5.0 + - `v3.3.0.0 `_ + - + * - ESP32-C2 + - Wi-Fi 4 (或 BLE 5.0) + - `v3.3.0.0 `_ + - + * - ESP32 + - Wi-Fi 4 + BLE v4.2 (+ **BT**) + - `v3.4.0.0 `_ + - + * - ESP32-S2 + - Wi-Fi 4 + - `v3.4.0.0 `_ + - 推荐使用性价比更高的 ESP32-C 系列 + +- ``(或 BLE 5.0)`` 表示 AT 软件方案中支持低功耗蓝牙功能，但发布的固件中未包含此功能。 +- ``(+ BT)`` 表示 AT 软件方案中支持经典蓝牙功能，但发布的固件中未包含此功能。 + +.. note:: + 出厂的模组或芯片中，均未烧录 AT 固件。若您有量产需求，请及时联系对接的商务人员或 sales@espressif.com，我们将提供定制生产。 + +.. _firmware-selection: + +我该选哪种类型的 AT 固件？ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ESP-AT 固件有以下几种类型，其中下载或准备固件的工作量自上而下依次递增，支持的模组类型也自上而下依次递增。 + +.. contents:: + :local: + :depth: 1 + +.. _official-released-firmware: + +官方发布版固件（推荐） +"""""""""""""""""""""""" + +**官方发布版固件** 又称“发布版固件”、“官方固件”、“默认固件”，为乐鑫官方团队测试通过并发布的固件，固件会根据内部开发计划周期性发布，此种固件可直接基于乐鑫 OTA 服务器升级固件。如果 **官方发布版固件** 完全满足您的项目需求，建议您优先选择 **官方发布版固件**。如果官方固件不支持您的模组，您可以根据 :doc:`硬件差异 <../Compile_and_Develop/esp-at_firmware_differences>`，选择和您的模组硬件配置相近的固件进行测试验证。 + +.. list:: + + - 获取途径：:doc:`{IDF_TARGET_NAME} AT 固件 <../AT_Binary_Lists/esp_at_binaries>` + - 优点： + + - 稳定 + - 可靠 + - 获取固件工作量小 + + - 缺点： + + - 更新周期长 + - 覆盖的模组有限 + + - 参考文档： + + - :doc:`硬件连接 <../Get_Started/Hardware_connection>` + - :doc:`固件下载及烧录指南 <../Get_Started/Downloading_guide>` + - 有关 ESP-AT 固件支持/不支持哪些芯片系列，请参考 ESP-AT GitHub 首页 `readme.md `_ + +.. _github-temporary-firmware: + +GitHub 临时固件 +"""""""""""""""""""""""" + +**GitHub 临时固件** 为每次将代码推送到 GiHub 时都会生成但并未达到固件发布周期条件的固件，或者说是开发中的固件，包括 **官方发布版固件** 的临时版本和适配过但是不计划正式发布的固件，其中前者可直接基于乐鑫 OTA 服务器升级固件。 + +- 获取途径：请参考 :doc:`../Compile_and_Develop/How_to_download_the_latest_temporary_version_of_AT_from_github`。 +- 优点： + + - 实时性强，新的特性和漏洞修补都会实时同步出来。 + - 包含一些非正式发布的固件，如基于 SDIO 通讯的固件、基于 SPI 通讯的固件。 + - 获取固件工作量小。 + +- 缺点：基于非正式发布的 commit 生成的固件未经过完整的测试，可能会存在一些风险，需要您自己做完整的测试。 + +.. _firmware-modify-paras-not-source-code: + +修改参数的固件 +"""""""""""""""""""""""" + +**修改参数的固件** 指的是只修改参数区域而并不需要重新编译的固件，适用于固件功能满足项目要求、但只有某些参数不满足的情况下，如 UART 波特率、UART GPIO 管脚等参数的变更，此种固件可直接基于乐鑫 OTA 服务器升级固件。 + +- 关于如何修改参数文件，请参考 :doc:`../Compile_and_Develop/tools_at_py`。 +- 优点： + + - 不需要重新编译固件。 + - 固件稳定、可靠。 + +- 缺点：需要基于发布版的固件修改，更新周期长，覆盖的模组有限。 + +.. _self-compiled-firmware: + +自行编译的固件 +"""""""""""""""""""""""" + +当您需要进行二次开发时可采用此种方式。需要自己部署 OTA 服务器以支持 OTA 功能。 + +- 关于如何自行编译固件，请参考 :doc:`../Compile_and_Develop/How_to_clone_project_and_compile_it`。 +- 优点：功能、周期自己可控。 +- 缺点：需要自己搭建环境编译。 + +如果您希望稳定性优先，推荐基于该芯片最新已发布的版本对应的分支开发您的 AT 固件。如果您希望更多新功能，推荐基于 `master 分支 `_ 开发您的 AT 固件。 + +项目初期准备 +------------ + +项目初期准备阶段， **强烈建议** 您选择 `乐鑫开发板 `_ 开始您的项目。在项目初期，能够帮助您快速原型验证，评估硬件和软件能力，减少项目风险；在项目中期，能够帮助您快速功能集成和验证，性能优化，提高开发效率；在项目后期，能够帮助您快速模拟和定位问题，实现产品快速迭代。 + +如果您是 :ref:`self-compiled-firmware`，建议您优先选择 Linux 系统作为开发环境。 diff --git a/docs/zh_CN/Get_Started/What_is_ESP-AT.rst b/docs/zh_CN/Get_Started/What_is_ESP-AT.rst index 9ca64a974..3d7c05f33 100644 --- a/docs/zh_CN/Get_Started/What_is_ESP-AT.rst +++ b/docs/zh_CN/Get_Started/What_is_ESP-AT.rst @@ -3,7 +3,7 @@ ESP-AT 是什么 :link_to_translation:`en:[English]` -ESP-AT 是乐鑫开发的可直接用于量产的物联网应用固件，旨在降低客户开发成本，快速形成产品。通过 ESP-AT 指令，您可以快速加入无线网络、连接云平台、实现数据通信以及远程控制等功能，真正的通过无线通讯实现万物互联。 +ESP-AT 是乐鑫开发的可直接用于量产的物联网应用固件，旨在降低客户开发成本，快速形成产品。通过 ESP-AT 命令，您可以快速加入无线网络、连接云平台、实现数据通信以及远程控制等功能，真正的通过无线通讯实现万物互联。 ESP-AT 是基于 ESP-IDF 实现的软件工程。它使 {IDF_TARGET_NAME} 模组作为从机，MCU 作为主机。MCU 发送 AT 命令给 {IDF_TARGET_NAME} 模组，控制 {IDF_TARGET_NAME} 模组执行不同的操作，并接收 {IDF_TARGET_NAME} 模组返回的 AT 响应。ESP-AT 提供了大量功能不同的 AT 命令，如 Wi-Fi 命令、TCP/IP 命令、Bluetooth LE 命令、Bluetooth 命令、MQTT 命令、HTTP 命令、Ethernet 命令等。 diff --git a/docs/zh_CN/Get_Started/index.rst b/docs/zh_CN/Get_Started/index.rst index 661c59354..9d8009c82 100644 --- a/docs/zh_CN/Get_Started/index.rst +++ b/docs/zh_CN/Get_Started/index.rst @@ -4,15 +4,16 @@ :link_to_translation:`en:[English]` -本指南详细介绍 ESP-AT 是什么、如何连接硬件、以及如何下载和烧录 AT 固件，由以下章节组成： +本指南详细介绍 ESP-AT 是什么、技术选型、如何连接硬件、以及如何下载和烧录 AT 固件，由以下章节组成： .. toctree:: :maxdepth: 1 ESP-AT 是什么 + 技术选型 硬件连接 下载指导 如果您尚不了解 ESP-AT 工程，请阅读 :doc:`What_is_ESP-AT`。 -如果您想学习如何使用 ESP-AT，请首先阅读 :doc:`Hardware_connection`，了解所需的硬件以及硬件之间如何连接，然后再阅读 :doc:`Downloading_guide`，了解如何下载和烧录 AT 固件。 +如果您想学习如何使用 ESP-AT，请首先阅读 :doc:`Technology_selection`，帮助您选型硬件和软件，再阅读 :doc:`Hardware_connection`，了解所需的硬件以及硬件之间如何连接，然后再阅读 :doc:`Downloading_guide`，了解如何下载和烧录 AT 固件。 diff --git a/docs/zh_CN/about.rst b/docs/zh_CN/about.rst index b8e0b416a..0502367ba 100644 --- a/docs/zh_CN/about.rst +++ b/docs/zh_CN/about.rst @@ -18,7 +18,7 @@ - 内置 TCP/IP 堆栈和数据缓冲 - 能便捷地集成到资源受限的主机平台中 -- 主机对指令的回应易于解析 +- 主机对命令的回应易于解析 - 用户可自定义 AT 命令 .. figure:: ../_static/about-esp-at-commands.png diff --git a/docs/zh_CN/faq.rst b/docs/zh_CN/faq.rst index b27875c19..7835d2bd7 100644 --- a/docs/zh_CN/faq.rst +++ b/docs/zh_CN/faq.rst @@ -156,7 +156,7 @@ AT 命令中串口波特率是否可以修改？（默认：115200） - 第一种方法，您可以通过串口命令 :ref:`AT+UART_CUR ` 或 :ref:`AT+UART_DEF `。 - 第二种方法，您可以重新编译 AT 固件，编译介绍： :doc:`如何编译 AT 工程 ` 与 :doc:`修改 UART 波特率配置 `。 -{IDF_TARGET_NAME} 使用 AT 指令进入透传模式，如果连接的热点断开，{IDF_TARGET_NAME} 能否给出相应的提示信息？ +{IDF_TARGET_NAME} 使用 AT 命令进入透传模式，如果连接的热点断开，{IDF_TARGET_NAME} 能否给出相应的提示信息？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - 可以通过命令 :ref:`AT+SYSMSG ` 进行配置，可设置 AT+SYSMSG=4，如果连接的热点断开，串口会上报 "WIFI DISCONNECT\\r\\n"。 diff --git a/docs/zh_CN/index.rst b/docs/zh_CN/index.rst index defeabcfd..d3ab67d36 100644 --- a/docs/zh_CN/index.rst +++ b/docs/zh_CN/index.rst @@ -3,7 +3,7 @@ ESP-AT 用户指南 :link_to_translation:`en:[English]` -这里是乐鑫 `ESP-AT `_ 开发框架的文档中心。ESP-AT 作为由 `Espressif Systems `_ 发起和提供技术支持的官方项目，适用于 Windows、Linux、macOS 上的 `ESP32、ESP32-C2、ESP32-C3、ESP32-C6、ESP32-S2、和 ESP8266 `_ 系列芯片。 +这里是乐鑫 `ESP-AT `_ 开发框架的文档中心。ESP-AT 作为由 `Espressif Systems `_ 发起和提供技术支持的官方项目，适用于 Windows、Linux、macOS 上的 `ESP32、ESP32-C2、ESP32-C3、ESP32-C6、和 ESP32-S2 `_ 系列芯片。 .. only:: html @@ -48,6 +48,7 @@ ESP-AT 用户指南 AT Binary 列表 AT 命令集 AT 命令示例 + AT 版本简介 编译和开发 第三方定制化 AT 命令和固件 FAQ diff --git a/docs/zh_CN/versions.rst b/docs/zh_CN/versions.rst new file mode 100644 index 000000000..25ab1b44b --- /dev/null +++ b/docs/zh_CN/versions.rst @@ -0,0 +1,183 @@ +ESP-AT 版本简介 +================ + +:link_to_translation:`en:[English]` + +本文档主要介绍了 ESP-AT 的版本、如何选择版本、版本管理、支持期限、查看版本、和订阅 AT 发布等内容。 + +发布版本 +--------- + +ESP-AT 在 GitHub 平台上的完整发布历史请见 `发布说明页面 `_。您可以在该页面查看各个版本的 AT 固件、发布说明、配套文档及相应获取方式。 + +我该选择哪个版本？ +---------------------- + +请阅读 :ref:`AT 软件方案选型 `。 + +.. _versioning-scheme: + +版本管理 +----------------- + +ESP-AT 发布固件管理 +^^^^^^^^^^^^^^^^^^^^^^^^ + +ESP-AT 发布是针对芯片的，通常是指发布一个或者几个芯片的 AT 固件。ESP-AT :doc:`发布的 AT 固件 ` 所支持的 AT 命令集通常是向后兼容的。这意味着，您可以将新版本的 AT 固件更新至旧版本的设备中。 + +ESP-AT 发布的固件采用了和 `语义版本管理方法 `_ 类似的方式，即您可以从字面含义理解每个版本的差异。例如 ``v3.3.0.0``， ``v`` 代表版本，其后为版本号，版本号的格式如下： + +:: + + ... + +其中： + +- 为主要版本。例如 ``v4.0.0.0`` 代表有重大更新，通常包括引入新的芯片支持、新特性、和问题修复。 +- 为次要版本。例如 ``v3.3.0.0`` 代表有较大更新，通常包括新增特性、ESP-IDF 版本升级、和问题修复。 +- 为修复版本，也叫 bugfix 版本。例如 ``v2.4.2.0`` 代表仅修复了一些问题，并不增加任何新特性。 +- 为自定义版本。通常用于下游代理商、或定制项目的版本。 + +ESP-AT 发布分支管理 +^^^^^^^^^^^^^^^^^^^^^^^^ + +ESP-AT 发布 AT 固件的同时，如果有主要版本或者次要版本的更新，会创建一个新的 `发布分支 `_。 + +ESP-AT 发布的分支采用了和 `语义版本管理方法 `_ 类似的方式，即您可以从字面含义理解每个版本的差异。例如 ``release/v3.3.0.0``， ``release`` 代表着发布的分支， ``v`` 代表着发布分支的版本，其后为版本号，版本号的格式如下： + +:: + + ..0.0 + +其中： + +- 为主要版本。例如 ``release/v4.0.0.0`` 代表有重大更新，通常包括引入新的芯片支持、新特性、和问题修复。 +- 为次要版本。例如 ``release/v3.3.0.0`` 代表有较大更新，通常包括新增特性、ESP-IDF 版本升级、和问题修复。 + +通常情况下，待发布的 AT 固件会在发布分支上进行多轮测试，直到没有重大问题后，会发布 AT 固件并同步发布分支到 GitHub。 + +- 新的特性开发通常会在 master 分支上进行，不会合并到发布分支上。 +- 问题修复通常会在 master 分支上进行，如果问题严重，会合并到发布分支上。 + +支持期限 +--------------- + +ESP-AT 的每个主要版本和次要版本都有相应的支持期限。支持期限满后，版本停止更新维护，将不再提供支持。由于 ESP-AT 是基于 ESP-IDF 开发的项目，因此 ESP-AT 的支持期限是受限于 ESP-IDF 的支持期限。当前 ESP-AT 各版本信息如下： + +.. list-table:: + :header-rows: 1 + :width: 100% + + * - AT 版本（发布时间） + - 发布固件适用芯片 + - IDF 版本 + - IDF 支持期限截止 + - AT 新版本迭代计划 + * - **v4.0.0.0** (2023.12.29) + - ESP32-C6 + - `v5.1.2 `_ + - 2025.12.30 + - 2025.7.30 - 2025.9.30 + * - **v3.4.0.0** (2024.6.7) + - + * ESP32 + * ESP32-S2 + - `v5.0.6 `_ + - 2025.5.29 + - 2024.12.29 - 2025.2.28 + * - **v3.3.0.0** (2024.5.9) + - + * ESP32-C2 + * ESP32-C3 + - `v5.0.6 `_ + - 2025.5.29 + - 2024.12.29 - 2025.2.28 + * - **v3.2.0.0** (2023.7.28) + - + * ESP32 + * ESP32-C3 + - ~v5.0.3 (`24b9d38 `_) + - 2025.5.29 + - + * ESP32 已发布新版本 v3.4.0.0 + * ESP32-C3 已发布新版本 v3.3.0.0 + +**ESP-AT 各发布版本支持期限如下：** + +.. figure:: ../_static/at-support-periods.png + :align: center + :alt: ESP-AT 版本支持期限 + :figclass: align-center + + ESP-AT 版本支持期限 + +- 支持期限的服务期 + + 通常为从 AT 发布该芯片的 AT 固件开始，到计划发布该芯片下一个 AT 版本为止。下一个 AT 版本的发布时间通常在该芯片有重大问题需要修复，或者对应的 `ESP-IDF 支持期限 `_ 结束前几个月（AT 发布说明中有介绍该芯片对应的 ESP-IDF 版本）。 + +- 支持期限的维护期 + + 通常为从服务期结束后，到该芯片对应的 `ESP-IDF 支持期限 `_ 结束（AT 发布说明中有介绍该芯片对应的 ESP-IDF 版本）。例如，ESP-IDF v5.0 的支持期限到 2025 年 5 月 29 日，那么 ESP-AT v3.0 ~ v3.3 的维护期限也到 2025 年 5 月 29 日。 + +一般而言： + +- 一旦 AT 发布新的版本，则旧版本的支持期限的服务期结束，进入支持期限的维护期。 + + 例如，AT 发布了 v3.3.0.0 版本（针对 ESP32-C2 和 ESP32-C3 芯片），那么 ESP32-C3 的 v3.2.0.0 版本的支持期限的服务期结束，进入支持期限的维护期；ESP32-C2 的 v3.1.0.0 版本的支持期限的服务期结束，进入支持期限的维护期。 + +- 如您有 GitHub 账号，请 :ref:`sub-at-release` ，GitHub 将会在新版本发布的时候通知您。当您所使用的 AT 固件有 Bugfix 版本发布时，请做好升级至该 Bugfix 版本的规划。 +- 请确保您所使用的版本停止更新维护前，已做好升级至新版本的规划。 +- 在支持期限内意味着 ESP-AT 团队将继续在 GitHub 的发布分支上进行重要 bug 修复、安全修复等，并根据需要定期发布新的 Bugfix 版本。 + +查看当前 AT 固件版本 +---------------------------- + +请发送 :ref:`AT+GMR ` 命令查看 AT 固件版本信息，参考 :ref:`AT+GMR ` 命令下的参数说明了解更多信息。 + +.. _sub-at-release: + +订阅 AT 版本发布 +-------------------- + +* :ref:`at-sr-github-login` +* :ref:`at-sr-watch-custom` +* :ref:`at-sr-release-apply` + +.. _at-sr-github-login: + +第一步：登录您的 GitHub 账号 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +在开始之前，请先 `登录您的 GitHub 账号 `_，因为订阅发布需要登录权限。 + +.. _at-sr-watch-custom: + +第二步：选择定制化的通知 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +访问 `ESP-AT 仓库 `_，点击页面右上角的 ``Watch``，再点击 ``Custom``。 + + .. figure:: ../_static/at-sub-release-custom.png + :align: center + :alt: + :figclass: align-center + :scale: 70% + + 定制化通知（点击放大） + +.. _at-sr-release-apply: + +第三步：定制发布应用 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +勾选 ``Releases`` 并点击 ``Apply``。 + + .. figure:: ../_static/at-sub-release-apply.png + :align: center + :alt: + :figclass: align-center + :scale: 70% + + 定制发布应用（点击放大） + +这样就完成了订阅 AT 发布的操作。当有新的 AT 版本发布时，您将会收到 GitHub 的通知。