diff --git a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h index dd48ab982d..f81ad21800 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h @@ -1455,7 +1455,7 @@ esp_err_t esp_ble_gap_config_local_privacy (bool privacy_enable); * * * @param[in] icon - External appearance value, these values are defined by the Bluetooth SIG, please refer to - * https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.characteristic.gap.appearance.xml + * https://specificationrefs.bluetooth.com/assigned-values/Appearance%20Values.pdf * * @return * - ESP_OK : success diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst index bb50901242..5e652ea7b1 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst @@ -527,11 +527,13 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m 3.2 Why is the Wi-Fi throughput so low when Wi-Fi and ESP-BLE-MESH coexist? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The `ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>`_ board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps. + .. only:: esp32 - And some configurations in menuconfig shall be enabled to support PSRAM. + The :doc:`ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>` board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps. - - :code:`ESP32-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...` + Some configurations in menuconfig shall be enabled to support PSRAM. + + - :code:`{IDF_TARGET_NAME}-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...` - :code:`Bluetooth --> Bluedroid Enable --> BT/BLE will first malloc the memory from the PSRAM` - :code:`Bluetooth --> Bluedroid Enable --> Use dynamic memory allocation in BT/BLE stack.` - :code:`Bluetooth --> Bluetooth controller --> BLE full scan feature supported.` diff --git a/docs/en/api-reference/api-conventions.rst b/docs/en/api-reference/api-conventions.rst index f47911c2b4..008dcf84d7 100644 --- a/docs/en/api-reference/api-conventions.rst +++ b/docs/en/api-reference/api-conventions.rst @@ -9,7 +9,7 @@ ESP-IDF provides several kinds of programming interfaces: * C functions, structures, enums, type definitions and preprocessor macros declared in public header files of ESP-IDF components. Various pages in the API Reference section of the programming guide contain descriptions of these functions, structures and types. * Build system functions, predefined variables and options. These are documented in the :ref:`build system guide`. -* `Kconfig `_ options can can be used in code and in the build system (CMakeLists.txt) files. +* :doc:`Kconfig ` options can can be used in code and in the build system (CMakeLists.txt) files. * :doc:`Host tools <../api-guides/tools/index>` and their command line parameters are also part of ESP-IDF interface. ESP-IDF consists of components written specifically for ESP-IDF as well as third-party libraries. In some cases, an ESP-IDF-specific wrapper is added to the third-party library, providing an interface that is either simpler or better integrated with the rest of ESP-IDF facilities. In other cases, the original API of the third-party library is presented to the application developers. @@ -96,7 +96,7 @@ It is not recommended to reference these components directly in custom projects API Stability ------------- -ESP-IDF uses `Semantic Versioning `_ as explained in the :ref:`versions page`. +ESP-IDF uses `Semantic Versioning `_ as explained in the :ref:`versions page`. Minor and bugfix releases of ESP-IDF guarantee compatibility with previous releases. The sections below explain different aspects and limitations to compatibility. @@ -109,7 +109,7 @@ The following changes are allowed between minor versions and do not break source * Deprecating functions (using the ``deprecated`` attribute) and header files (using a preprocessor ``#warning``). Deprecations are listed in ESP-IDF relese notes. It is recommended to update the source code to use the newer functions or files that replace the deprecated ones, however this is not mandatory. Deprecated functions and files can be removed in major versions of ESP-IDF. * Renaming components, moving source and header files between components — provided that the build system ensures that correct files are still found. -* Renaming Kconfig options. Kconfig system `renaming mechanism `_ ensures that the original Kconfig option names can still be used by the application in ``sdkconfig`` file, CMake files and source code. +* Renaming Kconfig options. Kconfig system :ref:`renaming mechanism ` ensures that the original Kconfig option names can still be used by the application in ``sdkconfig`` file, CMake files and source code. Lack of binary compatibility ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -132,7 +132,7 @@ While we try to make upgrading to a new ESP-IDF version easy, there are parts of * Changes made to mitigate security issues or to replace insecure default behaviors with a secure ones. * Features which were never functional. For example, if it was never possible to use a certain function or an enumeration value, it may get renamed (as part of fixing it) or removed. This includes software features which depend on non-functional chip hardware features. * Unexpected or undefined behavior (for example, due to missing validation of argument ranges) that is not documented explicitly may be fixed/changed. -* Location of `Kconfig `_ options in menuconfig. +* Location of :doc:`Kconfig ` options in menuconfig. * Location and names of example projects. .. _designated initializers: https://en.cppreference.com/w/c/language/struct_initialization diff --git a/docs/en/api-reference/peripherals/touch_pad.rst b/docs/en/api-reference/peripherals/touch_pad.rst index d224757f00..025921e7f7 100644 --- a/docs/en/api-reference/peripherals/touch_pad.rst +++ b/docs/en/api-reference/peripherals/touch_pad.rst @@ -25,7 +25,7 @@ In-depth design details of touch sensors and firmware development guidelines for .. only:: SOC_TOUCH_VERSION_1 - For more information about testing touch sensors in various configurations, please check the `Guide for ESP32-Sense-Kit `_. + For more information about testing touch sensors in various configurations, please check the `Guide for ESP32-Sense-Kit `_. Functionality Overview ---------------------- diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index 8eaf0d530a..72c65539a7 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -151,12 +151,14 @@ Implementation Notes Knowledge about the regions of memory in the chip comes from the "soc" component, which contains memory layout information for the chip, and the different capabilities of each region. Each region's capabilities are prioritised, so that (for example) dedicated DRAM and IRAM regions will be used for allocations ahead of the more versatile D/IRAM regions. -Each contiguous region of memory contains its own memory heap. The heaps are created using the `multi_heap `_ functionality. multi_heap allows any contiguous region of memory to be used as a heap. +Each contiguous region of memory contains its own memory heap. The heaps are created using the :ref:`multi_heap ` functionality. multi_heap allows any contiguous region of memory to be used as a heap. The heap capabilities allocator uses knowledge of the memory regions to initialize each individual heap. Allocation functions in the heap capabilities API will find the most appropriate heap for the allocation (based on desired capabilities, available space, and preferences for each region's use) and then calling :cpp:func:`multi_heap_malloc` or :cpp:func:`multi_heap_calloc` for the heap situated in that particular region. Calling ``free()`` involves finding the particular heap corresponding to the freed address, and then calling :cpp:func:`multi_heap_free` on that particular multi_heap instance. +.. _multi-heap: + API Reference - Multi Heap API ------------------------------ diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 4675b79549..a09eedbf86 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -1136,7 +1136,7 @@ CMake 在许多开源的 C/C++ 项目中广泛使用，用户可以在自己的 实际的案例请参考 :example:`build_system/cmake/import_lib`。请注意，导入第三方库所需要做的工作可能会因库的不同而有所差异。建议仔细阅读第三方库的文档，了解如何将其导入到其它项目中。阅读第三方库的 CMakeLists.txt 文件以及构建结构也会有所帮助。 -用这种方式还可以将第三方库封装成 ESP-IDF 的组件。例如 :component:`mbedtls` 组件就是封装了 `mbedtls 项目 `_ 得到的。详情请参考 :component_file:`mbedtls 组件的 CMakeLists.txt 文件 `。 +用这种方式还可以将第三方库封装成 ESP-IDF 的组件。例如 :component:`mbedtls` 组件就是封装了 `mbedtls 项目 `_ 得到的。详情请参考 :component_file:`mbedtls 组件的 CMakeLists.txt 文件 `。 每当使用 ESP-IDF 构建系统时，CMake 变量 ``ESP_PLATFORM`` 都会被设置为 1。如果要在通用的 CMake 代码加入 IDF 特定的代码时，可以采用 ``if (ESP_PLATFORM)`` 的形式加以分隔。 @@ -1582,7 +1582,7 @@ CMake 中不可用的功能 - ``COMPONENT_OBJS``：以前，可以以目标文件列表的方式指定组件源，现在，可以通过 ``COMPONENT_SRCS`` 以源文件列表的形式指定组件源。 - ``COMPONENT_OBJEXCLUDE``：已被 ``COMPONENT_SRCEXCLUDE`` 替换。用于指定源文件（绝对路径或组件目录的相对路径）。 - ``COMPONENT_EXTRA_CLEAN``：已被 ``ADDITIONAL_MAKE_CLEAN_FILES`` 属性取代，注意，:ref:`CMake 对此项功能有部分限制 `。 -- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``：已被 CMake `外部项目 `_ 替代，详细内容请参阅 :ref:`component-build-full-override`。 +- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``：已被 CMake `外部项目 ` 替代，详细内容请参阅 :ref:`component-build-full-override`。 - ``COMPONENT_CONFIG_ONLY``：已被 ``register_config_only_component()`` 函数替代，请参阅 :ref:`config_only_component`。 - ``CFLAGS``、``CPPFLAGS``、``CXXFLAGS``：已被相应的 CMake 命令替代，请参阅 :ref:`component_build_control`。 diff --git a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst index 377444b907..5983bb7b2a 100644 --- a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst +++ b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst @@ -530,11 +530,13 @@ ESP-BLE-MESH 常见问题手册 3.2 Wi-Fi 和 ESP-BLE-MESH 共存时，为什么 Wi-Fi 吞吐量很低？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - 未搭载 PSRAM 的 `ESP32-DevKitC <../../hw-reference/get-started-devkitc>`_ 开发板，Wi-Fi 和 ESP-BLE-MESH 共存可以正常运行，但是吞吐率较低。当 Wi-Fi 和 ESP-BLE-MESH 共存时，搭载 PSRAM 的 ESP32-DevKitC 速率可以稳定在 1 Mbps 以上。 + .. only:: esp32 + + 未搭载 PSRAM 的 :doc:`ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>` 开发板，Wi-Fi 和 ESP-BLE-MESH 共存可以正常运行，但是吞吐率较低。当 Wi-Fi 和 ESP-BLE-MESH 共存时，搭载 PSRAM 的 ESP32-DevKitC 速率可以稳定在 1 Mbps 以上。 应使能 menuconfig 中的一些配置来支持 PSRAM。 - - :code:`ESP32-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...` + - :code:`{IDF_TARGET_NAME}-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...` - :code:`Bluetooth --> Bluedriod Enable --> BT/BLE will first malloc the memory from the PSRAM` - :code:`Bluetooth --> Bluedriod Enable --> Use dynamic memory allocation in BT/BLE stack.` - :code:`Bluetooth --> Blutooth controller --> BLE full scan feature supported.` diff --git a/docs/zh_CN/api-reference/peripherals/touch_pad.rst b/docs/zh_CN/api-reference/peripherals/touch_pad.rst index 17658dc8f9..703d8d471f 100644 --- a/docs/zh_CN/api-reference/peripherals/touch_pad.rst +++ b/docs/zh_CN/api-reference/peripherals/touch_pad.rst @@ -25,7 +25,7 @@ .. only:: SOC_TOUCH_VERSION_1 - 如果想评估触摸传感器的多种应用场景，请查看 `ESP32 触摸功能开发套件 `_。 + 如果想评估触摸传感器的多种应用场景，请查看 `ESP32 触摸功能开发套件 `_。 功能介绍 ---------------------- diff --git a/docs/zh_CN/hw-reference/esp32/user-guide-devkits-r-v1.1.rst b/docs/zh_CN/hw-reference/esp32/user-guide-devkits-r-v1.1.rst index 6460088a88..46fe1cec1a 100644 --- a/docs/zh_CN/hw-reference/esp32/user-guide-devkits-r-v1.1.rst +++ b/docs/zh_CN/hw-reference/esp32/user-guide-devkits-r-v1.1.rst @@ -9,9 +9,9 @@ ESP32-DevKitS(-R) ESP32-DevKitS(-R) 包括两款开发板，分别是 ESP32-DevKitS 和 ESP32-DevKitS-R。S 代表弹簧 (spring)，R 代表 WROVER 模组。 +-----------------+-------------------+ -| |ESP32-DevKitS| | |ESP32-DevKitS-R| | +| |ESP32-DevKitS| | |ESP32-DevKitS-R| | +-----------------+-------------------+ -| ESP32-DevKitS | ESP32-DevKitS-R | +| ESP32-DevKitS | ESP32-DevKitS-R | +-----------------+-------------------+ .. |ESP32-DevKitS| image:: ../../../_static/esp32-devkits-v1.1-layout-isometric-raw.png @@ -146,14 +146,14 @@ Windows 用户也可以使用 `Flash 下载工具 `_ (PDF) - `ESP32-WROOM-32D & ESP32-WROOM-32U 技术规格书 `_ (PDF) - `ESP32-SOLO-1 技术规格书 `_ (PDF) -- `ESP32-WROVER 技术规格书 `_ (PDF) +- `ESP32-WROVER 技术规格书 `_ (PDF) - `ESP32-WROVER-B 技术规格书 `_ (PDF) -- `乐鑫产品选型工具 `__ +- `乐鑫产品选型工具 `__ \ No newline at end of file