diff --git a/docs/en/api-reference/peripherals/i2c.rst b/docs/en/api-reference/peripherals/i2c.rst index f138601ad5..cf2676bf28 100644 --- a/docs/en/api-reference/peripherals/i2c.rst +++ b/docs/en/api-reference/peripherals/i2c.rst @@ -82,12 +82,12 @@ Configuration example (master): int i2c_master_port = 0; i2c_config_t conf = { .mode = I2C_MODE_MASTER, - .sda_io_num = I2C_MASTER_SDA_IO, // select GPIO specific to your project + .sda_io_num = I2C_MASTER_SDA_IO, // select SDA GPIO specific to your project .sda_pullup_en = GPIO_PULLUP_ENABLE, - .scl_io_num = I2C_MASTER_SCL_IO, // select GPIO specific to your project + .scl_io_num = I2C_MASTER_SCL_IO, // select SCL GPIO specific to your project .scl_pullup_en = GPIO_PULLUP_ENABLE, .master.clk_speed = I2C_MASTER_FREQ_HZ, // select frequency specific to your project - .clk_flags = 0, // you can use I2C_SCLK_SRC_FLAG_* flags to choose i2c source clock here + .clk_flags = 0, // optional; you can use I2C_SCLK_SRC_FLAG_* flags to choose i2c source clock here }; .. only:: SOC_I2C_SUPPORT_SLAVE @@ -98,15 +98,15 @@ Configuration example (master): int i2c_slave_port = I2C_SLAVE_NUM; i2c_config_t conf_slave = { - .sda_io_num = I2C_SLAVE_SDA_IO, // select GPIO specific to your project + .sda_io_num = I2C_SLAVE_SDA_IO, // select SDA GPIO specific to your project .sda_pullup_en = GPIO_PULLUP_ENABLE, - .scl_io_num = I2C_SLAVE_SCL_IO, // select GPIO specific to your project + .scl_io_num = I2C_SLAVE_SCL_IO, // select SCL GPIO specific to your project .scl_pullup_en = GPIO_PULLUP_ENABLE, .mode = I2C_MODE_SLAVE, .slave.addr_10bit_en = 0, - .slave.slave_addr = ESP_SLAVE_ADDR, // address of your project + .slave.slave_addr = ESP_SLAVE_ADDR, // slave address of your project .slave.maximum_speed = I2C_SLAVE_MAX_SPEED // expected maximum clock speed - .clk_flags = 0, // you can use I2C_SCLK_SRC_FLAG_* flags to choose i2c source clock here + .clk_flags = 0, // optional; you can use I2C_SCLK_SRC_FLAG_* flags to choose I2C source clock here }; At this stage, :cpp:func:`i2c_param_config` also sets a few other I2C configuration parameters to default values that are defined by the I2C specification. For more details on the values and how to modify them, see :ref:`i2c-api-customized-configuration`. @@ -281,7 +281,7 @@ The example below shows how to build a command link for an I2C master to read *n :align: center -Compared to writing data, the command link is populated in Step 4 not with ``i2c_master_write...`` functions but with :cpp:func:`i2c_master_read_byte` and / or :cpp:func:`i2c_master_read`. Also, the last read in Step 5 is configured so that the master does not provide the ACK bit. +Compared to writing data, the command link is populated in Step 4 not with ``i2c_master_write...`` functions but with :cpp:func:`i2c_master_read_byte` and/or :cpp:func:`i2c_master_read`. Also, the last read in Step 5 is configured so that the master does not provide the ACK bit. Indicating Write or Read diff --git a/docs/en/api-reference/peripherals/spi_flash/index.rst b/docs/en/api-reference/peripherals/spi_flash/index.rst index 1531a4eed9..b0111803c3 100644 --- a/docs/en/api-reference/peripherals/spi_flash/index.rst +++ b/docs/en/api-reference/peripherals/spi_flash/index.rst @@ -13,7 +13,7 @@ For higher-level API functions which work with partitions defined in the :doc:`p .. note:: ``esp_partition_*`` APIs are recommended to be used instead of the lower level ``esp_flash_*`` API functions when accessing the main SPI Flash chip, since they do bounds checking and are guaranteed to calculate correct offsets in flash based on the information in the partition table. ``esp_flash_*`` functions can still be used directly when accessing an external (secondary) SPI flash chip. -Different from the API before IDF v4.0, the functionality of ``esp_flash_*`` APIs is not limited to the "main" SPI flash chip (the same SPI flash chip from which program runs). With different chip pointers, you can access external flash chips connected to not only SPI0/1 but also other SPI buses like SPI2. +Different from the API before ESP-IDF v4.0, the functionality of ``esp_flash_*`` APIs is not limited to the "main" SPI flash chip (the same SPI flash chip from which program runs). With different chip pointers, you can access external flash chips connected to not only SPI0/1 but also other SPI buses like SPI2. .. note:: @@ -35,7 +35,7 @@ Support for Features of Flash Chips Quad/Dual Mode Chips ^^^^^^^^^^^^^^^^^^^^ -Features of different flashes are implemented in different ways and thus need speical support. The fast/slow read and Dual mode (DOUT/DIO) of almost all 24-bits address flash chips are supported, because they don't need any vendor-specific commands. +Features of different flashes are implemented in different ways and thus need special support. The fast/slow read and Dual mode (DOUT/DIO) of almost all 24-bit address flash chips are supported, because they don't need any vendor-specific commands. Quad mode (QIO/QOUT) is supported on following chip types: @@ -49,7 +49,7 @@ Quad mode (QIO/QOUT) is supported on following chip types: .. note:: - For every flash chip vendor listed above will only be supported by default when the flash is officially supported. If you want to enable/disable the flash series you can go through Kconfig manu ``Auto-detect flash chips``. + Flash vendors listed above will only be supported by default when the flash is officially supported. You can also enable or disable the flash series in the Kconfig menu ``Auto-detect flash chips``. Optional Features ^^^^^^^^^^^^^^^^^ @@ -71,7 +71,7 @@ There are some features that are not supported by all flash chips, or not suppor - High performance mode (HPM) - means that flash works under high frequency which is higher than 80MHz. -- Flash unique ID - means that flash supports its unique 64-bits ID. +- Flash unique ID - means that flash supports its unique 64-bit ID. .. only:: esp32c3 @@ -179,7 +179,7 @@ The ``esp_flash_t`` structure holds chip data as well as three important parts o 2. The chip driver, which provides compatibility service to different chips; 3. The OS functions, provide support of some OS functions (e.g. lock, delay) in different stages (1st/2nd boot, or the app). -Host driver +Host Driver ^^^^^^^^^^^ The host driver relies on an interface (``spi_flash_host_driver_t``) defined in the ``spi_flash_types.h`` (in the ``hal/include/hal`` folder). This interface provides some common functions to communicate with the chip. diff --git a/docs/en/migration-guides/release-5.x/5.1/peripherals.rst b/docs/en/migration-guides/release-5.x/5.1/peripherals.rst index c832623a06..9eb1a449d3 100644 --- a/docs/en/migration-guides/release-5.x/5.1/peripherals.rst +++ b/docs/en/migration-guides/release-5.x/5.1/peripherals.rst @@ -54,7 +54,7 @@ Peripherals GPSPI ----- - Following items are deprecated. Since IDF v5.1, GPSPI clock source is configurable. + Following items are deprecated. Since ESP-IDF v5.1, GPSPI clock source is configurable. - ``spi_get_actual_clock`` is deprecated, you should use :cpp:func:`spi_device_get_actual_freq` instead. diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index a19d9b5c05..d74c863d84 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -310,7 +310,7 @@ ESP-IDF 在搜索所有待构建的组件时，会按照 ``COMPONENT_DIRS`` 指 以下变量在项目级别中被设置，但可在组件 CMakeLists 中使用： - ``CONFIG_*``：项目配置中的每个值在 cmake 中都对应一个以 ``CONFIG_`` 开头的变量。更多详细信息请参阅 :doc:`Kconfig `。 -- ``ESP_PLATFORM``：ESP-IDF 构建系统处理 CMake 文件时，其值设为1。 +- ``ESP_PLATFORM``：ESP-IDF 构建系统处理 CMake 文件时，其值设为 1。 构建/项目变量 ----------------- @@ -397,7 +397,7 @@ ESP-IDF 构建系统会在命令行中添加以下 C 预处理器定义： - ``PRIV_REQUIRES`` 需要包含被当前组件的源文件 `#include` 的头文件所在的组件（除非已经被设置在了 ``REQUIRES`` 中）。以及是当前组件正常工作必须要链接的组件。 -- ``REQUIRES`` 和 ``PRIV_REQUIRES`` 的值不能依赖于任何配置选项 (``CONFIG_xxx`` 宏)。这是因为在配置加载之前，依赖关系就已经被展开。其它组件变量（比如包含路径或源文件）可以依赖配置选择。 +- ``REQUIRES`` 和 ``PRIV_REQUIRES`` 的值不能依赖于任何配置选项（``CONFIG_xxx`` 宏）。这是因为在配置加载之前，依赖关系就已经被展开。其它组件变量（比如包含路径或源文件）可以依赖配置选择。 - 如果当前组件除了 `通用组件依赖项`_ 中设置的通用组件（比如 RTOS、libc 等）外，并不依赖其它组件，那么对于上述两个 ``REQUIRES`` 变量，可以选择其中一个或是两个都不设置。 @@ -1159,7 +1159,7 @@ ESP-IDF 构建命令 - PROJECT_VER - 项目的版本/版本号，默认为 "1"。 - SDKCONFIG - 生成的 sdkconfig 文件的输出路径，根据是否设置 PROJECT_DIR，默认为 PROJECT_DIR/sdkconfig 或 CMAKE_SOURCE_DIR/sdkconfig。 - SDKCONFIG_DEFAULTS - 包含默认配置的文件列表（列表中必须包含完整的路径），默认为空；对于列表中的每个值 *filename*，如果存在的话，也会加载文件 *filename.target* 中的配置。对于列表中的 *filename* 的每一个值，也会加载文件 *filename.target* （如果存在的话）中的配置。 -- BUILD_DIR - 用于放置 ESP-IDF 构建相关工具的目录，如生成的二进制文件、文本文件、组件；默认为CMAKE_BINARY_DIR。 +- BUILD_DIR - 用于放置 ESP-IDF 构建相关工具的目录，如生成的二进制文件、文本文件、组件；默认为 CMAKE_BINARY_DIR。 - COMPONENTS - 从构建系统已知的组件中选择要处理的组件（通过 ``idf_build_component`` 添加）。这个参数用于精简构建过程。 如果在依赖链中需要其它组件，则会自动添加，即自动添加这个列表中组件的公共和私有依赖项，进而添加这些依赖项的公共和私有依赖，以此类推。如果不指定，则会处理构建系统已知的所有组件。 @@ -1357,8 +1357,6 @@ ESP-IDF 中的组件使用了第三方的 Git CMake 集成模块（:idf_file:`/t JSON 配置服务器 --------------- -.. highlight :: json - ``kconfserver`` 工具可以帮助 IDE 轻松地与配置系统的逻辑进行集成，它运行在后台，通过使用 stdin 和 stdout 读写 JSON 文件的方式与调用进程交互。 您可以通过 ``idf.py confserver`` 或 ``ninja kconfserver`` 从项目中运行 ``kconfserver``，也可以使用不同的构建生成器来触发类似的目标。 @@ -1486,7 +1484,7 @@ CMake 中不可用的功能 以下变量不再具有默认值： - 源目录（Make 中的 ``COMPONENT_SRCDIRS`` 变量，CMake 中 ``idf_component_register`` 的 ``SRC_DIRS`` 参数） -- include 目录（Make中的 ``COMPONENT_ADD_INCLUDEDIRS`` 变量，CMake中 ``idf_component_register`` 的 ``INCLUDE_DIRS`` 参数) +- include 目录（Make 中的 ``COMPONENT_ADD_INCLUDEDIRS`` 变量，CMake 中 ``idf_component_register`` 的 ``INCLUDE_DIRS`` 参数） 不再需要的变量 -------------- diff --git a/docs/zh_CN/api-reference/peripherals/i2c.rst b/docs/zh_CN/api-reference/peripherals/i2c.rst index e5b1f507cf..d6b5628337 100644 --- a/docs/zh_CN/api-reference/peripherals/i2c.rst +++ b/docs/zh_CN/api-reference/peripherals/i2c.rst @@ -12,7 +12,7 @@ I2C 是一种串行同步半双工通信协议，总线上可以同时挂载多 I2C 具有简单且制造成本低廉等优点，主要用于低速外围设备的短距离通信（一英尺以内）。 -{IDF_TARGET_NAME} 有{IDF_TARGET_I2C_NUM}个 I2C 控制器（也称为端口），负责处理在 I2C 总线上的通信。每个控制器都可以设置为主机或从机。 +{IDF_TARGET_NAME} 有 {IDF_TARGET_I2C_NUM} 个 I2C 控制器（也称为端口），负责处理在 I2C 总线上的通信。每个控制器都可以设置为主机或从机。 驱动程序的功能 --------------- @@ -82,12 +82,12 @@ I2C 驱动程序管理在 I2C 总线上设备的通信，该驱动程序具备 int i2c_master_port = 0; i2c_config_t conf = { .mode = I2C_MODE_MASTER, - .sda_io_num = I2C_MASTER_SDA_IO, // select GPIO specific to your project + .sda_io_num = I2C_MASTER_SDA_IO, // 配置 SDA 的 GPIO .sda_pullup_en = GPIO_PULLUP_ENABLE, - .scl_io_num = I2C_MASTER_SCL_IO, // select GPIO specific to your project + .scl_io_num = I2C_MASTER_SCL_IO, // 配置 SCL 的 GPIO .scl_pullup_en = GPIO_PULLUP_ENABLE, - .master.clk_speed = I2C_MASTER_FREQ_HZ, // select frequency specific to your project - // .clk_flags = 0, /*!< Optional, you can use I2C_SCLK_SRC_FLAG_* flags to choose i2c source clock here. */ + .master.clk_speed = I2C_MASTER_FREQ_HZ, // 为项目选择频率 + .clk_flags = 0, // 可选项，可以使用 I2C_SCLK_SRC_FLAG_* 标志来选择 I2C 源时钟 }; .. only:: SOC_I2C_SUPPORT_SLAVE @@ -98,14 +98,15 @@ I2C 驱动程序管理在 I2C 总线上设备的通信，该驱动程序具备 int i2c_slave_port = I2C_SLAVE_NUM; i2c_config_t conf_slave = { - .sda_io_num = I2C_SLAVE_SDA_IO, // select GPIO specific to your project + .sda_io_num = I2C_SLAVE_SDA_IO, // 配置 SDA 的 GPIO .sda_pullup_en = GPIO_PULLUP_ENABLE, - .scl_io_num = I2C_SLAVE_SCL_IO, // select GPIO specific to your project + .scl_io_num = I2C_SLAVE_SCL_IO, // 配置 SCL 的 GPIO .scl_pullup_en = GPIO_PULLUP_ENABLE, .mode = I2C_MODE_SLAVE, .slave.addr_10bit_en = 0, - .slave.slave_addr = ESP_SLAVE_ADDR, // address of your project - .clk_flags = 0, + .slave.slave_addr = ESP_SLAVE_ADDR, // 项目从机地址 + .slave.maximum_speed = I2C_SLAVE_MAX_SPEED // 预期的最大时钟速度 + .clk_flags = 0, // 可选项，可以使用 I2C_SCLK_SRC_FLAG_* 标志来选择 I2C 源时钟 }; 在此阶段，:cpp:func:`i2c_param_config` 还将其他 I2C 配置参数设置为 I2C 总线协议规范中定义的默认值。有关默认值及修改默认值的详细信息，请参考 :ref:`i2c-api-customized-configuration`。 @@ -209,9 +210,9 @@ I2C 驱动程序管理在 I2C 总线上设备的通信，该驱动程序具备 .. note:: - SCL 的时钟频率会被上拉电阻和线上电容（或是从机电容）一起影响。因此，用户需要自己选择合适的上拉电阻去保证 SCL 时钟频率是准确的。尽管 I2C 协议推荐上拉电阻值为 1K 欧姆到 10K 欧姆，但是需要根据不同的频率需要选择不同的上拉电阻。 + SCL 的时钟频率会被上拉电阻和线上电容（或是从机电容）一起影响。因此，用户需要自己选择合适的上拉电阻去保证 SCL 时钟频率是准确的。尽管 I2C 协议推荐上拉电阻值为 1 K 欧姆到 10 K 欧姆，但是需要根据不同的频率需要选择不同的上拉电阻。 - 通常来说，所选择的频率越高，需要的上拉电阻越小 （但是不要小于 1K 欧姆）。这是因为高电阻会减小电流，这会延长上升时间从而是频率变慢。通常我们推荐的上拉阻值范围为 2K 欧姆到 5K 欧姆，但是用户可能也需要根据他们的实际情况做出一些调整。 + 通常来说，所选择的频率越高，需要的上拉电阻越小（但是不要小于 1 K 欧姆）。这是因为高电阻会减小电流，这会延长上升时间从而使频率变慢。通常我们推荐的上拉阻值范围为 2 K 欧姆到 5 K 欧姆，但是用户可能也需要根据他们的实际情况做出一些调整。 .. _i2c-api-install-driver: diff --git a/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst b/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst index f236188fb4..33af2f36b0 100644 --- a/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst +++ b/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst @@ -13,7 +13,7 @@ spi_flash 组件提供外部 flash 数据读取、写入、擦除和内存映射 .. note:: 访问主 flash 芯片时，建议使用上述 ``esp_partition_*`` API 函数，而非低层级的 ``esp_flash_*`` API 函数。分区表 API 函数根据存储在分区表中的数据，进行边界检查并计算在 flash 中的正确偏移量。不过，您仍可以使用 ``esp_flash_*`` 函数直接访问外部（额外）的 SPI flash 芯片。 -与 ESP-IDF V4.0 之前的 API 不同，这一版 ``esp_flash_*`` API 功能并不局限于主 SPI flash 芯片（即运行程序的 SPI flash 芯片）。使用不同的芯片指针，您可以访问连接到 SPI0/1 或 SPI2 总线的外部 flash 芯片。 +与 ESP-IDF v4.0 之前的 API 不同，这一版 ``esp_flash_*`` API 功能并不局限于主 SPI flash 芯片（即运行程序的 SPI flash 芯片）。使用不同的芯片指针，您可以访问连接到 SPI0/1 或 SPI2 总线的外部 flash 芯片。 .. note:: @@ -23,7 +23,7 @@ spi_flash 组件提供外部 flash 数据读取、写入、擦除和内存映射 .. note:: - ESP-IDF V4.0 之后的 flash API 不再是 *原子* 的。因此，如果读操作执行过程中发生写操作，且读操作和写操作的 flash 地址出现重叠，读操作返回的数据可能会包含旧数据和新数据 (新数据为写操作更新产生的数据)。 + ESP-IDF v4.0 之后的 flash API 不再是 *原子* 的。因此，如果读操作执行过程中发生写操作，且读操作和写操作的 flash 地址出现重叠，读操作返回的数据可能会包含旧数据和新数据（新数据为写操作更新产生的数据）。 .. note:: @@ -47,6 +47,10 @@ Flash 功能支持情况 6. XMC 7. BOYA +.. note:: + + 芯片只会默认支持官方的 flash 厂家/型号。可以在 Kconfig 菜单 ``Auto-detect flash chips`` 中选择启用或禁用特定 flash 厂家/型号。 + Flash 可选的功能 ^^^^^^^^^^^^^^^^^^^^ @@ -61,13 +65,13 @@ Flash 可选的功能 - OPI flash - 表示 Flash 支持 8 线模式。 -- 32 比特地址的 flash 支持 - 通常意味着拥有大于 16MB 内存空间的大容量 flash 需要更长的地址去访问。 +- 32 比特地址的 flash 支持 - 通常意味着拥有大于 16 MB 内存空间的大容量 flash 需要更长的地址去访问。 .. only:: esp32s3 - 高性能 (HPM) 模式 - 表示 flash 工作频率大于 80MHz 。 -- flash 的私有ID (unique ID) - 表示 flash 支持它自己的 64-bits 独有 ID 。 +- flash 的私有 ID (unique ID) - 表示 flash 支持它自己的 64-bit 独有 ID 。 .. only:: esp32c3 diff --git a/docs/zh_CN/migration-guides/release-5.x/5.1/peripherals.rst b/docs/zh_CN/migration-guides/release-5.x/5.1/peripherals.rst index ebe888d5ed..92b4f7b796 100644 --- a/docs/zh_CN/migration-guides/release-5.x/5.1/peripherals.rst +++ b/docs/zh_CN/migration-guides/release-5.x/5.1/peripherals.rst @@ -47,3 +47,20 @@ - ``dac_digi_deinit`` 更新为 :cpp:func:`dac_continuous_del_channels`。 - ``dac_digi_start``、 ``dac_digi_fifo_reset`` 和 ``dac_digi_reset`` 合并为 :cpp:func:`dac_continuous_enable`。 - ``dac_digi_stop`` 更新为 :cpp:func:`dac_continuous_disable`。 + + +.. only:: SOC_GPSPI_SUPPORTED + + GPSPI + ----- + + 不再支持以下函数。从 ESP-IDF v5.1 版本起，GPSPI 时钟源可配置。 + + - ``spi_get_actual_clock`` 已废弃，更新为 :cpp:func:`spi_device_get_actual_freq`。 + +.. only:: SOC_LEDC_SUPPORTED + + LEDC + ---- + + - :cpp:enumerator:`soc_periph_ledc_clk_src_legacy_t::LEDC_USE_RTC8M_CLK` 已废弃，更新为 ``LEDC_USE_RC_FAST_CLK``。