forked from espressif/esp-idf
docs: update application examples related to system
This commit is contained in:
Linda
BOT
@ -173,6 +173,8 @@ Remaining external RAM can also be added to the capability heap allocator using
|
||||
|
||||
- The cache will not be disabled during an SPI1 flash operation, thus optimizing the code execution performance during SPI1 flash operations. For ISRs, ISR callbacks and data which might be accessed during this period, you do not need to place them in internal RAM, thus internal RAM usage can be optimized. This feature is useful for high throughput peripheral involved applications to improve the performance during SPI1 flash operations.
|
||||
|
||||
:example:`system/xip_from_psram` demonstrates the usage of XiP from PSRAM, optimizing internal RAM usage and avoiding cache disabling during flash operations from user call (e.g., flash erase/read/write operations).
|
||||
|
||||
.. only:: esp32p4
|
||||
|
||||
.. _external_ram_config_xip:
|
||||
|
||||
@ -192,6 +192,12 @@ Standard I/O streams (``stdin``, ``stdout``, ``stderr``) are mapped to file desc
|
||||
|
||||
Note that creating an eventfd with ``EFD_SUPPORT_ISR`` will cause interrupts to be temporarily disabled when reading, writing the file and during the beginning and the ending of the ``select()`` when this file is set.
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
- :example:`system/eventfd` demonstrates how to use ``eventfd()`` to collect events from tasks and ISRs in a ``select()`` based main loop, using two tasks and a timer ISR (interrupt service routine) callback.
|
||||
|
||||
- :example:`system/select` demonstrates how to use synchronous I/O multiplexing with the ``select()`` function, using UART and socket file descriptors, and configuring both to act as loopbacks to receive messages sent from other tasks.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
@ -14,6 +14,13 @@ Developers can use this library to send application specific state of execution
|
||||
2. Lightweight logging to the host, see :ref:`app_trace-logging-to-host`.
|
||||
3. System behaviour analysis, see :ref:`app_trace-system-behaviour-analysis-with-segger-systemview`.
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
- :example:`system/app_trace_to_plot` demonstrates how to use the Application Level Tracing Library to send and plot dummy sensor data to a host via JTAG, providing a faster alternative to logging via UART.
|
||||
|
||||
- :example:`system/app_trace_basic` demonstrates how to use the Application Level Tracing Library to log messages to a host via JTAG, providing a faster alternative to UART logs.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
|
||||
@ -566,5 +566,13 @@ Part of the functionality of this tool is also provided directly by ``idf.py`` c
|
||||
|
||||
.. include:: inc/espefuse_summary_{IDF_TARGET_NAME}.rst
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
- :example:`system/efuse` demonstrates how to use the eFuse API on {IDF_TARGET_NAME}, showing read and write operations with fields from the common and custom eFuse tables, and explaining the use of virtual eFuses for debugging purposes.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_efuse_chip.inc
|
||||
.. include-build-file:: inc/esp_efuse.inc
|
||||
|
||||
@ -8,9 +8,6 @@ Overview
|
||||
|
||||
``esp_https_ota`` provides simplified APIs to perform firmware upgrades over HTTPS. It is an abstraction layer over the existing OTA APIs.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
esp_err_t do_firmware_upgrade()
|
||||
@ -56,15 +53,6 @@ Signature Verification
|
||||
|
||||
For additional security, signature of OTA firmware images can be verified. For more information， please refer to :ref:`secure-ota-updates`.
|
||||
|
||||
|
||||
Advanced APIs
|
||||
-------------
|
||||
|
||||
``esp_https_ota`` also provides advanced APIs which can be used if more information and control is needed during the OTA process.
|
||||
|
||||
Example that uses advanced ESP_HTTPS_OTA APIs: :example:`system/ota/advanced_https_ota`.
|
||||
|
||||
|
||||
.. _ota_updates_pre-encrypted-firmware:
|
||||
|
||||
OTA Upgrades with Pre-Encrypted Firmware
|
||||
@ -94,14 +82,6 @@ This whole workflow is managed by an external component `esp_encrypted_image <ht
|
||||
.. note::
|
||||
The supported scheme is based on RSA-3072 and the private key on device side must be protected using platform security features.
|
||||
|
||||
Example
|
||||
^^^^^^^
|
||||
|
||||
To perform OTA upgrades with pre-encrypted firmware, please enable :ref:`CONFIG_ESP_HTTPS_OTA_DECRYPT_CB` in component menuconfig.
|
||||
|
||||
For detailed workflow and setup instructions, please refer to this example: :example:`system/ota/pre_encrypted_ota`.
|
||||
|
||||
|
||||
OTA System Events
|
||||
-----------------
|
||||
|
||||
@ -163,6 +143,14 @@ Expected data type for different ESP HTTPS OTA events in the system event loop:
|
||||
- ESP_HTTPS_OTA_FINISH : ``NULL``
|
||||
- ESP_HTTPS_OTA_ABORT : ``NULL``
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
- :example:`system/ota/pre_encrypted_ota` demonstrates how to perform OTA updates with pre-encrypted binary using the `esp_encrypted_img` component's APIs and tool, ensuring the confidentiality of the firmware on the network channel, but not its authenticity. To perform OTA upgrades with pre-encrypted firmware, please enable :ref:`CONFIG_ESP_HTTPS_OTA_DECRYPT_CB` in component `menuconfig`.
|
||||
|
||||
- :example:`system/ota/advanced_https_ota` demonstrates how to use the Advanced HTTPS OTA update functionality on {IDF_TARGET_NAME} using the `esp_https_ota` component's APIs. For the applicable SoCs, please refer to :example_file:`system/ota/advanced_https_ota/README.md`.
|
||||
|
||||
- :example:`system/ota/simple_ota_example` demonstrates how to use the `esp_https_ota` component's APIs to support firmware upgrades through specific networking interfaces such as Ethernet or Wi-Fi Station on {IDF_TARGET_NAME}. For the applicable SoCs, please refer to :example_file:`system/ota/simple_ota_example/README.md`.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
@ -224,6 +224,11 @@ To set the version in your project manually, you need to set the ``PROJECT_VER``
|
||||
|
||||
If the :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` option is set, the value of :ref:`CONFIG_APP_PROJECT_VER` will be used. Otherwise, if the ``PROJECT_VER`` variable is not set in the project, it will be retrieved either from the ``$(PROJECT_PATH)/version.txt`` file (if present) or using git command ``git describe``. If neither is available, ``PROJECT_VER`` will be set to "1". Application can make use of this by calling :cpp:func:`esp_app_get_description` or :cpp:func:`esp_ota_get_partition_description` functions.
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
- :example:`system/base_mac_address` demonstrates how to retrieve, set, and derive the base MAC address for each network interface on {IDF_TARGET_NAME} from non-volatile memory, using either the eFuse blocks or external storage.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
|
||||
@ -341,10 +341,12 @@ See Also
|
||||
* :doc:`../peripherals/spi_flash/index`
|
||||
* :doc:`esp_https_ota`
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
End-to-end example of OTA firmware update workflow: :example:`system/ota`.
|
||||
- :example:`system/ota/native_ota_example` demonstrates how to use the `app_update` component's APIs for native Over-the-Air (OTA) updates on {IDF_TARGET_NAME}. For the applicable SoCs, please refer to :example_file:`system/ota/native_ota_example/README.md`.
|
||||
|
||||
- :example:`system/ota/otatool` demonstrates how to use the OTA tool to perform operations such as reading, writing, and erasing OTA partitions, switching boot partitions, and switching to factory partition. For more information, please refer to :example_file:`system/ota/otatool/README.md`.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
@ -173,6 +173,8 @@ ESP-IDF 启动过程中，片外 RAM 被映射到数据虚拟地址空间，该
|
||||
|
||||
- 在进行 SPI1 flash 操作期间，cache 仍然保持启用状态，这样可以优化代码执行性能。由于无需把中断服务程序 (ISR)、ISR 回调和在此期间可能被访问的数据放置在片上 RAM 中，片上 RAM 可用于其他用途，从而提高了使用效率。这个特性适用于需要处理大量数据的高吞吐量外设应用，能显著提高 SPI1 flash 操作期间的性能。
|
||||
|
||||
:example:`system/xip_from_psram` 演示了如何从 PSRAM 直接执行代码，从而优化内部 RAM 的使用，并避免用户调用 flash 操作（例如闪存擦除/读取/写入操作）时关闭 cache。
|
||||
|
||||
.. only:: esp32p4
|
||||
|
||||
.. _external_ram_config_xip:
|
||||
|
||||
@ -192,6 +192,12 @@ VFS 对文件路径长度没有限制，但文件系统路径前缀受 ``ESP_VFS
|
||||
|
||||
注意，用 ``EFD_SUPPORT_ISR`` 创建 eventfd 将导致在读取、写入文件时，以及在设置这个文件的 ``select()`` 开始和结束时，暂时禁用中断。
|
||||
|
||||
应用示例
|
||||
----------------
|
||||
|
||||
- :example:`system/eventfd` 使用了两个任务和一个定时器 ISR 回调函数演示了如何使用 ``eventfd()`` 在基于 ``select()`` 的主循环中收集任务和中断服务程序的事件。
|
||||
|
||||
- :example:`system/select` 演示了如何使用 ``select()`` 函数进行同步 I/O 多路复用，使用 UART 和套接字文件描述符，并将二者配置为回环模式，以接收来自其他任务发送的消息。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
@ -14,6 +14,13 @@ ESP-IDF 支持用于程序行为分析的 **应用级追踪** 功能。在 menuc
|
||||
2. 向主机发送轻量级日志，参见 :ref:`app_trace-logging-to-host`。
|
||||
3. 系统行为分析，参见 :ref:`app_trace-system-behaviour-analysis-with-segger-systemview`。
|
||||
|
||||
应用示例
|
||||
---------------
|
||||
|
||||
- :example:`system/app_trace_to_plot` 演示了如何使用应用层跟踪库通过 JTAG 发送并绘制虚拟传感器数据到主机上，提供了比通过 UART 记录更快的替代方案。
|
||||
|
||||
- :example:`system/app_trace_basic` 演示了如何使用应用层跟踪库通过 JTAG 向主机记录消息，提供了比 UART 记录更快的替代方案。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
|
||||
@ -566,5 +566,13 @@ esptool 中包含一个用于读取/写入 {IDF_TARGET_NAME} eFuse 位的有用
|
||||
|
||||
.. include:: inc/espefuse_summary_{IDF_TARGET_NAME}.rst
|
||||
|
||||
应用示例
|
||||
-----------------
|
||||
|
||||
- :example:`system/efuse` 演示了如何在 {IDF_TARGET_NAME} 上使用 eFuse API，展示了从通用和自定义 eFuse 表中读取和写入字段的操作，并解释了虚拟 eFuse 在调试中的用途。
|
||||
|
||||
API 参考
|
||||
----------------
|
||||
|
||||
.. include-build-file:: inc/esp_efuse_chip.inc
|
||||
.. include-build-file:: inc/esp_efuse.inc
|
||||
|
||||
@ -8,9 +8,6 @@ ESP HTTPS OTA 升级
|
||||
|
||||
``esp_https_ota`` 是现有 OTA（空中升级）API 的抽象层，其中提供了简化的 API，能够通过 HTTPS 升级固件。
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
esp_err_t do_firmware_upgrade()
|
||||
@ -46,7 +43,7 @@ ESP HTTPS OTA 升级
|
||||
|
||||
要使用部分镜像下载功能，请启用 ``esp_https_ota_config_t`` 中的 ``partial_http_download`` 配置。启用此配置后，固件镜像将通过多个指定大小的 HTTP 请求进行下载。将 ``max_http_request_size`` 设置为所需值，即可指定每个请求的最大内容长度。
|
||||
|
||||
在从 AWS S3 等服务获取镜像时，这一选项非常有用。在启用该选项时， 可以将 mbedTLS Rx 的 buffer 大小（即 :ref:`CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN`）设置为较小的值。不启用此配置时，无法将其设置为较小值。
|
||||
在从 AWS S3 等服务获取镜像时，这一选项非常有用。在启用该选项时，可以将 mbedTLS Rx 的 buffer 大小（即 :ref:`CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN`）设置为较小的值。不启用此配置时，无法将其设置为较小值。
|
||||
|
||||
mbedTLS Rx buffer 的默认大小为 16 KB，但如果将 ``partial_http_download`` 的 ``max_http_request_size`` 设置为 4 KB，便能将 mbedTLS Rx 的 buffer 减小到 4 KB。使用这一配置方式预计可以节省约 12 KB 内存。
|
||||
|
||||
@ -56,15 +53,6 @@ mbedTLS Rx buffer 的默认大小为 16 KB，但如果将 ``partial_http_downloa
|
||||
|
||||
要进一步提升安全性，还可以验证 OTA 固件镜像的签名。更多内容请参考 :ref:`secure-ota-updates`。
|
||||
|
||||
|
||||
高级 API
|
||||
-------------
|
||||
|
||||
``esp_https_ota`` 还提供一些高级 API，用于查看 OTA 过程的更多信息并满足其他控制需求。
|
||||
|
||||
如需查看使用高级 ESP_HTTPS_OTA API 的示例，请前往 :example:`system/ota/advanced_https_ota`。
|
||||
|
||||
|
||||
.. _ota_updates_pre-encrypted-firmware:
|
||||
|
||||
使用预加密固件进行 OTA 升级
|
||||
@ -94,14 +82,6 @@ mbedTLS Rx buffer 的默认大小为 16 KB，但如果将 ``partial_http_downloa
|
||||
.. note::
|
||||
该支持方案基于 RSA-3072，必须使用平台安全功能保护设备端的私钥。
|
||||
|
||||
示例
|
||||
^^^^
|
||||
|
||||
如需使用预加密的固件进行 OTA 升级，请在组件的菜单配置中启用 :ref:`CONFIG_ESP_HTTPS_OTA_DECRYPT_CB` 选项。
|
||||
|
||||
如需了解详细的配置流程和说明，请参考示例 :example:`system/ota/pre_encrypted_ota`。
|
||||
|
||||
|
||||
OTA 系统事件
|
||||
-----------------
|
||||
|
||||
@ -163,6 +143,14 @@ ESP HTTPS OTA 过程中可能发生各种系统事件。当特定事件发生时
|
||||
- ESP_HTTPS_OTA_FINISH : ``NULL``
|
||||
- ESP_HTTPS_OTA_ABORT : ``NULL``
|
||||
|
||||
应用示例
|
||||
----------------
|
||||
|
||||
- :example:`system/ota/pre_encrypted_ota` 演示了如何使用 `esp_encrypted_img` 组件的 API 和工具进行带预加密二进制文件的 OTA 更新，确保固件在网络通道上的机密性，但不保证其真实性。要进行带预加密固件的 OTA 升级，请在组件 `menuconfig` 中启用 :ref:`CONFIG_ESP_HTTPS_OTA_DECRYPT_CB`。
|
||||
|
||||
- :example:`system/ota/advanced_https_ota` 演示了如何在 {IDF_TARGET_NAME} 上使用 `esp_https_ota` 组件的 API 来使用 HTTPS OTA 更新功能。关于该示例适用的芯片，请参考 :example_file:`system/ota/advanced_https_ota/README.md`。
|
||||
|
||||
- :example:`system/ota/simple_ota_example` 演示了如何使用 `esp_https_ota` 组件的 API，通过特定的网络接口，如以太网或 Wi-Fi Station，在 {IDF_TARGET_NAME} 上进行固件升级。关于该示例适用的芯片，请参考 :example_file:`system/ota/simple_ota_example/README.md`。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
@ -224,6 +224,11 @@ SDK 版本
|
||||
|
||||
如果设置了 :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` 选项，则将使用 :ref:`CONFIG_APP_PROJECT_VER` 的值。否则，如果在项目中未设置 ``PROJECT_VER`` 变量，则该变量将从 ``$(PROJECT_PATH)/version.txt`` 文件（若有）中检索，或使用 git 命令 ``git describe`` 检索。如果两者都不可用，则 ``PROJECT_VER`` 将被设置为 “1”。应用程序可通过调用 :cpp:func:`esp_app_get_description` 或 :cpp:func:`esp_ota_get_partition_description` 函数来获取应用程序的版本信息。
|
||||
|
||||
应用示例
|
||||
--------------
|
||||
|
||||
- :example:`system/base_mac_address` 演示了如何从非易失性存储器中检索、设置和派生 {IDF_TARGET_NAME} 上每个网络接口的基准 MAC 地址，可以使用 eFuse 或外部存储。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
|
||||
@ -341,10 +341,10 @@ Python API
|
||||
* :doc:`../peripherals/spi_flash/index`
|
||||
* :doc:`esp_https_ota`
|
||||
|
||||
应用程序示例
|
||||
应用示例
|
||||
------------
|
||||
|
||||
端对端的 OTA 固件升级示例请参考 :example:`system/ota`。
|
||||
- :example:`system/ota/otatool` 演示了如何使用 OTA 工具执行读取、写入和擦除 OTA 分区、切换启动分区以及切换到出厂分区等操作。有关更多信息，请参考 :example_file:`system/ota/otatool/README.md`。
|
||||
|
||||
API 参考
|
||||
--------
|
||||
|
||||
Reference in New Issue
Block a user