ResearchGate 树莓派单板计算机使用说明书

法律免责声明
树莓派产品（包括数据表）的技术和可靠性数据（“资源”）由树莓派有限公司（“RPL”）“按原样”提供，不作任何明示或暗示的保证，包括但不限于适销性和特定用途适用性的暗示保证。在适用法律允许的最大范围内，RPL 在任何情况下均不对任何直接、间接、附带、特殊、惩罚性或后果性损害（包括但不限于替代商品或服务的采购；使用、数据或利润的损失；或业务中断）承担责任，无论此类损害是如何造成的，也无论基于何种责任理论，无论是合同、严格责任还是侵权（包括过失或其他），即使已被告知此类损害的可能性。

RPL 保留随时对资源或其中描述的任何产品进行任何增强、改进、更正或任何其他修改的权利，无需另行通知。
本资源适用于具有适当设计知识水平的熟练用户。用户对本资源的选择和使用以及其中描述的任何产品的应用负全部责任。用户同意赔偿 RPL 并使其免受因使用本资源而产生的所有责任、费用、损害或其他损失。
RPL 仅允许用户将资源与 Raspberry Pi 产品结合使用。禁止将资源用于其他任何用途。不授予任何其他 RPL 或其他第三方知识产权许可。

高风险活动。Raspberry Pi 产品并非设计、制造或用于需要故障安全性能的危险环境，例如核设施、飞机导航或通信系统、空中交通管制、武器系统或安全关键应用（包括生命支持系统和其他医疗设备）的运行，在这些环境中，产品故障可能直接导致死亡、人身伤害或严重的物理或环境损害（“高风险活动”）。RPL 明确否认对高风险活动适用性的任何明示或暗示担保，并且对在高风险活动中使用或包含 Raspberry Pi 产品不承担任何责任。
Raspberry Pi 产品受 RPL 标准条款约束。RPL 提供的资源不会扩大或以其他方式修改 RPL 标准条款，包括但不限于其中表达的免责声明和保证。

文档版本历史

发布	日期	描述
1	1 年 2025 月 XNUMX 日	初始版本

文件范围
本文档适用于以下树莓派产品：

单板计算机/SBC

Pi 零	Pi Zero 2	树莓派 1	树莓派 2	树莓派 3	树莓派 4	树莓派 5
✓	✓	✓	✓	✓	✓	–

计算模块

CM1	CM3	CM4	CM5
✓	✓	✓	✓

介绍

USB On-The-Go (OTG) 是一种规范，它允许设备既可以作为 USB 主机（例如 PC），也可以作为 USB 设备/外设（例如键盘、以太网适配器或大容量存储设备）。维基百科的“USB On-The-Go”页面提供了关于 OTG 规范的大量详细信息： https://en.wikipedia.org/wiki/USB_On-The-Go.
通常，USB 连接涉及一个固定的主机（例如计算机）和一个外围设备（例如鼠标）。USB OTG 允许设备在两者之间切换。例如：amp例如，树莓派可以在读取数据时充当主机。 file可以从闪存驱动器读取数据，或者连接到计算机时本身就可以作为闪存驱动器使用。

树莓派系列包含多款支持OTG/外设模式的开发板，但具体支持情况因型号和系统芯片（SoC）而异。在这种外设模式下，该设备通常被称为“小工具”。
本白皮书详细介绍了树莓派单板计算机产品线，解释了它们的OTG功能，并提供了配置/代码示例。amp它涵盖了两种不同的 OTG 机制：传统方法（仍然非常流行，首先进行描述）和当前推荐的方案 ConfigFS。

传统 OTG

树莓派 Zero / Zero W / Zero 2 W
这些开发板是树莓派系列中最支持OTG功能的。它们将SoC的USB控制器直接暴露在USB数据端口（标有USB而非PWR IN的端口）上，并且可以通过配置板载软件使树莓派充当OTG设备。

启用 OTG 模式

提示： 由于您将树莓派 Zero 上唯一的 USB 端口用于 OTG 功能，因此无法插入键盘或鼠标。您可以改用 Wi-Fi 连接和 SSH 与树莓派 Zero 通信……

dtoverlay=dwc2

现在我们需要配置软件，将所需的OTG驱动程序连接到USB系统……

console=serial0,115200 console=tty1 root=PARTUUID=xxxxxxxx-02 rootfstype=ext4 fsck.repair=yes rootwait modules-load=dwc2,g_ether

其他小工具模块
而不是 g_ether您可以尝试：

g_serial：显示为 USB 串口设备
g_mass_storage：曝光图像 file 用作U盘
g_composite模拟复合设备

提示
USB复合设备是一种物理设备，它能作为多个独立设备在计算机上运行，表现为多个独立的接口或设备类。它集成了多种功能，例如键盘和鼠标，或者存储驱动器和…… web摄像头集成到一个USB设备和接口中。连接后，操作系统会识别并使用设备各项不同功能的独立驱动程序，从而使它们能够独立运行。

要创建 USB 串口设备，我们可以从命令行加载相应的模块：

代码
sudo modprobe g_serial

当连接到 Windows PC 时，Raspberry Pi 将在设备管理器中显示为 COM 端口；当连接到 Linux 设备（例如 Raspberry Pi SBC）时，它将显示为类似 /dev/ttyACM0 的串行设备。

树莓派 4 和 5（通过 USB-C 电源端口支持 OTG）
树莓派 4 的 USB-C 电源/OTG 端口在不用于给电路板供电时支持外设模式。
树莓派 5 引入了一个 PCIe 连接的 USB 控制器，该控制器不支持 OTG 功能。但是，与树莓派 4 一样，SoC 上的原生 OTG 外设功能通过电源接口暴露出来。

步骤
通过 GPIO 接头（5V 和 GND）为 Raspberry Pi 供电，使 USB-C 接口空闲。
将 USB-C 端口连接到主机。

在 /boot/firmware/config.txt 中启用 OTG

代码
dtoverlay=dwc2,dr_mode=外设

笔记
您需要在 overlay 文件中使用 dr_mode=peripheral 选项，强制控制器进入 OTG 外设模式（而不是主机模式），因为 Raspberry Pi 4 或 5 上没有通常用于选择 OTG 外设的 OTG_ID 行。）

加载设备模块（以太网）：
代码
sudo modprobe g_ether
您的树莓派现在将被主机识别为 USB 设备。

提示
并非所有主机系统都能可靠地支持树莓派 4 的 OTG 模式。以太网和串口连接效果最佳。

树莓派计算模块系列
树莓派计算模块 1、3、3+ 和 4 将 SoC 的 USB OTG 控制器直接暴露给载板，使其具有很高的灵活性。
CM1/CM3/CM3+ 的 USB OTG 接口位于专用引脚上；载板通常通过 micro-USB 端口提供此接口。CM4 提供支持 OTG 功能的 USB 2.0 接口 (USB_OTG)。此接口连接至计算模块 4 IO 板的 micro-USB 连接器。

CM4 OTG example（以太网设备）
将micro-USB线缆插入IO板上的USB端口。

在 /boot/firmware/config.txt 文件中添加：

代码
dtoverlay=dwc2,dr_mode=外设

在 /boot/cmdline.txt 文件中添加：

代码
modules-load=dwc2,g_ether

重启后，计算模块 4 将显示为 USB 以太网适配器。

树莓派 A、B、B+、2B、3B、3B+
这些型号的USB端口通过集线器芯片（LAN9512/LAN9514或VIA Labs）连接，因此丧失了OTG功能。它们只能作为USB主机运行，所以不支持OTG。

使用各种设备类型
本节介绍如何设置最常用的设备模式。

大容量存储设备
要将树莓派用作大容量存储设备（例如U盘），您需要创建一个后端。 file 用于保存存储的数据：

代码
- ＃前任ample：制作一个 256 MB file 用作“U盘”
- sudo dd if=/dev/zero of=drive.bin bs=1M count=256
- # 创建 VFAT file 后备商店的系统
- sudo mkfs.vfat drive.bin
编辑 /etc/modprobe.d/g_mass_storage.conf 文件，告诉系统使用后备存储：
- 代码
- 选项 g_mass_storage file=/drive.bin 停滞=0 可移除=1
- 您可以通过将后端存储挂载到树莓派上来查看其内容。这里我们将其挂载到名为 mountpoint 的文件夹中：
代码
- sudo mkdir mountpoint
- sudo mount -o loop drive.bin 挂载点

您需要根据实际情况调整路径。

以太网设备
当 g_ether 设备插入 Linux 主机时，它通常会显示为名为 usb0 的网络接口（使用 ifconfig 时）。
通常情况下，您可以使用 SSH 连接到设备，方法如下：

代码
ssh pi@raspberrypi.local

串行设备

当树莓派被设置为 g_serial 设备时，会出现一个新的串口设备（在使用内核版本为 6.12.34 的树莓派操作系统 Bookworm 时，该设备为 /dev/ttyGS0）。然后，当该树莓派设备插入（例如）amp例如，在 Linux 主机上，该设备将被识别为符合 CDC ACM 标准的设备，并显示为另一个串口。amp例如，在运行 Bookworm 的 Raspberry Pi 500 上，它显示为 /dev/ttyACM0。
在 Linux 系统下，您可以使用 screen 命令在每个设备上测试串口连接。如果主机使用的是 Windows 系统，则可以使用 PuTTY 之类的工具。

在你的树莓派上：

代码
屏幕 /dev/ttyGS0

在 Linux 主机上：

代码
屏幕 /dev/ttyACM0

然后在每个窗口中输入内容——输出结果应该会显示在另一个屏幕上。

笔记
如果未安装 screen，请在终端窗口中使用 sudo apt install screen。
很容易看出，此功能可用于为树莓派设备提供串行接口，该设备监控多个传感器（例如通过 I2C 或 SPI），并将收集到的信息通过串行端口传递回主机。

ConfigFS/usb_gadget：一个崭新的世界

尽管上述机制是目前在 Raspberry Pi 设备上设置 OTG 的最常见方法，但实际上已被 usb_gadget 取代，而 usb_gadget 是 ConfigFS 的一部分。
ConfigFS 是 Linux 内核的一个接口（一个虚拟接口）。 file 系统挂载在 /sys/kernel/config 目录下，用于以模块化方式配置内核对象（包括 USB 设备驱动程序）。使用 ConfigFS / usb_gadget 比旧的 g_mass_storage /g_ether 方法更灵活，因为您可以同时组合多个 USB 功能（例如以太网 + 串口 + 大容量存储）。
然而，这些额外的功能也带来了更高的设置成本。
基本思路是，一组虚拟文件夹和 files 在 /sys/kernel/config 文件夹下创建，该文件夹定义了所需的 gadget。
这里提供了一些关于 usb_gadgets 的内核文档： https://docs.kernel.org/driver-api/usb/gadget.html 和 https://www.kernel.org/doc/Documentation/ABI/testing/configfs-usb-gadget.

设置
DWC USB 外设的设置与传统模式下相同。使用 sudo 编辑 config.txt 文件并添加：

我们可以通过查看 /sys/kernel/config 的内容来检查它是否已正确加载，该目录现在应该包含一个名为 usb_gadget 的文件夹。
接下来是创建实际的 USB 设备，这包括创建一个以设备名称命名的文件夹，然后在该文件夹内创建一组条目来定义设备的属性。以下 bash 脚本片段完成了大部分必要的设置：

现在基本设备数据已经设置完毕，我们需要告诉设备它的具体用途。创建每个设备都很简单，只需在 ConfigFS 小工具的 functions 文件夹中创建一个文件夹，然后将该文件夹链接到同一小工具中的配置条目即可。

序列号（CDC ACM）：

以太网（RNDIS 和 ECM）：

大容量储存：
与传统方案一样，我们的海量存储设备需要一个备用存储：

而要使用它：

提示
/sys/class/udc 是 sysfs 中的一个目录。 file 该系统用于表示可用的 USB 设备控制器 (UDC)。它允许内核的 USB 设备子系统识别设备上的硬件 UDC 并与之交互，从而使系统能够作为 USB 外设运行。您可以使用 `ls /sys/class/udc/` 命令列出其内容，以查找 UDC 的名称，例如 `3f980000.usb`，然后将该名称写入设备的配置，以将设备绑定到该 UDC。

设置完成后，文件夹结构和内容应与之前类似。amp下面的示例在同一设备上设置串行设备和以太网设备：

现在重启，然后将树莓派连接到主机设备（例如另一台树莓派、Windows PC 或 Linux PC）。主机应连接一个 USB 以太网设备和一个串口设备。

让一切运转起来
上述所有命令都需要在每次 Raspberry Pi 设备启动时运行。由于 Raspberry Pi OS 使用 systemd，因此这是运行启动脚本（执行所有设置）的正确方法。以下是一个示例。amp汇总以上所有指令的脚本：

现在我们需要告诉 systemd 在启动时运行我们的脚本。
创建一个 file 在 /lib/systemd/system 目录下——你可以随意选择名称（只要后缀是 .service 即可），但对于这个例子来说……amp例如，我们将使用 mass-storage-device.service。请将以下内容输入到…… file （请注意，这些服务有很多不同的选项） file（我们只用了我们需要的那些）：

您需要修改 ExecStart 行，使其指向您保存安装脚本的位置。然后，您需要告诉 systemd 在启动时运行该服务：

现在，当你将树莓派连接到主机时，它应该会显示为一个大容量存储设备。你可以按如下方式禁用 systemd 服务：

将登录控制台连接到串口

如果您已将 Raspberry Pi 设置为串口设备，您可能希望使用该串口设备登录，而不仅仅是用于点对点串口通信。在运行 systemd 的最新版 Raspberry Pi OS 上，这很容易实现。您需要指示系统在串口上创建一个 getty 终端，然后指示 systemd 启动它。以下命令在 ttyGS0（使用 ConfigFS 设置串口设备时创建的终端）上设置 getty 终端；您可能需要根据实际分配给串口设备的终端进行调整。

这将启动串口上的 getty 服务，并确保每次重启后都能自动启动。

提示
什么是 getty？在 Linux 中，getty 是一个管理终端（包括物理串口和虚拟控制台）的程序，它允许多个用户登录到系统，处理诸如初始化终端、显示登录提示符以及调用登录程序来验证用户身份等任务。

这项功能在 Raspberry Pi Zero 或 Raspberry Pi Zero 2 W 等设备上尤其有用。只需一根 USB 连接线即可同时提供电源和串口通信，您可以插入设备并通过终端登录。

结论
对于真正的 USB 设备项目（例如以太网、串行、大容量存储），树莓派 Zero 系列和树莓派计算模块是最佳选择。
树莓派 4 和树莓派 5 确实提供了 OTG 支持，但它们的功耗可能是一个问题。
树莓派 A、B、2B、3B 和 3B+ 板不支持 OTG。
如果你的项目严重依赖 OTG，那么最好的选择是 Raspberry Pi Zero 2 W 或 Raspberry Pi Compute Module 4 搭配 Compute Module 4 IO 板。
软件方面有两种选择：传统系统仍然很常用，而且设置简单；ConfigFS 系统需要更多的设置工作，但确实提供了更好的功能。

快速参考表

模型	OTG 支持	笔记
树莓派 Zero / Zero W / Zero 2 W	是的	完全支持 USB 数据端口
树莓派 4	是的¹	USB-C 端口处于设备模式
树莓派 5	是的¹	USB-C 端口处于设备模式
树莓派 A/B/2B/3B/3B+	不	仅主机模式
树莓派计算模块 1–3	是的	OTG引脚裸露在外
Raspberry Pi 计算模块 4	是的	CM4 IO 板上的 micro-USB 接口

¹ 树莓派 4 和 5 通常通过 USB 电缆从主机获取电源，因此由于这些设备的功率需求较高，可用电流可能会受到限制。

联系方式，了解更多信息
请联系应用程序@raspberrypi.com 如果您对本白皮书有任何疑问。 Web: www.raspberrypi.com

常见问题

启用OTG模式有哪些风险？

启用OTG模式需要编辑系统。 file这些操作如果操作不当可能会带来风险。建议您仔细阅读并遵循说明，并在进行任何更改之前备份重要数据。

除了Zero、Zero W和Zero 2 W之外，我可以在树莓派的其他型号上使用OTG模式吗？

虽然提供的说明是针对所提及的型号的，但您可以通过适当的调整在其他 Raspberry Pi SBC 上探索类似的配置。

文件/资源

ResearchGate 树莓派单板计算机 [pdf] 使用说明书
树莓派单板计算机，树莓派，单板计算机，板载计算机，计算机

参考

用户手册

ResearchGate 树莓派单板计算机

产品信息

介绍