使用外设

这些示例适用于标准的完整开发板镜像。目标端命令在 S31 上以 root 身份运行；明确标注为构建命令的步骤在 Linux 构建主机上执行。按从源码构建准备完整匹配镜像集。rootfs 包含 libgpiod v2 工具、I2C 工具、 spidev_test、aplay/arecord、candump 和 cansend。下文 CAN 示例还需要完整的 iproute2，外部 codec 示例则需要额外的内核选项。

示例依据驱动、随仓库提供的覆盖层，以及现有辅助程序/HIL 用法编写。已记录的硬件状态见支持矩阵，控制器限制和错误说明见外设参考。

连接前的准备

先用开发板默认路由确定 SoC GPIO 编号，再用自己开发板的原理图找到对应焊盘或连接器引脚。仓库没有提供完整的排针映射。应匹配信号电平，并在需要时共地。

每次只运行一个示例：UART1、SPI2 和 I2S0 默认配置会复用 GPIO42–45。先查看活动覆盖层和可用路由：

s31-overlay list
s31-overlay routes uart1
s31-overlay routes gpspi2
s31-overlay routes i2s0

继续前先停止占用冲突引脚的程序，并移除相应的临时覆盖层。各示例都使用 --volatile，不会更改已保存的启动选择。启动时恢复的持久覆盖层仍可能与临时示例冲突。应用命令失败时应停止，不要继续假定设备或引脚路由已经生效。

配置 GPIO

在 esp32-config 中选择 Interfaces → GPIO，选中引脚并设置模式：

模式	效果
Application controlled	释放引脚，交给应用或驱动使用
Input	保持输入模式，可选择无上下拉、上拉或下拉
Output low	保持逻辑 0 输出
Output high	保持逻辑 1 输出

选择 Save and apply 后立即生效，并在 Linux 启动时恢复。提交前返回会放弃本页编辑。引脚列表显示当前用途，以及尚未成功应用的保存设置。配置工具不能申请保留引脚，也不能占用其他应用或接口正在使用的引脚。

例如，GPIO42 空闲时：

esp32-config gpio list
esp32-config gpio set 42 high

退出命令或菜单后，输出仍会保持。将 GPIO43 配置为上拉输入，再读取电平：

esp32-config gpio set 43 input up
esp32-config gpio read 43

辅助服务运行期间会持续持有这些 GPIO 请求。通过 libgpiod 或其他接口使用这些引脚前，先释放它们：

esp32-config gpio set 42 application
esp32-config gpio set 43 application

选择应用控制会移除该引脚的保存配置。释放后不保证保持某个电平。启动恢复从 Linux 服务开始运行时生效；如果上电起就需要确定的电平，应通过板级电路或更早运行的固件处理。

在应用中使用 GPIO

确认 GPIO42 和 GPIO43 空闲后，将 GPIO42 接到 GPIO43，构成数字回环。先查看线路：

gpioinfo -c gpiochip0

在一个终端中，将 GPIO42 保持为高电平：

gpioset -c gpiochip0 42=1

在另一个终端读取 GPIO43，应报告有效/高电平输入：

gpioget --unquoted -c gpiochip0 43

在第一个终端按 Ctrl-C 释放输出请求，再使用 42=0 重复测试；GPIO43 应报告无效/低电平。Ctrl-C 会释放线路，应用不能依赖释放后的输出电平。将这些引脚分配给外设之前，先拆除回环线。

这些命令使用GPIO HIL 执行器采用的 libgpiod v2 语法。

UART1 接线回环

随仓库提供的 uart1 覆盖层将 TX 路由到 GPIO42、RX 路由到 GPIO43。将两者连接起来，确保 RX 上没有其他发送器驱动，然后执行：

s31-overlay apply uart1 --volatile
s31-hil-io uart /dev/ttyS1 115200 256
s31-overlay remove uart1 --volatile

辅助程序将串口设为原始模式、115200 波特率，发送 256 字节的测试模式并逐字节比较回传数据。成功时输出 PASS uart；未接线、超时或数据不匹配都会使命令失败。这里使用物理回传路径；uart-loopback 是辅助程序中另一种内部回环操作。连接外部 UART 设备时，将设备 TX 接到 S31 RX、设备 RX 接到 S31 TX，并匹配帧格式和波特率。保留 UART0 用作控制台。参见UART 辅助程序实现和UART1 路由。

SPI 主机：接线回环

未修改的 gpspi2 覆盖层使用 GPIO42 作为 SCLK、GPIO43 作为 MOSI、GPIO44 作为 CS0、GPIO45 作为 MISO。此回环只需将 MOSI 接到 MISO。以 100 kHz 运行 8 位传输：

s31-overlay apply gpspi2 --volatile
spidev_test -D /dev/spidev2.0 -s 100000 -b 8 -v -p '\x01\x02\x03\x04'
s31-overlay remove gpspi2 --volatile

详细输出中的 TX 和 RX 字节序列应一致。连接真实外设时，先拆除回环线，按需要连接 SCLK/MOSI/MISO/CS，并使用该外设规定的模式、事务格式和允许的时钟速率。主机驱动只接受 8 位字长；16/32 位支持属于目标模式。随仓库提供的 spidev 子节点还将传输速率限制为最高 20 MHz。

现有 s31-hil-io spi 辅助程序要求外部响应器返回特定的变换后模式，不能用它检查 MOSI/MISO 原样回传。来源：主机字长掩码、覆盖层默认配置、 spidev_test 选项。

SD 卡和 USB 存储

修改或关闭 SDMMC 接口前，先卸载 SD 文件系统并停用 SD 上的 swap。两个卡槽共用控制器，因此需要检查两个卡槽。任一 SD 卡仍被挂载或用于 swap 时，配置菜单会拒绝改动；保存未修改的设置不会重启控制器。

以下命令假定介质上已有 FAT 分区。先查看检测到的设备，必要时替换示例分区名；如果文件系统直接位于整个设备上，应使用磁盘节点而不是带 p1/1 的分区节点。

使用 SDMMC0 时，将合适的卡座连接到开发板表格中的固定引脚。默认覆盖层选择 4 位总线；仅接了 1 位数据线的卡座需要在应用时指定 bus-width=1。即使 DAT3 未连接到 S31，也要确保卡座在卡的 DAT3 引脚上提供 10 kΩ 上拉电阻。初始化时 DAT3 必须保持高电平，卡才能进入原生 SD 模式；未接到卡的 S31 焊盘上的上拉无法作用于卡引脚。参见固定版本的 S31 SD 卡接线及 1 位模式说明和 Linux 的 SD 初始化要求。完成卡座接线和供电后，执行：

s31-overlay apply sdmmc0 --volatile
ls /sys/class/mmc_host
cat /proc/partitions
mkdir -p /mnt/sd
mount -t vfat -o ro /dev/mmcblk0p1 /mnt/sd
ls /mnt/sd
umount /mnt/sd
s31-overlay remove sdmmc0 --volatile

基础设备树选择 USB 主机模式。确认 usb-device 未处于活动状态，通过开发板的 DWC2 主机连接接入存储设备，并在挂载前查看新增磁盘：

cat /proc/partitions
dmesg | tail -n 30
mkdir -p /mnt/usb
mount -t vfat -o ro /dev/sda1 /mnt/usb
ls /mnt/usb
umount /mnt/usb

成功列出目录表示已经能访问该文件系统。若未枚举出设备，应检查供电、接线、驱动探测消息和当前 USB 角色。若磁盘已出现但挂载失败，应检查分区和文件系统类型。完整内核包含 VFAT 和 EXT4；本示例以只读方式挂载 VFAT。仓库还提供了SD 读取和 USB 挂载 HIL 用例。

连接外部 codec 播放音频

请参阅连接外部 codec 播放音频，完成 PCM5102A 播放集成，包括接线、内核选项、声卡 overlay 和播放检查。该指南还说明了如何使用仓库提供的、接收外部时钟的 I2S overlay 进行录音。

USB CDC ACM gadget

请参阅 USB CDC ACM gadget，切换 DWC2 角色、配置串口功能、确定其设备节点，并在清理后恢复 host 模式。

通过外部收发器使用 CAN

按照开发板表格，将 TWAI0 TX/RX 接到合适的 CAN 收发器，再连接终端电阻正确配置、且有另一个活动节点的总线。两个节点必须使用相同的位速率。另一节点提供应答，也可发送已知帧用于接收检查。

rootfs 选择了 candump 和 cansend，但当前源 defconfig 没有选择 iproute2。使用下方 ip ... type can 命令之前，应在主机上的 buildroot-external/configs/esp32s31_rootfs_defconfig 中，用以下设置替换现有的禁用项，然后重新配置、获取所需软件包源码，并构建和烧录完整匹配集：

BR2_PACKAGE_IPROUTE2=y

make buildroot-reconfigure
make fetch
make image
make flash-existing-all PORT=/dev/ttyUSB0

在 S31 上配置 500 kbit/s 总线：

s31-overlay apply twai0 --volatile
ip link set can0 type can bitrate 500000
ip link set can0 up
ip -details -statistics link show can0
candump can0

保持 candump 运行，在第二个终端发送以下帧并在对端查看。再让对端发回一个已知帧，检查 candump 输出：

cansend can0 123#11223344

按 Ctrl-C 停止 candump，然后释放接口：

ip link set can0 down
s31-overlay remove twai0 --volatile

若发送失败，应检查错误计数器及对端接收情况。支持矩阵仍将 CAN 列为开发中。来源： rootfs 软件包选择、 SocketCAN 位速率设置。

使用仓库提供的 PHY 配置连接以太网

gmac 覆盖层启用基础 RGMII 配置，针对 MDIO 地址为 0、复位使用 GPIO7 的 YT8531DC-CA PHY。请结合开发板表格和基础 DTS，匹配 RGMII/MDIO 接线、PHY 地址、复位与延时；使用不同 PHY 时应编写相应的板级设备树。

在匹配的开发板上连接有 DHCP 服务的网络后：

s31-overlay apply gmac --volatile
ip link set eth0 up
cat /sys/class/net/eth0/carrier
udhcpc -n -q -i eth0
ip addr show dev eth0

载波状态应变为 1，成功的 DHCP 交互会分配地址。使用该地址与已知对端交换数据包。若 DHCP 失败，应分别检查链路状态和网络地址服务。关闭使用以太网的应用后：

ip link set eth0 down
s31-overlay remove gmac --volatile

此示例依据具体 PHY 描述和现有以太网探测/链路检查。报告硬件结果时，请记录开发板版本、PHY、内核/构建配置、链路对端和观察结果。