使用覆盖层

设备树覆盖层（overlay）用于启用可选外设并选择引脚。在 esp32-config 的 Interfaces 中选择接口，编辑引脚和参数。页面分别显示当前启用状态和保存的启动选择；字段值不同时，会标出保存值。 Unavailable 表示无法读取当前状态。已启用的接口可以直接编辑；固定引脚只显示，不能修改。

选择 Enabled 后显示参数字段，再选择 Save and apply 更新接口和启动选择。保存 Disabled 会删除该接口的保存配置。如果提交值与当前值和保存值都相同，接口会继续运行，不会重新应用。

脚本可以通过 s31-overlay 命令完成覆盖层操作。

列出可用的覆盖层

s31-overlay list
s31-overlay status

list 显示镜像中已安装的覆盖层。在 status 输出中，active: 条目来自运行中的内核， persisted: 列出为下次启动保存的预期选择。可选外设驱动已包含在统一的完整配置中，仍需配置覆盖层与实际硬件。

分组	覆盖层名称	备注
UART	`uart1`, `uart2`, `uart3`, `uart3-dma`	DMA 使用 UHCI0 和 AHB GDMA 通道对 0
I2C	`i2c0`, `i2c1`	独立的控制器及 SCL/SDA 路由
SPI	`gpspi2`, `gpspi2-target`, `gpspi3`, `gpspi3-target`	为各控制器选择主机或目标端模式
音频	`i2s0`, `i2s1`	I2S 控制器和音频路由
CAN	`twai0`, `twai1`	需要外部 CAN 收发器
SD/MMC	`sdmmc0`, `sdmmc1`, `sdmmc-dual`, `sdmmc-uhs`	各变体共享 SD/MMC 主机
以太网	`gmac`	外部 PHY 和 RGMII 接线
USB	`usb-device`	将 USB OTG 控制器切换到设备模式
定时器	`timers`	提供每个定时器组中的定时器 0
PWM/计数器	`pwm-counter`	PWM 和脉冲计数器模块
模拟	`analog`	模拟模块及其焊盘选择
看门狗	`watchdogs`	看门狗模块
DMA	`gdma`	AHB GDMA 通道对 4
无线	`radio-wifi`, `radio-bluetooth`, `radio-combo`	选择一个无线覆盖层
LP 核	`lp`	LP remoteproc 和邮箱

应用覆盖层

使用默认设置启用 I2C0：

s31-overlay apply i2c0

工具会立即应用覆盖层，并保存该名称对应的选择。如需临时更改并保留原有保存设置，可添加 --volatile：

s31-overlay apply i2c0 --volatile

使用 status 检查结果，然后通过该外设的 Linux 接口使用它。

选择引脚和参数

先查看可用设置：

s31-overlay routes i2c0
s31-overlay parameters i2c0
s31-overlay describe i2c0

routes 和 parameters 显示已安装覆盖层的默认值与可选项。 describe 以制表符分隔的记录分别显示默认值、当前值和保存值。如果无法确定活动覆盖层的当前参数，current_known 为 0，当前值字段显示 -。固定 GPIO 声明以 fixed_gpio 记录显示。无法读取当前引脚值时，菜单会要求先关闭该接口，再重新配置。

例如，使用 GPIO35 作为 SCL、GPIO36 作为 SDA，并将总线频率设为 400 kHz：

s31-overlay apply i2c0 i2c0.scl=35 i2c0.sda=36 clock-frequency=400000

路由键由覆盖层定义。标准目录提供以下数值参数：

覆盖层	参数	允许的值
`i2c0`, `i2c1`	`clock-frequency`	`100000`, `400000`, `1000000`
SD/MMC 变体	`bus-width`	`1`, `4`

管理器检查 GPIO、输入路由、控制器或 DMA 资源是否冲突。flash 和控制台引脚已预留。连接外部设备前应检查的事项及默认路由见开发板指南。

移除或恢复覆盖层

关闭使用该外设的应用程序，然后移除其覆盖层：

s31-overlay remove i2c0

覆盖层已经停用时，此命令仍可清除它的保存选择。

使用 remove --all 移除所有受管理的覆盖层。命令成功后，对当前状态和保存设置的影响如下：

命令	当前生效的覆盖层	保存的选择
`apply NAME`	应用或替换 `NAME`	仅添加或替换 `NAME` 条目
`remove NAME`	移除 `NAME`	仅移除 `NAME` 条目
`remove --all`	移除所有受管理的覆盖层	清空所有已保存条目
为以上命令添加 `--volatile`	执行相同的运行时更改	保持已保存条目不变

后续的常规命令会保留其他已保存条目。例如，先通过 --volatile 应用 uart1，再正常应用 uart2，只会保存对 uart2 的更改。反过来，通过 --volatile 移除已保存的覆盖层，也会保留其下次启动时的选择。

保存的覆盖层会在启动时自动恢复。如需手动重新加载该集合，运行：

s31-overlay restore

保存文件存在且可读时，restore 会移除当前集合并应用已保存的条目，从而中断涉及的外设。空文件会清空当前集合。文件不存在时，命令成功返回并保持当前覆盖层不变；文件格式错误或不可读时，会在更改当前覆盖层之前停止。

要根据已安装的覆盖层目录检查配置文件，并保持硬件不变，可运行 s31-overlay check /etc/esp32-conf/overlays.conf。该命令校验文件、覆盖层名称和参数；实际应用时再检查当前的引脚和资源冲突。

USB 角色切换还会重新启动 USB 控制器；应先卸载已连接的 USB 存储设备，并禁用位于 USB 上的 swap。

保存的设置与故障排查

覆盖层通过 /dev/s31-overlay 加载。覆盖层文件存储在 /usr/lib/s31-overlays 下，保存的设置位于 /etc/esp32-conf/overlays.conf。 CLI 将运行时选择记录在 /run/s31-overlay.current 中；status 则向内核查询当前生效的集合。存储容量和文件保留规则见配置。

操作失败时，请检查错误信息、s31-overlay status 和 dmesg：

故障	检查事项
准备持久化集合失败	检查保存文件的语法和可读性。命令会在更改当前覆盖层之前停止。
替换当前覆盖层失败	内核会尝试重新应用原有覆盖层。如果回滚也失败，原有覆盖层将丢失；请在 `dmesg` 中查找回滚错误。
`overlay applied, but recording state failed` 或对应的移除错误	硬件更改已经发生。分别检查当前状态和保存设置，解决存储错误后，再次执行所需命令。
`restore` 应用某个条目时失败	CLI 会尝试移除已恢复的部分集合。它不会重建执行 `restore` 前的集合；继续操作前应检查当前生效的覆盖层。

保存文件无法读取或解析时，也会显示 persisted: (none)。如果已保存的选择意外从状态输出中消失，请检查 /etc/esp32-conf/overlays.conf，并参照配置中的存储检查步骤。