mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs(ldo): add api reference for ldo regulator driver
This commit is contained in:
morris
parent
061e5dc695
commit
7de228d0a3
@ -102,6 +102,8 @@ DAC_DOCS = ['api-reference/peripherals/dac.rst']
|
||||
|
||||
ETM_DOCS = ['api-reference/peripherals/etm.rst']
|
||||
|
||||
LDO_DOCS = ['api-reference/peripherals/ldo_regulator.rst']
|
||||
|
||||
TEMP_SENSOR_DOCS = ['api-reference/peripherals/temp_sensor.rst']
|
||||
|
||||
TOUCH_SENSOR_DOCS = ['api-reference/peripherals/touch_pad.rst']
|
||||
@ -251,6 +253,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
|
||||
'SOC_SPI_SUPPORT_SLAVE_HD_VER2':SPI_SLAVE_HD_DOCS,
|
||||
'SOC_WIFI_NAN_SUPPORT':NAN_DOCS,
|
||||
'SOC_JPEG_CODEC_SUPPORTED':JPEG_DOCS,
|
||||
'SOC_GP_LDO_SUPPORTED':LDO_DOCS,
|
||||
'esp32':ESP32_DOCS,
|
||||
'esp32s2':ESP32S2_DOCS,
|
||||
'esp32s3':ESP32S3_DOCS,
|
||||
|
||||
@ -173,6 +173,7 @@ INPUT = \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/esp_mac.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/esp_random.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/esp_sleep.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/ldo/include/esp_ldo_regulator.h \
|
||||
$(PROJECT_PATH)/components/esp_lcd/include/esp_lcd_panel_io.h \
|
||||
$(PROJECT_PATH)/components/esp_lcd/include/esp_lcd_panel_ops.h \
|
||||
$(PROJECT_PATH)/components/esp_lcd/include/esp_lcd_panel_vendor.h \
|
||||
|
||||
@ -156,7 +156,7 @@ Application Example
|
||||
|
||||
.. list::
|
||||
|
||||
* Emulate UART/I2C/SPI peripherals in assembly with dedicate CPU instructions designed for manipulating the GPIOs: :example:`peripherals/dedicated_gpio`.
|
||||
* Software emulation (bit banging) of the UART/I2C/SPI protocols in assembly using the dedicated GPIOs and their associated CPU instructions: :example:`peripherals/dedicated_gpio`.
|
||||
:SOC_DEDIC_GPIO_HAS_INTERRUPT: * Matrix keyboard example based on dedicated GPIO: :example:`peripherals/gpio/matrix_keyboard`.
|
||||
|
||||
|
||||
|
||||
@ -22,6 +22,7 @@ Peripherals API
|
||||
i2c
|
||||
:SOC_I2S_SUPPORTED: i2s
|
||||
lcd/index
|
||||
:SOC_GP_LDO_SUPPORTED: ldo_regulator
|
||||
ledc
|
||||
:SOC_MCPWM_SUPPORTED: mcpwm
|
||||
:SOC_PARLIO_SUPPORTED: parlio
|
||||
|
||||
59
docs/en/api-reference/peripherals/ldo_regulator.rst
Normal file
59
docs/en/api-reference/peripherals/ldo_regulator.rst
Normal file
@ -0,0 +1,59 @@
|
||||
Low Dropout Voltage Regulator (LDO)
|
||||
===================================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
{IDF_TARGET_LDO_CHANNELS:default="unknown", esp32p4="4"}
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
The {IDF_TARGET_NAME} chip internally integrates {IDF_TARGET_LDO_CHANNELS} channels of low-dropout voltage regulators (LDOs). Each channel's voltage is programmable. In our hardware reference designs, some of these LDO outputs are typically used to power the internal Flash and PSRAM, while the remaining LDOs can be used to supply external devices.
|
||||
|
||||
.. note::
|
||||
|
||||
It's essential to read the manual first and ensure that the required current does not exceed the chip's specifications.
|
||||
|
||||
Functional Overview
|
||||
-------------------
|
||||
|
||||
The description of the LDO driver is divided into the following sections:
|
||||
|
||||
- :ref:`ldo-channel-acquisition` - Introduces the types of LDO channels and how to apply for LDO channel resources.
|
||||
- :ref:`ldo-adjust-voltage` - Describes how to adjust the voltage of the LDO channel.
|
||||
|
||||
.. _ldo-channel-acquisition:
|
||||
|
||||
LDO Channel Acquisition
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
LDO channels can be classified into two types: fixed voltage and adjustable voltage. For a fixed voltage channel, it allows multiple users to simultaneously use it (in software, we allow a variable to have multiple immutable references ). However, for an adjustable voltage channel, only one user is allowed to use it at a time (in software, we don't allow a variable to have multiple mutable references or coexistence of mutable and immutable references).
|
||||
|
||||
In the driver, the LDO channel is represented by the :cpp:type:`esp_ldo_channel_handle_t`. You can use the :cpp:func:`esp_ldo_acquire_channel` function to request LDO channel resources. Upon successful acquisition, a handle for the LDO channel will be returned, which can be used for subsequent voltage adjustment operations. When applying for a channel, the :cpp:type:`esp_ldo_channel_config_t` structure is used to specify the basic information of the LDO channel, including the channel ID, the desired output voltage, and whether the voltage can be dynamically adjusted.
|
||||
|
||||
- :cpp:member:`esp_ldo_channel_config_t::chan_id` - LDO channels are uniquely identified by a label, which is used to distinguish different LDO channels. Please note that this information needs to be determined based on the circuit schematic and chip datasheet. For example, an LDO channel labeled as ``LDO_VO3`` corresponds to an ID of ``3``.
|
||||
- :cpp:member:`esp_ldo_channel_config_t::voltage_mv` - The desired output voltage of the LDO channel, in millivolts.
|
||||
- :cpp:member:`esp_ldo_channel_config_t::ldo_extra_flags::adjustable` - Whether the LDO channel's output voltage can be dynamically adjusted. Only when it is set to `true`, can the :cpp:func:`esp_ldo_channel_adjust_voltage` function be used to dynamically adjust the output voltage.
|
||||
|
||||
Since multiple users are allowed to use a fixed voltage LDO channel simultaneously, the driver internally maintains a reference counter. The LDO channel will be automatically closed when the last user releases the LDO channel resources. The function to release LDO channel resources is :cpp:func:`esp_ldo_release_channel`. Additionally, it is important to note that the acquisition and release of LDO channels should appear in pairs during usage.
|
||||
|
||||
.. _ldo-adjust-voltage:
|
||||
|
||||
LDO Voltage Adjustment
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
:cpp:func:`esp_ldo_channel_adjust_voltage` function is used to adjust the output voltage of an LDO channel at runtime. However, please note that this function can only be used for LDO channels with adjustable voltage. Attempting to use this function on a fixed voltage LDO channel will result in an error.
|
||||
|
||||
Also, it is important to keep in mind that due to hardware limitations, the LDO channel voltage may have a deviation of approximately 50-100mV. Therefore, it is not advisable to rely on the LDO channel's output voltage for precise analog control.
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
.. list::
|
||||
|
||||
:SOC_MIPI_DSI_SUPPORTED: * Use the internal LDO channel to power up the MIPI DPHY: :example:`peripherals/lcd/mipi_dsi`
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_ldo_regulator.inc
|
||||
@ -156,7 +156,7 @@ GPIO 捆绑包操作
|
||||
|
||||
.. list::
|
||||
|
||||
* 通过汇编代码使用专用的 CPU 指令来操作 GPIO 以模拟 UART/I2C/SPI 外设 :example:`peripherals/dedicated_gpio`.
|
||||
* 通过汇编代码使用专用的 CPU 指令来操作 GPIO 以模拟 UART/I2C/SPI 协议（Bit Banging） :example:`peripherals/dedicated_gpio`.
|
||||
:SOC_DEDIC_GPIO_HAS_INTERRUPT: * 基于专用 GPIO 驱动的矩阵键盘：:example:`peripherals/gpio/matrix_keyboard`.
|
||||
|
||||
|
||||
|
||||
@ -22,6 +22,7 @@
|
||||
i2c
|
||||
:SOC_I2S_SUPPORTED: i2s
|
||||
lcd/index
|
||||
:SOC_GP_LDO_SUPPORTED: ldo_regulator
|
||||
ledc
|
||||
:SOC_MCPWM_SUPPORTED: mcpwm
|
||||
:SOC_PARLIO_SUPPORTED: parlio
|
||||
|
||||
59
docs/zh_CN/api-reference/peripherals/ldo_regulator.rst
Normal file
59
docs/zh_CN/api-reference/peripherals/ldo_regulator.rst
Normal file
@ -0,0 +1,59 @@
|
||||
低压差线性稳压器 (LDO)
|
||||
======================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
{IDF_TARGET_LDO_CHANNELS:default="unknown", esp32p4="4"}
|
||||
|
||||
简介
|
||||
----
|
||||
|
||||
{IDF_TARGET_NAME} 芯片内部集成了 {IDF_TARGET_LDO_CHANNELS} 路低压差线性稳压器 (LDO)，每路的电压都是可编程调节的。在硬件的参考设计中，我们通常会将其中一些的 LDO 输出作为内部 Flash 和 PSRAM 的电源，剩余的一些 LDO 可以用于给外部设备供电。
|
||||
|
||||
.. note::
|
||||
|
||||
使用前请阅读手册，确保你需要的电流不会超过芯片的规格。
|
||||
|
||||
功能概述
|
||||
--------
|
||||
|
||||
下文将分节介绍 LDO 驱动的功能：
|
||||
|
||||
- :ref:`ldo-channel-acquisition` - 介绍LDO通道的种类以及如何申请 LDO 通道资源
|
||||
- :ref:`ldo-adjust-voltage` - 介绍如何调节 LDO 通道的输出电压
|
||||
|
||||
.. _ldo-channel-acquisition:
|
||||
|
||||
LDO 通道申请
|
||||
^^^^^^^^^^^^
|
||||
|
||||
LDO 通道可以分为两种，一种是电压固定的，另一种是电压可调的。对于同一个输出通道，如果电压固定，那么可以允许有多个用户同时使用（软件允许一个变量拥有多个不可变引用）。如果电压可调，那么只能允许一个用户使用（软件上不允许一个变量有多个可变引用或者可变和不可变引用同时存在）。
|
||||
|
||||
LDO 通道在驱动软件中由 :cpp:type:`esp_ldo_channel_handle_t` 句柄表示。申请 LDO 通道资源的函数是 :cpp:func:`esp_ldo_acquire_channel`。申请成功后，会返回一个 LDO 通道的句柄，这个句柄可以用于后续的电压调节操作。在申请通道的时候，我们需要通过 :cpp:type:`esp_ldo_channel_config_t` 结构体来指定 LDO 通道的基本信息，包括通道 ID，期望的输出电压，以及电压是否可以动态调节。
|
||||
|
||||
- :cpp:member:`esp_ldo_channel_config_t::chan_id` - LDO 通道的唯一标记，用于区分不同的 LDO 通道。注意，这需要你根据电路原理图和芯片数据手册来确定。比如，一个标记着 "LDO_VO3" 的 LDO 通道，对应的 ID 是 3。
|
||||
- :cpp:member:`esp_ldo_channel_config_t::voltage_mv` - 期望的输出电压，单位是毫伏。
|
||||
- :cpp:member:`esp_ldo_channel_config_t::ldo_extra_flags::adjustable` - 是否允许调节输出电压。只有设置为 `true`，才允许使用 :cpp:func:`esp_ldo_channel_adjust_voltage` 函数来动态地调节输出电压。
|
||||
|
||||
由于允许多个用户同时使用固定电压的 LDO 通道，所以驱动内部会维持一个引用计数器。当最后一个用户释放 LDO 通道资源时，LDO 通道会被自动关闭。释放 LDO 通道资源的函数是 :cpp:func:`esp_ldo_release_channel`。另外还需要注意，申请和释放 LDO 通道在使用的时候需要成对出现。
|
||||
|
||||
.. _ldo-adjust-voltage:
|
||||
|
||||
LDO 通道电压调节
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
:cpp:func:`esp_ldo_channel_adjust_voltage` 函数用来在运行时调整 LDO 通道的输出电压。但是，这个函数只能用于可调节电压的 LDO 通道，否则会返回错误。
|
||||
|
||||
注意，由于硬件限制，LDO 通道电压的精度可能会 50~100mV 左右的偏差，请勿依赖于 LDO 通道的输出电压来进行精确的模拟量控制。
|
||||
|
||||
应用示例
|
||||
--------
|
||||
|
||||
.. list::
|
||||
|
||||
:SOC_MIPI_DSI_SUPPORTED: * Use the internal LDO channel to power up the MIPI DPHY: :example:`peripherals/lcd/mipi_dsi`
|
||||
|
||||
API 参考
|
||||
--------
|
||||
|
||||
.. include-build-file:: inc/esp_ldo_regulator.inc
|
||||
Loading…
Reference in New Issue
Block a user