# 低压差线性稳压器 (LDO)

[English]

## 简介

ESP32-S31 芯片内部集成了 1 路低压差线性稳压器 (LDO)，每路的电压都是可编程调节的。在硬件的参考设计中，我们通常会将其中一些的 LDO 输出作为内部 Flash 和 PSRAM 的电源，剩余的一些 LDO 可以用于给外部设备供电。

备注

使用前请阅读手册，确保你需要的电流不会超过芯片的规格。

## 功能概述

下文将分节介绍 LDO 驱动的功能：

- LDO 通道申请 - 介绍LDO通道的种类以及如何申请 LDO 通道资源

- LDO 通道电压调节 - 介绍如何调节 LDO 通道的输出电压

### LDO 通道申请

LDO 通道可以分为两种，一种是电压固定的，另一种是电压可调的。对于同一个输出通道，如果电压固定，那么可以允许有多个用户同时使用（软件允许一个变量拥有多个不可变引用）。如果电压可调，那么只能允许一个用户使用（软件上不允许一个变量有多个可变引用或者可变和不可变引用同时存在）。

LDO 通道在驱动软件中由 `esp_ldo_channel_handle_t` 句柄表示。申请 LDO 通道资源的函数是 `esp_ldo_acquire_channel()`。申请成功后，会返回一个 LDO 通道的句柄，这个句柄可以用于后续的电压调节操作。在申请通道的时候，我们需要通过 `esp_ldo_channel_config_t` 结构体来指定 LDO 通道的基本信息，包括通道 ID，期望的输出电压，以及电压是否可以动态调节。

- `esp_ldo_channel_config_t::chan_id` - LDO 通道的唯一标记，用于区分不同的 LDO 通道。注意，这需要你根据电路原理图和芯片数据手册来确定。比如，一个标记着 "LDO_VO3" 的 LDO 通道，对应的 ID 是 3。

- `esp_ldo_channel_config_t::voltage_mv` - 期望的输出电压，单位是毫伏。

- `esp_ldo_channel_config_t::ldo_extra_flags::adjustable` - 是否允许调节输出电压。只有设置为 true，才允许使用 `esp_ldo_channel_adjust_voltage()` 函数来动态地调节输出电压。

由于允许多个用户同时使用固定电压的 LDO 通道，所以驱动内部会维持一个引用计数器。当最后一个用户释放 LDO 通道资源时，LDO 通道会被自动关闭。释放 LDO 通道资源的函数是 `esp_ldo_release_channel()`。另外还需要注意，申请和释放 LDO 通道在使用的时候需要成对出现。

### LDO 通道电压调节

`esp_ldo_channel_adjust_voltage()` 函数用来在运行时调整 LDO 通道的输出电压。但是，这个函数只能用于可调节电压的 LDO 通道，否则会返回错误。

注意，由于硬件限制，LDO 通道电压的精度可能会 50~100mV 左右的偏差，请勿依赖于 LDO 通道的输出电压来进行精确的模拟量控制。

## 应用示例

## API 参考

### Header File

- components/esp_hw_support/ldo/include/esp_ldo_regulator.h

- This header file can be included with:

  >     #include "esp_ldo_regulator.h"

### Functions

esp_err_t esp_ldo_acquire_channel(const esp_ldo_channel_config_t *config, esp_ldo_channel_handle_t *out_handle)

  Acquire an LDO channel with the specified configuration.

  备注

  This function can't automatically search a LDO channel for you, you must specify a LDO channel ID manually, based on your schematic.

  备注

  The same channel can be acquired multiple times in different places of the application code, however, if the LDO channel is adjustable, you can't acquire it multiple times, in case user A changes the voltage and breaks the voltage setting of user B.

  备注

  You should release the channel by `esp_ldo_release_channel` when it's no longer needed.

  参数:

    - config -- [in] The configuration of the LDO channel

    - out_handle -- [out] The returned LDO channel handle

  返回:

    - ESP_OK: Acquire the LDO channel successfully

    - ESP_ERR_INVALID_ARG: Acquire the LDO channel failed due to invalid arguments

    - ESP_FAIL: Acquire the LDO channel failed due to other reasons

esp_err_t esp_ldo_release_channel(esp_ldo_channel_handle_t chan)

  Release the LDO channel.

  参数:

    chan -- [in] The LDO channel handle returned from `esp_ldo_acquire_channel`

  返回:

    - ESP_OK: Release the LDO channel successfully

    - ESP_ERR_INVALID_ARG: Release the LDO channel failed due to invalid arguments

    - ESP_ERR_INVALID_STATE: Release the LDO channel failed due to invalid state, e.g., the channel handle is double released

    - ESP_FAIL: Release the LDO channel failed due to other reasons

esp_err_t esp_ldo_channel_adjust_voltage(esp_ldo_channel_handle_t chan, int voltage_mv)

  Adjust the voltage of the LDO channel.

  参数:

    - chan -- [in] The LDO channel handle returned from `esp_ldo_acquire_channel`

    - voltage_mv -- [in] The voltage value to be set to the LDO channel, in millivolts

  返回:

    - ESP_OK: Adjust the voltage of the LDO channel successfully

    - ESP_ERR_INVALID_ARG: Adjust the voltage of the LDO channel failed due to invalid arguments

    - ESP_ERR_NOT_SUPPORTED: Adjust the voltage of the LDO channel failed due to the channel is not adjustable

    - ESP_FAIL: Adjust the voltage of the LDO channel failed due to other reasons

esp_err_t esp_ldo_dump(FILE *stream)

  Dump LDO channel status to the specified stream.

  参数:

    stream -- [in] IO stream. Can be stdout, stderr, or a file/string stream.

  返回:

    - ESP_OK: Dump the LDO channel status successfully

    - ESP_FAIL: Dump the LDO channel status failed

### Structures

struct esp_ldo_channel_config_t

  LDO channel configurations.

  Public Members

  int chan_id

    You must set the LDO channel ID according to the datasheet, e.g., set it to 1 for LDO_VO1

  int voltage_mv

    The voltage value to be set to the LDO channel

  uint32_t voltage_stable_delay_us

    Delay in microseconds after LDO enable, wait for output voltage to stabilize. Set to 0 to skip

  struct esp_ldo_channel_config_t::ldo_extra_flags flags

    Flags for the LDO channel

  struct ldo_extra_flags

    Extra flags of a LDO channel.

    Public Members

    uint32_t adjustable

      Whether the LDO channel is adjustable, and the voltage can be updated by `esp_ldo_channel_adjust_voltage`

    uint32_t owned_by_hw

      If the LDO channel is owned by hardware, then software configurations can be overridden by hardware (e.g. eFuse)

    uint32_t bypass

      Whether to bypass the regulator, i.e., the input voltage is sourced directly to the output

### Type Definitions

typedef struct ldo_regulator_channel_t *esp_ldo_channel_handle_t

  Type of LDO regulator channel handle.

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。