mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Docs: Update cn trans api guides (backport v5.1)
This commit is contained in:
Mo Fei Fei
morris
parent
5736694dbc
commit
3a34660d54
@ -18,7 +18,7 @@ For a full description of the startup process including the ESP-IDF bootloader,
|
||||
|
||||
.. _bootloader-compatibility:
|
||||
|
||||
Bootloader compatibility
|
||||
Bootloader Compatibility
|
||||
------------------------
|
||||
|
||||
It is recommended to update to newer :doc:`versions of ESP-IDF </versions>`: when they are released. The OTA (over the air) update process can flash new apps in the field but cannot flash a new bootloader. For this reason, the bootloader supports booting apps built from newer versions of ESP-IDF.
|
||||
@ -59,7 +59,7 @@ The default bootloader log level is "Info". By setting the :ref:`CONFIG_BOOTLOAD
|
||||
|
||||
Reducing bootloader log verbosity can improve the overall project boot time by a small amount.
|
||||
|
||||
Factory reset
|
||||
Factory Reset
|
||||
-------------
|
||||
|
||||
Sometimes it is desirable to have a way for the device to fall back to a known-good state, in case of some problem with an update.
|
||||
@ -88,11 +88,16 @@ In addition, the following configuration options control the reset condition:
|
||||
|
||||
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
|
||||
|
||||
Sometimes an application needs to know if the Factory Reset has occurred. For this purpose, there is a function :cpp:func:`bootloader_common_get_rtc_retain_mem_factory_reset_state`, which returns its status, after reading the status is reset to false. This feature reserves some RTC FAST memory (the same size as the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` feature).
|
||||
If an application needs to know if the factory reset has occurred, users can call the function :cpp:func:`bootloader_common_get_rtc_retain_mem_factory_reset_state`.
|
||||
|
||||
- If the status is read as true, the function will return the status, indicating that the factory reset has occurred. The function then resets the status to false for subsequent factory reset judgement.
|
||||
- If the status is read as false, the function will return the status, indicating that the factory reset has not occurred, or the memory where this status is stored is invalid.
|
||||
|
||||
Note that this feature reserves some RTC FAST memory (the same size as the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` feature).
|
||||
|
||||
.. only:: not SOC_RTC_FAST_MEM_SUPPORTED
|
||||
|
||||
Sometimes an application needs to know if the Factory Reset has occurred. The {IDF_TARGET_NAME} chip does not have RTC FAST memory, so there is no API to detect it. Instead, there is a workaround: you need an NVS partition that will be erased by bootloader while Factory Reset (add this partition to :ref:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET`). In this NVS partition, create a "factory_reset_state" token that will be increased in the application. If the "factory_reset_state" is 0 then the factory reset has occurred.
|
||||
Sometimes an application needs to know if the factory reset has occurred. The {IDF_TARGET_NAME} chip does not have RTC FAST memory, so there is no API to detect it. Instead, there is a workaround: you need an NVS partition that will be erased by the bootloader if factory reset occurs (add this partition to :ref:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET`). In this NVS partition, create a "factory_reset_state" token that will be increased in the application. If the "factory_reset_state" is 0 then the factory reset has occurred.
|
||||
|
||||
.. _bootloader_boot_from_test_firmware:
|
||||
|
||||
@ -132,7 +137,7 @@ By default, the hardware RTC Watchdog timer remains running while the bootloader
|
||||
Bootloader Size
|
||||
---------------
|
||||
|
||||
{IDF_TARGET_MAX_BOOTLOADER_SIZE:default = "64KB (0x10000 bytes)", esp32 = "48KB (0xC000 bytes)"}
|
||||
{IDF_TARGET_MAX_BOOTLOADER_SIZE:default = "64 KB (0x10000 bytes)", esp32 = "48 KB (0xC000 bytes)"}
|
||||
{IDF_TARGET_MAX_PARTITION_TABLE_OFFSET:default = "0x12000", esp32 = "0xE000"}
|
||||
.. Above is calculated as 0x1000 at start of flash + IDF_TARGET_MAX_BOOTLOADER_SIZE + 0x1000 signature sector
|
||||
|
||||
@ -152,12 +157,12 @@ When Secure Boot V2 is enabled, there is also an absolute binary size limit of {
|
||||
|
||||
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
|
||||
|
||||
Fast boot from Deep Sleep
|
||||
Fast Boot from Deep-Sleep
|
||||
-------------------------
|
||||
|
||||
The bootloader has the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` option which allows the wake-up time from deep sleep to be reduced (useful for reducing power consumption). This option is available when :ref:`CONFIG_SECURE_BOOT` option is disabled. Reduction of time is achieved due to the lack of image verification. During the first boot, the bootloader stores the address of the application being launched in the RTC FAST memory. And during the awakening, this address is used for booting without any checks, thus fast loading is achieved.
|
||||
The bootloader has the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` option which allows the wake-up time from Deep-sleep to be reduced (useful for reducing power consumption). This option is available when :ref:`CONFIG_SECURE_BOOT` option is disabled. Reduction of time is achieved due to the lack of image verification. During the first boot, the bootloader stores the address of the application being launched in the RTC FAST memory. And during the awakening, this address is used for booting without any checks, thus fast loading is achieved.
|
||||
|
||||
Custom bootloader
|
||||
Custom Bootloader
|
||||
-----------------
|
||||
|
||||
The current bootloader implementation allows a project to extend it or modify it. There are two ways of doing it: by implementing hooks or by overriding it. Both ways are presented in :example:`custom_bootloader` folder in ESP-IDF examples:
|
||||
|
||||
@ -97,7 +97,7 @@ Because some buffers can only be allocated in internal memory, a second configur
|
||||
|
||||
.. _external_ram_config_bss:
|
||||
|
||||
Allow .bss Segment to be Placed in External Memory
|
||||
Allow .bss Segment to Be Placed in External Memory
|
||||
--------------------------------------------------
|
||||
|
||||
Enable this option by checking :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`.
|
||||
@ -116,7 +116,7 @@ Remaining external RAM can also be added to the capability heap allocator using
|
||||
|
||||
.. _external_ram_config_noinit:
|
||||
|
||||
Allow .noinit Segment to be Placed in External Memory
|
||||
Allow .noinit Segment to Be Placed in External Memory
|
||||
--------------------------------------------------------------
|
||||
|
||||
Enable this option by checking :ref:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY`. If enabled, a region of the address space provided in external RAM will be used to store non-initialized data. The values placed in this segment will not be initialized or modified even during startup or restart.
|
||||
@ -164,14 +164,14 @@ External RAM use has the following restrictions:
|
||||
|
||||
.. only:: SOC_PSRAM_DMA_CAPABLE and not esp32s3
|
||||
|
||||
* External RAM cannot be used as a place to store DMA transaction descriptors or as a buffer for a DMA transfer to read from or write into. Therefore when External RAM is enabled, any buffer that will be used in combination with DMA must be allocated using ``heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`` and can be freed using a standard ``free()`` call. Note, although {IDF_TARGET_NAME} has hardware support for DMA to / from external RAM, this is not yet supported in ESP-IDF.
|
||||
* External RAM cannot be used as a place to store DMA transaction descriptors or as a buffer for a DMA transfer to read from or write into. Therefore when External RAM is enabled, any buffer that will be used in combination with DMA must be allocated using ``heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`` and can be freed using a standard ``free()`` call. Note, although {IDF_TARGET_NAME} has hardware support for DMA to or from external RAM, this is not yet supported in ESP-IDF.
|
||||
|
||||
.. only:: esp32s3
|
||||
|
||||
* Although {IDF_TARGET_NAME} has hardware support for DMA to / from external RAM, there are still limitations:
|
||||
* Although {IDF_TARGET_NAME} has hardware support for DMA to or from external RAM, there are still limitations:
|
||||
|
||||
- The bandwidth that DMA accesses external RAM is very limited, especially when CPU is trying to access the external RAM at the same time.
|
||||
- You can configure :ref:`CONFIG_SPIRAM_SPEED` as 120 MHz for an Octal PSRAM. The bandwidth will be improved. However there are still restrictions for this option, see :ref:`All Supported PSRAM Modes and Speeds <flash-psram-combination>` for more details.
|
||||
- You can configure :ref:`CONFIG_SPIRAM_SPEED` as 120 MHz for an octal PSRAM. The bandwidth will be improved. However there are still restrictions for this option. See :ref:`All Supported PSRAM Modes and Speeds <flash-psram-combination>` for more details.
|
||||
|
||||
* External RAM uses the same cache region as the external flash. This means that frequently accessed variables in external RAM can be read and modified almost as quickly as in internal ram. However, when accessing large chunks of data (>32 KB), the cache can be insufficient, and speeds will fall back to the access speed of the external RAM. Moreover, accessing large chunks of data can "push out" cached flash, possibly making the execution of code slower afterwards.
|
||||
|
||||
@ -180,7 +180,7 @@ External RAM use has the following restrictions:
|
||||
The option :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` can be used to allow placing task stacks into external memory. In these cases :cpp:func:`xTaskCreateStatic` must be used to specify a task stack buffer allocated from external memory, otherwise task stacks will still be allocated from internal memory.
|
||||
|
||||
|
||||
Failure to initialize
|
||||
Failure to Initialize
|
||||
=====================
|
||||
|
||||
By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND`.
|
||||
@ -195,7 +195,7 @@ Failure to initialize
|
||||
Encryption
|
||||
==========
|
||||
|
||||
It is possible to enable automatic encryption for data stored in external RAM. When this is enabled any data read and written through the cache will automatically be encrypted/decrypted by the external memory encryption hardware.
|
||||
It is possible to enable automatic encryption for data stored in external RAM. When this is enabled any data read and written through the cache will automatically be encrypted or decrypted by the external memory encryption hardware.
|
||||
|
||||
This feature is enabled whenever flash encryption is enabled. For more information on how to enable and how it works see :doc:`Flash Encryption </security/flash-encryption>`.
|
||||
|
||||
|
||||
@ -60,8 +60,8 @@ Configuration
|
||||
|
||||
Via Menuconfig options you can specify:
|
||||
|
||||
- Several of descriptor's parameters (see: Descriptors Configuration bellow)
|
||||
- USB Serial low-level Configuration
|
||||
- Several descriptor's parameters (see Descriptors Configuration below)
|
||||
- USB Serial low-level configuration
|
||||
- The verbosity of the TinyUSB's log
|
||||
- Disable the TinyUSB main task (for the custom implementation)
|
||||
|
||||
@ -103,9 +103,9 @@ To initialize the driver, users should call :cpp:func:`tinyusb_driver_install`.
|
||||
Self-Powered Device
|
||||
-------------------
|
||||
|
||||
USB specification mandates self-powered devices to monitor voltage level on USB's VBUS signal. As opposed to bus-powered devices, a self-powered device can be fully functional even without USB connection. The self-powered device detects connection and disconnection events by monitoring the VBUS voltage level. VBUS is considered valid if it rises above 4.75V and invalid if it falls below 4.35V.
|
||||
USB specification mandates self-powered devices to monitor voltage level on USB's VBUS signal. As opposed to bus-powered devices, a self-powered device can be fully functional even without USB connection. The self-powered device detects connection and disconnection events by monitoring the VBUS voltage level. VBUS is considered valid if it rises above 4.75 V and invalid if it falls below 4.35 V.
|
||||
|
||||
No {IDF_TARGET_NAME} pin is 5V tolerant, so you must connect the VBUS to {IDF_TARGET_NAME} via a comparator with voltage thresholds as described above, or use a simple resistor voltage divider that will output (0.75 x Vdd) if VBUS is 4.4V (see figure below). In both cases, voltage on the sensing pin must be logic low within 3ms after the device is unplugged from USB host.
|
||||
No {IDF_TARGET_NAME} pin is 5 V tolerant, so you must connect the VBUS to {IDF_TARGET_NAME} via a comparator with voltage thresholds as described above, or use a simple resistor voltage divider that will output (0.75 x Vdd) if VBUS is 4.4 V (see figure below). In both cases, voltage on the sensing pin must be logic low within 3 ms after the device is unplugged from USB host.
|
||||
|
||||
.. figure:: ../../../_static/diagrams/usb/usb_vbus_voltage_monitor.png
|
||||
:align: center
|
||||
|
||||
@ -113,18 +113,16 @@ Examples of Authentication Configuration
|
||||
Event Handling
|
||||
--------------
|
||||
|
||||
ESP HTTP Client supports event handling by triggering an event handler corresponding to the event which took place.
|
||||
:cpp:enum:`esp_http_client_event_id_t` contains all the events which could occur while performing an HTTP request using the ESP HTTP Client.
|
||||
ESP HTTP Client supports event handling by triggering an event handler corresponding to the event which takes place. :cpp:enum:`esp_http_client_event_id_t` contains all the events which could occur while performing an HTTP request using the ESP HTTP Client.
|
||||
|
||||
To enable event handling, you just need to set a callback function using the :cpp:member:`esp_http_client_config_t::event_handler` member.
|
||||
|
||||
ESP HTTP Client Diagnostic Information
|
||||
--------------------------------------
|
||||
Diagnostic information could be helpful to gain insights into a problem. In the case of ESP HTTP Client, this diagnostic information can be collected by registering an event handler with :doc:`the Event Loop library <../system/esp_event>`.
|
||||
This feature has been added by keeping in mind the `ESP Insights <https://github.com/espressif/esp-insights>`_ framework which collects the diagnostic information. However, this feature can also be used without any dependency on ESP Insights framework for the diagnostic purpose.
|
||||
Event handler can be registered to the event loop using the :cpp:func:`esp_event_handler_register` function.
|
||||
|
||||
Expected data types for different HTTP Client events in the event loop:
|
||||
Diagnostic information could be helpful to gain insights into a problem. In the case of ESP HTTP Client, the diagnostic information can be collected by registering an event handler with :doc:`the Event Loop library <../system/esp_event>`. This feature has been added by keeping in mind the `ESP Insights <https://github.com/espressif/esp-insights>`_ framework which collects the diagnostic information. However, this feature can also be used without any dependency on the ESP Insights framework for the diagnostic purpose. Event handler can be registered to the event loop using the :cpp:func:`esp_event_handler_register` function.
|
||||
|
||||
Expected data types for different HTTP Client events in the event loop are as follows:
|
||||
|
||||
- HTTP_EVENT_ERROR : ``esp_http_client_handle_t``
|
||||
- HTTP_EVENT_ON_CONNECTED : ``esp_http_client_handle_t``
|
||||
@ -135,8 +133,7 @@ Expected data types for different HTTP Client events in the event loop:
|
||||
- HTTP_EVENT_DISCONNECTED : ``esp_http_client_handle_t``
|
||||
- HTTP_EVENT_REDIRECT : ``esp_http_client_redirect_event_data_t``
|
||||
|
||||
The :cpp:type:`esp_http_client_handle_t` received along with the event data will be valid until :cpp:enumerator:`HTTP_EVENT_DISCONNECTED <esp_http_client_event_id_t::HTTP_EVENT_DISCONNECTED>` is not received. This handle has been sent primarily to differentiate between different client
|
||||
connections and must not be used for any other purpose (as it may change based on client connection state).
|
||||
The :cpp:type:`esp_http_client_handle_t` received along with the event data will be valid until :cpp:enumerator:`HTTP_EVENT_DISCONNECTED <esp_http_client_event_id_t::HTTP_EVENT_DISCONNECTED>` is not received. This handle has been sent primarily to differentiate between different client connections and must not be used for any other purpose, as it may change based on client connection state.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
@ -86,6 +86,19 @@ ROM 中的 :ref:`first-stage-bootloader` 从 flash 中读取 :ref:`second-stage-
|
||||
|
||||
- :ref:`CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVEL` - 设置管脚电平高低。设备重置后，根据此设置将管脚拉高或拉低，才能触发出厂重置事件。如果管脚具有内部上拉，则上拉会在管脚采样前生效。有关管脚内部上拉的详细信息，请参考 {IDF_TARGET_NAME} 的技术规格书。
|
||||
|
||||
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
|
||||
|
||||
如果应用程序需要知道设备是否触发了出厂重置，可以通过调用 :cpp:func:`bootloader_common_get_rtc_retain_mem_factory_reset_state` 函数来确定：
|
||||
|
||||
- 如果读取到设备出厂重置状态为 true，会返回状态 true，说明设备已经触发出厂重置。此后会重置状态为 false，以便后续的出厂重置触发判断。
|
||||
- 如果读取到设备出厂重置状态为 false，会返回状态 false，说明设备并未触发出厂重置，或者保存此状态的内存区域已失效。
|
||||
|
||||
同时需要注意该功能需要占用部分 RTC FAST 内存（占用的内存与 :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` 大小相同）。
|
||||
|
||||
.. only:: not SOC_RTC_FAST_MEM_SUPPORTED
|
||||
|
||||
有时应用程序需要知道设备是否触发了出厂重置，但 {IDF_TARGET_NAME} 没有 RTC FAST 内存，因此没有相应的 API 可用于监测。然而也有方法实现出厂重置监测，比如，设置一个在出厂重置时会被引导加载程序擦除的 NVS 分区（需将此分区添加到 :ref:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET` 中）。在这个 NVS 分区中保存一个令牌数据 "factory_reset_state"，让该令牌在应用程序中自增。"factory_reset_state" 为 0 时则表明触发了出厂重置。
|
||||
|
||||
.. _bootloader_boot_from_test_firmware:
|
||||
|
||||
从测试固件启动
|
||||
@ -124,14 +137,13 @@ ROM 中的 :ref:`first-stage-bootloader` 从 flash 中读取 :ref:`second-stage-
|
||||
引导加载程序大小
|
||||
---------------------
|
||||
|
||||
{IDF_TARGET_DEFAULT_MAX_BOOTLOADER_SIZE:default = "0x8000 (32768)", esp32 = "0x7000 (28672)", esp32s2 = "0x7000 (28672)"}
|
||||
{IDF_TARGET_MAX_BOOTLOADER_SIZE:default = "64KB (0x10000 bytes)", esp32 = "48KB (0xC000 bytes)"}
|
||||
{IDF_TARGET_MAX_BOOTLOADER_SIZE:default = "64 KB (0x10000 bytes)", esp32 = "48 KB (0xC000 bytes)"}
|
||||
{IDF_TARGET_MAX_PARTITION_TABLE_OFFSET:default = "0x12000", esp32 = "0xE000"}
|
||||
.. Above is calculated as 0x1000 at start of flash + IDF_TARGET_MAX_BOOTLOADER_SIZE + 0x1000 signature sector
|
||||
|
||||
当需要启用额外的引导加载程序功能，包括 :doc:`/security/flash-encryption` 或安全启动，尤其是设置高级别 :ref:`CONFIG_BOOTLOADER_LOG_LEVEL` 时，监控引导加载程序 .bin 文件的大小变得非常重要。
|
||||
|
||||
当使用默认的 :ref:`CONFIG_PARTITION_TABLE_OFFSET` 值 0x8000 时，二进制文件最大可为 {IDF_TARGET_DEFAULT_MAX_BOOTLOADER_SIZE} 字节。
|
||||
当使用默认的 :ref:`CONFIG_PARTITION_TABLE_OFFSET` 值 0x8000 时，二进制文件最大可为 {IDF_TARGET_CONFIG_PARTITION_TABLE_OFFSET} 字节。
|
||||
|
||||
如果引导加载程序二进制文件过大，则引导加载程序会构建将失败并显示 "Bootloader binary size [..] is too large for partition table offset" 的错误。如果此二进制文件已经被烧录，那么 {IDF_TARGET_NAME} 将无法启动 - 日志中将记录无效分区表或无效引导加载程序校验和的错误。
|
||||
|
||||
|
||||
@ -162,19 +162,24 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 {IDF_TARGET_PSRAM_ADDR_STAR
|
||||
|
||||
* flash cache 禁用时（比如，正在写入 flash），片外 RAM 将无法访问；同样，对片外 RAM 的读写操作也将导致 cache 访问异常。出于这个原因，ESP-IDF 不会在片外 RAM 中分配任务堆栈（详见下文）。
|
||||
|
||||
* 片外 RAM 不能用于储存 DMA 事务描述符，也不能用作 DMA 读写操作的缓冲区 (Buffer)。因此，当片外 RAM 启用时，与 DMA 搭配使用的 Buffer 必须先使用 ``heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`` 进行分配，之后可以调用标准 ``free()`` 回调释放 Buffer。
|
||||
.. only:: SOC_PSRAM_DMA_CAPABLE and not esp32s3
|
||||
|
||||
.. only:: SOC_PSRAM_DMA_CAPABLE
|
||||
* 片外 RAM 不能用于储存 DMA 事务描述符，也不能用作 DMA 读写操作的缓冲区 (Buffer)。因此，当片外 RAM 启用时，与 DMA 搭配使用的 Buffer 必须先使用 ``heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`` 进行分配，之后可以调用标准 ``free()`` 回调释放 Buffer。注意，尽管 {IDF_TARGET_NAME} 中已有硬件支持 DMA 与片外 RAM，但在 ESP-IDF 中，尚未提供软件支持。
|
||||
|
||||
注意，尽管 {IDF_TARGET_NAME} 中已有硬件支持 DMA 与片外 RAM，但在 ESP-IDF 中，尚未提供软件支持。
|
||||
.. only:: esp32s3
|
||||
|
||||
注意，尽管 {IDF_TARGET_NAME} 中已有硬件支持 DMA 与片外 RAM，但仍有以下限制：
|
||||
|
||||
- DMA 访问外部 RAM 的带宽十分有限，尤其是当 CPU 同时访问外部 RAM 时。
|
||||
- 将八线 PSRAM 的 :ref:`CONFIG_SPIRAM_SPEED` 配置为 120 MHz 可提高带宽，但使用此选项仍有一定限制，更多信息请参见 :ref:`所有支持的 PSRAM 模式和速度 <flash-psram-combination>`。
|
||||
|
||||
* 片外 RAM 与片外 flash 使用相同的 cache 区域，这意味着频繁在片外 RAM 访问的变量可以像在片上 RAM 中一样快速读取和修改。但访问大块数据时（大于 32 KB），cache 空间可能会不足，访问速度将回落到片外 RAM 访问速度。此外，访问大块数据会挤出 flash cache，可能降低代码执行速度。
|
||||
|
||||
* 一般来说，片外 RAM 不会用作任务堆栈存储器。:cpp:func:`xTaskCreate` 及类似函数始终会为堆栈和任务 TCB 分配片上储存器。
|
||||
|
||||
|
||||
可以使用 :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` 选项将任务堆栈放入片外存储器。这时，必须使用 :cpp:func:`xTaskCreateStatic` 指定从片外存储器分配的任务堆栈缓冲区，否则任务堆栈将会从片上存储器分配。
|
||||
|
||||
|
||||
初始化失败
|
||||
=====================
|
||||
|
||||
|
||||
@ -110,6 +110,30 @@ ESP HTTP 客户端同时支持 **基本** 和 **摘要** 认证。
|
||||
.auth_type = HTTP_AUTH_TYPE_BASIC,
|
||||
};
|
||||
|
||||
事件处理
|
||||
---------
|
||||
|
||||
ESP HTTP 客户端支持事件处理，发生相关事件时会触发相应的事件处理程序。:cpp:enum:`esp_http_client_event_id_t` 中包含了所有使用 ESP HTTP 客户端执行 HTTP 请求时可能发生的事件。
|
||||
|
||||
通过 :cpp:member:`esp_http_client_config_t::event_handler` 设置回调函数即可启用事件处理功能。
|
||||
|
||||
ESP HTTP 客户端诊断信息
|
||||
--------------------------
|
||||
|
||||
诊断信息可以帮助用户深入了解出现的问题。在 ESP HTTP 客户端中，可以通过在 :doc:`事件循环库 <../system/esp_event>` 中注册事件处理程序来获取诊断信息。此功能的增加基于 `ESP Insights <https://github.com/espressif/esp-insights>`_ 框架，该框架可帮助收集诊断信息。然而，即使不依赖 ESP Insights 框架，也可以获取诊断信息。事件处理程序可通过 :cpp:func:`esp_event_handler_register` 函数注册到事件循环中。
|
||||
|
||||
事件循环中不同 HTTP 客户端事件的预期数据类型如下所示：
|
||||
|
||||
- HTTP_EVENT_ERROR : ``esp_http_client_handle_t``
|
||||
- HTTP_EVENT_ON_CONNECTED : ``esp_http_client_handle_t``
|
||||
- HTTP_EVENT_HEADERS_SENT : ``esp_http_client_handle_t``
|
||||
- HTTP_EVENT_ON_HEADER : ``esp_http_client_handle_t``
|
||||
- HTTP_EVENT_ON_DATA : ``esp_http_client_on_data_t``
|
||||
- HTTP_EVENT_ON_FINISH : ``esp_http_client_handle_t``
|
||||
- HTTP_EVENT_DISCONNECTED : ``esp_http_client_handle_t``
|
||||
- HTTP_EVENT_REDIRECT : ``esp_http_client_redirect_event_data_t``
|
||||
|
||||
在无法接收到 :cpp:enumerator:`HTTP_EVENT_DISCONNECTED <esp_http_client_event_id_t::HTTP_EVENT_DISCONNECTED>` 之前，与事件数据一起接收到的 :cpp:type:`esp_http_client_handle_t` 将始终有效。这个句柄主要是为了区分不同的客户端连接，无法用于其他目的，因为它可能会随着客户端连接状态的变化而改变。
|
||||
|
||||
API 参考
|
||||
---------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user