计算模块硬件

计算模块

树莓派计算模块是衍生于旗舰级树莓派的嵌入式核心板（system-on-module，SOM）。计算模块在工业和商业应用中极受欢迎，如数字标牌、瘦客户机和自动化流程。上述程序有设计用于旗舰级树莓派的，但许多用户希望拥有更紧凑的设计及内置 eMMC 存储。

计算模块有多款衍生产品，内存和嵌入式多媒体卡（eMMC）闪存容量各不相同。eMMC 类似于 SD 卡，只是焊接在主板上。与 SD 卡不同，eMMC 专门设计用作磁盘，包含增强功能来提高可靠性。Lite 型号未搭载内置存储，并且有时用简写后缀 L 来表示，例如“CM3L”。

计算模块使用以下树莓派 SoC（片上系统）:

CM1 采用 BCM2835
CM3, CM3+ 采用 BCM2837
适用于 CM4，CM4S 的 BCM2711

计算模块 4

最新款的计算模块是计算模块 4（CM4）。我们建议，现在所有的开发都应使用 CM4。

计算模块 4

计算模块 4（CM4）搭载了树莓派 4 的内部构件（BCM2711 处理器和 1GB、2GB、4GB 或 8GB 的 RAM），以及可选的 0GB（Lite）、8GB、16GB 或 32GB 的 eMMC 闪存存储。

与 CM1、CM3 和 CM3+ 不同，CM4 未使用 DDR2 SODIMM 外形规格。相反，CM4 使用了两个 100 针高密度连接器，有更小的物理空间占用。这种变化帮助增加了以下接口：

额外的第二个 HDMI
PCIe
以太网

旧版的外形规格无法支持这些接口。

计算模块 4S

计算模块 4S（CM4S）搭载了树莓派 4 的内部构件（BCM2711 处理器和 1GB、2GB、4GB 或 8GB 的 RAM），以及可选的 0GB（Lite）、8GB、16GB 或 32GB 的 eMMC 闪存存储。与 CM4 不同，CM4S 采用了与 CM1、CM3 和 CM3+ 相同的 DDR2 SODIMM 外形规格。

计算模块 3+

计算模块 3+（CM3+）搭载了树莓派 3B+（BCM2837 处理器和 1GB 内存）的内部构件，以及可选的 0GB（Lite）、8GB、16GB 或 32GB eMMC 闪存存储。

计算模块 3

计算模块 3（CM3）搭载了树莓派 3 的内部构件（BCM2837 处理器和 1GB 的 RAM），以及可选的 4GB eMMC 闪存存储。

计算模块 1

计算模块 1（CM1）搭载了树莓派的内部构件（BCM2835 处理器和 512MB 内存），以及可选的 4GB eMMC 闪存存储。

IO 板

树莓派 IO 板提供了一种将单个计算模块连接到各种 I/O（输入/输出）接口的方法。由于计算模块本质上较小，因此它们缺少端口和连接器。IO 板提供了一种将计算模块连接到各种外围设备的方法。

IO 板是旨在开发的分支板；在生产中，你应该使用一个更小的、也许是定制的板——这块板仅提供了你的用例所需的端口和外部设备。

计算模块 4 IO 板

计算模块 4 IO 板提供以下接口：

带有 40 针 GPIO 连接器和 PoE 标头的 HAT 印记
两个 HDMI 端口
两个 USB 2.0 端口
带 PoE 支持的千兆以太网 RJ45

计算模块 IO 板

计算模块 IO 板提供以下接口：

120 个 GPIO 引脚
一个 HDMI 端口
一个 USB-A 端口
MIPI DSI × 2 显示器 FPC 连接器（22 针 0.5 mm 间距电缆）

计算模块 IO 板有两个衍生：版本 1 和版本 3。版本 1 仅兼容 CM1。版本 3 兼容 CM1、CM3、CM3+ 和 CM4S。计算模块 IO 板版本 3 有时被简写为 CMIO3。

IO 板兼容性

不是所有计算模块 IO 板都适用于所有计算模块型号。以下表格显示了每个 IO 板适用于哪些计算模块：

IO 板

兼容的计算模块

将镜像刷写到计算模块

计算模块搭载了连接到主 SD 卡接口的内置 eMMC 设备。本指南解释了如何将操作系统镜像刷写到单个计算模块的 eMMC 存储器。

当向多个计算模块刷写镜像时，请考虑使用计算模块配置工具：

使用计算模块配置器进行大规模配置

计算模块配置器是一款 Web 应用程序，可帮助开发人员同时为多个计算模块设备编程。

它提供了内核镜像数据库和在闪存过程中运行脚本的能力，以及自动标签打印和固件更新。

准备工作

要刷写计算模块 eMMC，你需要以下物品：

本指南中称为主机设备的其他计算机。你可以使用 Linux（树莓派系统或 Ubuntu）、Windows 和 macOS。
与你的计算模块型号对应的计算模块 IO 板。
一根 Micro USB 线。

设置 IO 板

要开始，物理设置你的 IO 板。比如将计算模块和主机设备接入 IO 板。

使用计算模块 4 IO 板

设置计算模块 4 IO 板：

将计算模块连接到 IO 板。连接后，计算模块应该平放。
将 nRPI_BOOT 安装到 IO 板跳线帽 J2（ disable eMMC Boot ）。
将一根电缆从 IO 板上的 micro USB 从机端口 J11 连接到主机设备。

使用计算模块 IO 板

要设置计算模块 IO 板：

将计算模块连接到 IO 板。连接后，计算模块应平行于板放置，使接合夹牢固地卡入位。
将 J4（启用 USB SLAVE BOOT）设置为 1-2 =（启用 USB BOOT）
将一根电缆从 IO 板上的 micro USB 从机端口 J15 连接到主机设备。

配置主机设备

接下来，在主机设备上配置软件。

在 Linux 上配置软件

在 Linux 主机设备上配置软件：

运行以下命令安装 rpiboot ：
将 IO 板接入电源。
然后运行 rpiboot :

技巧
你还可以从源代码编译 rpiboot。

在 macOS 上配置软件

在 macOS 主机设备上配置软件：

首先，从源代码编译 rpiboot。
将 IO 板连接到电源。
然后，使用以下命令运行 rpiboot 可执行文件：

在 Windows 上配置软件

在 Windows 主机设备上配置软件：

下载 Windows 安装程序
双击安装程序运行。这将安装驱动程序和引导工具。
将 IO 板连接到电源。Windows 应该会发现硬件并配置所需的驱动程序。
双击运行 RPiBoot.exe

技巧
或者，你可以从源代码编译 rpiboot。

刷写 eMMC

你可以使用树莓派启动盘制作工具把操作系统镜像刷写到计算模块上。

还可使用 dd 来将裸操作系统镜像（例如树莓派系统）写入你的计算模块。运行以下命令，请把 /dev/sdX 替换成你的计算模块的大容量存储设备代表形式的路径，并把 raw_os_image.img 替换为你的原始操作系统镜像的路径：

镜像写入后，断开计算模块，然后重新接入。现在应该能看到两个分区（用于树莓派系统）：

你可以正常挂载分区 /dev/sdX1 和 /dev/sdX2。

从 eMMC 启动

使用计算模块 4 IO 板

从 IO 板跳线上的 J2 (禁用 eMMC Boot) 断开 nRPI_BOOT。

使用计算模块 IO 板

将 J4（启用 USB SLAVE BOOT）设置为 2-3（禁用 USB BOOT）。

启动

断开 USB 从属端口。重启 IO 板，从你刚刚写入 eMMC 的新镜像引导计算模块。

已知问题

小部分 CM3 存在启动问题。我们已经认识到这些问题与创建 FAT32 分区的方法有关；我们认为问题是由于 CPU 和 eMMC 之间的时序差异造成的。如果你在启动 CM3 时遇到问题，请使用以下命令手动创建分区：
CM1 引导加载程序会向主机返回一个略有错误的 USB 数据包。大多数 USB 主机会忽略它，但由于该问题，某些 USB 接口无法工作。CM3 已修复该错误。

计算模块 4 引导加载程序

CM4 上的默认引导加载程序配置旨在支持在计算模块 4 IO 板上启动和开发，并且在制造时刷写的软件版本可能比最新版本要旧。对于最终产品，请考虑：

选择并验证特定的引导加载程序版本。usbboot 存储库中的版本始终是最新稳定版本。
配置引导设备（例如网络引导）。请参阅引导加载程序配置指南中的 BOOT_ORDER 部分。
启用引导加载程序 EEPROM 上的硬件写保护，可确保在无法触及的产品（如远程和嵌入式设备）上的引导加载程序无法被篡改。

注意
计算模块 4 ROM 不从 SD/EMMC 运行 recovery.bin，在默认情况下，服务 rpi-eeprom-update 未启用。这是必要的，因为 EMMC 不可拆卸，无效的 recovery.bin 文件将妨碍系统启动。这可以被覆盖，与 self-update 模式一同使用，其中引导加载程序可以从 USB 大容量存储设备和网络引导进行更新。但是，在更新 EEPROM 时发生断电后，self-update 模式不是原子更新，所以不安全。

除存储卡之外的闪存设备

基于 Linux 的大容量存储设备支持 NVMe、EMMC 和 USB 设备的闪存存储。这通常比使用 rpiboot 固件驱动程序更快，还为设备提供串口控制台，可更容易地进行调试。

另请参阅：CM4 rpiboot 扩展。

修改引导加载程序配置

要修改 CM4 引导加载程序配置：

切换到目录 usbboot/recovery
如果需要特定的引导加载程序版本，请替换 pieeprom.original.bin
编辑默认的引导加载程序配置文件 boot.conf；通常至少需要更新 BOOT_ORDER：

文件 pieeprom.bin 现在已准备好刷写到计算模块 4 了。

为计算模块 4 刷写引导加载程序 EEPROM

要刷写引导加载程序 EEPROM，请遵循与刷写 EMMC 相同的硬件设置，但还要确保 EEPROM_nWP 未被拉低。完成后，EEPROM_nWP 可以再次被拉低。运行以下命令将 recovery/pieeprom.bin 写入引导加载程序 EEPROM：

连接外围设备

本指南帮助开发人员将外围设备连接到计算模块引脚。此外，本指南解释了如何更改软件以启用这些外围设备。

SoC 的大多数引脚（GPIO、两个 CSI 摄像头接口、两个 DSI 显示接口、HDMI 等）可用于连接。通常可以将未使用的引脚保持未连接状态。

带有 DDR2 SODIMM 外形规格的计算模块能插入 DDR2 SODIMM 插槽。但是，引脚分配与 SODIMM 内存模块不同。

要使用计算模块，用户设计的主板必须满足：

为计算模块供电（3.3V，最低 1.8V）
将引脚连接到用户应用程序所需的外围设备

树莓派的 IO 板提供以下功能：

为模块供电
将 GPIO 引线连接到引脚排
将摄像头和显示接口引线连接到 FFC 连接器
将 HDMI 引线连接到 HDMI 端口

本指南首先解释了引导过程以及设备树如何描述连接的硬件。

然后，我们将解释如何将 I²C 和 SPI 外围设备连接到 IO 板。最后，我们将创建使用这两个外围设备所需的设备树文件，以便在树莓派系统上使用。

BCM283x GPIO

BCM283x 带有三个通用输入/输出（GPIO）引脚组：BANK0 上有 28 个引脚，BANK1 上有 18 个引脚，BANK2 上有 8 个引脚，总共 54 个引脚。这些引脚可以用作真正的 GPIO 引脚：软件可以将它们设置为输入或输出，读取和/或设置状态，并将它们用作中断。它们还可以运行诸如 I²C、SPI、I²S、UART、SD 卡等其他功能。

所有计算模块上都可以使用 BANK0 和 BANK1。不要使用 BANK2：它控制 eMMC、HDMI 热插拔检测和 ACT LED/USB 引导控制。

使用 pinctrl 来检查 GPIO 引脚的电压和功能，以查看你的设备树是否按预期工作。

BCM283x 引导过程

BCM283x 设备搭载了 VideoCore GPU 和 Arm CPU 核心。GPU 包括 DSP 处理器和用于图像处理、视频编解码、3D 图形和图像合成的硬件加速器。

在 BCM283x 设备中，首先启动了 GPU 中的 DSP 核心。它在启动主 Arm 处理器之前处理设置。

树莓派 BCM283x 设备有三阶段引导过程：

GPU DSP 退出复位并从小型内部引导 ROM 执行代码。此代码通过外部接口加载第二阶段引导加载程序。此代码首先在称为 bootcode.bin 的引导分区上查找第二阶段引导加载程序。如果未找到引导设备或未找到 bootcode.bin，引导 ROM 将在 USB 引导模式下等待主机提供第二阶段引导加载程序（usbbootcode.bin）。
第二阶段引导加载程序负责设置 LPDDR2 SDRAM 接口和其他关键系统功能。设置完成后，第二阶段引导加载程序加载并执行主 GPU 固件（start.elf）。

设备树

树莓派的 Linux 设备树编码了连接到系统的硬件信息以及用于与该硬件通信的驱动程序。

引导分区包含几个二进制设备树（.dtb）文件。设备树编译器使用可读的设备树描述（.dts）创建这些二进制文件。

引导分区包含两种不同类型的设备树文件。一种仅供 GPU 使用；其余是针对每个基于 BCM283x 的树莓派产品的标准 Arm 设备树文件：

dt-blob.bin（供 GPU 使用）
bcm2708-rpi-b.dtb（用于树莓派 1B 和 B）
bcm2708-rpi-b-plus.dtb（用于树莓派 i 1B+ 和 A+）

在启动过程中，用户可以通过 device_tree 参数在 config.txt 中指定了要使用的特定 Arm 设备树。例如，config.txt 中的 device_tree=mydt.dtb 这行指定了一个名为 mydt.dtb 文件中的 Arm 设备树。

你可以为计算模块产品创建完整的设备树，但我们建议改用叠加层。叠加层向基本设备树添加非特定于板的硬件描述。这包括使用的 GPIO 引脚及其功能，以及连接的设备，以便正确加载驱动程序。引导加载程序在将设备树传递给 Linux 内核之前将叠加层与基本设备树合并。基本设备树偶尔会更改，通常不会破坏叠加层。

使用 dtoverlay 参数在 config.txt 中加载设备树叠加层。树莓派系统假定所有叠加层位于目录 /overlays 中，使用后缀 -overlay.dtb。例如，dtoverlay=myoverlay 这行加载了叠加层 /overlays/myoverlay-overlay.dtb。

要将外围设备连接到计算模块，请在叠加层中描述连接到 BANK0 和 BANK1 GPIO 的所有硬件。这样你就可以使用标准的树莓派系统镜像，因为叠加层已合并到标准基础设备树中。或者，你还可以为你的应用程序定义自定义设备树，但你将无法使用标准的树莓派系统镜像。因此，你必须创建一个包含你自定义设备树的修改后的树莓派系统镜像，以便分发你想分发的每个操作系统更新。如果基础叠加层发生更改，则可能需要更新你的定制设备树。

`dt-blob.bin`

当 start.elf 运行时，它首先读取 dt-blob.bin。这是一种特殊形式的设备树 blob，告诉 GPU 如何设置 GPIO 引脚状态。

dt-blob.bin 包含由 GPU 而不是 SoC 控制的 GPIO 和外围设备的信息。例如，GPU 管理摄像头模块。GPU 需要独占访问 I²C 接口和一些引脚，以便与摄像头模块通信。

在大多数树莓派型号上，I2C0 专为 GPU 独占使用。dt-blob.bin 定义了用于 I2C0 的 GPIO 引脚。

默认情况下，dt-blob.bin 不存在。作为替代，start.elf 是此文件的内置版本。许多计算模块项目提供了一个自定义 dt-blob.bin，该文件覆盖了默认的内置文件。

dt-blob.bin 指定了：

用于 HDMI 热插拔检测的引脚
用作 GPCLK 输出的 GPIO 引脚
GPU 在引导过程中可以使用的 ACT LED

minimal-cm-dt-blob.dts 是一个示例 .dts 设备树文件。它设置了 HDMI 热插拔检测，ACT LED，并将所有其他 GPIO 设置为带有默认拉电的输入。

要将 minimal-cm-dt-blob.dts 编译为 dt-blob.bin，请使用设备树编译器 dtc。要在树莓派上安装 dtc，请运行以下命令：

然后，运行以下命令将 minimal-cm-dt-blob.dts 编译为 dt-blob.bin ：

获取更多信息，请参阅我们的创建指南 dt-blob.bin。

Arm Linux 设备树

在 start.elf 读取 dt-blob.bin，设置初始引脚状态和时钟后，它就会读取 config.txt，其中包含许多其他系统设置选项。

在读取 config.txt 后，start.elf 会读取一个特定于模型的设备树文件。例如，计算模块 3 使用 bcm2710-rpi-cm.dtb。该文件是一个标准的 Arm Linux 设备树文件，详细说明连接到处理器的硬件。它枚举了：

外围设备的种类和位置
使用了哪些 GPIO
这些 GPIO 有什么功能
连接了哪些物理设备

如果与 dt-blob.bin 不同，此文件将通过覆盖引脚状态来设置 GPIO，并尝试为特定设备加载驱动程序。

特定型号的设备树文件包含了对外围设备的禁用条目。除了 eMMC/SD 卡外设备的 GPIO 引脚定义外，它不包含其他 GPIO 引脚定义，并且始终使用相同的引脚。

设备树源码和编译

树莓派系统镜像提供了预编译的 dtb 文件，但源 dts 文件位于树莓派 Linux 内核分支中。在文件名中查找 rpi。

默认叠加层 dts 文件位于 arch/arm/boot/dts/overlays。这些叠加层文件是创建自己的叠加层的好起点。要将这些 dts 文件编译为 dtb 文件，请使用设备树编译器 dtc。

在编译自己的内核时，构建主机需要 scripts/dtc 中的设备树编译器。要自动构建叠加层，请将它们添加到 dtbs 中的 make 目标中 arch/arm/boot/dts/overlays/Makefile。

设备树调试

当启动 Linux 内核时，GPU 使用基础 dts 和任意叠加层创建完整的设备树。这个完整的树可以通过 Linux proc 接口在 /proc/device-tree 中浏览。节点变成目录，属性变成文件。

你可以使用 dtc 将其写成可供人类阅读的 dts 文件以进行调试。要查看完整的组装设备树，请运行以下命令：

pinctrl 提供了 GPIO 引脚的状态。如果出现问题，请尝试转储 GPU 日志消息：

技巧
要在输出中包含更多诊断信息，请将 dtdebug=1 添加到 config.txt。

使用设备树树莓派论坛提出设备树相关问题或报告问题。

示例

以下示例使用带有通过跳线连接的外围设备的 IO 板。我们假设使用了旧版的精简版树莓派系统运行 CM1+CMIO 或 CM3+CMIO3。这里的示例需要互联网连接，因此我们建议将 USB 集线器、键盘和无线局域网或以太网转接器插入 IO 板的 USB 端口。

将 I²C RTC 连接到 BANK1 引脚

在这个示例中，我们将 NXP PCF8523 实时时钟（RTC）连接到 IO 板的 BANK1 GPIO 引脚：3V3、GND、GPIO44 上的 I2C1_SDA 和 GPIO45 上的 I2C1_SCL。

下载 minimal-cm-dt-blob.dts，将其复制到 /boot/firmware/ 的引导分区中。

编辑 minimal-cm-dt-blob.dts,将 GPIO44 和 45 的引脚状态更改为带上拉的 I2C1：

替换以下行：

使用以下上拉定义：

我们可以在不进行任何改动的情况下使用此 dt-blob.dts，因为 Linux 设备树在特定驱动程序加载时重新配置这些引脚。但是，如果配置了 dt-blob.dts，GPIO 在 GPU 引导阶段尽快达到最终状态。在某些情况下，必须在 GPU 引导时配置引脚，以便在加载 Linux 驱动程序时处于特定状态。例如，重置线可能需要保持在正确的方向上。

运行以下命令编译 dt-blob.bin ：

下载 example1-overlay.dts，将其复制到 /boot/firmware/ 中的引导分区，然后使用以下命令编译：

参数 -@ 编译具有外部引用的 dts 文件。一般是必要的。

将以下行添加到 /boot/firmware/config.txt 中：

最后，使用 sudo reboot 重启。

重启后，你将在 /dev 中看到一项 rtc0。运行以下命令查看硬件时钟时间：

在 BANK0 上连接一个 ENC28J60 SPI 以太网控制器

在这个示例中，我们使用已在 /boot/firmware/overlays 中定义的叠加层，将以太网控制器 ENC28J60 SPI 添加到 BANK0。以太网控制器使用 SPI 引脚 CE0、MISO、MOSI 和 SCLK（分别为 GPIO8-11），GPIO25 用于下降沿中断，另外还有 GND 和 3.3V。

在本示例中，我们不会更改 dt-blob.bin。而是将以下行添加到 /boot/firmware/config.txt 中：

使用 sudo reboot 重启。

你将在 /dev 中看到一项 rtc0。运行以下命令查看硬件时钟时间：

你还应该具有以太网连接性。运行以下命令测试你的连接性：

运行以下命令显示 GPIO 功能；GPIO8-11 现在应提供 ALT0（SPI）功能：

连接摄像头模块

计算模块具有两个 CSI-2 摄像头接口：CAM1 和 CAM0。本节将说明如何使用计算模块 I/O 板将一个或两个树莓派摄像头连接到计算模块的 CAM1 和 CAM0 接口。

更新你的系统

在配置摄像头之前，请确保你树莓派的固件是最新的。

连接一个摄像头

要将单个摄像头连接到计算模块，请完成以下步骤：

断开计算模块的电源。
使用 RPI-CAMERA 板/树莓派 Zero 摄像头电缆将摄像头模块连接到 CAM1 接口。

（仅限 CM1、CM3、CM3+ 和 CM4S）：使用跳线电缆连接以下 GPIO 引脚：
- 0 到 CD1_SDA
- 1 到 CD1_SCL

重新连接计算模块到电源。
在 /boot/firmware/config.txt 中删除（或使用前缀 # 注释掉）以下行，如果存在的话：
(仅适用于 CM1、CM3、CM3+ 和 CM4S)：向 /boot/firmware/config.txt 添加以下指令，以适应 I/O 板上 GPIO 引脚分配的交换：

相机型号

参数

使用 sudo reboot 重启你的计算模块。
运行以下命令以检查检测到的相机列表：
你应该能在上表中由驱动程序指令引用的摄像头型号中看到输出。

连接两台摄像头

要将两台摄像头连接到计算模块，请完成以下步骤：

按照上述单摄像头说明操作。
断开计算模块的电源。
使用 RPI-CAMERA 板/树莓派 Zero 摄像头电缆将摄像头模块连接到 CAM0 接口。

(仅适用于 CM1、CM3、CM3+ 和 CM4S)：使用跳线连接以下 GPIO 引脚：
- 28 到 CD0_SDA
- 29 到 CD0_SCL

(仅限 CM4)：使用两根垂直方向的跳线连接 J6 GPIO 引脚。

重新连接计算模块到电源。
（仅适用于 CM1、CM3、CM3+ 和 CM4S）：向 /boot/firmware/config.txt 添加以下指令，将 GPIO 31 分配为 CAM0 调节器：
向 /boot/firmware/config.txt 添加对应的参数，手动配置相机型号的驱动程序：

相机型号

参数

使用 sudo reboot 重启你的计算模块。
运行以下命令以检查检测到的相机列表：
你应该在上表中的驱动命令中看到两款摄像头型号的输出。

软件

树莓派系统内置了 libcamera 库，可帮助你使用树莓派拍摄图像。

拍照

使用以下命令即时拍照，并将其保存成 PNG 编码的文件，文件名使用日期格式为 MMDDhhmmss：

使用参数 -t 添加毫秒级延迟。使用参数 --width 和 --height 可指定图像的宽度和高度。

拍摄视频

使用以下命令立即开始录制十秒钟的视频，并将其保存到一个名为 video.h264，带有 h264 编解码器的文件中：

指定要使用的摄像头

默认情况下，libcamera 总是使用 --list-cameras 列表中编号为 0 的相机。要指定相机参数，请从以下命令获取每个相机的编号值：

在上述输出中：

imx477 指的是编号为 0 的 HQ 相机
imx708 指的是具有编号 1 的摄像头模块 3

要使用 HQ 摄像头，请将其编号(0) 传给参数 --camera libcamera：

要使用摄像头模块 3，请将其编号 (1) 传给参数 --camera libcamera：

GPIO 引脚的 I²C 映射

在默认情况下，提供的摄像头驱动程序假定 CAM1 使用 i2c-10，CAM0 使用 i2c-0。计算模块 I/O 板将以下 GPIO 引脚映射到 i2c-10 和 i2c-0 ：

I/O 板型号

i2c-10 引脚

i2c-0 引脚

要连接相机到计算模块 1、计算模块 3、计算模块 3+和计算模块 4S I/O 板，添加以下参数到 /boot/firmware/config.txt 可匹配交换的引脚分配:

替代板可能使用其他引脚分配。查阅你板子的文档，并根据你的布局使用以下替代叠加层：

交换

叠加层

用于关机的 GPIO 引脚

对于相机关机，设备树使用叠加层 cam1_reg 和 cam0_reg 分配的引脚。

CM4 IO 板为两个别名提供单个 GPIO 引脚，因此两个相机共享同一个调节器。

CM1、CM3、CM3+ 和 CM4S I/O 板未提供 cam1_reg 和 cam0_reg 的 GPIO 引脚，因此这些板上的稳压器已禁用。但是，你可以通过在 /boot/firmware/config.txt 中使用以下指令来启用它们：

dtparam=cam1_reg
dtparam=cam0_reg

要将 cam1_reg 和 cam0_reg 分配到自定义板上的特定引脚，请在 /boot/firmware/config.txt 中加入以下参数：

dtparam=cam1_reg_gpio=<pin 值>
dtparam=cam0_reg_gpio=<pin 值>

例如，要将引脚 42 用作 CAM1 的稳压器，请将指令 dtparam=cam1_reg_gpio=42 添加到 /boot/firmware/config.txt。

这些指令仅适用于直连 SoC 的 GPIO 引脚，而不适用于扩展的 GPIO 引脚。

连接官方 7 吋显示屏

在开始之前，请将系统软件和固件更新到最新版本。计算模块大多使用相同的流程，但有时物理差异会迫使针对特定型号进行更改。

连接显示器到 DISP1

注意
树莓派 Zero 相机线不能作为 RPI-DISPLAY 适配器的替代品。这两款线的布线不同。

要连接显示器到 DISP1：

断开计算模块的电源。
通过 22W 至 15W 显示适配器，将显示器连接到计算模块 IO 板上的 DISP1 接口。
（仅限 CM1、CM3、CM3+和 CM4S）：使用跳线电缆连接以下 GPIO 引脚：

将显示器连接到 DISP0

连接显示器到 DISP0：

通过 15w-22W 电源适配器将显示器连接到计算模块 IO 板上的 DISP0 接口。
（仅适用于 CM1、CM3、CM3+和 CM4S）：使用跳线电缆连接以下 GPIO 引脚：
- 28 到 CD0_SDA

禁用触摸屏

触摸屏不需要额外配置。将其连接到你的计算模块，如果成功检测到，触摸屏元素和显示器都应该正常工作。

要禁用触摸功能，但仍使用显示器，请在 /boot/firmware/config.txt 中添加以下行：

禁用显示器

在连接时完全忽略显示器，请将以下行添加到 /boot/firmware/config.txt：

规格

计算模块 4 数据表

了解有关计算模块 4（CM4）及其相应 IO 板的更多信息，请参阅以下文档：

配置计算模块 4

计算模块 4 有多种不同的硬件配置。一些用例禁用不需要的某些功能。

本文档描述了如何禁用各种硬件和软件接口。

计算模块 4 IO 板数据表

设计数据可以在计算模块 4 IO 板（CM4IO）的数据表中找到：

我们还为 CM4 IO 板提供 KiCad PCB 设计套件：

计算模块 4S 数据表

计算模块 4S（CM4S）在 CM1、CM3 和 CM3+的 DDR2-SODIMM 尺寸中提供了 CM4 的内部组件。要了解有关 CM4S 的更多信息，请参阅以下文档：

计算模块 3+ 数据表

计算模块 3+ (CM3+) 是一款受支持的产品，其终止生命周期（EOL）日期不早于 2028 年 1 月。要了解有关 CM3+及其对应 IO 板的更多信息，请参阅以下文档：

计算模块 1 和计算模块 3 数据表

树莓派计算模块 1 (CM1) 和计算模块 3 (CM3) 是支持的产品，其终止生命周期 (EOL) 日期不早于 2026 年 1 月。要了解有关 CM1 和 CM3 的更多信息，请参阅以下文档：

从计算模块 1 和计算模块 3 过渡到计算模块 4

这份白皮书帮助开发人员从计算模块 1 和计算模块 3 迁移到计算模块 4。

计算模块 IO 板原理图

计算模块 IO 板（CMIO）为 CM1、CM3、CM3L 和 CM3+提供各种接口。计算模块 IO 板有两个衍生版本：版本 1 和版本 3。版本 1 仅兼容 CM1。版本 3 兼容 CM1、CM3、CM3+和 CM4S。计算模块 IO 板版本 3 有时被简写为 CMIO3。要了解有关 CMIO1 和 CMIO3 的更多信息，请参阅以下文档：

计算模块摄像头/显示适配板原理图

计算模块摄像头/显示适配板（CMCDA）为计算模块提供摄像头和显示接口。要了解有关 CMCDA 的更多信息，请参阅以下文档：

欠压检测

以下原理图描述了用于旧款树莓派的欠压检测电路：

config.txt

`config.txt` 是什么？

树莓派设备采用了配置文件——config.txt，来代替普通 PC 上的 BIOS 。GPU 会先读取 config.txt，然后再初始化 Arm CPU 及 Linux。树莓派系统（Raspberry Pi OS）会把 config.txt 放在 boot 分区（/boot/firmware/）中。

注意
树莓派 Bookworm 之前的旧系统，会把 boot 分区放在 /boot/。

你可以直接在你当前的树莓派系统上编辑 config.txt。你也可弹出存储设备，在其他计算机上，编辑启动分区中的文件（含 config.txt）。

所有对 config.txt 的修改，均仅在重启后生效。你可使用以下命令，获取当下使用的设置：

vcgencmd get_config <参数>

　　打印指定参数的值，如 vcgencmd get_config arm_freq

vcgencmd get_config int

　　列出所有非零（0）的整数参数

vcgencmd get_config str

　　列出所有非空字符串参数

注意
vcgencmd 仅能获取到部分配置设置。

文件格式

config.txt 文件会由早期启动固件读取，因此所采取的文件格式非常简单：每行一条语句：属性=值，其中 值 可以是整数、字符串。 可以在行首添加字符 # 来插入注释，或注释掉现有配置值以禁用。

每行条目的最大长度为 98 个字符。树莓派系统会忽略掉所有溢出此限制的字符。

示例文件如下：

高级功能

`include`

在当前文件引用指定文件的内容。

比如：把 include extraconfig.txt 这行添加到 config.txt，就会在 config.txt 文件中引用 extraconfig.txt 文件的内容。

注意
bootcode.bin、EEPROM 引导加载程序均不支持 include 指令。
以下由引导加载程序控制的设置，仅在 config.txt（而非其他附带文件）中指定时才能生效：
bootcode_delay、

条件筛选器

条件筛选器位于。

`autoboot.txt`

autoboot.txt 是可选配置文件，用于指定 boot_partition 的编号。

亦可与 tryboot 功能一同使用，实现系统更新的 A/B 启动。

autoboot.txt 被限制为 512 字节，支持筛选器 [all]、[none] 和 [tryboot] 。

另见启动流程。

`boot_partition`

指定启动的分区号。也可以直接把分区号作为参数传给 reboot（如 sudo reboot 2）命令来实现。

分区号从 1 开始，MBR 分区号为 1 到 4。指定分区 0 意味着从默认分区启动，默认分区是首个可引导的 FAT 分区。

作为启动分区，其文件系统仅支持 FAT12、FAT16 和 FAT32，并包含了 start.elf 文件（若为树莓派 5，则改为文件 config.txt），以便引导程序将其视为可引导。

筛选器 `[tryboot]`

如果在启动时系统已设置标志位 tryboot，则将激活此筛选器。

`tryboot_a_b`

当标志位 tryboot 被激活后，若将属性 tryboot_a_b 置为 1，会加载通常的文件 config.txt、boot.img，而不会加载文件 tryboot.txt、tryboot.img。

这样就可以在分区级（而非在文件级）上控制 tryboot 的开关，且无需修改 A/B 分区中的配置文件。

A/B 启动更新流程示例

以下伪代码：假设了操作系统更新服务在 autoboot.txt 中使用 tryboot 执行安全的操作系统更新。

简单的 autoboot.txt :

安装更新

设备上电，然后从默认分区 2 启动
Update service（更新服务）下载新版操作系统到分区 3
重启到 tryboot 模式：用 reboot "0 tryboot" 来测试更新，其中 0

进行、取消更新

系统将从分区 3 启动，因为在 tryboot mode 中，筛选器 [tryboot] 的结果为真（true）
如果 tryboot 处于激活状态 ( /proc/device-tree/chosen/bootloader/tryboot == 1 )

更新 autoboot.txt：

注意
autoboot.txt 修改后并不必须重启。然而，必须小心不要让 Update service（更新服务） 覆盖当前分区：因为已经修改了 autoboot.txt，执行了最后的更新。有关更多信息，请参阅。

常见参数

常见显示参数

`hdmi_enable_4kp60`（仅适用于树莓派 4）

在默认情况下，当接入 4K 显示器时，树莓派 4B、400 和 CM4 将输出 30Hz 的刷新率。使用此参数可输出 60Hz 的刷新率。树莓派 4 无法在两个 micro HDMI 接口上同时输出 4Kp60。设置 hdmi_enable_4kp60 将增加功耗和温度。

常见硬件配置参数

`camera_auto_detect`

启用此设置（树莓派系统默认已启用），固件将自动加载所识别的 CSI 摄像头叠加层。如 camera_auto_detect=0 则意味着禁用该设置。

`display_auto_detect`

启用此设置（树莓派系统默认已启用），固件将自动加载所识别的 DSI 显示屏的叠加层。设置 display_auto_detect=0 可禁用。

`dtoverlay`

dtoverlay 参数将要求固件加载指定的设备树覆盖层——这是个配置文件，可启用内、外围硬件的内核支持。例如，dtoverlay=vc4-kms-v3d 会加载叠加层，启用内核图形驱动程序。

作为例外，如果在调用时未赋值（即 dtoverlay=），则表示直接覆盖至参数列表的末尾。如果定义在一切 dtoverlay、dtparam 参数之前，那么所有的扩展板叠加层均不会加载。

更多有关信息，请参阅。

`dtparam`

树莓派的设备树配置文件支持多种参数，如启用 I²C、SPI 接口。大部分 DT 叠加层也都能用参数进行配置。这两类的参数都可以用 dtparam 进行配置。此外，还可以把叠加层参数添加到参数 dtoverlay 里：以逗号分隔，但请注意，字符长度限制为 98 个字符。

欲了解更多详情，请查阅 DTB、叠加层和 config.txt。

`arm_boost`（仅适用于树莓派 4）

所有树莓派 400 系列和修订版树莓派 4B 均搭载了额外的开关电源（SMPS）（用于 SoC 电压轨），这使默认超频状态下的主频，从 1.5GHz 提升到 1.8GHz。此更改在树莓派系统下默认已生效。设置 arm_boost=0 可禁用。

`power_force_3v3_pwm`（仅适用于树莓派 5）

使用 3.3V 电源时强制 PWM。设置 power_force_3v3_pwm=0 可禁用。

板载模拟音频（3.5 mm 插孔）

使用配置参数可以修改板载音频输出的模拟音频驱动方式，以及是否启用某些固件功能。

`audio_pwm_mode`

audio_pwm_mode=1 选择传统低质量模拟音频，基于 3.5 mm AV 端子。

audio_pwm_mode=2 选择使用高级调制方案的高质量模拟音频。（默认）

注意
此参数将占用更多的 GPU 计算资源，可能会对某些型号的特定用例造成影响。

`disable_audio_dither`

在默认情况下，如果音频流路由输出到了模拟音频，则会应用 1.0LSB 抖动。在某些情况下（如 ALSA 音量处于较低水平），就有可能产生可感的背景噪音。将 disable_audio_dither 置为 1 可禁用抖动功能。

`enable_audio_dither`

当音频样本大于 16 位时，通常就会禁用音频抖动（请参阅上述 disable_audio_dither）。将此参数置为 1 可强制对所有位深度都应用抖动。

`pwm_sample_bits`

命令 pwm_sample_bits 能调整模拟音频输出的位深度。默认位深度为 11。如果位深度设置低于 8，音频将无法正常工作。因为低于 8 的值会导致 PLL 频率过低：对于设备来说，是不可能的。该参数通常仅用于演示位深度对量化噪声的影响。

HDMI 音频

在默认情况下，所有搭载了 HDMI 输出接口的树莓派型号，均启用了 HDMI 音频输出。

要禁用 HDMI 音频输出，请在 /boot/firmware/config.txt 中的 dtoverlay=vc4-kms-v3d 这行末尾添加 ,noaudio ：

启动参数

`start_file`、`fixup_file`

这些参数指可指定：在启动前传给 VideoCore GPU 的固件文件。

start_file 指定要使用的 VideoCore 固件文件。fixup_file 用于修正 start_file 所使用的内存位置，以匹配 GPU 内存分配。

start_file 和 fixup_file 是一对关联文件：错误搭配将导致开发板无法启动。这是个专业参数，因此我们不建议你使用，你应该用 start_x 和 start_debug。

注意
使用配置参数 start*cd.elf、fixup*cd.dat 无法调用精简固件，只会导致系统无法启动。唯一能启用精简固件的方法是指定 gpu_mem=16。精简固件删除了对编解码器、3D 和调试日志的支持，以及把初始早期引导帧缓冲区限制成 1080p @16bpp——正如同其他固件，KMS 在后续阶段可使用高达 32bpp 4K 帧缓冲区代替之。

注意
树莓派 5 的固件内置在 EEPROM 引导加载程序中。

`cmdline`

cmdline 是启动分区中的一个可选文件名（默认值为 cmdline.txt），用于读取内核命令行字符串。

`kernel`

kernel 是用于加载内核的启动分区上的一个可选文件名。树莓派 1，树莓派 Zero、Zero W 和计算模块 1 的默认值为 kernel.img。树莓派 2、3、3+，树莓派 Zero 2 W，计算模块 3、3+ 的默认值为 kernel7.img。树莓派 4、400 和计算模块 4 的默认值为 kernel8.img；如将 arm_64bit 设置为 0，则默认值为 kernel7l.img。

树莓派 5 固件默认加载 kernel_2712.img，因为此镜像为树莓派 5 进行了优化（例如 16K 页面大小）。如果此文件不存在，则会加载 64 位通用内核（ kernel8.img）。

`arm_64bit`

如果置为 1，则内核将以 64 位模式启动。设置为 0 会选择 32 位模式。

在 64 位模式下，固件将选择合适的内核（例如 kernel8.img）。如未显式设置参数 kernel，则将使用该参数。

在树莓派 4 系列（4B、400、CM4 和 CM4S）上默认值为 1，在其他所有平台上默认值为 0。但是，如果显式设置的参数 kernel 中给定的名称与已知的任一内核匹配，则 arm_64bit 将应用相应设置。

注意
64 位内核可以是未压缩的镜像文件，也可以是 gzip 压缩的镜像文件（仍可称为作 kernel8.img。引导加载程序能从开头的签名字节识别压缩文件）。64 位内核仅适用于树莓派 3、3+、4、400，树莓派 Zero 2 W，树莓派 2B 修订版 1.2，树莓派计算模块 3、3+、4。树莓派 5 仅支持 64 位内核，因此对树莓派 5 来说，该参数无效。

`ramfsfile`

ramfsfile 是引导分区上的 ramfs 的一个可选文件名。

注意
新版固件可加载多个 ramfs 文件。请注意：多个文件名需以逗号分隔，不要超过 80 个字符的行长限制。所有已加载的文件在内存中拼接在一起，被视为单个 ramfs 二进制块。有关更多信息，请参阅。

`ramfsaddr`

ramfsaddr 指定 ramfsfile 将加载的内存地址。

`initramfs`

命令 initramfs 同时指定了 ramfs 的文件名和 ramfs 将加载的内存地址。它在一个参数中同时执行了操作 ramfsfile 和 ramfsaddr。地址也可以是 followkernel （或 0），将其放在内核镜像之后的内存中。示例值为：initramfs initramf.gz 0x00800000、initramfs init.gz followkernel。同 ramfsfile 一样，新版固件可加载多个文件，多个文件名以逗号分隔。

注意
参数 initramfs 使用的语法与其他参数有所不同，你不能在此处使用字符 =。

`auto_initramfs`

如果把 auto_initramfs 置为 1，将按照所选内核的匹配规则查找文件 initramfs。

`disable_poe_fan`

在默认情况下，启动时，会在 I²C 总线上进行探测（哪怕并未接入 PoE 扩展板）。将此参数置为 1，可禁用在 I²C（在 ID_SD＆ID_SC 引脚）上对 PoE 扩展板风扇的检测行为。如果你不打算使用 PoE 扩展板，那么这是最大程度上缩短启动时间的有效方式。

`disable_splash`

如果将 disable_splash 置为 1，启动时将不会出现彩虹屏。默认值为 0。

`enable_uart`

enable_uart=1 （与 console=serial0 在 cmdline.txt 中联合使用）能让内核创建串口控制台——可使用 GPIO 14 和 15（40 脚排针上的引脚 8 和引脚 10）访问。编辑 cmdline.txt，删除 quiet 字段，就能把内核的启动消息也输出到这个串口上。另请参阅 uart_2ndstage。

`force_eeprom_read`

将此参数置为 0 可禁止：固件在上电时读取 I²C 扩展板的 EEPROM（连接至 ID_SD 和 ID_SC 引脚）。另请参阅。

`os_prefix`

os_prefix 是可选配置，能让你在同一张卡上，安装多个版本的内核和设备树文件，并进行切换。os_prefix 中的一切值都会被前置到固件加载的所有操作系统文件的名称之前，其中“操作系统文件”的定义是指内核、initramfs、cmdline.txt、.dtbs 和叠加层。该前缀通常是目录名称，但也可以是文件名的一部分，比如“test-”。因此，目录前缀必须以字符 / 结尾。

为了提高系统启动的几率，固件首先会测试所提供的前缀值是否可行——除非在新位置/新名称下能够找到对应的内核和文件 .dtb，否则将忽略前缀（置为“”）。对叠加层可行性测试的特例是：如果存在 ${os_prefix}${overlay_prefix}README，将仅从 ${os_prefix}${overlay_prefix} （其中的默认值为 "overlays/"）加载覆盖层；否则，它将忽略 os_prefix，并将叠加层视为共享。

（固件在检查前缀时，是判断关键文件（而非目录）的存在与否。原因有二：前缀可能不是目录，并非所有启动方法都支持使用测试目录。）

注意
所有操作系统文件都可以通过用户指定使用的绝对路径（相对于启动分区）来修改前缀——只需以 / 开头：如 kernel=/my_common_kernel.img。

另请参阅和。

`otg_mode`（仅适用于树莓派 4）。

USB On-The-Go（通常缩写为 OTG）是一项功能，它能让受支持的 USB 设备通过相应的 OTG 线把自己配置成 USB 主机。在旧款树莓派系列上，单个 USB2 控制器可同时作为 USB 主机模式和 USB 设备模式。

树莓派 4B 和 400（不含 CM4、CM4IO）添加了一个连接至 PCIe 的高性能 USB 3 控制器，用于驱动主要的 USB 端口。传统的 USB 2 控制器仍然可用：它通过 Type-C 电源接口，以设备模式进行连接。（otg_mode=0 为默认）。

otg_mode=1 可将 Type-C 接口的主控制器切换成更为强大的 XHCI USB 2 控制器。

注意
由于 CM4 和 CM4IO 未搭载单独的 USB 3 控制器，在树莓派操作系统镜像上，为 CM4 上设置了 otg_mode=1，以实现最佳性能。

`overlay_prefix`

指定从哪个子目录/前缀加载叠加层，默认为 overlays/ （注意末尾的 /）。如果同时使用了，则 os_prefix 将位于 overlay_prefix 之前。即 dtoverlay=disable-bt 将会加载 ${os_prefix}${overlay_prefix}disable-bt.dtbo。

注意
除非存在 ${os_prefix}${overlay_prefix}README，否则叠加层将与主操作系统复用（即无视 os_prefix）。

配置属性

树莓派 5 需要一个文件 config.txt 来标识分区可启动。

`boot_ramdisk`

如果此属性置为 1，则引导程序将尝试加载名为 boot.img 的 ramdisk 文件（其中包含）。随后的文件（例如 start4.elf ）将从 ramdisk 中读取，而非原始引导文件系统。

boot_ramdisk 的主要目的是支持安全启动（secure-boot），但未签名的 boot.img 文件也可用于网络引导或配置 RPIBOOT。

RAM 磁盘文件的最大值为 96MB。
boot.img 文件是裸磁盘的 .img 文件。推荐格式是不带 MBR 的普通 FAT32 分区。
在操作系统启动之前从内存中释放 RAM 磁盘文件系统。

更多有关安全启动（secure-boot）和创建 boot.img 文件的信息，请参阅。

默认值： 0

`boot_load_flags`

定制固件（裸金属）的实验性属性。

位 0 (0x1) 表示 .elf 文件为定制固件。这将禁用一切兼容性检查（如是否支持 USB MSD 启动），并在加载可执行文件之前重置 PCIe。

对于树莓派 5 无关紧要，因为它就没有 start.elf 这个文件。

默认值： 0x0

`pciex4_reset`

仅适用于树莓派 5。

默认情况下，在启动操作系统之前，会对 RP1 使用的 PCIe x4 控制器进行复位。如果此参数置为 0，则将禁用复位，以实现操作系统或裸金属代码继承来自引导加载程序的 PCIe 配置设置。

默认值： 1

`uart_2ndstage`

如果 uart_2ndstage 为 1，则将启用串口调试日志记录。此参数还会自动启用 start.elf 中的串口日志记录。这也在页上有描述。

属性 BOOT_UART 也会启用引导加载程序的串口日志记录，但不会启用 start.elf 的串口日志记录——除非同时设置了 uart_2ndstage=1。

默认值： 0

`erase_eeprom`

如果 erase_eeprom 置为 1，那么 recovery.bin 将擦除整个 SPI EEPROM，而非刷新引导加载程序镜像。此属性在正常启动期间无效。

默认值：0

`eeprom_write_protect`

配置 EEPROM 写状态寄存器（write status register）。可将整个 EEPROM 标记为写保护，或清除写保护。

该参数必须与控制 EEPROM 写入状态寄存器更新的 EEPROM /WP 引脚一同使用。将 /WP 的引脚拉低（CM4 为 EEPROM_nWP、树莓派 4 为 TP5）——但若仅如此，并不会对 EEPROM 写保护，除非同时对写入状态寄存器进行了配置。

可查看、的数据手册以获取更多详细信息。

config.txt 中的 eeprom_write_protect 设置用于 recovery.bin。

值

说明

注意
flashrom 不能清除写保护区域，如果定义了写保护区域，将无法更新 EEPROM。

对于树莓派 5，在默认情况下，/WP 已拉低，因此只要配置了写状态寄存器，就会启用写保护。要清除写保护，请将 /WP 引脚拉高，方法是连接 TP14 和 TP1。

默认值: -1

`os_check`

对于树莓派 5，在从当前分区引导之前，固件默认会自动检查适配的设备树文件。如果没有找到，将加载旧的不兼容的内核，然后可能会卡住。要禁用此检查（如用于裸机开发），请在 config.txt 中设置 os_check=0。

默认值： 1

`bootloader_update`

可将此参数置为 0 以关闭自动更新（无需刷新 EEPROM 配置）。在通过网络引导更新多个树莓派时，有时会很有用，因为可以针对不同的树莓派控制此参数（例如，通过 config.txt 中的串号筛选器）。

默认值： 1

安全启动的配置属性

白皮书

本白皮书介了如何在基于树莓派 4 的设备上实现安全启动。有关我们实施安全启动方法的概述，请参阅白皮书。安全启动系统被设计成与基于 buildroot 的操作系统镜像搭配使用；不建议、或者说不支持将其与树莓派系统（Raspberry Pi O）一同使用。

以下 config.txt 属性用于编程安全启动的 OTP 设置。这些更改是不可逆的，只能在刷写引导加载程序 EEPROM 镜像时通过 RPIBOOT 进行编程。这阻止了使用远程设置或通过意外插入陈旧的存储卡镜像进行安全启动。

更多有关启用安全启动的信息，请参阅和存储库中的。

`program_pubkey`

如果将此属性置为 1，则 recovery.bin 将把 EEPROM 镜像中的公钥哈希值写入 OTP。一旦设置，启动加载程序将拒绝使用其他 RSA 密钥签名的 EEPROM 镜像及未签名的镜像。

默认值： 0

`revoke_devkey`

如果将此属性置为 1，则 recovery.bin 将向 OTP 写入一个值，以阻止 ROM 加载不支持安全启动的旧版第二阶段的启动加载程序。这可以阻止通过回滚到旧版启动加载程序以绕过安全启动的行为。

默认值： 0

`program_rpiboot_gpio`

由于树莓派 4B 和树莓派 400 上没有专用的 nRPIBOOT 跳线，因此必须使用别的 GPIO 配置 RPIBOOT 模式，可通过拉低 GPIO 来实现。请从以下参数中选择这个 GPIO：

此属性不要求安全启动，但要确认该 GPIO 配置不会与其他扩展板冲突，因为扩展板可能会在启动期间将 GPIO 拉低。

出于安全考量，此属性仅可通过 RPIBOOT 进行编程，因此必须首先用 erase_eeprom 擦除 EEPROM 引导加载程序。这将触发 BCM2711 ROM 故障转移到 RPIBOOT 模式，然后才能设置此参数。

默认值：

`program_jtag_lock`

如果将此属性置为 1，则 recovery.bin 将编程一个 OTP 值，来禁用 VideoCore JTAG（调试接口）。此参数必须与 program_pubkey 和 revoke_devkey 同时使用。启用此参数可禁用故障诊断，应仅在设备经过全面测试后设置此参数。

默认值： 0

GPIO 控制

`gpio`

gpio 指令能在启动时把 GPIO 引脚设置为特定模式、特定值，这种方式在以前需要一个自定义文件 dt-blob.bin。每一行都将相同的设置（或至少相同的更改）应用到一组引脚，可处理单个引脚（3）、某区间内的引脚（3-4）或以逗号分隔的列表（3-4,6,8）。

引脚设置后跟一个 = 和此列表中的一个或多个逗号分隔属性：

ip——输入
op——输出
a0-a5——Alt0-Alt5

gpio 设置将按顺序应用，因此后面出现的设置会覆盖先前出现的设置。

示例：

config.txt 中的条件筛选器“[...]” 兼容该 gpio 指令，因此可以根据型号、序列号和 EDID 使用不同的设置。

通过该机制进行的 GPIO 修改不会直接干预内核。它们不会把 GPIO 引脚暴露到 sysfs 接口，并且可被设备树中的 pinctrl 条目以及像 pinctrl 这样的工具所覆盖。

还请注意，从上电到修改生效会有几秒钟的延迟——如果通过网络启动或从 USB 大容量存储设备启动，那么延迟会更大。

超频参数

内核会默认启用驱动程序：安装后，在启动时会把调度程序从 powersave 切换到 ondemand。通过调度程序 ondemand，CPU 频率将随处理器负载而变化。如果你把配置参数 *_min 调整为最小值、使用了静态缩放调度程序（powersave、performance），亦或使用 force_turbo=1——他们都会禁用动态频率调整。

当 SoC 在运行时达到 temp_limit（见下文，默认为 85°C）时，就会禁用超频和过压功能，以降低 SoC 温度。你不大可能在树莓派 1、2 上受到此限制。在树莓派 3 及更新款上才有可能。当检测到欠电压时，也会禁用超频和过压功能。

注意
更多信息请参阅。

警告
将任意超频参数设置为非 raspi-config 使用的值可能会导致在 SoC 内部置一个永久位。这将使你的树莓派以往的超频情况变得可检测。当将 force_turbo 置为 1 且任一 over_voltage_* 参数置为大于 0 的值时，就会应用超频位设置。详细信息请查看有关。

超频

参数

说明

下表提供了各种树莓派型号参数的默认值，所有频率均以 MHz 表示。

参数

树莓派 Zero、Zero W

树莓派 1

树莓派 2

树莓派 3

树莓派 3A+、3B+

CM4 和树莓派 4B ⇐ R1.3

树莓派 4B R1.4

树莓派 400

树莓派 Zero 2 W

树莓派 5

下表提供了所有通用参数默认值。

参数

默认值

固件使用自适应电压调节（AVS）来确定最佳的 CPU/GPU 核心电压（由 over_voltage 和 over_voltage_min 定义的区间内）。

适用于树莓派 4、400 和 CM4

当系统处于空闲状态时，最低主频必须保持在一定的速度，以支持显示器的最高像素时钟（忽略 blanking）。因此，如果信号格式为 4Kp60，则将把 core_freq 提升到 500 MHz 以上。

注意
无需使用 hdmi_enable_4kp60，树莓派 5 默认即支持双 4Kp60 显示屏。

超频需要最新版本的固件。
最新的固件在系统超频时会自动提高电压。手动设定 over_voltage 会禁用超频时的自动电压调节。
建议在超频时对单个参数（isp_freq、v3d_freq 等）的频率进行设定。不建议设定 gpu_freq

`force_turbo`

在默认情况下（force_turbo=0），按需的 CPU 频率驱动程序会在 ARM 核心繁忙时把时钟提升到最大频率，并在 ARM 核心空闲时将其降至最低频率。

force_turbo=1 可覆盖上述行为，即使 ARM 核心负载并不大，也会强制使用最大频率。

时钟关系

树莓派 4

GPU 核心、CPU、内存（SDRAM）和 GPU 各自拥有自己的锁相环（PLL），且频率可互相独立。h264、v3d 和 ISP 模块则使用相同的锁相环（PLL）。

要查看树莓派当前的频率（KHz），请输入： cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq。将结果除以 1000 可获得以 MHz 为单位的值。请注意，此频率是内核请求的频率，若在有限制的情况下（如高温）CPU 的实际运行速度可能比报告的要慢。使用 vcgencmd——vcgencmd measure_clock arm 可获取 ARM CPU 实际频率的瞬时测量值。该频率以赫兹为单位显示。

监控核心温度

白皮书

本白皮书详细介绍了你的树莓派会发热的可能性原因，以及为何你可能想要对其进行降温，并提供了有关冷却过程的参数。

要查看树莓派的温度，请运行以下命令：

通过将结果除以 1000 可获得摄氏度的值。或者，你可以使用 vcgencmd measure_temp 报告的 GPU 温度。

达到温度极限不会对 SoC 造成伤害，只会导致 CPU 降频。散热器可以帮助控制核心温度，从而提高性能。如果给树莓派安装了外壳，则极为有用。散热器上的空气流动会使冷却效果更好。

当核心温度位于 80°C 和 85°C 之间时 ARM 核心将被限速。若温度超过 85°C，ARM 核心、GPU 均将被限速。

对于树莓派 3B+ 来说，其印刷电路板（PCB）技术有所改良，提供了更佳的散热性能，及更高的热质量。此外，还引入了软温度限制，旨在在设备达到 85°C 的硬限制之前，尽可能延长其“高性能”运行时间。当达到软限制时，时钟速度会从 1.4GHz 降至 1.2GHz，并略微降低工作电压。这减少了温度的上升速率：我们用更长时间的 1.2GHz，替代了短时间的 1.4GHz。在默认情况下，软限制为 60°C。可用 config.txt 设置中的 temp_soft_limit 更改此设置。

监控电压

维持供电电压大于 4.8V 才能确保可靠性能。请注意，某些 USB 充电器（电源）电压可能会降至 4.2V。这是因为它们通常设计用于为 3.7V 的锂聚合物电池充电，而非为计算机提供 5V 电源供应。

要监测树莓派的电源供电电压，你需要用万用表测量 GPIO 排针的 VCC 引脚和 GND 引脚。有关更多信息，请查看文档的部分。

如电压降至 4.63V（±5％）以下，ARM 核心、GPU 将降频，并将在内核日志中打印标识低电压状态的信息。

树莓派 5 的电源管理芯片（PMIC）内置了模数转换器（ADC），可测量供电电压。要查看当前供电电压，请运行以下命令：

超频问题

大多数超频问题会实时反应为启动失败。如果发生了这种情况，请在下次启动时按住 shift 键。将临时禁用所有超频，你即可成功启动，然后再修改你的设置。

条件筛选器

当单张存储卡（SD 卡镜像）与一块树莓派和一台显示器搭配使用时，很轻松地，就能根据所需的特定组合设置 config.txt。可维持这种方式，仅在发生变化时才进行修改。

但是，如果一块树莓派在不同显示器之间交换使用，或一张存储卡（SD 卡镜像）在多块开发板间交换使用，那么单套设置可能就不大够用了。条件筛选器能让你定义配置文件的某些部分仅适用于特定情况，从而让不同硬件在读取相同的 config.txt 时能创建不同的配置。

筛选器 `[all]`

筛选器 [all] 是最基本的筛选器。它会重置所有先前设置的筛选器，并能将任意下表列出设置应用于所有硬件。通常，最好在筛选设置组的末尾添加筛选器[all] ，以避免意外组合筛选器（另见下文）。

型号筛选器

型号条件筛选器的适用的型号如下表所示。

筛选器

适用型号

对于设置不同的 kernel、initramfs 和 cmdline 设置极为有用，因为树莓派 1、2 所需内核不同。它们还有助于定义不同的超频设置，因为树莓派 1、2 默认的主频各异。比如，为每块树莓派设置不同的 initramfs 映像：

记得在最后使用筛选器 [all] ，这样后续设置就不会仅限于树莓派 2 硬件。

注意
某些型号的树莓派（Zero W、Zero 2 W，树莓派 3B+、400，计算模块 4、4S）会引用多个筛选器的设置（如上表所述）。这意味着如果你想让某个设置仅用于（例如）4B，且不把该设置应用于树莓派 400，那么 [pi4] 部分中的设置需要在随后的 [pi400] 部分中通过替代设置来还原——此部分的顺序很重要。或者，你可以使用筛选器 [board-type=0x11]，这个筛选器与不同的硬件产品之间有一对一的映射关系。

筛选器 `[none]`

该 [none] 筛选器会阻止一切随后的设置应用于所有的硬件。尽管没有什么是你不能没有 [none] 做的，但它可以是一个有用的方法，可以在不必注释掉每一行的情况下，在 config.txt 中保留未使用设置的组。

筛选器 `[tryboot]`

如果为 reboot 设置了参数 tryboot，则此筛选器为真。

筛选器 [tryboot] 的用于 autoboot.txt，以便在 tryboot 模式下选择不同的引导分区，进行操作系统的安全失败（fail-safe）式更新。

筛选器 `[EDID=*]`

在树莓派上使用单张存储卡切换多台显示器时，并且空白配置不足以自动选择每台显示器所需的分辨率时，可根据显示器的 EDID 名称选择特定设置。

要查看已连接显示器的 EDID 名称，你需按照以下步骤操作。运行以下命令，查看你的树莓派上有哪些输出设备：

在树莓派 4 上，打印类似如下输出：

然后，你需要以每个这些文件名运行 edid-decode，比如：

如果没有显示器连接为输出设备，它将告诉你 EDID 为空；若已连接显示器，将为你提供有关显示器功能的丰富信息。你需查找Manufacturer、Display Product Name 所在行。然后，“EDID 名称”为 <Manufacturer>-<Display Product Name>，并将字符串中的所有空格都将换成下划线。比如，如果你的 edid-decode 输出为：

此显示器的 EDID 名称将是 DEL-DELL_U2422H。

然后，你可以将其用作条件筛选器，指定仅在连接此特定显示器时才适用的设置：

这些设置仅适用于启动时。必须在启动前接入显示器，=且树莓派必须能够读取其 EDID 信息以找到正确的名称。在启动后，若热插拔不同的显示器，在树莓派上也不会选择其他设定。

在树莓派 4 上，如果同时使用了两个 HDMI 端口，则 EDID 筛选器将与两者进行匹配，并将应用所有匹配条件筛选器的配置。

注意
在树莓派 5 上未提供此设置。

串号筛选器

有时候需将设置设定为仅适用于单块特定的树莓派——即使你将存储卡更换为另一张也如此。下面的示例涉及了许可证密钥和超频设置（虽然许可证密钥可以其他方式支持不同的存储卡交换）。你还可以使用此功能来设定不同的显示设置（即使无法识别上述 EDID），只要你不在树莓派之间切换显示器就行。例如，如果你的显示器没有提供能用的 EDID 名称（或你正在使用复合输出（亦无法读取 EDID））。

要查看你树莓派的串号，请运行以下命令：

尾部输出将打印一个 16 位十六进制值。你树莓派的串号是最后八位数字（十六进制）。比如，若你看到：

则串号为 12345678。

注意
在某些树莓派型号上，前 8 位数字（十六进制）会包含 0 以外的数值。即使在这种情况下，也只使用最后八位数字（十六进制）作为串号。

你可以定义仅用于特定树莓派的设置：

GPIO 筛选器

你还可以根据 GPIO 的状态进行筛选。例如：

组合条件筛选器

相同类型的筛选器会互相取代，因此 [pi2] 会覆盖 [pi1]，因为两者不可能同时为真。

不同类型的筛选器可通过逐个列出筛选器来进行组合，例如:

使用筛选器 [all] 可重置先前所有筛选器，避免意外地组合不同类型的筛选器。

内存参数

`total_mem`

此参数可用于强制限制树莓派的内存容量：指定你想要让树莓派使用的总内存量（MB）。如，要让 4GB 的树莓派 4B 表现为 1GB 款，请使用以下内容：

此值最小值为 128MB，最大值为板载的总内存量。

许可证密钥和编解码器参数

可通过购买许可证来激活硬件编解码器解码：树莓派 3 及其早期型号上的附带了编解码器。许可证绑定了你树莓派的 CPU 序列号。

树莓派 4 已永久禁用了 MPEG2、VC1 硬件解码器。无法启用这些编解码器，故无需硬件编解码器许可证密钥。对于典型用例，MPEG2、VC1 文件的软解性能已足矣。

树莓派 5 搭载了 H.265（HEVC）硬件解码器。该解码器默认已启用，因此亦无需硬件解码许可密钥。

`decode_MPG2`

decode_MPG2 是用于激活 MPEG-2 硬件解码器的许可密钥，类似 decode_MPG2=0x12345678。

`decode_WVC1`

decode_WVC1 是用于激活 VC-1 硬件解码器的许可密钥，类似 decode_WVC1=0x12345678。

如果你有多块树莓派，并为每块树莓派都购买了编解码器许可证，你可以在一个 config.txt 中写入多达八个许可证密钥——如 decode_MPG2=0x12345678,0xabcdabcd,0x87654321。这让你可以在不必每次都编辑 config.txt，就能在不同的树莓派间交换同张存储卡。

视频参数

HDMI 信号格式

要控制 HDMI 设置，请使用cmdline.txt 中的、。

用于树莓派 4 的 HDMI 管道

为了支持双显示器和最高 4Kp60 的分辨率，树莓派 4 每个时钟周期会产生 2 个输出像素。

每种 HDMI 信号格式都有一个时序列表，用于控制同步脉冲持续时间周围的所有参数。这些时序通常通过像素时钟、活动像素数量、上沿、同步脉冲以及水平和垂直方向的下沿来定义。

树莓派 4 以每时钟 2 像素的速度运行一切，意味着树莓派 4 不能支持无法被 2 整除的水平时序。

在 CEA 和 DMT 标准中的信号格式，仅有一种无法兼容：DMT mode 81, 1366x768 @ 60Hz。该信号格式的水平同步和下沿时序值为奇数，宽度无法被 8 整除。

如果你的显示器是这种信号格式，树莓派 4 会自动降到下个显示器标称的信号格式，通常为 1280x720。

树莓派 5 的 HDMI 管道

虽然树莓派 5 亦可在每个时钟周期输出 2 个像素，但它对奇异时序有特殊处理，可以直接处理这些分辨率。

复合视频信号格式

每款树莓派计算机上都能找到复合视频输出。

型号

复合输出

注意
树莓派 400 未提供复合视频输出。

`enable_tvout`

置为 1 将启用复合视频输出，置为 0 将禁用复合视频输出。在树莓派 4、5 上，仅当你将其置为 1 时，才可使用复合输出（同时亦会禁用 HDMI 输出）。树莓派 400 不支持复合输出。

型号

默认值

除了树莓派 4、5 以外，均须禁用 HDMI 输出才能启用复合输出。当未连接（或未检测到）HDMI 显示器时，将禁用 HDMI 输出。设置 enable_tvout=0 可阻止在 HDMI 禁用时启用复合输出。

要启用复合输出，请在 /boot/firmware/config.txt 的 dtoverlay=vc4-kms-v3d 这行末尾添加 ,composite ：

在默认情况下，会输出复合视频（NTSC）。要选择其他信号格式，请将以下内容添加到 /boot/firmware/cmdline.txt 中这一行：

请用以下值替换占位符 <视频信号格式>：

NTSC
NTSC-J
NTSC-443

LCD 显示器和触摸屏

`ignore_lcd`

在默认情况下，会在 I²C 总线上检测树莓派触摸显示屏。ignore_lcd=1 可跳过这个检测阶段，以禁用 LCD 显示屏。

`disable_touchscreen`

启用和禁用触摸屏。

disable_touchscreen=1 可禁用树莓派官方触摸显示屏的触摸屏组件。

通用显示参数

`disable_fw_kms_setup`

在默认情况下，固件会解析所有接入 HDMI 显示器的 EDID，并选择适当的信号格式，然后通过内核命令行上的设置将显示的分辨率和帧率（以及过扫描参数）传给 Linux 内核。在极少数情况下，固件可能会选择 EDID 中不存在的信号格式，可能并不兼容该设备。使用 disable_fw_kms_setup=1 可以禁用传递的视频信号格式，从而避免此问题。Linux 视频模式系统（KMS）会自己解析 EDID 并选择适当的信号格式。

注意
在树莓派 5 上，此参数默认为 1。

相机设置

`disable_camera_led`

将 disable_camera_led 置为 1 可在录制视频、拍摄照片时关闭摄像机的红色 LED 指示灯。这对于防止反光（如摄像机正对着窗户时）极其有用。

`awb_auto_is_greyworld`

将 awb_auto_is_greyworld 置为 1，可让自身不带灰度世界算法的库和应用程序使用夜视（NoIR）摄像头捕捉到有效的图像、视频。它将自动 awb 信号格式切换使用灰度世界算法。仅适用于夜视 NoIR 摄像机、的高质量（HQ）摄像机。

旧版 config.txt 参数

旧版参数

此处所述的 config.txt 参数被视为陈旧设置，树莓派 Bookworm 系统不再使用，亦无官方支持。它们要么涉及旧软件（如固件中的图形驱动程序）、要么已弃用、要么几乎无人使用。然而，它们仍被记录在此，因为它们对于那些使用旧操作系统的用户，及进行裸机开发的人来说，可能仍有用。

旧版启动参数

（另请参阅启动参数。）

`start_x`、`start_debug`

这里提供了代替参数 start_file、fixup_file 的简单方法。这是选定固件配置的建议方法。

start_x=1 意味着

对于树莓派 4，如果存在文件 start4x.elf、fixup4x.dat，则会使用之。

start_debug=1 意味着

`disable_commandline_tags`

若将参数 disable_commandline_tags 置为 1，会在启动内核之前禁止 start.elf 覆盖 ATAGS（从 0x100 开始的内存）。

`arm_control`

警告
此参数已弃用。请改用 arm_64bit 来启用 64 位内核。

此设置特定于主板的控制位。

`armstub`

armstub 位于启动分区，是用于加载 ARM stub（存根）的文件名。默认的 ARM 存根存储在固件中，会根据树莓派型号及各种设置自动选定。

存根是在内核运行之前被执行的一小段 ARM 代码。它的任务是设置诸如中断控制器等底层硬件，然后再将控制权移交给内核。

`arm_peri_high`

若将 arm_peri_high 置为 1：可在树莓派 4 上启用高性能外设模式。若加载了恰当的 DTB，将会自动设定该参数。

注意
若在缺失兼容设备树（DTB）的情况下，启用高性能外设模式，将导致系统无法启动。目前的 ARM 存根支持尚不完善，因此你还需使用 armstub 加载对应的文件。

`kernel_address`

kernel_address 是加载内核镜像的内存地址。在默认情况下，32 位内核会加载到地址 0x8000，64 位内核会加载到地址 0x200000。若设置了 kernel_old，内核会被加载到地址 0x0。

`kernel_old`

若将 kernel_old 置为 1，可将内核加载至内存地址 0x0。

`init_uart_baud`

init_uart_baud 是串口的初始化波特率。默认值为 115200。

`init_uart_clock`

init_uart_clock 是串口的初始化时钟频率。默认值为 48000000（48MHz）。请注意，此时钟仅适用于 UART0（Linux 为 ttyAMA0），且串口的最大波特率受限为时钟的 1/16。树莓派 3 和树莓派 Zero 的默认串口是 UART1（Linux 为 ttyS0），其时钟等同于核心 VPU 时钟——至少为 250MHz。

`bootcode_delay`

参数 bootcode_delay 设定了在 bootcode.bin 阶段的延迟（秒），然后再加载 start.elf——默认值为 0。

这在读取显示器 EDID 前插入延迟极有用。比如，树莓派和显示器共用一部电源，但显示器的启动时间长于树莓派。如果显示器在初始启动时会检测到错误，但在不断电的情况下重启树莓派后就检测正确了，那么请尝试设置此参数。

`boot_delay`

参数 boot_delay 意味着在加载内核之前，会在 start.elf 阶段等待给定的时间（秒）。总延迟计算公式为 (1000 x boot_delay) + boot_delay_ms，单位为毫秒。如果你的存储卡需要一些时间才能准备好，继而才能启动 Linux，这可能极有用。

`boot_delay_ms`

参数 boot_delay_ms 意味着在加载内核之前，会在 start.elf 阶段（含 boot_delay）等待给定的时间（毫秒）。默认值为 0。

`enable_gic`（仅适用于树莓派 4）

在树莓派 4B 上，如果将此值置为 0，则中断将从旧的中断控制器（而非 GIC-400）路由到 Arm 处理器。默认值为 1。

`sha256`

如果设置为非 0 值，则将：为加载的文件（内核、initramfs、设备树 .dtb 文件和叠加层）记录 SHA256 哈希值日志，哈希值由工具 sha256sum 生成。如启用，日志输出将发送到串口，亦可通过 sudo vclog --msg 获取。在调试启动故障时，此参数可能极有用，但可能会使启动时间增加数秒。在所有平台上，默认值均为 0。

`uart_2ndstage`

设置 uart_2ndstage=1 会触发第二阶段加载程序（树莓派 4 之前的设备为 bootcode.bin、树莓派 4 设备为 EEPROM 中的引导代码）和主固件（start*.elf）把诊断信息输出到 UART0。

请注意，输出可能会干扰蓝牙正常工作，除非禁用蓝牙（dtoverlay=disable-bt）或把蓝牙切换到别的串口（dtoverlay=miniuart-bt），如串口同时被用于输出 Linux 数据，则可能会导致数据丢失，从而导致输出故障。此功能应仅在诊断早期引导加载故障时使用。

`upstream_kernel`

如果设定 upstream_kernel=1，固件会将 os_prefix 设置为"upstream/"——除非已明确将其设置为其他值。但就像其他 os_prefix 值一样，如果在使用前缀时无法找到所需的内核和 .dtb 文件，则会忽略该值。

固件还会优先使用上游 Linux 的 DTB 名称（bcm2837-rpi-3-b.dtb 先于 bcm2710-rpi-3-b.dtb）。如果找不到上游文件，则固件将加载下游衍生文件，并自动加载"upstream"叠加层来进行调整。请注意，此过程发生在 os_prefix 最终确定后。

旧版 GPIO 控制

（另请参阅。）

`enable_jtag_gpio`

设置 enable_jtag_gpio=1：会把 GPIO 引脚 22-27 设为 Alt4 模式，并在 SoC 内部进行相关配置，从而启用 Arm CPU 的 JTAG 接口。此设置适用于所有型号的树莓派。

引脚号

功能

旧版超频参数

（另请参阅。）

超频

`never_over_voltage`

会在一次性可编程（OTP）存储器中置一个位，防止设备过压。旨在锁定树莓派，以防止无意、或恶意地使用无效过电压篡改保修位。

`disable_auto_turbo`

对于树莓派 2、3，设置此参数将禁止 GPU 超频。而在特定负载下，GPU 原本可进入超频模式。

旧版条件筛选器

（另请参阅。）

筛选器 `[HDMI:*]`

注意
此筛选器仅适用于树莓派 4。

树莓派 4 有两个 HDMI 端口，有许多个同 HDMI 相关的 config.txt 参数，有必要指明所选定的 HDMI 端口。HDMI 条件筛选器将后续 HDMI 配置限定到特定端口。

所有特定于端口的 HDMI 参数都提供了另外一种语法：变量:值。你可以使用以下内容，这与前面的示例相同：

旧版内存参数

（另请参阅）

注意
树莓派 5 不会为操作系统分配 GPU 内存（显存），故以下参数无效。

`gpu_mem`

指定要为 GPU 保留多少专用内存（MB）：剩余内存分配给 Arm CPU 供操作系统使用。对于内存小于 1GB 的树莓派来说，默认值为 64；对于内存为 1GB 及更大容量的树莓派，默认值为 76。

重要
与 x86 平台（增大显存可提高 3D 性能）上的 GPU 不同。VideoCore 的架构意味着：指定比必要值更大的值不仅无法带来性能优势，相反还可能会降低性能。

为了确保 Linux 呈最佳性能，你应把 gpu_mem 设置成尽可能低的值。如果某个特定的图形功能无法正常工作，可尝试提高 gpu_mem 的值，但请注意下面展示的建议最大值。

在树莓派 4 上，GPU 的 3D 组件有自己的内存管理单元（MMU），故不使用 gpu_mem 分配的内存，而是使用 Linux 动态分配的内存。这使得树莓派 4 可指定比先前型号还小的 gpu_mem 值。

由旧款内核分配给 GPU 的内存，可用于显示器、3D、编解码器和摄像头等用途，以及一些基本固件管理。下面指定的最大值，假定你正使用着上述所有功能。如无，则应使用较小的 gpu_mem 值。

建议最大值如下：

重要
树莓派系统上的相机堆栈（libcamera）使用 Linux CMA（连续内存分配器）的内存分配缓冲区，并不占用 GPU 显存，所以增大 GPU 显存没有任何好处可言。

能把 gpu_mem 设置成更大的值，但不建议这么做，因为可能会引发故障（可能妨碍 Linux 启动）。gpu_mem 的最小值为 16——但此值会禁用某些 GPU 功能。

你还可以使用 gpu_mem_256、gpu_mem_512、gpu_mem_1024，以便在不同内存容量间的树莓派交换同一张存储卡，无需每次都编辑 config.txt：

`gpu_mem_256`

参数 gpu_mem_256 可为搭载 256MB 内存的树莓派设置 GPU 内存（MB）。如果内存容量不是 256MB，则会被忽略。该参数会覆盖 gpu_mem。

`gpu_mem_512`

参数 gpu_mem_512 可为搭载 512MB 内存的树莓派设置 GPU 内存（MB）。如果内存容量不是 512MB，则会被忽略。该参数会覆盖 gpu_mem。

`gpu_mem_1024`

参数 gpu_mem_1024 可为搭载 1GB（及更大容量）内存的树莓派设置 GPU 内存（MB）。如果内存容量小于 1GB，则会被忽略。该参数会覆盖 gpu_mem。

`disable_l2cache`

若将该参数置为 1（并同时禁用 L2 缓存的相关内核），会禁止 CPU 使用 GPU 的 L2 缓存。BCM2835 的默认值为 0。基于 BCM2836、BCM2837、BCM2711 和 BCM2712 的 ARM 有自己的 L2 缓存，故默认值为 1。标准版本的树莓派 kernel.img 和 kernel7.img 对应了缓存设置的差异。

旧版视频参数

（另请参阅。）

HDMI 信号格式

注意
因为树莓派 4、400 搭载了两个 HDMI 端口，故某些 HDMI 参数可以应用于特定接口。你可以使用语法 <参数>:<端口>，其中端口值为 0 或 1，用来指定此设置应用于哪个端口。如未指定端口，则默认为 0。如果在不支持端口号的参数上指定了端口号，则端口将被忽略。更多有关语法和可选机制的详细信息，请参阅文档的中的 HDMI 章节。

`hdmi_safe`

若将 hdmi_safe 置为 1，将触发使用“safe mode（安全模式）”，尝试以最大化 HDMI 兼容性启动。等同于设定以下参数：

`hdmi_ignore_edid`

如果你的显示器没有准确的 EDID。可将 hdmi_ignore_edid 置为 0xa5000080，以忽略显示器的 EDID（扩展显示识别数据）信息。它需要此异常值来避免触发故障。

`hdmi_edid_file`

若将 hdmi_edid_file 置为 1，将使 GPU 从启动分区中的 edid.dat 文件（而非显示器）中读取 EDID 数据。

`hdmi_edid_filename`

在树莓派 4B 上，你可以使用参数 hdmi_edid_filename 指定要使用的 EDID 文件的文件名，并指定文件要应用的 HDMI 端口。同时还需要 hdmi_edid_file=1 来启用 EDID 文件。

例如：

`hdmi_force_edid_audio`

若将 hdmi_force_edid_audio 置为 1，会把显示器伪装成支持一切音频格式，即使实际上不支持 DTS/AC3，也能进行音频透传。

`hdmi_ignore_edid_audio`

若将 hdmi_ignore_edid_audio 置为 1，会把显示器伪装成不支持一切音频格式。这意味着 ALSA 将默认使用模拟音频（耳机）插孔。

`hdmi_force_edid_3d`

若将 hdmi_force_edid_3d 置为 1，会将所有的 CEA 信号格式伪装成支持 3D，即使 EDID 信息并未标称支持。

`hdmi_ignore_cec_init`

若将 hdmi_ignore_cec_init 置为 1，可在启动过程中禁止发送初始化活动源信息。这可以防止：在重启树莓派时，带 CEC 支持的电视机因从待机状态中唤醒而切换频道。

`hdmi_ignore_cec`

若将 hdmi_ignore_cec 置为 1，会把显示器伪装成不支持 CEC。将不支持一切 CEC 功能。

`cec_osd_name`

参数 cec_osd_name 可为设备设置初始化 CEC 名称。默认为 Raspberry Pi。

`hdmi_pixel_encoding`

参数 hdmi_pixel_encoding 将强制使用像素编码模式。在默认情况下，它使用从 EDID 请求的信号格式，因此你不大需要更改此参数。

`hdmi_max_pixel_freq`

固件和 KMS 使用像素时钟来选定 HDMI 信号格式。请注意，这与帧率不同。它指定了有效信号格式可以具有的最大频率，从而剔除了更高频率的信号格式。因此，如果你希望彻底禁用 4K 信号格式，你可以指定最大频率为 200000000，因为所有的 4K 信号格式频率均大于此值。

`hdmi_blanking`

参数 hdmi_blanking 可控制该过程：操作系统为节省电源，要求使用 DPMS（Display Power Management Signaling，显示电源管理信号）让显示器置于待机模式。如果未设置此参数或将其置为 0，则 HDMI 输出将被清空但不会关闭。为了模仿其他计算机的行为，你可以同时把 HDMI 输出也设置为关闭，方法是将此参数置为 1：已连接的显示器将进入低功耗待机模式。

注意
在树莓派 4 上，设置 hdmi_blanking=1 不会停止 HDMI 输出，因为该功能未实现。当使用不使用 framebuffer（帧缓冲器）的应用程序（如 omxplayer）时，此功能可能会引发问题。

`hdmi_drive`

hdmi_drive 参数能让你在输出信号格式 HDMI 和 DVI 间进行切换。

`config_hdmi_boost`

配置 HDMI 端口的信号强度。最小值为 0，最大值为 11。

早期型号的 B、A 默认值为 2。B+ 及所有后续型号的默认值为 5。

如果你遇到了 HDMI 故障（雪花等干扰），请尝试 7。特别长的 HDMI 线缆可能需要 11 这么大才行——但除非绝对必要，否则不应使用这么高的值。

旧款树莓派 4 会忽略此参数。

`hdmi_group`

hdmi_group 参数定义了 HDMI 输出组，可以是 CEA（美国消费电子协会标准，一般由电视使用）和 DMT（显示监视器时序标准，一般由显示器使用）。此设置应与 hdmi_mode 联合使用。

`hdmi_mode`

与 hdmi_group 一道，hdmi_mode 定义了 HDMI 输出格式。信号格式编号符合。

注意
并非全部型号都能使用以下所有信号格式。

以下值仅在 hdmi_group=1（CEA）下有效：

① 仅在处理器超频主频下可用：须设置 core_freq_min=600 和 core_freq=600。。

双倍像素、四倍像素意味着更高的时钟主频，每个像素各重复两次、四次。

以下值仅在 hdmi_group=2（DMT）下有效：

注意
像素时钟有限制。树莓派 4 之前的型号支持的最高信号格式为 1920×1200 60Hz，带降低清屏（reduced blanking）时间，而树莓派 4 可以支持高达 4096×2160（俗称 4k）60Hz。还请注意，如果你正在使用树莓派 4 的两个 HDMI 端口进行 4k 输出，则两者都将被限制至 30Hz。

`hdmi_timings`

可自定义原始 HDMI 时序值：用 hdmi_group=2 和 hdmi_mode=87 可自定义信号格式。

可将宽高比设置为以下八个值之一。请从以下选项中，选择一个与你屏幕的宽高比最相近的值：

宽高比

名称

值

`hdmi_force_mode`

若置为 1，将从内部列表中删除所有除 hdmi_mode 和 hdmi_group 指定外的其他信号格式，这意味着它们不会出现在一切信号格式的枚举列表中。如果显示器似乎无视 hdmi_mode 和 hdmi_group 配置，此参数可能有用。

`edid_content_type`

强制将 EDID 的内容类型设置为特定值。

参数如下：

0 = EDID_ContentType_NODATA，内容类型为无
1 = EDID_ContentType_Graphics，内容类型为图形，必须把 ITC 置为 1
2 = EDID_ContentType_Photo

我的显示器能使用哪些值？

你的 HDMI 显示器可能仅支持有限的信号格式。要找出受支持的格式，请使用以下方法：

将输出格式设置为 VGA 60Hz ( hdmi_group=1 和 hdmi_mode=1 ) ，然后启动你的树莓派
输入以下参数可列出受支持的 CEA 信号格式: /opt/vc/bin/tvservice -m CEA
输入以下参数可列出受支持的 DMT 信号格式: /opt/vc/bin/tvservice -m DMT

在排除默认 HDMI 信号格式的故障时，也应附带 edid.dat。

自定义信号格式

如果你的显示器所需的信号格式未列在上述表格中，那么可以为其自定义一种 CVT 信号格式：

值

默认值

说明

可省略末尾的字段，使用默认值。

请注意，这仅 创建了 信号格式（group 2 mode 87）。要使树莓派默认应用该信号格式，你需要进行一些额外设置。例如，要选择分辨率 800×480 并启用音频驱动：

如果你的显示器不支持标准 CVT 时序，则可能无法正常工作。

复合视频信号格式

`sdtv_mode`

参数 sdtv_mode 定义了用于复合视频输出的电视标准。

`sdtv_aspect`

sdtv_aspect 参数定义了复合视频输出的纵横比。默认值为 1。

`sdtv_disable_colourburst`

若将 sdtv_disable_colourburst 置为 1，会禁用复合视频输出上的彩色突发信号。图片将以单色显示，但可能会更清晰。

液晶显示屏和触摸屏

`display_default_lcd`

如果检测到了树莓派触摸显示屏，它将被用作默认显示器，并显示帧缓冲区。设置 display_default_lcd=0 可确保液晶显示屏并非是默认显示器，这通常意味着使用 HDMI 的默认输出。仍可通过在受支持的应用程序（如 omxplayer）中选择显示器编号来使用液晶显示屏。

`lcd_framerate`

可指定树莓派触摸显示屏的帧率（Hz/fps）。默认为 60Hz。

`lcd_rotate`

将使用 LCD 内置的旋转功能调整显示方向，这比使用基于 GPU 的旋转操作更节省计算资源。

如，lcd_rotate=2 可回正倒立的显示界面。

`enable_dpi_lcd`

启用连接到 DPI GPIO 的 LCD 显示器。将允许使用并行显示接口的第三方 LCD 显示器。

`dpi_group`, `dpi_mode`, `dpi_output_format`

参数 dpi_group 和 dpi_mode config.txt 用于设置预定信号格式（在 HDMI 中使用的 DMT、CEA 信号格式，如上所述）。用户可以以与 HDMI 相同的方式生成自定义信号格式（请参阅 dpi_timings 部分）。

dpi_output_format 是个位掩码，可指定用于设置显示格式的各种参数。

`dpi_timings`

可设置原始 DPI 时序值，用于自定义信号格式，通过 dpi_group=2 和 dpi_mode=87 选定。

可将宽高比设置为以下八个值之一。请从以下选项中，选择一个与你屏幕的宽高比最相近的值：

宽高比

名称

值

通用显示参数

`hdmi_force_hotplug`

若将 hdmi_force_hotplug 置为 1，会把 HDMI 热插拔信号伪装已触发，使系统认为已接入了 HDMI 显示器。换句话说，即使未检测到 HDMI 显示器，也会使用 HDMI 信号输出。

`hdmi_ignore_hotplug`

若将 hdmi_ignore_hotplug 置为 1，会把 HDMI 热插拔信号伪装成未被触发，因此看起来好似没有连接 HDMI 显示器一样。因此，即使连接了显示器，HDMI 输出也将被禁用。

`disable_overscan`

disable_overscan 的默认值为 0，将为左右上下四周边缘设置默认的过扫描值：CEA 高清信号为 48、对于 CEA 标清信号格式为 32、DMT 信号格式为 0。

若将 disable_overscan 置为 1，将禁用固件设置的默认的值。

`overscan_left`

参数 overscan_left 可指定将添加到屏幕左边缘的固件默认过扫描值的像素数。默认值为 0。

若文本溢出屏幕左边缘，请增加此值；若屏幕左边缘和文本之间有黑色边框，请调低此值。

`overscan_right`

参数 overscan_right 可指定将添加到屏幕右边缘过扫描的固件默认值的像素数。默认值为 0。

若文本溢出屏幕右边缘，请增加此值；若屏幕右边缘和文本之间有黑色边框，请减少此值。

`overscan_top`

overscan_top 参数可指定将添加到屏幕顶部过扫描的固件默认值的像素数。默认值为 0。

若文本溢出屏幕顶部边缘，请增加此值；若屏幕顶部边缘和文本之间有黑色边框，请减少此值。

`overscan_bottom`

overscan_bottom 参数可指定将添加到屏幕底部边缘过扫描的像素数。默认值为 0。

若文本溢出屏幕底部边缘，请增加此值；若屏幕底部边缘和文本之间有黑色边框，请减少此值。

`overscan_scale`

若将 overscan_scale 置为 1，可强制所有非帧缓冲层遵守过扫描设置。默认值为 0。

注意
通常不建议使用此功能：若这样做，显示器上的所有图层都将由 GPU 缩放，可能会降低图像质量。建议针对显示器自身禁用过扫描，以避免图像被 GPU 和显示器缩放两回。

`framebuffer_width`

参数 framebuffer_width 可指定像素中的控制台帧缓冲区宽度。默认值为显示宽度减去总水平过扫描量。

`framebuffer_height`

参数 framebuffer_height 可指定控制台帧缓冲区的像素高度。默认值为显示高度减去总垂直过扫描量。

`max_framebuffer_height`、`max_framebuffer_width`

可指定内部帧缓冲区的最大尺寸。

`framebuffer_depth`

使用 framebuffer_depth 来指定每像素位的控制台帧缓冲区深度。默认值为 16。

`framebuffer_ignore_alpha`

若将 framebuffer_ignore_alpha 置为 1，会禁用 alpha 管道。可以改善 32 位 framebuffer_depth 显示。

`framebuffer_priority`

如设备接入了多个显示器，若此时使用旧款（KMS 之前）图形驱动程序，回强制特定的内部显示设备成为首个 Linux 帧缓冲区（即 /dev/fb0）。

可设置的参数有：

显示器

`max_framebuffers`

此配置条目将设置可创建的固件帧缓冲区的最大数量。有效值为 0、1 和 2。在旧设备上，默认设置为 1，因此当使用多个显示器时（如 HDMI、DSI、DPI 显示器）时，需要将其增加到 2。树莓派 4 的默认配置即是 2，因为它有两个 HDMI 端口。

在大多数情况下，将其设置为 2 是安全的，因为只有在实际检测到已连接的设备后才会创建帧缓冲区。

若将此值置为 0，可在无头模式下减少内存需求，因为这将阻止分配帧缓冲区。

`test_mode`

参数 test_mode 可在启动过程中，以持续给定的时间（秒），显示测试图像和声音（仅输出至复合视频输出和模拟音频），然后继续正常启动操作系统。用作工厂测试。默认值为 0。

`display_hdmi_rotate`

使用 display_hdmi_rotate 旋转、镜像 HDMI 显示方向。默认值为 0。

请注意，旋转 90 度、270 度需要更多的 GPU 内存，因此这些参数在 16MB GPU 分配下不可用。

你可以组合旋转、镜像将其叠加。你也可以用相同的方式同时进行水平镜像和垂直镜像。例如，旋转 180 度，再加上垂直镜像、水平镜像为 0x20000 + 0x10000 + 2 = 0x30002。

`display_lcd_rotate`

对于旧款图形驱动程序（适用于树莓派 4 先前的型号），请使用 display_lcd_rotate 来旋转和镜像 LCD 方向。参数与 display_hdmi_rotate 相同。另请参阅 lcd_rotate。

`display_rotate`

在最新款固件中，display_rotate 已弃用。仅保留用于向下兼容。请改用 display_lcd_rotate、display_hdmi_rotate。

使用 display_rotate 可旋转和镜像屏幕方向。参数与 display_hdmi_rotate 相同。

其他参数

`dispmanx_offline`

可强制在两个离屏帧缓冲区中离线完成 dispmanx 合成。这样可以合成更多的 dispmanx 元素，但速度较慢，可能会将屏幕帧率限制在约 30fps 左右。

旧版树莓派 4 HDMI 管道

重要
当使用图形驱动程序 VC4 KMS 时，完整的显示管道由 Linux 管理——包括 HDMI 输出。这些设置仅兼容于旧的 FKMS 和基于固件的图形驱动程序。

树莓派 4 无法在 HDMI 输出 1366×768 @ 60Hz。对于这些显示器，可配置其使用 1360×768 @ 60Hz。它们通常未通过 EDID 广播此信号格式，因此无法自动选定，但可以手动添加来选定：

……到 config.txt。

在 hdmi_timings= 这一行，手动指定的时间也需要遵守限制：所有水平时序参数必须为 2 的倍数。

dpi_timings= 不受相同限制，因为该管道在每个时钟周期仍然仅运行一个像素。

其他旧版参数

`avoid_warnings`

avoid_warnings=2：允许在低电压下进入超频模式。

`logging_level`

设置 VideoCore 的日志级别。该值是 VideoCore 的一个特定的位掩码。

摄像头软件

本文档说明了如何使用树莓派的软件工具和受支持的摄像头模块。所有的树莓派摄像头都可以使用我们的软件工具，来拍摄高分辨率照片，录制全高清 1080p（及更高）视频。

树莓派官方生产了多款摄像头模块，包括：

摄像头模块 1。搭载 500 万像素（最早，已停产）
摄像头模块 2。搭载 800 万像素，红外滤镜可选
摄像头模块 3。搭载 1200 万像素，标准镜头、广角镜头可选，红外滤镜可选
高质量（High Quality）相机，配有 CS 和 M12 卡口，搭载 1200 万像素，可同外部镜头搭配使用
全局快门（Global Shutter）相机，搭载 160 万像素，用于高速运动摄影

有关摄像头硬件的更多信息，请参阅摄像头硬件文档。

首先安装你的摄像头模块。然后，依此部分的指南，使用摄像头模块。

`rpicam-apps`

注意
树莓派系统 Bookworm 把相机捕获应用程序从 libcamera-* 重命名为 rpicam-*。用户可暂时以符号链接使用旧名称。请尽快采用新的软件名。之前的旧版树莓派系统仍使用 libcamera-* 这个名称。

树莓派提供了一小组示例 rpicam-apps。这些命令行应用程序基于 libcamera，从相机捕获图像和视频。这些应用程序包括：

rpicam-hello ：相机版“hello world”，将启动相机预览流并在屏幕上显示它。
rpicam-jpeg ：打开预览窗口，随后捕获高分辨率的静止图像。
rpicam-still ：模拟了旧软件 raspistill

最新版的树莓派系统内置了五款基本的 rpicam-apps，因此即使在全新安装的树莓派系统上，你也可以使用摄像头记录图像和视频。

用户可创建基于 rpicam 的应用程序，定制其功能，足以满足用户需求。rpicam-apps 的源代码在 BSD-2-Clause 许可下自由提供。

`libcamera`

libcamera 是一款开源软件库，旨在直接在基于 Arm 处理器上运行的 Linux 操作系统来使用相机设备。在博通 GPU 上运行的私有代码已被最小化。有关 libcamera 的更多信息，请参阅 libcamera 网站。

libcamera 提供了 C++ API，用于配置相机，能让应用程序请求图像帧。这些图像缓冲区驻留在系统内存中，并可以直接传参给静态图像编码器（如 JPEG）/视频编码器（如 H.264）。libcamera 不会对图像进行编码和显示：要使用该功能，请使用 rpicam-apps。

你可以在 libcamera 官方存储库中找到源代码。树莓派系统发行版使用分支控制更新。

在 libcamera 核心下，我们提供了自定义的管道流来处理程序。libcamera 使用这层来驱动树莓派上的传感器和图像信号处理器（ISP）。libcamera 包含了一系列图像处理算法（IPA），包括自动曝光/增益控制（AEC/AGC）、自动白平衡（AWB）和自动镜头阴影校正（ALSC）。

树莓派的 libcamera 实现可支持以下摄像头：

官方摄像头:
- OV5647 (V1)
- IMX219 (V2)

要增加对新传感器的支持，请贡献至 libcamera。

`rpicam-hello`

rpicam-hello 能在简单的预览窗口中，显示来自接入摄像头的视频源。要让 rpicam-hello 在终端里显示 5 秒钟的预览窗口，请运行以下命令：

你可以使用参数 timeout 指定可选的持续时间（毫秒）。值为 0 会无限期运行预览：

要结束 rpicam-hello，可在终端中按 Ctrl + C，或在预览窗口上点击关闭按钮。

显示图像传感器预览

大多数 rpicam-apps 都在窗口中显示预览图像。如果没有正在运行的桌面环境，则将直接使用 Linux Direct Rendering Manager（DRM，直接渲染管理器）把预览绘制到显示器。如果都没有，rpicam-apps 会尝试使用桌面环境。这两种路径都使用零拷贝 GPU 缓冲区共享：即导致不支持 X 转发。

如果你运行着 X 窗口服务器，想要使用 X 转发，请使用参数 qt-preview，可在 Qt 窗口中渲染预览窗口。与其他方案相比，用 Qt 预览窗口将消耗更多资源。

注意
使用 Gtk2 的旧版系统在与 OpenCV 链接时，可能会产生 Glib-GObject 报错，且无法显示 Qt 预览窗口。在这种情况下，请以 root 身份，编辑文件 /etc/xdg/qt5ct/qt5ct.conf，把 style=gtk2 这行改成 style=gtk3。

要彻底禁止预览窗口，请使用参数 nopreview ：

参数 info-text 使用可指令 % 在窗口标题栏上显示图像信息。例如，以下命令会显示当前的红色和蓝色增益值：

要查看指令的完整列表，请参阅 info-text 参考。

`rpicam-jpeg`

rpicam-jpeg 可帮助你在树莓派设备上捕获图像。

要捕获全分辨率 JPEG 图像并将其保存成名为 test.jpg 的文件，请运行以下命令：

你将在五秒内看到预览窗口。然后，rpicam-jpeg 会捕获保存全分辨率的 JPEG 图像。

可使用参数 timeout 来修改预览窗口的显示时间。参数 width 和 height 可更改保存图像的分辨率。例如，以下命令显示预览窗口 2 秒，然后捕获并保存分辨率为 640×480 像素的图像：

`rpicam-still`

rpicam-still，同 rpicam-jpeg 一样，帮助你在树莓派设备上捕获图像。与 rpicam-jpeg 不同，rpicam-still 能兼容许多旧版应用程序中提供的参数。

要捕获全分辨率的 JPEG 图像并将其保存成名为 test.jpg 的文件，请运行以下命令：

编码器

rpicam-still 可以多种格式保存图像，包括 png、bmp、RGB 和 YUV 二进制像素转储。要读取这些二进制转储，用于读取文件的应用程序都必须兼容像素排列。

使用参数 encoding 能指定输出格式。传参给 output 的文件名不会影响输出文件类型。

要捕获全分辨率的 PNG 图像并将其保存成名为 test.png 的文件，请运行以下命令：

要了解有关指定图像格式的更多信息，请参阅 encoding 参数参考。

捕获原始图像

原始图像是直接由图像传感器生成的图像，未经图像信号处理器（ISP）和 CPU 的处理。彩色图像传感器通常使用 Bayer 格式。使用参数 raw 来捕获原始图像。

要捕获图像，并将其保存成名为 test.jpg 的文件，再把图像的原始版本保存成名为 test.dng 的文件，请运行以下命令：

rpicam-still 以 DNG（Adobe 数字负片）格式保存原始图像。要确定原始图像的文件名，rpicam-still 使用与输出文件相同的文件名，但将其扩展名更改为 .dng。要处理 DNG 图像，请使用类似于 Dcraw、RawTherapee 的应用程序。

DNG 文件包含了有关图像捕获的元数据，包括黑电平、白平衡信息以及 ISP 用于生成 JPEG 的色彩矩阵。使用 ExifTool 查看 DNG 元数据。以下输出显示了通过使用 HQ 相机捕获的原始图像中存储的典型元数据：

要找到模拟增益，请将 ISO 数除以 100。自动白平衡（AWB）算法确定一个始终标记为 D65 的单个校准光源。

拍摄长曝光照片

要拍摄非常长时间的曝光照片，请禁用自动曝光/增益控制（AEC/AGC）和自动白平衡（AWB）。否则，这些算法会强制用户等待一定数量的帧数，直到它们收敛。

要禁用这些算法，请为增益和 AWB 提供明确的值。因为长时间曝光本身就需要很多时间，通常最好完全跳过预览阶段，使用参数 immediate 。

运行以下命令执行 100 秒曝光捕捉：

要查找官方树莓派相机的最大曝光时间，请参阅相机硬件规格。

创建延时摄影视频

创建延时摄影视频，定期拍摄静止图像，例如每分钟一次，然后使用应用程序将图片拼接成视频。

通过 rpicam-still 延时模式

要使用 rpicam-still 的内置延时模式，请使用 timelapse 功能。此参数需要一个值，代表你希望树莓派在捕获之间等待的时间间隔，单位为毫秒。

首先，创建一个目录，用于存储你的延时摄影照片：

运行以下命令，将创建一项 30 秒的延时摄影，每两秒记录一张照片，将输出保存为 image0000.jpg 至 image0013.jpg：

通过 cron

你还可以使用 cron 自动化延时摄影。首先，创建一个脚本，命名为 timelapse.sh，包含以下指令。把占位符 <用户名> 改成你树莓派上的用户账户名：

然后，使脚本可执行：

创建目录 timelapse ，你将在其中保存延时摄影图片：

打开你的 crontab 进行编辑：

请你在编辑器中打开文件后，添加以下行以安排每分钟捕获图像，把占位符 <用户名> 换成你主用户账户的用户名：

保存退出，你应看到此信息：

技巧
停止录制图像以进行延时摄影，请再次运行 crontab -e 并从你的 crontab 中删除上述行。

拼接图像

如果你拥有一系列延时摄影照片，你可能希望将它们合并成视频。在树莓派上使用 ffmpeg 来完成这个操作。

首先，安装 ffmpeg ：

从包含目录 timelapse 的目录中运行以下命令，将你的 JPEG 文件转换为 mp4 视频：

上述命令使用以下参数：

-r 10 ：将帧率（Hz）设置为每秒十帧的输出视频
-f image2 ：设置 ffmpeg 以从由模式指定的图像文件列表中读取
-pattern_type glob

要了解有关 ffmpeg 参数的更多信息，请在终端中运行 ffmpeg --help。

`rpicam-vid`

rpicam-vid 可帮助你在树莓派设备上捕获视频。rpicam-vid 将显示一个预览窗口并将编码比特流写入指定的输出。这会产生未打包的视频比特流，不含容器（如 mp4 文件）格式。

注意
在可用时，rpicam-vid 使用硬件 H.264 编码。

例如，以下命令将十秒钟的视频写入名为 test.h264 的文件：

你可以使用 VLC 和其他视频播放器播放生成的文件：

在树莓派 5 上，你可以通过为输出文件指定 mp4 文件扩展名，直接输出到 MP4 容器格式：

编码器

rpicam-vid 支持运动 JPEG 以及未压缩和未格式化的 YUV420：

codec 参数决定输出格式，而不是输出文件的扩展名。

segment 参数将输出文件分成以毫秒为单位的段。这对于通过指定非常短的（1 毫秒）段来将运动 JPEG 流分解为单独的 JPEG 文件非常方便。例如，以下命令将 1 毫秒的段与输出文件名中的计数器结合起来，为每个段生成一个新的文件名：

捕获高帧率视频

为了减少高帧率（> 60fps）视频的帧丢失，请尝试以下配置调整：

使用 --level 4.2 将 H.264 目标级别设置为 4.2。
通过将参数 denoise 设置为 cdn_off 来禁用软件颜色去噪处理。

以下命令演示了如何实现 1280×720 120fps 视频：

`rpicam-vid` 与 libav 的集成

rpicam-vid 可以使用 ffmpeg / libav 编解码后端来对音频和视频流进行编码。你可以将这些流保存到文件，也可以通过网络进行流传输。当存在时，libav 使用硬件 H.264 视频编码。

要启用 libav 后端，请将 libav 传参给参数 codec：

`rpicam-raw`

rpicam-raw 直接从传感器以原始 Bayer 帧记录视频。它不显示预览窗口。要将两秒的原始剪辑记录到名为 test.raw 的文件中，请运行以下命令：

rpicam-raw 以原始帧的形式输出，没有格式信息，直接一个接一个。应用程序会在终端窗口打印像素格式和图像尺寸，以帮助用户解释像素数据。

默认情况下，rpicam-raw 将原始帧输出到单个、可能非常大的文件中。使用参数 segment 将每个原始帧定向到单独的文件，使用 %05d 指令使每个帧文件名唯一：

使用快速存储设备，rpicam-raw 可以以 10fps 的速度将 18MB 1200 万像素 HQ 相机帧写入磁盘。rpicam-raw 无法将输出帧格式化为 DNG 文件；要使用该功能，请使用 rpicam-still。使用低于参数 10 的级别 framerate 以避免丢帧：

有关原始格式的更多信息，请参阅 mode 文档。

`rpicam-detect`

注意
树莓派系统不包括 rpicam-detect。但是，如果你已安装了 TensorFlow Lite，可以编译 rpicam-detect。有关更多信息，请参阅 rpicam-apps 编译说明。运行 cmake 时，请不要忘记参数 -DENABLE_TFLITE=1。

rpicam-detect 显示一个预览窗口，并使用经过训练的 Google MobileNet v1 SSD（Single Shot Detector）神经网络监视内容，以识别大约 80 种对象类别，使用 Coco 数据集。rpicam-detect 可以识别人、汽车、猫和许多其他对象。

每当 rpicam-detect 检测到目标物体时，它会拍摄全分辨率的 JPEG。然后返回监视预览模式。

查看 TensorFlow Lite 对象检测器部分，了解有关模型使用的一般信息。例如，你可以在离开时秘密监视你的猫。

配置

大多数用例无需更改摄像头配置即可自动工作。但是，某些常见用例确实需要进行配置调整，包括：

第三方摄像头（制造商的说明应进行的必要配置更改，如果有）
使用官方树莓派摄像头的非标准驱动程序或叠加物

树莓派系统在 /boot/firmware/config.txt 中识别以下叠加层。

要使用这些叠加层，你必须禁用自动摄像头检测。要禁用自动检测，请在 /boot/firmware/config.txt 中设置 camera_auto_detect=0。如果 config.txt 已包含分配 camera_auto_detect 值的行，请将该值更改为 0。使用 sudo reboot 重启你的树莓派以加载更改。

使用调整文件调整摄像头行为

树莓派的 libcamera 实现包括每个摄像头的调整文件。该文件控制算法和硬件以产生最佳图像质量。libcamera 只能确定正在使用的传感器，而不能确定模块。因此，一些模块需要调整文件覆盖。使用参数 tuning-file 指定覆盖。你还可以复制和修改现有的调整文件以定制摄像头行为。

例如，传感器的无红外滤光片（NoIR）版本使用与标准版本不同的自动白平衡（AWB）设置。在树莓派 5 及更高版本上，你可以使用以下命令为 IMX219 传感器指定夜视红外调整文件：

注意
旧版树莓派型号使用其他的调整文件。在这些设备上，请改用 /usr/share/libcamera/ipa/rpi/vc4/ 中存储的文件。

libcamera 维护着多种摄像头的调整文件，包括第三方型号。例如，你可以在 se327m12.json 找到 Soho Enterprises SE327M12 的调整文件。

使用多个摄像头

rpicam-apps 对多个摄像头有基本支持。你可以通过以下方式将多个摄像头连接到树莓派：

对于树莓派计算模块，你可以直接连接两个摄像头到树莓派计算模块 I/O 板。有关详细信息，请参阅摄像头模块文档。使用此方法，你可以同时使用两个摄像头。
对于树莓派 5，你可以使用双 MIPI 连接器直接将两个摄像头连接到主板上。
对于带有摄像头接口的其余树莓派设备，你可以使用 Video Mux 板连接两个或更多摄像头，例如这种第三方产品。由于两个摄像头连接到单个 Unicam 端口，因此一次只能使用一个摄像头。

要列出平台上所有可用的摄像头，请使用参数 list-cameras。要选择要使用的摄像头，请将摄像头索引传参给参数 camera。

注意
libcamera 尚不支持立体摄像头。当同时运行两个摄像头时，它们必须在单独的进程中运行。这意味着它们之间没有同步传感器帧及 3A 操作的方法。一种解决方法是，你可以通过外部同步信号同步摄像头，对于 HQ（IMX477）摄像头，如果需要，就将 3A 切换到手动模式。

安装 libcamera 和 rpicam-apps

树莓派提供了两种 rpicam-apps 包：

rpicam-apps 包含完整的应用程序，支持使用桌面环境进行预览。此软件包已预装在树莓派系统中。
rpicam-apps-lite 不支持桌面环境，仅提供 DRM 预览。此软件包已预装在精简版树莓派系统中。

依赖关系

rpicam-apps 依赖于名为 library-名称<版本> 的库，其中 <版本> 是 ABI 版本。这些你的软件包管理器应能自动安装。

开发包

你可以重新构建 rpicam-apps 而无需从头开始构建 libcamera 和 libepoxy。有关更多信息，请参阅在不重新构建 libcamera 的情况下构建 rpicam-apps。

使用 `rpicam-apps` 在网络上进行视频流传输

本节说明了使用 rpicam-vid 进行本地流传输。你还可以使用 libav 后端进行网络流传输。

UDP

使用以下命令在树莓派作为服务器上通过 UDP 流式传输视频，把占位符 <IP地址> 换成客户端的 IP 地址（或组播地址），并把占位符 <端口> 换成你想要用于流式传输的端口：

使用以下命令在树莓派作为客户端上查看通过 UDP 流式传输的视频，替换 <端口> 占位符为你想要从中流式传输的端口：

或者，在客户端上使用以下命令来使用 ffplay 进行流媒体传输：

TCP

你还可以通过 TCP 进行视频流传输。要将树莓派用作服务器：

使用以下命令在树莓派作为客户端查看通过 TCP 流式传输的视频：

或者，在客户端使用以下命令以 30 帧每秒使用 ffplay 进行流式传输：

RTSP

使用以下命令将 VLC 用作服务器通过 RTSP 流式传输视频时，请使用树莓派：

使用以下命令将 VLC 用作客户端查看通过 RTSP 流式传输的视频时，请使用树莓派：

或者，使用以下命令在客户端上使用 VLC 进行流式传输：

在服务器上禁止预览窗口，请使用 nopreview。

使用参数 inline 强制将流头信息注入每个帧内，这有助于客户端了解流，即使它们错过了开头。

`libav`

你可以将 libav 后端用作音视频的网络流源。要使用树莓派作为服务器通过 TCP 流式传输视频，请使用以下命令，把占位符 <IP地址> 改成客户端的 IP 地址/组播地址，并把占位符 <端口> 改成要用于流式传输的端口：

你可以使用类似的命令通过 UDP 进行流式传输：

GStreamer

GStreamer 是用于读取、处理和播放多媒体文件的 Linux 框架。本节展示了如何使用 rpicam-vid 来通过网络进行视频流传输。

此设置使用 rpicam-vid 将编码的 h.264 比特流输出到标准输出。然后，我们使用 GStreamer fdsrc 元素接收比特流，并使用额外的 GStreamer 元素将其发送到网络上。在服务器上，运行以下命令以启动流，把占位符 <IP地址> 改为客户端的 IP 地址（或组播地址），并把占位符 <端口> 改为用于流式传输的端口：

在客户端上，运行以下命令以接收流，把占位符 <IP地址> 改成客户端的 IP 地址/组播地址，并将占位符 <端口> 改成用于流式传输的端口：

技巧
要测试此配置，请在同一设备的不同终端上运行服务器和客户端命令，使用 localhost 作为地址。

RTP

要使用 RTP 进行流媒体传输，请在服务器上运行以下命令，把占位符 <IP地址> 换成客户端的 IP 地址/组播地址，并把占位符 <端口> 换成要用于流媒体传输的端口：

要接收 RTP，请在客户端上运行以下命令，把占位符 <IP地址> 换为客户端的 IP 地址/组播地址，并把占位符 <端口> 换为要用于流媒体传输的端口：

如果客户端不是树莓派，则可能有不同的 GStreamer 元素可用。在运行 Linux 的 x86 设备上，你可能会运行以下命令：

libcamerasrc GStreamer 元素

libcamera 提供了一个 libcamerasrc GStreamer 元素，可以直接替代 rpicam-vid。要使用此元素，请在服务器上运行以下命令，把占位符 <IP地址> 换为客户端的 IP 地址/多播地址，并把占位符 <端口> 换为你希望用于流式传输的端口：

在客户端上，我们使用与以前相同的播放管道。

rpicam-apps 参数参考

常见参数

适用于所有具有相似/相同语义的 rpicam-apps 的以下参数，除非另有说明。

要将以下参数之一传参给应用程序，请在参数名称前加上 --。如果参数需要一个值，请在参数名称后立即传参该值，用单个空格分隔。如果值包含空格，请用引号括起来。

一些参数具有速记别名，例如 -h 可代替 --help。使用这些速记别名代替完整的参数名称，以节省空间和时间，但牺牲可读性。

`help`

别名： -h

打印完整的参数集，以及每个参数的简要概述。不接受值。

`version`

以字符串打印出 libcamera 和 rpicam-apps 的版本。不接受值。

示例输出：

`list-cameras`

列出连接到你的树莓派的检测到的摄像头及其可用的传感器模式。不接受值。

传感器模式标识符具有以下形式： S<Bayer order><Bit-depth>_<Optional packing> : <Resolution list>

在传感器阵列中，即使在像素合并模式下，裁剪也以本机传感器像素指定为(<x>, <y>)/<宽>×<高>。(x, y) 指定了传感器阵列中尺寸为宽 × 高的裁剪窗口的位置。

例如，以下输出显示有关索引为 0 处的 IMX219 传感器和索引为 1 处的 IMX477 传感器的信息：

对于上述示例中的 IMX219 传感器：

所有模式都具有 RGGB Bayer 排序
所有模式在所列分辨率上提供 8 位或 10 位 CSI2 打包读出

`camera`

选择要使用的摄像头。指定从可用摄像头列表中的索引。

`config`

别名： -c

指定包含命令行参数和值的文件。设想一个名为 example_configuration.txt 的文件，其中包含以下文本，将参数和值指定为键值对，每行一个参数，只使用长（非别名）参数名称：

技巧
省略通常在命令行上传参的 -- 开头。对于缺少值的标志，例如上面示例中的 verbose，必须包含尾随 =。

然后，你可以运行以下命令来指定超时时间为 99000 毫秒并输出详细信息：

`timeout`

别名： -t

默认值：5000 毫秒（5 秒）

指定应用程序在关闭之前运行的时间长度。这适用于视频录制和预览窗口。在捕获静态图像时，应用程序在捕获输出图像之前显示预览窗口 timeout（毫秒）。

要无限期运行应用程序，请指定值 0。

`preview`

别名： -p

设置桌面或 DRM 预览窗口的位置（x，y 坐标）和大小（w，h 尺寸）。不影响从摄像头请求的图像的分辨率或宽高比。将图像大小缩放并将图像宽高比裁剪或填充以适应预览窗口。

以以下逗号分隔的形式传参预览窗口尺寸： x,y,w,h

示例： rpicam-hello --preview 100,100,500,500

`fullscreen`

别名： -f

强制预览窗口使用整个屏幕，无边框或标题栏。调整图像大小并在整个屏幕内按比例缩放图像纵横比以适应。不接受值。

`qt-preview`

使用 Qt 预览窗口，消耗的资源比其他参数多，但支持 X 窗口转发。同参数 fullscreen 不兼容。不接受值。

`nopreview`

别名： -n

使应用程序不显示预览窗口。不接受值。

`info-text`

默认值："#%frame (%fps fps) exp %exp ag %ag dg %dg"

将提供的字符串设置为在桌面环境中运行时预览窗口的标题。支持以下图像元数据替换：

指令

意义

`width` 和 `height`

每个都接受一个定义为像素的捕获图像尺寸的单个数字。

对于 rpicam-still，rpicam-jpeg 和 rpicam-vid，指定输出分辨率。

对于 rpicam-raw，指定原始帧分辨率。对于具有 2×2 倍频读出模式的相机，指定分辨率等于或小于倍频模式的捕获 2×2 倍频原始帧。

对 rpicam-hello 无效。

示例：

rpicam-vid -o test.h264 --width 1920 --height 1080 拍摄 1080p 视频。
rpicam-still -r -o test.jpg --width 2028 --height 1520 拍摄 2028×1520 分辨率的 JPEG。如果与 HQ 相机一起使用，则使用 2×2 二次取样模式，因此原始文件（ test.dng ）包含 2028×1520 的原始 Bayer 图像。

`viewfinder-width` 和 `viewfinder-height`

每个都接受一个定义图像在预览窗口中显示的尺寸（以像素为单位）的单个数字。不影响预览窗口尺寸，因为图像会被调整大小以适应。不影响捕获的静止图像或视频。

`mode`

能让你用以下以冒号分隔的格式指定相机模式： <宽>:<高>:<位深度>:<打包参数>。如果提供的值没有完全匹配项，系统将选择最接近的可用参数以用于传感器。你可以使用打包（ P ）或未打包（ U ）的打包格式。影响存储的视频和静止图像的格式，但不影响传参到预览窗口的帧的格式。

位深度和打包是可选的。默认位深度为 12。默认打包为 P （打包）。

有关传感器可用的位深度、分辨率和打包参数的信息，请参阅 list-cameras。

例子：

4056:3040:12:P - 4056×3040 分辨率，每像素 12 位，打包。
1632:1224:10 - 1632×1224 分辨率，每像素 10 位。
2592:1944:10:U - 2592×1944 分辨率，每像素 10 位，未压缩。

打包格式详细信息

打包格式使用更少的存储空间来存储像素数据。

在树莓派 4 和早期设备上，打包格式使用 MIPI CSI-2 标准来打包像素。这意味着：

10 位相机模式将 4 个像素打包成 5 个字节。前 4 个字节包含每个像素的 8 个最高有效位（MSB），最后一个字节包含 4 对最低有效位（LSB）。
12 位相机模式将 2 个像素打包成 3 个字节。前 2 个字节包含每个像素的 8 个最高有效位（MSB），最后一个字节包含两个像素的 4 个最低有效位（LSB）。

在树莓派 5 及更高版本设备上，打包格式使用视觉无损压缩方案将像素值压缩为每像素 8 位（1 B）。

未打包格式详细信息

未打包格式提供的像素值更容易手动操作，但会以使用更多存储空间来存储像素数据为代价。

在所有设备上，未打包格式每像素使用 2 字节。

在树莓派 4 及旧款设备上，应用程序在最高有效端应用零填充。在未打包格式中，来自 10 位相机模式的像素不能超过值 1023。

在树莓派 5 和更新设备上，应用程序在最低有效端应用零填充，因此图像使用传感器提供的像素深度的完整 16 位动态范围。

`viewfinder-mode`

与 mode 参数相同，但它适用于传参到预览窗口的数据。有关更多信息，请参阅 mode 文档。

`lores-width` 和 `lores-height`

从摄像头传送第二个、分辨率较低的图像流，缩小到指定的尺寸。

每个都接受一个定义较低分辨率流的像素尺寸的数字。

可用于预览和视频模式。不适用于静态捕获。如果你指定与正常分辨率流不同的宽高比，则会生成非方形像素。

对于 rpicam-vid，可禁用额外的色彩去噪处理。

与图像后处理结合使用时，用于图像分析。

`hflip`

水平翻转图像。不接受值。

`vflip`

垂直翻转图像。不接受值。

`rotation`

旋转从传感器提取的图像。仅接受值 0 或 180。

`roi`

从传感器的整个场景中裁剪图像。接受四个小数值，范围为 0 到 1，格式如下： <x>,<y>,<宽>,<高>。这些值中的每一个代表可用宽度和高度的百分比，介于 0 和 1 之间的小数。

这些值定义了以下比例：

<x> ：提取图像前要跳过的 X 坐标
<y> ：提取图像前要跳过的 Y 坐标
<宽> ：要提取的图像宽度

默认为 0,0,1,1 （从第一个 X 坐标和第一个 Y 坐标开始，使用图像宽度的 100％，使用图像高度的 100％）。

示例：

rpicam-hello --roi 0.25,0.25,0.5,0.5 从图像中心裁剪出总像素数量的一半（跳过 X 坐标的前 25％，跳过 Y 坐标的前 25％，使用总图像宽度的 50％，使用总图像高度的 50％）。
rpicam-hello --roi 0,0,0.25,0.25 选择从图像左上角裁剪的像素总数的四分之一（跳过 X 坐标的前 0％，跳过 Y 坐标的前 0％，使用图像宽度的 25％，使用图像高度的 25％）。

`hdr`

默认值： off

以 HDR 模式运行相机。如果未传参值，则假定 auto。接受以下值之一：

off - 禁用 HDR。
auto - 在支持的设备上启用 HDR。如果可用，使用传感器的内置 HDR 模式。如果传感器缺乏内置 HDR 模式，则使用板载 HDR 模式（如果可用）。
single-exp - 使用板载 HDR 模式（如果可用），即使传感器具有内置 HDR 模式。如果板载 HDR 模式不可用，则禁用 HDR。

树莓派 5 及更高版本设备内置了 HDR 模式。

要检查传感器中的内置 HDR 模式，请在 list-cameras 中添加此参数。

摄像头控制参数

控制图像处理和影响相机图像质量的算法的参数。

`sharpness`

设置图像锐度。接受以下光谱范围内的数值：

0.0 不应用锐化。
大于 0.0 的值，但小于 1.0 的值应用比默认锐化量少的值
1.0

`contrast`

指定图像对比度。接受沿以下光谱的数值。

0.0 应用最小对比度
大于 0.0 但小于 1.0 的值应用少于默认对比度量。
1.0

`brightness`

指定图像亮度，作为输出图像中所有像素的偏移量。接受以下光谱范围内的数值。

-1.0 应用最低亮度（黑色）
0.0 应用标准亮度
1.0 应用最大亮度（白色）

对于许多用例，更喜欢 ev。

`saturation`

指定图像的颜色饱和度。接受沿以下光谱的数值：

0.0 应用最小饱和度（灰度）
大于 0.0 但小于 1.0 的值应用比默认饱和度少的量
1.0

`ev`

指定图像的曝光值（EV）补偿，以光圈为单位。接受一个数值，控制传参给自动曝光/增益控制（AEC/AGC）处理算法的目标值，沿以下光谱：

-10.0 应用最小目标值
0.0 应用标准目标值
10.0 应用最大目标值

`shutter`

使用快门指定曝光时间（以微秒为单位）。在使用此参数时，增益仍可能变化。如果相机以太快的帧速率运行，不允许指定的曝光时间（例如，帧速率为 1fps，曝光时间为 10000 微秒），则传感器将使用帧速率允许的最大曝光时间。

有关官方相机的最小和最大快门时间列表，请参阅相机硬件文档。超过最大值的数值会导致未定义行为。

`gain`

别名： --analoggain

设置组合模拟和数字增益。当传感器驱动程序可以提供请求的增益时，仅使用模拟增益。当模拟增益达到最大值时，ISP 应用数字增益。接受数值。

对于官方摄像头的模拟增益限制列表，请参阅摄像头硬件文档。

有时，数字增益可以超过 1.0，即使模拟增益限制没有超过。这可能发生在以下情况下：

任一颜色增益低于 1.0，这将导致数字增益稳定为 1.0/min(red_gain,blue_gain)。这可以保持应用于所有颜色通道的总数字增益高于 1.0，以避免出现变色伪影。
在自动曝光/增益控制（AEC/AGC）变化期间出现轻微差异。

`metering`

默认值: centre

设置自动曝光/增益控制（AEC/AGC）算法的测光模式。接受以下数值:

centre - 中央加权测光
spot - 点测光
average - 平均或整体测光

有关在树莓派相机和 libcamera 的调整指南中定义自定义测光模式和调整区域权重的更多信息。

`exposure`

设置曝光配置文件。更改曝光配置文件不应影响图像曝光。相反，不同模式会调整增益设置以实现相同的净结果。接受以下值：

sport ：短曝光，更大增益
normal ：正常曝光，正常增益
long ：长曝光，较小增益

你可以使用调整文件编辑曝光配置文件。有关更多信息，请参阅树莓派相机和 libcamera 的调整指南。

`awb`

设置自动白平衡（AWB）模式。接受以下数值：

模式名称

色温范围

这些值仅为近似值：根据相机调整，值可能会有所变化。

未设置模式会完全禁用 AWB。相反，你可以使用 awbgains 来固定颜色增益。

有关 AWB 模式的更多信息，包括如何定义自定义模式，请参阅树莓派摄像头和 libcamera 的调整指南。

`awbgains`

设置固定的红色和蓝色增益值，以替代自动白平衡（AWB）算法。设置非零值以禁用 AWB。接受以逗号分隔的数字输入，格式如下： <red_gain>,<blue_gain>

`denoise`

默认值： auto

设置去噪模式。接受以下数值：

auto ：启用标准空间去噪。视频使用超快速色彩去噪，图像使用高质量色彩去噪。在预览窗口中不启用额外的色彩去噪。
off ：禁用空间和颜色去噪。
cdn_off ：禁用颜色去噪。

即使快速彩色降噪也会降低帧率。高质量的彩色降噪会显著降低帧率。

`tuning-file`

指定相机调整文件。调整文件允许你控制图像处理的许多方面，包括自动曝光/增益控制（AEC/AGC）、自动白平衡（AWB）、颜色阴影校正、颜色处理、降噪等。接受调整文件路径作为输入。

有关调整文件的更多信息，请参阅调整文件。

`autofocus-mode`

默认值： default

指定自动对焦模式。接受以下值：

default ：除非 lens-position 或 autofocus-on-capture 覆盖手动模式，否则将相机置于连续自动对焦模式
manual ：除非使用 lens-position 手动配置，否则根本不移动镜头
auto ：仅当相机启动时或在捕获之前使用 autofocus-on-capture 时，镜头才会进行自动对焦扫描

该参数仅适用于某些摄像头模块。

`autofocus-window`

默认值： normal

指定自动对焦范围。接受以下数值：

normal ：从相当近的地方对焦到无限远
macro ：仅对近距离物体进行对焦，包括相机支持的最近对焦距离
full ：专注于整个范围，从最接近的物体到无限远

该参数仅适用于某些摄像头模块。

`autofocus-speed`

默认值： normal

指定自动对焦速度。接受以下值：

normal ：以正常速度改变镜头位置
fast ：快速改变镜头位置

该参数仅适用于某些摄像头模块。

`autofocus-range`

指定传感器全视场角内的自动对焦窗口。接受四个小数值，范围为 0 到 1，格式如下： <x>,<y>,<宽>,<高>。每个值代表可用宽度和高度的百分比，为 0 到 1 之间的小数。

这些值定义了以下比例：

<x> ：应用自动对焦前要跳过的 X 坐标
<y> ：应用自动对焦前要跳过的 Y 坐标
<宽> ：自动对焦区域宽度

默认值在两个维度上使用输出图像的中间三分之一（总图像面积的 1/9）。

例子：

rpicam-hello --autofocus-window 0.25,0.25,0.5,0.5 选择从图像中心裁剪的像素总数的一半（跳过 X 坐标的前 25%，跳过 Y 坐标的前 25%，使用总图像宽度的 50%，使用总图像高度的 50%）。
rpicam-hello --autofocus-window 0,0,0.25,0.25 选择从图像左上角裁剪的像素总数的四分之一（跳过 X 坐标的前 0%，跳过 Y 坐标的前 0%，使用图像宽度的 25%，使用图像高度的 25%）。

该参数仅适用于某些摄像头模块。

`lens-position`

默认值： default

将镜头移动到固定的焦距，通常以屈光度（米的倒数单位）表示。接受以下数值范围：

0.0 ：将镜头移动到“无穷远”位置
其他数值 ：将镜头移动到 1/ 其他数值位置。例如，数值 2.0 将对焦在大约 0.5m 处
default

镜头校准不完美，因此同一型号的不同相机模块可能会有所不同。

`verbose`

别名： -v

默认值： 1

设置详细级别。接受以下值：

0 ：无输出
1 ：正常输出
2 ：详细输出

输出文件参数

`output`

别名: -o

设置用于记录图像或视频的文件的名称。除了纯文本文件名外，还接受以下特殊值：

-：写入标准输出。
udp:// （前缀）：用于 UDP 流媒体的网络地址。
tcp:// （前缀）：用于 TCP 流媒体的网络地址。

例子：

rpicam-vid -t 100000 --segment 10000 -o chunk%04d.h264 记录一个 100 秒的文件，每 10 秒划分一个段，每个文件包含一个递增的四位数计数器，前面补零：例如 chunk0001.h264，chunk0002.h264 等。
rpicam-vid -t 0 --inline -o udp://192.168.1.13:5000 使用 UDP 在端口 5000 上将 H.264 视频流传输到网络地址 192.168.1.13。

`wrap`

为 output %d 指令使用的计数器设置最大值。计数器在达到此值后将重置为零。接受数值。

`flush`

在帧完成写入后立即将输出文件刷新到磁盘，而不是等待系统处理。不接受数值。

`post-process-file`

指定配置图像管道应用的后处理的 JSON 文件。这适用于相机图像在到达应用程序之前。这类似于旧版 raspicam“图像效果”。接受文件名路径作为输入。

后处理是一个广泛的主题，允许使用第三方软件如 OpenCV 和 TensorFlowLite 来分析和操作图像。有关更多信息，请参阅后处理。

图像参数

本节中指定的命令行参数仅适用于静态图像输出。

一些参数具有速记别名，例如 -h 而不是 --help。使用这些速记别名而不是完整的参数名称，以节省空间和时间，但牺牲可读性。

`quality`

别名： -q

默认值： 93

设置 JPEG 质量。接受介于 1 和 100 之间的值。

`exif`

在 JPEG 输出文件中保存额外的 EXIF 标签。仅适用于 JPEG 输出。由于 libexif 库的限制，许多标签当前（错误地）格式化为 ASCII 并在终端中打印警告。

此参数是添加与相机设置相关的某些 EXIF 标签所必需的。你可以在使用 ExifTool 录制后将与相机设置无关的标签添加到输出 JPEG 中。

示例： rpicam-still -o test.jpg --exif IDO0.Artist=Someone

`timelapse`

按指定间隔记录图像。接受以毫秒为单位的间隔。将此设置与 timeout 结合使用，以随时间捕获重复图像。

你可以使用字符串格式设置为每个输出文件指定单独的文件名，例如 --output test%d.jpg。

示例： rpicam-still -t 100000 -o test%d.jpg --timelapse 10000 每隔 10 秒捕获一次图像，持续 100 秒。

`framestart`

配置输出文件名中作为 %d 访问的帧计数的起始值。接受整数起始值。

`datetime`

在输出文件名中使用当前日期和时间，格式为 MMDDhhmmss.jpg ：

MM = 2 位数字月份编号
DD = 2 位数字的日期
hh = 2 位数字的 24 小时小时数

不接受值。

`timestamp`

使用当前系统 Unix 时间作为输出文件名。不接受值。

`restart`

默认值： 0

配置 JPEG 输出的重启标记间隔。JPEG 重启标记有助于限制对 JPEG 图像的损坏影响，并且还可以启用多线程 JPEG 编码和解码。接受整数值。

`immediate`

当应用程序运行时立即捕获图像。

`keypress`

在超时或按下 回车键 时捕获图像，以先发生者为准。按 x 键，然后按 回车键 可以退出而不捕获图像。此选项不接受值。

`signal`

在超时或收到 SIGUSR1 信号时捕获图像。使用 SIGUSR2 信号可以退出而不捕获图像。此选项不接受值。

`thumb`

默认值: 320:240:70

使用以下格式配置缩略图的尺寸和质量: <w:h:q> (或 none，省略缩略图)。

`encoding`

别名: -e

默认值： jpg

设置要用于图像输出的编码器。接受以下值：

jpg - JPEG
png - PNG
bmp - BMP

此参数始终确定编码，覆盖传参给 output 的扩展名。

在使用参数 datetime 和 timestamp 时，此参数确定输出文件扩展名。

`raw`

别名： -r

除了输出图像外，还以 DNG 格式保存原始 Bayer 文件。将输出文件名扩展名替换为 .dng。你可以使用 dcraw 或 RawTherapee 等工具处理这些标准 DNG 文件。不接受值。

原始文件中的图像数据完全是从传感器输出的，未经 ISP 或其他处理。文件中保存的 EXIF 数据包括：

曝光时间
模拟增益（ISO 标记是模拟增益的 100 倍）
白平衡增益（它们是“拍摄中性”值的倒数）
ISP 使用的颜色矩阵

`latest`

创建指向最近保存文件的符号链接。接受符号链接名称作为输入。

`autofocus-on-capture`

如果设置，会在捕获图像之前运行自动对焦循环。与以下 autofocus_mode 值交互：

default 或 manual ：仅运行捕获时自动对焦循环。
auto ：在预览窗口加载时运行额外的自动对焦循环。
continuous

不需要值，但你可以传参 1 以启用，传参 0 以禁用。不传参值相当于传参 1。

仅受某些摄像头模块支持（例如树莓派摄像头模块 3）。

视频参数

本节中指定的命令行参数仅适用于视频输出。

要将以下参数之一传参给应用程序，请在参数名称前加上 --。如果参数需要值，请在参数名称后立即传参值，用单个空格分隔。如果值包含空格，请用引号括起来。

一些参数具有速记别名，例如 -h 而不是 --help。使用这些速记别名而不是完整的参数名称，以节省空间和时间，但牺牲可读性。

`quality`

别名： -q

默认值： 50

接受介于 1 和 100 之间的 MJPEG 质量级别。仅适用于以 MJPEG 格式编码的视频。

`bitrate`

别名： -b

控制 H.264 编码器使用的目标比特率，单位为每秒比特数。仅适用于以 H.264 格式编码的视频。影响输出视频的大小。

例子： rpicam-vid -b 10000000 --width 1920 --height 1080 -o test.h264

`intra`

别名： -g

默认值： 60

设置 H.264 比特流中 I 帧（intra frames）的频率。接受帧数。仅适用于以 H.264 格式编码的视频。

`profile`

设置 H.264 配置文件。接受以下数值：

baseline
main
high

仅适用于以 H.264 格式编码的视频。

`level`

设置 H.264 级别。接受以下数值：

4
4.1
4.2

仅适用于以 H.264 格式编码的视频。

`codec`

设置用于视频输出的编码器。接受以下值：

h264 - 使用 H.264 编码器（默认值）
mjpeg - 使用 MJPEG 编码器
yuv420 - 输出未压缩的 YUV420 帧。

`save-pts`

警告
树莓派 5 不支持参数 save-pts 。请改用 libav 自动生成时间戳以替代。

启用帧时间戳输出，允许你使用类似 mkvmerge 的工具将比特流转换为容器格式。接受时间戳输出文件的纯文本文件名。

示例： rpicam-vid -o test.h264 --save-pts timestamps.txt

你可以使用以下命令从比特流和时间戳文件生成一个 MKV 容器文件：

`keypress`

别名： -k

允许 CLI 使用回车键启用和禁用视频输出。始终以录制状态启动，除非使用 initial 另行指定。键入 x 键 并按 回车键 退出。不接受值。

`signal`

别名： -s

允许 CLI 使用 SIGUSR1 启用和禁用视频输出。使用 SIGUSR2 退出。除非使用 initial 指定，始终以录制状态启动。不接受值。

`initial`

默认值： record

指定是否启动应用程序时启用或禁用视频输出。接受以下值：

record ：启用视频输出启动。
pause ：禁用视频输出启动。

使用此参数与 keypress/signal 一起，以在两种状态之间切换。

`split`

当使用 keypress、signal 切换录制时，将来自单独录制会话的视频输出写入单独的文件中。不接受值。除非与 output 结合使用以为每个文件指定唯一名称，否则每次写入文件时都会覆盖。

`segment`

将视频输出剪切成传参持续时间的多个文件。接受以毫秒为单位的持续时间。如果传参一个非常小的持续时间（例如，1 ），则将每帧记录到单独的输出文件中以模拟突发捕获。

你可以使用字符串格式化为每个文件指定单独的文件名，例如 --output test%04d.h264。

`circular`

默认值： 4

将视频录制写入内存中的循环缓冲区。当应用程序退出时，将循环缓冲区记录到磁盘。可接受以 MB 为单位的可选大小。

`inline`

在每个 I 帧（帧内）中写入序列头。这可以帮助客户端从视频的任何点解码视频序列，而不仅仅是从开头。建议与 segment，split，circular 和流媒体参数一起使用。

仅适用于以 H.264 格式编码的视频。不接受值。

`listen`

在对视频进行编码之前等待传入的客户端连接。用于通过 TCP/IP 进行网络流式传输。不接受值。

`frames`

记录完全指定数量的帧。任何非零值都会覆盖 timeout。接受非零整数。

`framerate`

记录完全指定的帧速率。接受非零整数。

`libav` 参数

本节中指定的命令行参数仅适用于 libav 视频后端。

要启用 libav 后端，请传参 codec 参数值为 libav。

一些参数具有速记别名，例如 -h 而不是 --help。使用这些速记别名而不是完整的参数名称，以节省空间和时间，但牺牲可读性。

`libav-format`

设置 libav 输出格式。接受以下值：

mkv 编码
mp4 编码
avi 编码

如果你未提供此参数，则传参给 output 参数的文件扩展名将确定文件格式。

`libav-audio`

启用音频录制。启用后，你还必须指定 audio-codec。不接受值。

`audio-codec`

默认值： aac

选择用于输出的音频编解码器。要查看可用编解码器的列表，请运行 ffmpeg -codecs。

`audio-bitrate`

设置音频编码的比特率，单位为每秒比特数。接受数字输入。

示例： rpicam-vid --codec libav -o test.mp4 --audio_codec mp2 --audio-bitrate 16384 （以 mp2 编解码器以 16 千位/秒记录音频）

`audio-samplerate`

默认值： 0

设置音频采样率（单位 Hz）。接受数字输入。0 使用输入采样率。

`audio-device`

为音频录制选择一个 ALSA 输入设备。要查看可用设备的列表，请运行以下命令：

你应该看到类似以下内容的输出：

`av-sync`

将音频样本时间戳按微秒值移动。接受正数和负数数值。

检测参数

本节中指定的命令行参数仅适用于使用 rpicam-detect 进行目标检测。

要将以下参数之一传参给 rpicam-detect，请在参数名称前加上 --。如果参数需要一个值，请在参数名称后立即传参该值，用单个空格分隔。如果值包含空格，请用引号括起来。

一些参数具有速记别名，例如 -h 而不是 --help。请使用这些速记别名，以节省空间和时间，但牺牲可读性。

`object`

从模型的标签文件中检测具有给定名称的对象。接受纯文本文件名作为输入。

`gap`

在捕获之间至少等待这么多帧。接受数值。

使用 `rpicam-apps` 进行后处理

rpicam-apps 共享一个通用的后处理框架。这使它们能够通过一系列自定义图像处理和图像分析例程传参从相机系统接收到的图像。每个这样的例程被称为一个阶段。要运行后处理阶段，请提供一个 JSON 文件，指示应用程序应用哪些阶段和参数。你可以在 rpicam-apps 存储库的 assets 文件夹中找到使用内置后处理阶段的示例 JSON 文件。

例如，否定阶段将亮像素变暗，暗像素变亮。由于否定阶段是基本的，不需要配置，negate.json 只是命名该阶段：

要将否定阶段应用于图像，请将 negate.json 传参给 post-process-file 参数：

要运行多个后处理阶段，请创建一个包含多个阶段作为顶级键的 JSON 文件。例如，以下配置运行 Sobel 阶段，然后是否定阶段：

Sobel 阶段使用 OpenCV，因此具有 cv 后缀。它具有一个可由用户配置的参数，ksize，指定要使用的滤波器的内核大小。在这种情况下，Sobel 滤波器在黑色背景上产生明亮边缘，否定阶段将其转换为白色背景上的暗边缘。

一个否定的 Sobel 滤波器。

一些阶段，如 negate，以某种方式改变图像。其他阶段分析图像以生成元数据。后处理阶段可以将此元数据传参给其他阶段甚至应用程序。

为了提高性能，图像分析通常使用降低的分辨率。rpicam-apps 直接从 ISP 提供专用的低分辨率馈送。

注意
使用树莓派系统附带的 rpicam-apps 未包含 OpenCV 和 TensorFlow Lite。因此，依赖于它们的某些后处理阶段被禁用。要使用这些阶段，请重新编译 rpicam-apps。在运行 32 位内核的树莓派 3、4 上，使用参数 -DENABLE_COMPILE_FLAGS_FOR_TARGET=armv8-neon 进行编译能加快某些阶段的速度。

内置阶段

negate 阶段

此阶段将亮像素变暗，暗像素变亮。

negate 阶段没有用户可配置的参数。

默认的 negate.json 文件：

运行以下命令以在 rpicam-hello 中使用此阶段文件：

示例输出：

一个否定的图像。

hdr 阶段

本阶段强调使用高动态范围（HDR）和动态范围压缩（DRC）来突出图像中的细节。DRC 使用单个图像，而 HDR 结合多个图像以获得类似的结果。

参数分为三组：LP 滤波器、全局色调映射和局部对比度。

该阶段对完全处理过的输入图像应用平滑滤波器，生成低通（LP）图像。然后从原始图像和 LP 图像的差异中生成高通（HP）图像。然后，对 LP 图像应用全局色调映射，并将其添加回 HP 图像。该过程有助于保留局部对比度。

你可以使用以下参数配置此阶段：

| num_frames | 累积帧数；对于 DRC，请使用 1；对于 HDR，请尝试 8| | | :--: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | lp_filter_strength| 低通 IIR 滤波器的系数。 | |lp_filter_threshold| 将像素级别与有意义细节的阈值相关联的分段线性函数。 | |global_tonemap_points| 输入图像直方图中的点映射到输出范围中的目标，我们希望将它们移动到那里。使用以下子配置：<br /> 一个在q和width之间的分位均值，作为完整输出范围的一部分（target），最大（max_up）和最小（max_down）增益，用于移动测量的分位均值，以防止图像变化过于剧烈 | |

控制处理强度，更改 global_tonemap_strength 和 local_tonemap_strength 参数。

在树莓派 4 上，处理单个图像需要 2 到 3 秒的时间。在累积多个帧时，此阶段仅将处理后的图像发送到应用程序。

DRC 的默认 drc.json 文件：

示例：

没有 DRC 处理的图像

运行以下命令以在 rpicam-still 中使用此阶段文件

DRC 处理过的图像

HDR 的默认 hdr.json 文件：

例子:

没有 HDR 处理的图像

运行以下命令以在 rpicam-still 中使用此阶段文件：

带有 HDR 处理的图像

`motion_detect` 阶段

motion_detect 阶段分析来自低分辨率图像流的帧。你必须配置低分辨率流以使用此阶段。该阶段通过比较帧中感兴趣区域（ROI）与先前帧中相应部分来检测运动。如果帧之间的像素变化足够多，此阶段将在元数据下的 motion_detect.result 键中指示运动。

此阶段不依赖第三方库。

你可以使用以下参数配置此阶段，将尺寸传参为低分辨率图像尺寸的比例，介于 0 和 1 之间：

默认 motion_detect.json 配置文件：

调整差异和阈值，使算法更加敏感或不那么敏感。为了提高性能，请使用参数 hskip 和 vskip。

运行以下命令以使用此阶段文件与 rpicam-hello：

使用 OpenCV 进行后期处理

注意
这些阶段需要安装 OpenCV。你可能需要重新构建带有 OpenCV 支持的 rpicam-apps。

sobel_cv 阶段

该阶段将 Sobel 滤波器应用于图像，以突出边缘。

你可以使用以下参数配置此阶段：

默认 sobel_cv.json 文件：

例子：

使用 Sobel 滤波器来强调边缘。

face_detect_cv 阶段

此阶段使用 OpenCV Haar 分类器来检测图像中的人脸。它返回人脸位置元数据，键为 face_detect.results，并可选择在图像上绘制位置。

你可以使用以下参数配置此阶段：

face_detect_cv 阶段仅在预览和视频捕获期间运行。它会忽略静态图像捕获。它在分辨率为 320×240 和 640×480 像素之间的低分辨率流上运行。

默认 face_detect_cv.json 文件:

示例：

在图像上检测到的面部绘制。

`annotate_cv` 阶段

该阶段使用与 info-text 参数相同的 % 替换，将文本写入图像的右上角。

首先解释指令 info-text ，然后将剩余的标记传参给 strftime。

例如，要在视频上实现日期时间戳，请传参 %F %T %z ：

%F 显示 ISO-8601 日期 (2023-03-07)
%T 显示 24 小时本地时间 (例如 "09:57:12")
%z 显示相对于 UTC 的时区 (例如 "-0800")

此阶段不会输出任何元数据，但会将在 JSON 配置文件中找到的元数据写入 annotate.text 的位置。这样，其他后处理阶段就可以将文本写入图像。

你可以使用以下参数配置此阶段：

默认 annotate_cv.json 文件:

示例：

使用注释将相机和日期信息写入图像。

使用 TensorFlow Lite 进行后处理。

先决条件

这些阶段需要导出 C++ API 的 TensorFlow Lite（TFLite）库。TFLite 不以这种形式分发库，但你可以从 lindevs.com 下载并安装一个导出 API 的版本。

安装后，你必须重新编译 rpicam-apps 以支持 TensorFlow Lite。

`object_classify_tf` 阶段

下载：

object_classify_tf 使用 Google MobileNet v1 模型对摄像头图像中的对象进行分类。此阶段需要一个 labels.txt 文件。

你可以使用以下参数配置此阶段：

示例 object_classify_tf.json 文件：

舞台使用尺寸为 224×224 的低分辨率流图像。运行以下命令以使用此舞台文件与 rpicam-hello ：

桌面电脑和显示器的对象分类。

`pose_estimation_tf` 阶段

下载：

pose_estimation_tf 使用 Google MobileNet v1 模型来检测姿势信息。

你可以使用以下参数配置此阶段：

使用单独的 plot_pose_cv 阶段将检测到的姿势绘制到主图像上。

你可以使用以下参数配置 plot_pose_cv 阶段：

示例 pose_estimation_tf.json 文件：

该阶段在尺寸为 257×257 的低分辨率流图像上运行。因为 YUV420 图像必须具有偶数尺寸，所以对于 YUV420 图像，将尺寸四舍五入为 258×258。

运行以下命令以在 rpicam-hello 中使用此阶段文件：

成年男性人体姿势检测。

`object_detect_tf` 阶段

下载:

object_detect_tf 使用 Google MobileNet v1 SSD（Single Shot Detector）模型来检测和标记对象。

你可以使用以下参数配置此阶段：

使用单独的 object_detect_draw_cv 阶段将检测到的对象绘制到主图像上。

你可以使用以下参数配置 object_detect_draw_cv 阶段：

示例 object_detect_tf.json 文件：

舞台在尺寸为 300×300 的低分辨率流图像上运行。运行以下命令，从尺寸为 400×300 的低分辨率图像中心传参一个 300×300 的裁剪到检测器，以使用此舞台文件与 rpicam-hello ：

检测对象为苹果和猫。

`segmentation_tf` 阶段

下载：https://tfhub.dev/tensorflow/lite-model/deeplabv3/1/metadata/2?lite-format=tflite

segmentation_tf 使用 Google MobileNet v1 模型。此阶段需要一个标签文件，在 assets/segmentation_labels.txt 处找到。

此阶段在尺寸为 257×257 的图像上运行。因为 YUV420 图像必须具有偶数尺寸，所以低分辨率图像的宽度和高度至少应为 258 像素。该阶段向图像元数据添加一个包含 257×257 个值的向量，其中每个值表示像素所属的类别。你可以选择在图像的右下角绘制分割的表示。

你可以使用以下参数配置此阶段：

示例 segmentation_tf.json 文件：

此示例将摄像头图像缩小至 258×258 像素。即使压缩非方形图像而无需裁剪，此阶段也能正常工作。此示例在右下角启用分割地图。

运行以下命令以使用此阶段文件与 rpicam-hello：

在地图的右下角运行分割并显示结果。

编写自己的后处理阶段

使用 rpicam-apps 后处理框架，用户可以创建自己的自定义后处理阶段。甚至可以包括来自 OpenCV 和 TensorFlow Lite 的算法和例程。

基本的后处理阶段

要创建自己的后处理阶段，请从 PostProcessingStage 类派生一个新类。所有后处理阶段必须实现以下成员函数：

char const *Name() const 返回阶段的名称。与 JSON 后处理配置文件中列出的阶段进行匹配。

void Read(boost::property_tree::ptree const &params) 从提供的 JSON 文件中读取阶段的配置参数。

void AdjustConfig(std::string const &use_case, StreamConfiguration *config) 为阶段提供影响相机配置的机会。对于不需要配置相机的阶段，通常为空。

void Configure() 在相机配置完成后调用，以分配资源并检查阶段是否可以访问必要的流。

void Start() 当摄像头启动时调用。对于不需要配置摄像头的阶段通常为空。

bool Process(CompletedRequest &completed_request) 展示已完成的摄像头请求以供后期处理。这是你将实现像素操作和图像分析的地方。如果后期处理框架不应将此请求传参给应用程序，则返回 true。

void Stop() 当摄像头停止时调用。用于关闭异步线程上的全部活动处理。

当相机配置被销毁时调用 void Teardown()。将其用作析构函数，在其中可以释放在 Configure 方法中设置的资源。

在所有阶段实现中，调用 RegisterStage 来向系统注册你的阶段。

不要忘记将你的阶段也添加到后处理文件夹的 CMakeLists.txt 中！

写自己的阶段时，请记住以下提示：

Process 方法会阻塞成像管道。如果花费的时间太长，管道会出现卡顿。始终将耗时算法委托给异步线程。
将工作委托给另一个线程时，必须复制图像缓冲区。对于像图像分析这样不需要全分辨率的应用程序，尝试使用低分辨率图像流。
后处理框架使用并行处理每一帧。这提高了吞吐量。然而，一些 OpenCV 和 TensorFlow Lite 函数在每一帧内引入了另一层并行性。考虑在每一帧内序列化调用，因为后处理已经利用了多个线程。

对于一个基本示例，请参见 negate_stage.cpp。这个阶段通过将亮像素变暗和暗像素变亮来否定图像。这个阶段主要是派生类样板，仅用几行代码实现否定逻辑。

对于另一个示例，请参见 sobel_cv_stage.cpp，它仅使用几行 OpenCV 函数实现了 Sobel 滤波器。

TensorFlow Lite 阶段

对于使用 TensorFlow Lite (TFLite) 的阶段，请从 TfStage 类派生一个新类。该类将模型执行委托给单独的线程，以防止相机出现卡顿。

TfStage 类实现了所有后处理阶段通常必须实现的成员函数，除了 Name。所有派生自 TfStage 的阶段必须实现 Name 函数，并应实现以下一个或多个虚拟成员函数：

void readExtras() 基类读取命名模型和诸如 refresh_rate 之类的某些其他参数。使用此函数读取派生阶段的额外参数，并检查加载的模型是否正确（例如，具有正确的输入和输出维度）。

void checkConfiguration() 基类获取 TFLite 操作的低分辨率流和派生阶段需要的完整分辨率流。使用此函数检查你的阶段所需的流。如果你的阶段无法访问所需的流之一，则可能会跳过处理或引发错误。

void interpretOutputs() 使用此函数读取和解释模型输出。在模型完成时与模型在同一线程中运行。

void applyResults() 使用此函数将模型的结果（可能是几帧旧的）应用于当前帧。通常涉及附加元数据或绘图。在交付帧之前在主线程中运行。

有关示例实现，请参见 object_classify_tf_stage.cpp 和 pose_estimation_tf_stage.cpp。

高级 `rpicam-apps`

构建 `libcamera` 和 `rpicam-apps`

为自己构建 libcamera 和 rpicam-apps 以获得以下好处：

你可以获取最新的增强功能和特性。
rpicam-apps 可以针对运行 32 位操作系统的树莓派 3 和树莓派 4 设备进行额外优化编译。
你可以包括可选的 OpenCV 和/或 TFLite 后处理阶段，或添加你自己的内容。

构建 `rpicam-apps` 而不构建 `libcamera`。

要构建 rpicam-apps 而不必先重新构建 libcamera 和 libepoxy，请使用 apt 安装 libcamera、libepoxy 及其依赖项：

技巧
如果你不需要支持 GLES/EGL 预览窗口，请省略 libepoxy-dev。

要使用 Qt 预览窗口，请安装以下附加依赖项：

为了在树莓派系统中支持 libav，请安装以下附加依赖项：

如果你使用精简版树莓派系统，请安装 git ：

接下来，构建 rpicam-apps。

构建 libcamera

注意
请仅在你需要定制行为或最新功能尚未进入 apt 存储库时，才从头开始构建 libcamera。

首先，安装以下 libcamera 依赖项：

现在我们准备构建 libcamera 本身。

从 GitHub 下载树莓派的 libcamera 本地副本：

切换到存储库的根目录：

接下来，运行 meson 来配置构建环境：

注意
在 meson 构建配置期间，你可以通过将 -Dgstreamer=enabled 替换为 -Dgstreamer=disabled 来禁用 gstreamer 插件。如果禁用 gstreamer，则无需安装 libglib2.0-dev 和 libgstreamer-plugins-base1.0-dev 依赖项。

现在，你可以使用 ninja 构建 libcamera：

最后，运行以下命令安装你刚构建的 libcamera 二进制文件：

技巧
在内存小于 1GB 的设备上，构建过程可能超出可用内存。应在 ninja 命令中添加参数 -j 1 将构建限制为单个进程。这应该可以防止在树莓派 Zero 和树莓派 3 等设备上溢出可用内存。

libcamera 尚未具有稳定的二进制接口。始终在构建 libcamera 之后构建 rpicam-apps。

构建 `rpicam-apps`

首先获取 rpicam-apps 的必要依赖项。

下载树莓派的 rpicam-apps GitHub 存储库的本地副本：

切换到存储库的根目录：

对于像树莓派系统这样的基于桌面的操作系统，使用以下 meson 命令配置 rpicam-apps 构建：

对于像精简版树莓派系统这样的无头操作系统，使用以下 meson 命令配置 rpicam-apps 构建：

技巧
使用 -Dneon_flags=armv8-neon 来启用树莓派 3 或树莓派 4 上 32 位操作系统的优化。如果已安装 OpenCV 并希望使用基于 OpenCV 的后处理阶段，请使用 -Denable_opencv=enabled。如果已安装 TensorFlow Lite 并希望在后处理阶段中使用它，请使用 -Denable_tflite=enabled。

现在可以使用以下命令构建 rpicam-apps：

技巧
在内存为 1GB 或更小的设备上，编译可能会溢出可用内存。请在 meson 命令中附加参数 -j 1，将构建限制为单个进程。这应该可以防止在设备上如树莓派 Zero 和树莓派 3 上超出可用内存。最后，运行以下命令安装你新构建的 rpicam-apps 二进制文件：

安装后打开一个新的终端窗口，以确保你使用新的二进制文件。

最后，在“配置”部分遵循 dtoverlay 和显示驱动程序说明。

rpicam-apps 墨森标志参考

meson 构建配置支持以下标志：

-Dneon_flags=armv8-neon 在运行 32 位操作系统的树莓派 3、4 设备上加快某些后处理功能。

-Denable_libav=enabled 启用/禁用 libav 编码器集成。

-Denable_drm=enabled 启用/禁用 DRM/KMS 预览渲染，这是在没有桌面环境的情况下使用的预览窗口。

-Denable_egl=enabled 启用/禁用非 Qt 桌面环境的预览。如果你的系统缺少桌面环境，请禁用。

-Denable_qt=enabled 启用/禁用对预览窗口的基于 Qt 的实现的支持。如果未安装桌面环境或者不打算使用基于 Qt 的预览窗口，则禁用它。通常不推荐使用基于 Qt 的预览，因为它在计算上非常昂贵，但它可以与 X 显示转发一起使用。

-Denable_opencv=enabled 强制 OpenCV 基于的后处理阶段链接或不链接。需要启用 OpenCV。默认为 disabled。

-Denable_tflite=enabled 启用或禁用 TensorFlow Lite 后处理阶段。默认情况下禁用。需要启用 Tensorflow Lite。根据你构建和/或安装 TFLite 的方式，你可能需要调整 post_processing_stages 目录中的文件 meson.build 。

以上参数中的每个参数（ neon_flags 除外）支持以下值：

enabled ：启用该参数，如果依赖项不可用，则构建失败
disabled ：禁用该参数
auto ：如果有依赖项可用，则启用该参数

构建 `libepoxy`

通常情况下不应重新构建 libepoxy，因为此库很少更改。但是，如果确实要从头构建它，请按照以下说明操作。

从安装必要的依赖项开始。

接下来，从 GitHub 下载 libepoxy 存储库的本地副本：

切换到存储库的根目录：

在存储库的根目录创建一个构建目录，然后进入该目录：

接下来，运行 meson 以配置构建环境：

现在，你可以使用 ninja 构建 libexpoxy ：

最后，运行以下命令安装你新构建的 libepoxy 二进制文件：

编写你自己的 rpicam 应用程序

rpicam-apps 并未提供所有摄像头相关功能，所有人都可能需要。相反，这些应用程序体积小巧灵活。需要不同行为的用户可以自行实现。

所有的 rpicam-apps 使用一个事件循环，当从摄像头系统接收到一组新的帧时会收到消息。这组帧被称为 CompletedRequest。这个 CompletedRequest 包含：

所有从单个摄像头帧派生的图像：通常是低分辨率图像和全尺寸输出
来自摄像头和后处理系统的元数据

`rpicam-hello`

rpicam-hello 是最小的应用程序，也是理解 rpicam-apps 设计的最佳起点。它从消息中提取 CompletedRequestPtr，一个指向 CompletedRequest 的共享指针，并将其转发到预览窗口：

每个 CompletedRequest 必须被回收到摄像头系统，以便缓冲区可以被重用。否则，摄像头会因为没有新的摄像头帧的缓冲区而耗尽。当不再有引用使用 C++ 的共享指针和自定义删除器机制时，这个回收过程会自动发生。

因此，rpicam-hello 必须完成以下操作以回收缓冲区空间：

事件循环必须完成一个周期，以便消息（代码中的 msg ），其中保存对 CompletedRequest 的引用，可以被下一条消息替换。这会丢弃对上一条消息的引用。
当事件线程调用 ShowPreview 时，它会向预览线程传参对 CompletedRequest 的引用。每次调用 ShowPreview 时，预览线程都会丢弃上一个 CompletedRequest 实例。

`rpicam-vid`

rpicam-vid 类似于 rpicam-hello，在事件循环中添加了编码。在事件循环开始之前，rpicam-vid 会使用回调函数配置编码器。回调函数处理包含编码图像数据的缓冲区。在下面的代码中，我们将缓冲区发送到 Output 对象。Output 可以根据指定的参数将其写入文件或流式传输。

因为此代码向编码器传参了对 CompletedRequest 的引用，所以 rpicam-vid 直到事件循环、预览窗口和编码器都丢弃它们的引用之前，无法回收缓冲区数据。

`rpicam-raw`

rpicam-raw 类似于 rpicam-vid。它也在事件循环中进行编码。然而，rpicam-raw 使用了一个名为 NullEncoder 的虚拟编码器。它将输入图像用作输出缓冲区，而不是使用编解码器对其进行编码。NullEncoder 仅在输出回调完成后丢弃对缓冲区的引用。这确保在回调处理图像之前不会回收缓冲区。

rpicam-raw 不会将任何内容转发到预览窗口。

NullEncoder 在 rpicam-raw 可能过度。我们可能直接将图像发送到 Output 对象，而不是。但是，rpicam-apps 需要限制事件循环中的工作。NullEncoder 演示了如何在其他线程中处理大多数进程（甚至保持引用）。

`rpicam-jpeg`

rpicam-jpeg 以通常方式启动预览模式中的相机。计时器完成时，它会停止预览并切换到静态捕获：

事件循环从静态模式返回的第一帧并将其保存为 JPEG。

使用 `libcamera` 与 Qt

Qt 是一种流行的应用程序框架和 GUI 工具包。rpicam-apps 包括一个参数，可以在相机预览窗口中使用 Qt。

不幸的是，Qt 在全局命名空间中将某些符号（如 slot 和 emit）定义为宏。这会导致包含 libcamera 文件时出错。这个问题在所有同时使用 Qt 和 libcamera 的平台上都很常见。尝试以下解决方法以避免这些错误：

尽可能在全部情况下在 Qt 头文件之前列出 libcamera 包含文件，或包含 libcamera 文件的文件（如 rpicam-apps 文件）。
如果确实需要将 Qt 应用程序文件与 libcamera 包含混合在一起，请用 Q_SIGNALS: 替换 signals:，用 Q_SLOTS:

使用 Python 与 Picamera2 一道使用 libcamera

Picamera2 库是基于 rpicam 的替代品，用于取代 Picamera，后者是 Python 接口，用于树莓派的旧版摄像头堆栈。Picamera2 提供了易于使用的 Python API。

有关 Picamera2 的文档可在 GitHub 和 Picamera2 手册中找到。

安装

最近的树莓派系统镜像包含了 Picamera2 以及所有 GUI（Qt 和 OpenGL）依赖项。最近的精简版树莓派系统镜像包含了 Picamera2 但不包含 GUI 依赖项，尽管可以使用 DRM/KMS 来显示预览图像。

如果你的镜像不包含 Picamera2，请运行以下命令安装包含所有 GUI 依赖项的 Picamera2：

如果你不想要 GUI 依赖项，可以运行以下命令安装 Picamera2 而不安装 GUI 依赖项：

注意
如果你之前使用 pip 安装了 Picamera2，请使用以下命令卸载： pip3 uninstall picamera2。

使用 USB 摄像头

大多数树莓派设备都有专用端口用于摄像头模块。摄像头模块是高质量、高度可配置的摄像头，深受树莓派用户喜爱。

然而，对于许多用途，USB 网络摄像头具备你从树莓派记录图片和视频所需的一切。本节将解释如何在树莓派上使用 USB 网络摄像头。

安装依赖项

首先，安装 fswebcam 软件包：

接下来，将你的用户名添加到 video 组，否则你可能会看到“权限被拒绝”错误：

要检查用户是否已正确添加到组中，请使用命令 groups 。

拍照

运行以下命令使用网络摄像头拍照并将图像保存到名为 image.jpg 的文件中：

你应该看到类似以下内容的输出：

默认情况下，fswebcam 使用低分辨率，并添加显示时间戳的横幅。

要为捕获的图像指定不同的分辨率，请使用参数 -r，传参宽度和高度作为两个由 x 分隔的数字：

你应该看到类似以下输出：

指定分辨率以捕获更高质量的图像。

删除横幅

要从捕获的图像中删除横幅，请使用参数 --no-banner：

你应该看到类似以下内容的输出：

指定 --no-banner 以保存图像而不带有时间戳横幅。

自动化图像捕获

与 rpicam-apps 不同，fswebcam 没有内置什么功能来替换输出图像名称中的时间戳和数字。在捕获多个图像时，手动编辑文件名可能会很繁琐。相反，使用 Bash 脚本来实现这个功能。

在你的主文件夹中创建一个名为 webcam.sh 的新文件。添加以下示例代码，该代码使用 bash 编程语言将图像保存到文件中，文件名包含年、月、日、小时、分钟和秒：

然后，通过运行以下命令使 bash 脚本可执行：

使用以下命令运行脚本，捕获图像并将其保存到带有时间戳名称的文件中，类似于 2024-05-10_12-06-33.jpg:

你应该看到类似以下内容的输出:

捕获时间间隔

使用 cron 来安排照片捕捉以给定间隔。通过正确的间隔，比如每分钟一次，你可以捕捉一个延时摄影。

首先，打开用于编辑的 cron 表：

请你在编辑器中打开文件，添加以下行到计划中，每分钟拍照一次，用你的用户名替换 <用户名> ：

保存并退出，然后你应该看到以下消息：

V4L2 驱动程序

V4L2 驱动程序为访问摄像头和编解码器功能提供了标准的 Linux 接口。通常，Linux 在启动时会自动加载驱动程序。但在某些情况下，你可能需要显式加载摄像头驱动程序。

使用 libcamera 时的设备节点

使用 V4L2 驱动程序

有关如何使用 V4L2 驱动程序的更多信息，请参阅 V4L2 文档。

Unicam

树莓派 SoC 都有两个相机接口，支持 CSI-2 D-PHY 1.1 或紧凑相机端口 2（CCP2）源。该接口以代号 Unicam 而闻名。第一个 Unicam 实例支持两个 CSI-2 数据通道，而第二个支持四个。每个通道最高可运行速度为 1Gbit/s（DDR，因此最大链路频率为 500MHz）。

计算模块和树莓派 5 都将两个外设的所有通道路由出去。在树莓派 5 之前的其他型号只暴露第二个实例，只将两个数据通道路由到相机连接器。

软件接口

V4L2 软件接口是与 Unicam 外围设备通信的唯一方式。曾经还有固件和 MMAL rawcam 组件接口，但这些已不再受支持。

V4L2

注意
仅在使用 libcamera 时，Unicam 的 V4L2 接口可用。

为 Unicam 块提供了一个完全开源的内核驱动程序；这个内核模块，称为 bcm2835-unicam，与 V4L2 子设备驱动程序进行交互，传参原始帧。这个 bcm2835-unicam 驱动程序控制传感器并配置摄像头串行接口 2（CSI-2）接收器。外围设备将原始帧（经过 Debayer 处理）写入 SDRAM，以便 V4L2 传参给应用程序。在摄像头传感器捕获图像和 bcm2835-unicam 驱动程序将图像数据放入 SDRAM 之间，除了 Bayer 解包到 16 位/像素之外，没有图像处理。

主线 Linux 包含一系列现有驱动程序。树莓派内核树具有一些额外的驱动程序和设备树叠加，用于配置它们：

设备

类型

解释

由于子设备驱动程序也是具有标准化 API 的内核驱动程序，第三方可以自由地为他们选择的来源编写自己的驱动程序。

编写第三方驱动程序

这是通过 Unicam 进行接口的推荐方法。

当为打算与 bcm2835-unicam 模块一起使用的新设备开发驱动程序时，你需要驱动程序和相应的设备树叠加。理想情况下，应将驱动程序提交给 linux-media 邮件列表进行代码审查和合并到主线，然后移至内核树；但也可以对直接将驱动程序进行审查和合并到树莓派内核做出例外。

注意
所有内核驱动程序均在 GPLv2 许可下授权，因此必须提供源代码。仅提供二进制模块的行为会违反 Linux 内核的 GPLv2 授权许可。

旧版 bcm2835-unicam 模块已经编写，以尝试适应当前在主线 Linux 内核中找到的所有类型的 CSI-2 源驱动程序。这些可以大致分为相机传感器和桥接芯片。桥接芯片允许在某些其他格式和 CSI-2 之间进行转换。

相机传感器

相机传感器的传感器驱动程序负责设备的所有配置，通常通过 I²C/SPI。与从头开始编写驱动程序不同，通常更容易以现有驱动程序为基础并根据需要进行修改。

IMX219 驱动程序是一个很好的起点。该驱动程序支持 8 位和 10 位 Bayer 读出，因此枚举帧格式和帧大小稍微复杂一些。

传感器通常支持 V4L2 用户控件。并非所有这些控件都需要在驱动程序中实现。IMX219 驱动程序仅实现了一个小子集，如下所列，其实现由 imx219_set_ctrl 函数处理。

V4L2_CID_PIXEL_RATE / V4L2_CID_VBLANK / V4L2_CID_HBLANK ：允许应用程序设置帧速率
V4L2_CID_EXPOSURE ：设置曝光时间（以行为单位）；应用程序需要使用 V4L2_CID_PIXEL_RATE、V4L2_CID_HBLANK 和帧宽度来计算行时间

在 IMX219 的情况下，许多这些控件直接映射到对传感器本身的寄存器写入。

进一步的指导可在 libcamera 传感器驱动要求和树莓派摄像头调整指南第 3 章中找到。

设备树

设备树用于选择传感器驱动程序并配置参数，如 CSI-2 通道数量、连续时钟通道操作和链路频率（通常仅支持一个）。

6.1 内核的 IMX219 设备树叠加层可在 GitHub 上获得。

桥接芯片

这些是将传入的视频流（例如 HDMI 或复合视频）转换为可以被树莓派 CSI-2 接收器接受的 CSI-2 流的设备。

处理桥接芯片更加复杂。与摄像头传感器不同，它们必须响应传入信号并将其报告给应用程序。

处理桥接芯片的机制可以分为两类：模拟或数字。

在下面的部分中使用 ioctls 时，名称中的 S 表示它是一个设置函数，而 G 是一个获取函数，ENUM 列举了一组允许的值。

模拟视频源

模拟视频源使用标准 ioctls 来检测和设置视频标准。VIDIOC_G_STD，VIDIOC_S_STD，VIDIOC_ENUMSTD，和 VIDIOC_QUERYSTD 可用。

选择错误的标准通常会导致图像损坏。设置标准通常也会在 V4L2 捕获队列上设置分辨率。无法通过 VIDIOC_S_FMT 设置。通常，在流媒体之前通过 VIDIOC_QUERYSTD 请求检测到的标准，然后用 VIDIOC_S_STD 设置是个好主意。

数字视频源

对于数字视频源，如 HDMI，有一组备用调用，允许指定所有数字定时参数： VIDIOC_G_DV_TIMINGS，VIDIOC_S_DV_TIMINGS，VIDIOC_ENUM_DV_TIMINGS，和 VIDIOC_QUERY_DV_TIMINGS。

与模拟桥一样，定时通常固定 V4L2 捕获队列分辨率，并在流之前使用 VIDIOC_QUERY_DV_TIMINGS 的结果调用 VIDIOC_S_DV_TIMINGS 应确保格式正确。

根据桥接芯片和驱动程序的不同，可能通过 VIDIOC_SUBSCRIBE_EVENT 和 V4L2_EVENT_SOURCE_CHANGE 向应用程序报告输入源的更改。

目前支持的设备

树莓派的 Linux 内核目前支持两种桥接芯片：用于模拟视频源的 Analog Devices ADV728x-M 和用于 HDMI 源的 Toshiba TC358743。

Analog Devices ADV728x(A)-M 模拟视频到 CSI2 桥接芯片将复合 S 视频(Y/C)或分量(YPrPb)视频转换为单通道 CSI-2 接口，并受 ADV7180 内核驱动程序支持。

有关该芯片各个版本的产品详细信息，请访问 Analog Devices 网站：ADV7280A，ADV7281A 和 ADV7282A。

由于当前核心 V4L2 实现中存在一些缺失的代码，选择源失败，因此树莓派内核版本添加了一个内核模块参数 dbg_input 到 ADV7180 内核驱动程序，每次调用 VIDIOC_S_STD 时设置输入源。在某个时候，主流将修复底层问题（内核 API 调用 s_routing 和用户空间调用 VIDIOC_S_INPUT 之间的不一致），并将删除此修改。

不支持接收隔行视频，因此 ADV7281(A)-M 版本的芯片的用途有限，因为它没有必要的 I2P 去隔行块。在选择设备时，请确保指定-M 参数。如果没有，你将获得一个无法与树莓派接口的并行输出总线。

目前没有已知商用板使用这些芯片，但此驱动程序已通过模拟器件 EVAL-ADV7282-M 评估板进行了测试。

如果你使用的是基于 ADV7282-M 芯片的衍生，则可以使用 config.txt dtoverlay adv7282m 加载此驱动程序；或者如果你使用其他变体，则可以使用参数 adv7280m=1、adv7281m=1 或 adv7281ma=1 加载。

Toshiba TC358743 是一款 HDMI 到 CSI-2 桥接芯片，能够将视频数据转换为高达 1080p60。

可在 Toshiba 网站上找到有关此桥接芯片的信息。

TC358743 将 HDMI 接口转换为 CSI-2 和 I²S 输出。它受 TC358743 内核模块支持。

芯片支持将传入的 HDMI 信号作为 RGB888、YUV444 或 YUV422，最高支持 1080p60。它可以转发 RGB888，或将其转换为 YUV444 或 YUV422，并在 YUV444 和 YUV422 之间双向转换。仅已测试 RGB888 和 YUV422 支持。当使用两个 CSI-2 通道时，支持的最大速率为 1080p30 作为 RGB888，或 1080p50 作为 YUV422。在计算模块上使用四个通道时，1080p60 可以以任一格式接收。

HDMI 通过接收设备广告 EDID 来协商分辨率，其中包含其支持的所有模式。内核驱动程序不了解你希望接收的分辨率、帧率或格式，因此用户需要通过 VIDIOC_S_EDID ioctl 提供一个合适的文件，或者更容易地使用 v4l2-ctl --fix-edid-checksums --set-edid=file=filename.txt （添加参数 --fix-edid-checksums 意味着你不必在源文件中正确获取校验和值）。生成所需的 EDID 文件（二进制 EDID 文件的文本十六进制转储）并不太繁琐，有可用工具可用于生成它们，但这超出了本页面的范围。

如上所述，使用 DV_TIMINGS ioctl 配置驱动程序以匹配传入视频。这样做的最简单方法是使用命令 v4l2-ctl --set-dv-bt-timings query。驱动程序确实支持生成 SOURCE_CHANGED 事件，如果你希望编写一个处理变化源的应用程序。通过设置输出像素格式来实现更改像素格式，但只有像素格式字段将被更新，因为分辨率是由 DV 定时配置的。

有几块商用板可以将该芯片连接到树莓派。Auvidea B101 和 B102 是最常见的，但也有其他等效的板可用。

使用 config.txt dtoverlay tc358743 加载此驱动程序。

该芯片还支持通过 I²S 捕获立体声 HDMI 音频。Auvidea 板将相关信号引出到一个标头，可连接到树莓派的 40 引脚排针。所需的接线是：

信号

B101 引脚

40 引脚

BCM GPIO

除了叠加层 tc358743 外，还需要叠加层 tc358743-audio。这应该为 HDMI 音频创建一个 ALSA 录音设备。

音频不进行重新采样。音频的存在反映在 V4L2 控制 TC358743_CID_AUDIO_PRESENT (音频存在) 中，传入音频的采样率反映在 V4L2 控制 TC358743_CID_AUDIO_SAMPLING_RATE (音频采样频率) 中。当没有音频存在或者采样率与报告的不同时录制会发出警告。

`rpicam` 和 `raspicam` 之间的差异

rpicam-apps 模拟旧版 raspicam 应用程序的大多数功能。然而，用户可能会注意到以下差异：

Boost program_options 不允许参数的多字符短版本，因此这些参数不得不被删除。长格式参数以相同的方式命名，并保留任意单字符短格式。
rpicam-still 和 rpicam-jpeg 在预览窗口中不显示捕获的图像。
rpicam-apps

故障排除

如果你的摄像头模块不像你期望的那样工作，请尝试以下一些修复方法：

在树莓派 3 及更旧版本的设备上运行树莓派系统 Bullseye 及更旧的版本：
- 要启用硬件加速的摄像头预览，请启用 Glamor。要启用 Glamor，请在终端中输入 sudo raspi-config，选择 Advanced Options > Glamor > Yes。然后使用 sudo reboot 重启你的树莓派。
- 如果你看到与显示驱动程序相关的错误，请将 dtoverlay=vc4-fkms-v3d

获取帮助

要获取有关 libcamera 和 rpicam-apps 的进一步帮助，请查看树莓派摄像头论坛。在发帖之前：

记下你的操作系统版本（ uname -a ）。
记下你 libcamera 和 rpicam-apps 的版本（ rpicam-hello --version ）。
报告你正在使用的摄像头模块的制造商和型号。

如果相机软件中存在特定问题（例如崩溃），请考虑在 GitHub 存储库中创建一个问题，包括上面列出的相同细节。

系统配置

`raspi-config`

技巧
树莓派桌面版（Raspberry Pi Desktop）用户可使用图形化版本的 raspi-config：位于“首选项（Preferences）” → “树莓派配置（Raspberry Pi Configuration）”。不过某些高级配置仅存在于 raspi-config。

raspi-config 能帮你配置树莓派。对于不同的树莓派型号，可配置的参数也不尽相同。若要打开这款配置工具，请执行如下命令：

你将在灰色窗口中，看到显现的蓝色背景界面，上面带有各种参数：

用 上箭头（↑）、下箭头（↓），你就能在可选条目间自由切换，当前所选会被高亮。

按 右箭头（→）、Tab 键 可切换按钮 <Select> 和 <Finish>。按 左箭头（←）、Tab 键 可返回上级菜单。

raspi-config 会自动修改及相关 Linux 配置文件。个别参数可能需要重启后才能生效：如果你修改了他们当中任何一个，在退出时，raspi-config 会要求你重启。

技巧
在参数值所提供的冗长列表中（如时区城市列表），输入单个字母即可跳转到列表中的对应部分。例如，输入 L 会跳转至 Lisbon（里斯本）。

System options——系统参数

系统参数（System options）的子菜单：能让你对启动、登录和网络过程的相关部分进行配置修改，以及其他系统级的修改。

Wireless LAN——无线局域网（WLAN）

可配置 WiFi 网络名称（SSID）和密码。

Audio——音频

指定音频输出位置。

Password——密码

修改你的密码。

获取更多信息，请参阅。

Hostname——主机名

在网络上为树莓派设置可见的域名。

选择启动到控制台，还是桌面。以及在接通电源时，是否自动登录到当前用户账户。

Network at boot——启动时联网

在启动前等待网络连接。

Splash screen——启动画面

启用或禁用：开机时显示的启动画面。

Power LED——电源灯

如果你的树莓派型号支持，可以修改电源灯的行为。

Browser——浏览器

修改默认的网络浏览器。

Display options——显示参数

Underscan——欠扫描

注意
在 Wayland 下不可用。

如果在屏幕上显示的文本开头于屏幕边缘消失，可启用 overscan（过扫描）调整边框。在某些显示器（特别是监控器）上，禁用过扫描会使画面填充到整个屏幕，即去除黑边。

Screen blanking——屏幕节能（无操作时关闭信号输出）

启用或禁用：Screen blanking——屏幕节能（无操作时关闭信号输出）。

VNC resolution——VNC 分辨率

用于设置所用的显示分辨率。

Composite——复合视频

启用或禁用复合视频（composite video）。

4Kp60 HDMI

启用或禁用：HDMI 的 4K 60p 分辨率输出。

Interface options——接口参数

启用和禁用各种物理接口、虚拟接口。

SSH

启用或禁用：树莓派终端 SSH 远程访问。

你可以在另一台计算机上，使用 SSH 远程访问树莓派的命令行。在默认情况下，SSH 处于禁用状态。在上能阅读更多关于 SSH 的使用信息。如果你将树莓派直接接入到了公共网络，请不要启用 SSH，除非你为所有用户都设置了安全的密码。

VNC

启用或禁用：WayVNC、RealVNC 虚拟网络计算服务（virtual network computing，VNC）。

SPI

启用或禁用：SPI 接口，是否自动加载 SPI 内核模块。

I2C——I²C

启用或禁用：I²C 接口，是否自动加载 I²C 内核模块。

Serial port——串口

启用或禁用：串口上的 shell 及内核信息输出。

1-Wire——单总线

启用或禁用：单总线（Dallas 1-wire）接口，通常用于 DS18B20 温度传感器。

Remote GPIO——GPIO 远程访问

启用或禁用：GPIO 引脚的远程访问。

Performance options——性能参数

Overclock——超频

如果你的树莓派型号支持，可对 CPU 超频。超频能力视树莓派设备个体体质而异，即使是相同型号也会有所不同。超频过高可能会导致不稳定。

警告
超频可能会缩短你树莓派的使用寿命。 如果因某个特定级别的超频导致系统不稳定，可以试试较为保守的超频。在启动过程中按住 Shift 键 可临时禁用超频。

GPU memory——GPU 显存

改变向 GPU 提供的内存大小。

Overlay file system——堆叠文件系统（OverlayFS）

启用或禁用：只读文件系统。

Fan——风扇

可自定义接入 GPIO 的风扇行为（自带）。对、（使用特殊四针风扇头）无效。

Localisation options——本地化参数

配置位置、国家/地区相关参数。

Locale——语言环境

可选择语言环境，如 en_GB.UTF-8 UTF-8（英语）（译者注：中文为zh_CN.UTF-8 UTF-8）。

Time zone——时区

设置你的本地时区，从地区（译者注：Asia，亚洲）开始，然后选择城市（译者注：北京时间为 Shanghai），例如"Asia/Shanghai"（译者注：IANA 规范）。键入单个字母可跳转到列表中的该字母。

Keyboard——键盘

将打开菜单，你可以在其中选择你的键盘布局（译者注：目前中国使用标准美式键盘布局）。一般修改会立即生效，但可能需要重启。键入单个字母会跳转到列表中的字母所在。

WLAN country——无线局域网区域

为你的无线网络设置区域码。

Advanced options——高级参数

Expand filesystem——扩展文件系统

扩展你的操作系统分区，可便利用整个存储设备，从而带来更大的文件存储空间。要完成此操作，你需重启树莓派。通常，在初次启开机时，树莓派系统会执行此操作。如果你把你的操作系统克隆到了容量大于旧设备的其他存储设备上，该功能可能会极其有用。

警告
没有再次确认的步骤。选择该参数会立刻开始分区扩展操作。

Network interface names——网络接口名称

启用或禁用：可预测的网络接口名称。

Network proxy settings——设置网络代理

配置网络代理。

Boot order——启动顺序

在树莓派 4 及后续新款设备上，设定如下：在未插入存储卡的情况下，是否使用 USB 启动、网络启动。有关更多信息，请参阅。

Bootloader version——引导加载程序版本

在树莓派 4 及后续新款设备上，更新到最新的 ROM 引导软件。或者，倘若最新版本引发了故障，你可以在此恢复出厂默认设置。

Wayland

在 X11 和 Wayland 后端间进行切换。在树莓派 4 及后续新款设备上，默认使用 Wayland。其他型号的树莓派默认使用 X11。

注意
要在树莓派 4 之前的型号上使用 Wayland，你还必须把 wayland=on 添加至 /boot/firmware/cmdline.txt。

Audio config——音频配置

在 Bookworm 以前，树莓派系统使用的是 PulseAudio。现在则可以在 PulseAudio 和 PipeWire 音频后端间进行切换。

Update——更新

把 raspi-config 更新到最新版本。

About raspi-config——关于 raspi-config

raspi-config 相关说明。

Finish——完成

退出 raspi-config。如果你进行的修改需要重启，raspi-config 会提示你重启。首次进行修改时，最好重启。如果选择了调整存储卡大小，重启可能会花比平时更久的时间。

非交互式 `raspi-config`

工具 raspi-config 还支持非交互式选项及参数，无需可视化组件，就可以用命令行修改所有参数。可用参数可能因树莓派型号而异。

注意
0 和 1 的含义因参数而异。在将值赋给参数之前，请务必查阅文档。

System options——系统参数

Wireless LAN——无线局域网（WLAN）

配置 WiFi 网络名称（SSID）和密码。

填入无线网络名称（SSID）和密码（如需要）。以下是可选参数：

参数 <隐藏的网络> 代表网络名称可见性。如果网络名称开放广播，请使用 0 或省略该参数。如果你的网络名称是隐藏的，请填 1。默认为 0。

参数 <明文> 代表你是否打算明文传输密码。如果你的密码包含空格、特殊字符（如 !)，则必须使用 0，并在密码两头加上英文双引号 "。如无以上情形，你可以使用 1 或省略该参数。默认为 1。但若要使用该参数，你必须同时赋值给 <隐藏的网络>。

例如，通过执行以下命令，可以连接至：

未隐藏的网络 myssid，密码为 mypassphrase：
隐藏的网络 myssid，密码为 mypassphrase：

Audio——音频

指定音频输出位置。

在树莓派 4B 上，你可使用以下参数：

0：bcm2835 headphone jack（耳机插孔）
1：vc4-hdmi-0
2：vc4-hdmi-1

要查看参数 <数字> 的所有可用值列表，请参阅交互版 raspi-config 中所使用的缩写。

Password——密码

修改你的密码。

有关修改用户密码的更多信息，请参阅。

注意
此功能会使用全屏界面进行交互，即使在命令行执行参数亦如此。

Hostname——主机名

在网络上为此树莓派设置可见的域名。

选择：启动到控制台，还是桌面；在接通电源时，是否自动登录到当前用户账户。

B1：启动到控制台，需要登录
B2：启动到控制台，自动登录
B3：启动到桌面，需要登录

Network at boot——启动时联网

是否在启动前等待网络连接。

0：启动前不等待网络连接
1：启动前等待网络连接

Splash screen——启动画面

启用或禁用：启动时显示的启动画面。

0：启用启动画面
1：禁用启动画面

Power LED——LED 电源灯

如果你的树莓派型号支持，可以改变 LED 电源灯的行为。

0：用闪烁代表磁盘活动状态
1：LED 电源灯常亮

Browser——浏览器

修改默认的网络浏览器。若所选网络浏览器在当前并未安装，将不生效。

Display options——显示参数

Underscan——欠扫描

注意
在 Wayland 下不可用。

如果在屏幕上显示的文本开头于屏幕边缘消失，可启用 overscan（过扫描）调整边框。在某些显示器上，特别是监控器上，禁用过扫描会把图像填充到整个屏幕，即去除黑边。

设备:

1: HDMI-1
2: HDMI-2

使用：

0：启用过扫描
1：禁用过扫描

Screen blanking——屏幕节能

启用或禁用：屏幕节能（无操作时关闭屏幕信号）。

0：启用屏幕节能（无操作时关闭屏幕信号）
1：禁用屏幕节能（无操作时不会关闭屏幕信号）

VNC resolution——VNC 分辨率

用于设置所使用的显示分辨率。

Composite——复合视频

启用或禁用复合视频（composite video）输出。

在树莓派 4 上：

V1：启用 HDMI 4K 60p 输出
V2：启用复合视频输出
V3：禁用 4K 60p 和复合输出

对于其他型号：

0：启用复合视频
1：禁用复合视频

Interface options——接口参数

SSH

启用或禁用：树莓派终端 SSH 远程访问。

SSH 能让你在另一台计算机远程访问树莓派的命令行。有关 SSH 的更多信息，请参阅。

0：启用 SSH
1：禁用 SSH

VNC

启用或禁用：虚拟网络计算服务（virtual network computing，VNC）。有关 VNC 的更多信息，请参阅。

0：启用 VNC
1：禁用 VNC

SPI

启用或禁用：SPI 接口，是否自动加载 SPI 内核模块。

0：启用 SPI
1：禁用 SPI

I2C——I²C

启用或禁用：I²C 接口，是否自动加载 I²C 内核模块。

0：启用 I²C
1：禁用 I²C

Serial port——串口

启用或禁用：串口硬件。

0：启用串口
1：禁用串口

Serial console——串口控制台

启用或禁用： shell 及内核信息的串口输出。

0：启用串口控制台
1：禁用串口控制台

1-wire——单总线

启用或禁用：Dallas 1-wire（单总线）接口，通常用于 DS18B20 温度传感器。

0：启用 1-wire
1：禁用 1-wire

Remote GPIO——GPIO 远程访问

启用或禁用：GPIO 引脚的远程访问。

0：启用 GPIO 远程访问
1：禁用 GPIO 远程访问

Performance options——性能参数

Overclock——超频

若你的树莓派型号支持，可对 CPU 超频。超频潜力视树莓派设备个体体质而异，即使是相同型号也会有所不同。超频过高可能会导致不稳定。

警告
超频可能会缩短你树莓派的使用寿命。 如因某个特定级别的超频造成系统不稳定，可尝试更为保守的超频。在启动过程中按住 Shift 键 可暂时禁用超频。

此命令接受以下 <设置> 值：

None：不超频（默认）
Modest：超频至最大值 50%
Medium：超频至最大值 75%

GPU memory——GPU 显存

修改向 GPU 提供的内存量。

Overlay file system——堆叠文件系统（OverlayFS）

启用或禁用：只读文件系统。

0：启用堆叠文件系统（OverlayFS）
1：禁用堆叠文件系统（OverlayFS）

Fan——风扇

可自定义接入 GPIO 的风扇行为（自带）。对、（使用特殊四针风扇接头接入）无效。

0：启用风扇
1：禁用风扇

默认 gpio 为 14。

onTemp 默认为 80 °C。

Localisation options——本地化参数

Locale——语言环境

选择语言环境，如 en_GB.UTF-8 UTF-8（英语）（译者注：中文为 zh_CN.UTF-8 UTF-8）。

要查看参数 <语言环境> 的所有可用值列表，请参阅交互版 raspi-config 中所使用的缩写。

Time zone——时区

设置你的本地时区，从地区开始，然后选择城市，如"Asia/Shanghai"。

要查看 <时区> 参数的所有缩写值列表，请参见交互版 raspi-config。

Keyboard——键盘

设置键盘布局。一般来说，修改会立即生效，但也可能需重启才能生效。

要查看参数 <键盘布局> 的所有可用值列表，请参阅交互版 raspi-config 中所使用的缩写。

WLAN country——无线局域网区域

设置无线网络的区域码。

要查看 <区域码> 参数的所有可用值列表，请参阅交互版 raspi-config 中所使用的缩写。

Advanced options——高级参数

Expand filesystem——扩展文件系统

扩展你的操作系统分区，可使用整个存储设备，能为你带来更多的文件存储空间。需要需重启你的树莓派才能完成该操作。通常，树莓派系统会在初次开机时执行此操作。如果你将你的操作系统克隆到了容量大于旧设备的其他存储设备上，该功能可能会极其有用。

警告
没有再次确认的步骤。选择该参数会立刻执行分区扩展操作。

Network interface names——网络接口名称

启用或禁用：可预测的网络接口名称。

0：启用可预测的网络接口名称
1：禁用可预测的网络接口名称

Network proxy settings——设置网络代理

配置网络代理。

Boot order——启动顺序

对于树莓派 4 及后续新款设备，在未插入存储卡的情况下，指定：是否进行 USB 启动和网络启动。有关更多信息，请参阅。

视你的设备而定，你可以在以下参数中进行选择：

B1 ：存储卡启动：若存储卡可用，则优先从存储卡启动；如存储卡不可用，再从 NVMe 启动；若存储卡、NVMe 均不可用，那么则从 USB 启动
B2 ：NVMe/USB 启动：若 NVMe 可用，则优先从 NVMe 启动；如 NVMe 不可用，再从 USB 启动；若 NVMe、USB 均不可用，那么则从存储卡启动
B3 ：网络启动：若存储卡可用，则优先从存储卡启动；如存储卡不可用，则从网络启动

Bootloader version——引导加载程序版本

对于树莓派 4 及后续新款设备，要更新到最新版的 ROM 引导软件。或者，倘若最新版本引发了故障，你也可以在此恢复出厂默认设置。

E1：使用最新的引导 ROM
E2：使用出厂默认设置

Wayland

在 X11 和 Wayland 后端间进行切换。对于树莓派 4 及后续新款设备，默认使用 Wayland。其他型号的树莓派默认为 X11。

W1：使用 X11 后端
W2：使用 Wayland 后端

注意
要在树莓派 4 先前的型号上使用 Wayland，你还必须把 wayland=on 添加到 /boot/firmware/cmdline.txt。

Audio config——音频配置

使用此参数在 PulseAudio 和 PipeWire 音频后端之间进行切换。在树莓派系统 Bookworm 之前，树莓派系统使用 PulseAudio。

1：使用 PulseAudio 后端
2：使用 PipeWire 后端

Update——更新

将 raspi-config 更新至最新版本。

显示

要配置你的树莓派，使用非默认显示模式，请手动设定分辨率和方向。

HDMI 显示器支持

对于大多数 HDMI 显示器，树莓派系统都能使其达到最高分辨率和刷新率。

树莓派 Zero、Zero W 和 Zero 2 W 均搭载了 mini HDMI 接口，因此你需要 mini HDMI 转全尺寸 HDMI 转接线（转接头）。

树莓派 4、5 和 400 均搭载了两个 micro HDMI 端口，因此你需要为每台你想使用的显示器，各准备一份 micro HDMI 转标准 HDMI 转接线（转接头）。请在树莓派开机之前接入上述适配器。

树莓派 4 和 400 可以同时输出到两个显示器（高达 1080p 分辨率、60Hz 刷新率），或输出至两台 4K 30Hz 刷新率的显示器。如果你把显示器接入了 HDMI0 口，并在设置了参数 hdmi_enable_4kp60=1，还可以用 60Hz 刷新率输出单台 4K 显示器。

无须专门配置，树莓派 5 就可以 4K 分辨率、60Hz 刷新率，输出至两台显示器。

设置分辨率和方向

通过桌面设置分辨率和方向

在树莓派桌面上，打开菜单“首选项（Preferences）”，然后选择工具“屏幕配置（Screen Configuration）”。你应该会看到当前树莓派已接入的显示器（用图标表示）。右键单击要修改的显示器，然后选择一项参数。单击“应用（Apply）”并退出“屏幕配置（Screen Configuration）”保存修改。

通过命令行设置分辨率和方向

使用以下命令能打开工具 屏幕配置（Screen Configuration） ：

你应该会看到当前树莓派已接入的显示器（以图标表示）。右键单击要修改的显示器，然后选择一项参数。单击“应用(Apply)”并退出 屏幕配置（Screen Configuration） 以保存修改。

手动设定分辨率和屏幕方向

确定显示设备名称

要手动配置分辨率和方向，你得知道显示设备的名称。要确定设备名称，请运行以下命令，来显示已接入设备的信息：

设置自定义分辨率

如果你使用着 Wayland 桌面混成器，你可以通过编辑你主目录中的文件来，设置自定义显示分辨率：.config/wayfire.ini。可编辑现有的 [output:<device>] 部分。倘若没有，则添加新部分 [output:<device>]，以适配你的显示设备。要修改显示分辨率，请添加 mode 这行。例如，对于以下示例，配置为：设备名称是 HDMI-A-1、分辨率是 1080p 60Hz：

有关可支持的分辨率和 mode 语法的信息，请参阅。

将相同的配置段落添加到 /usr/share/greeter.ini，可以配置登录屏幕分辨率。

设定自定义屏幕方向

如果你正在运行 Wayland 桌面混成器，可以通过设置 wlr-randr 自定义屏幕显示方向。以下命令分别将屏幕方向配置为 0°、90°、180° 和 270°：

参数 --output 可指定要修改屏幕方向的设备。

注意
如要通过 SSH 运行此命令，请添加如下前缀： WAYLAND_DISPLAY=wayland-1。比如 WAYLAND_DISPLAY=wayland-1 wlr-randr --output HDMI-A-1 --transform 90。

你还可以使用以下某个 --transform 参数，在镜像屏幕的同时改变显示方向：flipped、flipped-90、flipped-180、flipped-270。

当然，你还可以通过编辑你主目录（home）中的文件，来旋转屏幕方向：.config/wayfire.ini。请编辑现有的 [output:<device>] 部分。倘若没有，则添加新的 [output:<device>] 部分以适配你的。要旋转屏幕方向，需添加 transform 这行。以下示例配置：设备名称是 HDMI-A-1、分辨率是 1080p 60Hz，旋转角度是 270°：

Wayland 支持以下 transform 参数：

normal
90
180

将相同的配置内容添加到 /usr/share/greeter.ini，来改变登录界面的屏幕方向。

Console resolution and rotation——控制台分辨率和屏幕方向

要修改树莓派控制台模式下的分辨率和方向，请使用 KMS 设置。有关更多信息，请参阅。

注意
若将控制台模式同时输出至多个显示器，那么所有接入的显示器将使用相同的屏幕方向。

Audio——音频

树莓派系统支持多种音频输出模式：HDMI 1、耳机插孔（如果你的设备有）和 USB 音频。

在默认情况下，树莓派系统将音频输出到 HDMI 1。如果 HDMI 输出不可用，树莓派系统会将音频输出到耳机插孔、已接入的 USB 音频设备。

修改音频输出

本节介绍了在树莓派系统中，多种配置音频输出的方法。

通过桌面控制音频

单击系统托盘上的音量图标，打开音频输出选择器。该界面可让你选择音频输出设备。单击音频输出设备，能切换音频输出到该设备。

专业音频配置文件

在 音频输出选择器（audio output selector） 中查看音频设备时，你大概会看到一个叫专业音频（Pro Audio）的设备配置文件。该配置文件在每个音频设备上暴露了最大数量的通道，使你能够更好地控制信号的路由。除非你要对音频输出进行细粒度调整控制，否则请使用其他设备配置文件。

更多有关专业音频配置文件的内容，请访问。

使用 `raspi-config` 控制音频

要修改音频输出，请使用，运行以下命令：

你将看到配置界面。完成以下步骤，可修改你的音频输出：

选择 System options 并按 回车键。
选择 Audio options 并按 回车键。
选择所需模式，然后按 回车键 选定该模式。

网络

可以用图形化用户界面（GUI）配置树莓派系统的无线连接。精简版树莓派系统和无头机器的用户可以用，在命令行设置无线网络连接。

注意
自树莓派系统 Bookworm 以降，默认的网络配置工具变成了 Network Manager。旧款树莓派系统使用 dhcpd 和别的工具进行网络配置。

连接到无线网络

通过桌面连接到无线网络

点击菜单栏右侧的网络图标打开网络管理器。如果你使用的树莓派搭载了内置无线连接功能（或插入了无线适配器），则单击此图标即可显示可用无线网络列表。如果看到信息“未找到 AP——正在扫描……（No APs found - scanning…）”，请等待几秒，网络管理器应该就能搜到你的网络。

注意
搭载双频无线的树莓派设备（树莓派 3B+、4、计算模块 4、树莓派 400、5）会自动禁用网络，直到你分配无线局域网区域。要设置无线局域网区域，请在“首选项（Preferences）”菜单里打开工具树莓派配置（Raspberry Pi Configuration），选择 本地化（Localisation），然后从菜单中选择你的区域。

右侧的图标会提示网络是否加密，并指示了信号强度。单击要连接的网络。如果是加密网络，对话框将让你输入网络密钥：

输入密钥，然后单击“确定（OK）”，再等待几秒钟。网络图标会闪烁一下，表示正在建立连接。连接成功后，图标将停止闪烁并显示信号强度。

连接到隐藏的网络

要使用隐藏的网络，请在网络菜单中找到到 高级参数（Advanced options） → 连接到隐藏的 WiFi 网络（Connect to a hidden Wi-Fi network）：

然后，输入隐藏网络的网络名称（SSID）。询问你的网络管理员：你所用的网络使用了哪种加密方式。目前，大多数家用网络使用的是 WPA 和 WPA2 个人加密，公共网络有时使用 WPA 和 WPA2 企业加密。选择你网络的加密方式，并输入你的凭据：

单击“连接（Connect）”按钮可启动网络连接。

通过命令行连接到无线网络

本指南将帮你：在不使用图形化工具（且无需附加软件）的情况下，在树莓派上配置使用无线连接。

注意
本指南适用于 WEP、WPA、WPA2 和 WPA3 网络，但可能不适用于企业网络。

启用无线网络

在全新安装时，你必须指定你设备的使用位置。这样可以使你的设备选择正确的 5GHz 网络频段。在你指定无线局域网区域后，你就可以使用树莓派内置的无线网络模块了。

要做到这一点，请使用命令行工具 raspi-config，设置你的无线局域网区域。运行以下命令：

使用 方向键 选择菜单项“本地化参数（Localisation options）”。选择参数 WLAN 区域（WLAN country）。使用 方向键 从下拉菜单中选择你的区域。按 回车键 确认选择。

现在，你应该已经可以访问无线网络了。运行以下命令来查看你是否已启用 WiFi 无线电：

若此命令返回文字“enabled（已启用）”，则可以继续准备配置连接。若此命令返回“disabled（已禁用）”，请尝试使用以下命令启用 WiFi：

搜索网络

要扫描无线网络，请运行以下命令：

你应看到类似输出如下：

在“SSID”这一列，查找要连接的网络名称。使用网络名称（SSID）和密码连接到网络。

连接到网络

运行以下命令来配置网络连接，请把占位符 <网络名称> 改为你要配置的网络名称：

在出现提示后，输入你的网络密码。

在你输入密码后，你的树莓派应该会自动接入网络。

如果你看到了报错，提示你“Secrets were required, but not provided（需要密码，但未提供密码）”，则意味着你输入的密码错误。请再次运行上述命令，并仔细检查你输入的密码。

要检查是否已接入网络，请运行以下命令：

应该看到类似输出如下：

在“IN-USE”列中查找星号(*)；它应该出现在你打算接入网络的网络名称（SSID）所在的同一行。

注意
你也可以手动编辑你的连接，配置文件位于目录 /etc/NetworkManager/system-connections/ 下。

连接到未加密的网络

如果你要连接的网络未使用密码，请运行以下命令：

警告
未加密的无线网络可能会将你的个人信息暴露在风险之中。应尽可能请使用安全的无线网络（或 VPN）。

连接到隐藏的网络

如果你正在使用着隐藏的网络，请在运行 nmcli 时指定参数 “hidden”，并赋值为“yes”。

设置网络优先级

如果你的设备同时检测到了多个已知网络，它可能会随机接入到任意某个已检测到的已知网络。可使用优先级参数，强制让你的树莓派优先连接到特定网络。在范围内，你的设备将连接到具有最高优先级的网络。运行以下命令，可查看已知网络的优先级：

你应该看到类似输出如下：

使用命令 nmcli connection modify 可设置网络的优先级。以下示例命令：把叫做 "Pi Towers" 的网络的优先级设置为 10：

在范围内，你的设备将始终尝试连接到具有最高非负优先级值的网络。你亦可以为网络分配负优先级；仅在范围内，没有其他已知网络时，你的设备才会尝试连接到负优先级网络。例如，现有三个网络：

在范围内，若所有这些网络同时存在，你的设备将首先尝试连接到网络“dog”。
若网络“dog”连接失败，你的设备将尝试连接到网络“cat”。
若网络“cat”连接失败，你的设备将尝试连接到网络“rabbit”。

配置 DHCP

在默认情况下，树莓派系统会尝试用 DHCP 自动配置所有网络接口。如果 DHCP 失败，则回滚至自动分配的私有地址，范围是 169.254.0.0/16。

分配静态 IP 地址

若要给你的树莓派分配静态 IP 地址，请在路由器上为其设定一个保留地址。你的树莓派仍将通过 DHCP 分配其地址，但每次都会收到相同的地址。可以在 DHCP 服务器中，将树莓派的 MAC 地址绑定到静态 IP 地址，来实现“静态”地址的分配。

Screen Blanking 屏幕节能（无操作时关闭屏幕信号）

你可以配置你的树莓派使用 屏幕节能（Screen Blanking）：在一段时间内无操作后，断开屏幕信号。在默认情况下，在启用屏幕节能后，树莓派系统将在无操作十分钟后关闭屏幕。

通过桌面配置屏幕节能

你可以使用树莓派配置（Raspberry Pi Configuration）菜单中的参数屏幕节能来控制屏幕节能（无操作时关闭屏幕）。

通过树莓派配置设置屏幕节能

单击菜单栏中的树莓派按钮。切换到 首选项（Preferences） → 树莓派配置（Raspberry Pi Configuration）。

选择显示（Display）参数。将参数按钮切换到屏幕节能（Screen Blanking）。按下 完成（OK），确认你的选择。

通过命令行配置屏幕节能

你可以使用命令行工具 raspi-config，来启用和禁用屏幕节能。运行以下命令打开该工具：

使用 方向键 切换，使用 回车键 选择。选择 Display Options 。再使用 方向键：选择 yes 可启用屏幕节能；选择 no 可禁用屏幕节能。

你还可以编辑添加以下行到 ~/.config/wayfire.ini：

变量 dpms_timeout 控制了在树莓派系统在屏幕关闭之前所需的无操作时间（秒）。如，值若为 600，则意味着会在 600 秒（十分钟）后关闭屏幕。将值置 0，屏幕将永不熄灭。

通过控制台配置屏幕节能

树莓派配置使用的屏幕节能配置 dpms_timeout 仅涉及桌面会话。在 控制台模式 下，即当你的树莓派仅接入至带有终端输入的监控器和键盘时，请在内核命令行下，使用设置 consoleblank。

设置控制台模式下的屏幕节能（screen blanking）

要修改控制台模式下的屏幕节能配置，请以管理员身份，用文本编辑器打开 /boot/firmware/cmdline.txt：

你可以在这儿调整树莓派系统，在关闭屏幕之前，等待控制台的时间（秒）。例如，添加 consoleblank=600 可在其无操作 600 秒后关闭显示信号输出。将值置 0，屏幕将永不熄灭。

修改 cmdline.txt 后，只有在重启后才会生效。使用以下命令重启你的树莓派：

查看当前屏幕节能设置

你可以使用以下命令显示当前控制台屏幕关闭时间（秒）：

用户

修改用户密码

你可以用工具 raspi-config，在命令行来修改当前用户账户的密码：

选择 option 2，并按照说明修改密码。

还可以使用工具 passwd：

添加用户

要添加新用户，请输入以下命令：把占位符 <用户名> 改成新用户的用户名：

在出现提示时，为新用户输入密码。

新用户的主目录位于 /home/<用户名>/。

为了授予新用户必要的权限，比如 sudo，运行以下命令将该用户添加到相关用户组，请把占位符 <用户名> 换成新用户的用户名：

要检查权限是否成功授予，请运行以下命令，请将占位符 <用户名> 换成新用户的用户名：

如果上述命令成功运行，则已成功为该用户配置了权限。

删除用户

要删除用户，请运行以下命令，请将占位符 <用户名> 换成要删除的用户名：

此命令将删除用户及其主目录。如果你想保留该用户的主目录，请在执行命令时，把参数 -remove-home 去掉。

修改默认用户

要修改在启动时自动登录到你树莓派的用户，请运行以下命令：

选择 option 1, Boot/Auto login。重启以使修改生效。

外置存储

你可以将外置硬盘、固态硬盘和 USB 存储设备接入树莓派上的任意 USB 口，然后挂载文件系统，访问里面存储的数据。

在默认情况下，对于常见的文件系统（FAT、NTFS 和 HFS+），你的树莓派会自动挂载，挂载位置是 /media/pi/<HARD-DRIVE-LABEL>。

注意
精简版树莓派系统（Raspberry Pi OS Lite）未实现自动挂载功能。

要设置存储设备，必须手动挂载，把它挂载到你选择的特定位置。

挂载存储设备

你可以将存储设备挂载到特定文件夹位置。通常挂载到文件夹 /mnt 下，例如 /mnt/mydisk。请注意，文件夹必须为空。

将存储设备插入树莓派上的 USB 端口，并使用以下命令列出树莓派上的所有磁盘分区：

树莓派自身使用了挂载点 / 和 /boot/firmware/。你的存储设备将与其他已连接的存储设备一同显示在此列表中。

使用 SIZE、LABEL 和 MODEL 这几列来辨别指向存储设备的磁盘分区的名称（如 sda1）。FSTYPE 这列包含了文件系统类型。如果你的存储设备使用的是 exFAT 文件系统，请安装 exFAT 驱动程序：

如果你的存储设备使用 NTFS 文件系统，你将只能以只读方式使用它。如果你想要对设备进行写操作，可以安装驱动程序 ntfs-3g：

运行以下命令以获取磁盘分区的位置：

比如，/dev/sda1。

创建一个目标文件夹，用作存储设备的挂载点。在这种情况下，使用的挂载点名称是 mydisk。你可以指定成自己想要的名称：

将存储设备挂载到你创建的挂载点上：

要检查存储设备是否挂载成功，可通过列出内容来确认：

自动挂载存储设备

你可以修改 fstab 文件，设定树莓派在启动时，存储设备自动挂载的位置。在 fstab 文件中，磁盘分区由全局唯一标识符（UUID）标记。

获取磁盘分区的 UUID：

从列表中找到磁盘分区并标记 UUID。（如 5C24-1453）使用诸如 nano 之类的命令行编辑器打开 fstab 文件：

在 fstab 文件中添加以下几行：

用你在上述步骤中找到的文件系统类型（如 ntfs）替换 fstyp。

如果文件系统类型为 FAT 或 NTFS，请紧跟 nofail 之后，再添加 ,umask=000。这将让所有用户完全读写存储设备上的任意文件。

现在你已在 fstab 中设置了一个条目。在启动树莓派时，该存储设备是否接入均可开机。在拔下存储设备之前，你必须先将树莓派关机，或者手动卸载该存储设备。

注意
在树莓派启动时，如未接入存储设备，启动时将再多等 90 秒。你可以紧跟 nofail 之后，再添加 ,x-systemd.device-timeout=30 来缩短时间。这将把超时时间修改为 30 秒，这意味着系统仅会等待 30 秒，然后就会放弃磁盘挂载。

要获取有关每个 Linux 命令的更多信息，请使用 man 命令查阅特定的手册页。例如，man fstab。

卸载存储设备

当树莓派关机时，系统会负责卸载存储设备，以便安全拔出。如果你想手动卸载设备，可以使用以下命令：

如果收到报错“device is busy（设备正忙）”，意味着存储设备未被卸载。如果没有显示错误，现在可以安全地拔出设备。

解决“device is busy”（设备正忙）

“device is busy”（设备正忙）这个报错意味在着存储设备上，有文件被程序占用。要关闭这些文件，请执行如下步骤。

关闭所有打开了存储设备上的文件的软件。如果你打开了一个终端，请确保你未处于存储设备所挂载的文件夹（及其子文件夹）下。

如果你仍然无法卸载存储设备，你可以使用工具 lsof 检查是哪个程序在设备上打开了文件。首先你要用 apt 安装 lsof：

使用 lsof 命令：

内核命令行（`cmdline.txt`）

在启动时，Linux 内核可接受一组命令行参数。对于树莓派，可在启动分区中的文件 cmdline.txt 里定义该命令行。你可使用任意文本编辑器编辑该文本文件。

重要
请把所有参数放在 cmdline.txt 中的一行里。不要用换行符。

要查看在启动时传递给内核的命令行，请运行以下命令：

因为树莓派固件会在启动内核之前对命令行进行修改，所以此命令行的输出与 cmdline.txt 的内容不会完全吻合。

命令行参数

内核命令行参数有很多，其中某些由内核本身定义。其他的可能由内核正在使用的代码定义，如 Plymouth 闪屏系统。

标准条目

console

　　定义了串口控制台。通常有两个条目：

console=serial0,115200
console=tty1

root

　　定义了根文件系统的位置。例如，root=/dev/mmcblk0p2 表示多媒体卡区块 0 分区 2。

rootfstype

　　定义了根文件系统使用的文件系统类型，例如 rootfstype=ext4。

quiet

　　将默认的内核日志级别设置为 KERN_WARNING，在启动过程中将屏蔽除非常严重级别外的内核信息。

设置 KMS 显示模式

旧版树莓派系统中所使用的传统固件和 FKMS 显示模式，已不再支持。作为代替，最新版本的操作系统使用 KMS（内核模式设置）。

如果在 cmdline.txt 中没有 video 这个条目，树莓派操作系统将根据接入 HDMI 显示器的，自动选定（基于 Linux 内核信息）显示器能支持的最佳分辨率。在精简版树莓派系统（Raspberry Pi OS Lite）、控制台模式中，你必须自己手动修改 video 这个条目，才能调整分辨率和屏幕方向。

还可以添加屏幕旋转和翻转（屏幕镜像）参数，请参考标准。以下示例定义了一台显示器：名为 HDMI-A-1、分辨率为 1080p、刷新率为 60Hz、屏幕旋转 90 度、并在 X 轴上翻转屏幕（屏幕镜像）：

要指定屏幕旋转方向和翻转参数，必须同时显式声明分辨率。

显示类型的支持参数——video= 条目 = 后的部分，支持：

视频参数

显示

其他条目

此部分是可以在内核命令行中使用的其他条目。以下列表不是完整无遗的。

splash

启动时使用 Plymouth 模块显示启动画面。

plymouth.ignore-serial-consoles

如启用 Plymouth 模块，它通常会屏蔽掉出现在串口控制台上的所有启动信息。此参数能让 Plymouth 忽略所有串口控制台，重现启动消息，如同没有运行 Plymouth 一样。

dwc_otg.lpm_enable=0

禁用驱动程序 dwc_otg 中设置的链接状态电源管理（Link Power Management，LPM）。该驱动程序驱动着 USB 控制器（嵌入在树莓派计算机的处理器中）。在树莓派 4 上，此控制器默认已禁用，且它仅连接至 USB Type C 电源输入接口。树莓派 4 上的 USB-A 接口由其他的，同此设置无涉的 USB 控制器驱动。

dwc_otg.speed

可设置树莓派计算机 USB 控制器的速率（处理器内置）。设置 dwc_otg.speed=1 则为全速（USB 1.0），但低于高速（USB 2.0）。除非要排除 USB 设备故障，否则不应设置此参数。

smsc95xx.turbo_mode

启用或禁用：有线网络驱动程序超频。smsc95xx.turbo_mode=N 则关闭超频模式。

usbhid.mousepoll

指定鼠标轮询间隔。如果你遇到了无线鼠标移动缓慢、不稳定等故障，将其置 0（usbhid.mousepoll=0）也许有用。

drm.edid_firmware=HDMI-A-1:edid/your_edid.bin

使用它能覆盖你显示器内置 EDID（/usr/lib/firmware/edid/your_edid.bin）信息。

本地化你的树莓派

你可以使用工具配置树莓派系统的界面语言、键盘布局和时区。

保护你的树莓派

在这儿，我们介绍了一些常见方法，能优化你树莓派的安全性。

让 `sudo` 命令要求密码

以 sudo 打头运行的命令，将会以超级用户执行。在默认情况下无需密码。但是你可以要求，所有以 sudo 运行的命令，均需输入密码，来改善你树莓派的安全性。

要强制 sudo 需要密码，请编辑你用户账户的 sudoers 文件中的 nopasswd，请将文件名中的占位符 <用户名> 换成你的用户名：

将 <用户名> 这个条目修改为如下内容，请把 <用户名> 换成你的用户名：

保存文件。你的设置会立即生效。

更新树莓派系统

仅最新版本的操作系统包含了所有最新的安全补丁。请始终将你设备中的树莓派系统至最新版本。

自动更新你的 SSH 服务器

如果你通过 SSH 连接至树莓派，通过添加 cron 作业，专门更新 SSH 服务器可能是值得的。可把以下命令，作为每日 cron 作业运行，确保你能及时收到最新的 SSH 安全修复程序。它独立于你的正常更新流程。

改善 SSH 安全性

SSH 是远程访问树莓派的常用方式。在默认情况下，SSH 要求用户名和密码。为了提高 SSH 的安全性，请。

启用和禁用 SSH 用户

你还可以通过修改 sshd 配置，允许（allow） 或 拒绝（deny） 特定用户。

将以下行添加、编辑或添加到文件末尾，其中涉及了你想要允许登录的用户名：

你还可以使用 DenyUsers 来明确禁止某些用户名登录：

修改后，请使用以下命令重启 sshd 服务，以使修改生效：

使用防火墙

Linux 上有许多防火墙解决方案可用。大多数通过底层的项目来进行数据包过滤。该项目基于 Linux netfiltering 系统。在默认情况下，树莓派系统上预装了 iptables，但未设置。设置它可能是一件非常麻烦的事情。项目提供了比 iptables 更为易用的界面。UFW 是 Ubuntu 中默认的防火墙工具，也可以安装到你的树莓派上：

ufw 是一款命令行工具，然而也有图形界面可用。请注意，ufw 须以 root 权限运行，因此所有命令都以 sudo 开头。还可以使用参数 --dry-run 执行所有的 ufw 命令，这表示仅输出命令的执行结果，而不进行任何实质性修改。

启用防火墙，同时设定防火墙开机自启：

要禁用防火墙，同时禁用防火墙开机自启，请使用：

允许特定端口访问（我们在本例中使用了 22 端口）：

拒绝访问端口也非常简单（我们再次以 22 端口为例）：

你还可以指定在端口上允许和拒绝哪种服务。在此示例中，我们拒绝了 22 端口上的 TCP：

如果你不知道服务会使用哪个端口，那么可以指定服务。此示例允许 ssh 服务通过防火墙访问：

命令 status 可列出当前防火墙的所有配置：

规则可能十分复杂：允许/阻止特定 IP 地址、指定允许流量的方向、限制连接尝试的次数（有助于缓解 DDoS 攻击）。你还可以指定要应用规则的设备（如 eth0、wlan0）。请参阅 ufw 手册页（man ufw）以获取除下面命令之外的完整详细信息。

在 ssh 端口上（TCP）限制登录尝试。如果 IP 地址在过往 30 秒内有过六次及更多次连接尝试，则拒绝连接：

拒绝从 IP 地址 192.168.2.1 访问端口 30

使用 `fail2ban` 阻挡可疑活动

在树莓派作为服务器时，你必须在防火墙中创建有意的漏洞以允许服务器流量通过。可以帮助保护你的服务器。Fail2ban 会检查日志文件中的检查可疑活动，如多次暴力登录尝试。它可以帮助你避免：手动检查入侵尝试的日志文件，然后再通过 iptables 更新防火墙来阻止它们。

运行以下命令安装 fail2ban：

在安装过程中，Fail2ban 会创建 /etc/fail2ban/jail.conf。要启用 Fail2ban，请把 jail.conf 复制到 jail.local：

在此配置文件中包含了一组默认参数，以及用于检查特定服务异常的参数。要查看用于 ssh 的规则，请用编辑器打开 jail.local：

如果没有 [ssh] 这个部分，则需要手动创建：向里面添加以下几行：

这将启用对可疑 ssh 活动的 Fail2ban 检查，包括检查系统日志，并在阻止活动之前给予进行六次重试机会。

在同一文件中，此 [default] 部分定义了默认的封禁操作 iptables-multiport，当达到检测阈值时，执行文件 /etc/fail2ban/action.d/iptables-multiport.conf ：

multiport（多端口）会禁止全部端口上的一切访问。action.d 文件夹包含许多可用于自定义服务器响应可疑活动的替代操作配置文件。

例如，如果要在三次失败尝试后永久拉黑 IP 地址，请将 [ssh] 部分中的 maxretry 值修改为 3，并将 bantime 设置为负数：

设置无头树莓派

无头（headless）是指在没有显示器、键盘、鼠标的情况下运行树莓派。要运行无头树莓派，你需要一种在其他计算机上访问它的方法。要远程访问你的树莓派，你需要将树莓派接入网络，并找到一种使用该网络访问树莓派的方法。

要把树莓派连接到网络，你可以通过以太网，把设备进行有线连接，或者配置无线网络。

要通过该网络访问树莓派，请使用 SSH。通过 SSH 连接，你就可以使用 raspi-config 来（如果你更喜欢图形化桌面环境）。

如果你从头开始设置你的树莓派，请在设置无线网络和 SSH。如果你已经设置好了树莓派，你可以使用 raspi-config 配置 SSH。

警告
取决于你使用的树莓派、存储卡的型号，在初次开机时，你的树莓派，可能需要长达五分钟的时间才能启动，接入无线网络。

连接到有线网络

若要在首次启动时就连接到有线网络，请把你的树莓派接入以太网。如果说你的树莓派没有以太网接口，则需使用以太网转换器。你的树莓派将自动连接到网络。

连接到无线网络

要在初次启动无头树莓派时配置无线网络访问，请使用树莓派启动盘制作工具中的高级设置菜单。输入你首选无线网络的网络名称（SSID）和密码。在你的树莓派初次启动时，将用这些凭据接入网络。某些无线适配器及特定树莓派开发板并不支持 5GHz 网络；请查阅你的无线模块文档，以确保与你偏好网络的兼容性。

注意
旧款树莓派系统会使用一个叫 wpa_supplicant.conf 的文件，把该文件放入 boot 文件夹就可以配置无线网络设置。从树莓派系统 Bookworm 开始，此功能已弃用。

远程访问

如果没有键盘和显示器，你需要某种方法来你的无头树莓派。在初次启动时，唯一的办法就是 SSH。要在全新安装的树莓派系统上启用 SSH，请选择以下某种方法：

在树莓派启动盘制作工具的操作系统自定义菜单中启用 SSH，然后输入用户名和密码
在存储卡的根目录下创建一个文件 ssh，然后按照下面部分的说明手动配置用户 userconf.txt

欲了解更多信息，请参阅。通过 SSH 连接，你就可以使用 raspi-config 来启，如果你更喜欢图形桌面环境。

手动配置用户

在你的存储卡根目录下，创建一个文件 userconf.txt。

该文件应为一行文本，由 <用户明>:<密码> 组成：你想要使用的用户名，紧接一个英文冒号，然后是你想要用的密码的加密形式。

注意
<用户名> 仅支持小写英语字母，数字和 -。且必须以字母开头。长度不大于 31 个字符。

要生成加密密码，请在其他计算机上使用。打开终端并输入以下内容：

在提示后输入密码进行验证。然后，该命令将输出该密码的加密形式。

从你的树莓派发射无线网络

你的树莓派可以用无线模块发射自己的无线网络。如果你通过以太网口（或其他无线模块）把你的树莓派接入互联网，那么接入此无线网络的其他设备就可以通过你的树莓派来上网。

假如使用的有线网络 IP 段是 10.x.x.x。你可将你的树莓派连接到该网络，并在使用另一个 IP 段（如 192.168.x.x）的独立网络上，为无线客户端提供服务。

请注意：在以下拓扑中，笔记本电脑与路由器和有线客户端的 IP 段是分离的：

在这种网络配置下，无线客户端可以通过树莓派路由器彼此通信。但是，无线网络上的客户端不能直接与有线网络上的客户端进行通信（除了树莓派）。无线客户端位于私有网络中，与为有线客户端提供服务的网络相分离。

注意
树莓派 5、4、3，树莓派 Zero W、2 W 可使用内置的无线模块发射无线网络。未搭载内置无线网卡的树莓派型号可使用外置无线模块来实现此功能。

启用热点

要在命令行上创建发射无线网络，请运行以下命令，把占位符 <网络名称> 和 <密码> 改成你自己的值：

使用其他的无线客户端（如笔记本电脑和智能手机）连接至网络。查找与网络名称（SSID）与 <网络名称> 一致的网络。输入你的网络密码，你应成功连接至网络。如果你的树莓派通过以太网连接或者别的无线适配器接入互联网，你应该也能上网。

禁用热点

要禁用热点网络，并将你的树莓派还原成无线客户端，请运行以下命令：

在禁用热点后，运行以下命令，可重新连接到其他 WiFi 网络：

技巧
有关连接到无线网络的更多信息，请参阅。

将你的树莓派用作网桥

在默认情况下，你用树莓派发射的无线网络与已接入以太网的父网络相分离。在这种拓扑下，连接到父网络的设备无法直接与接入树莓派发射的无线网络的设备进行通信。如果你希望连接的无线设备能够与父网络上的设备通信，你可以将你的树莓派配置成。有了网桥，所有接入树莓派托管的无线网络的设备都会被分配一个父网络中的 IP 地址。

在以下拓扑中，笔记本电脑、路由器和有线客户端位于相同的 IP 段：

以下步骤记录了如何在你的树莓派上设置网桥，以实现无线客户端和父网络之间的通信。

首先，创建一个网桥接口：

接下来，把你设备的以太网连接添加到父网桥：

最后，把你的无线热点连接添加到桥接中。你可以添加现有的热点接口，亦可创建新的：

如果你已经按照上述说明创建了无线热点连接，请使用以下命令将现有接口添加至桥接：
如果你尚未创建无线热点连接，请使用单个命令（所有行是一条命令）来创建新接口并将其添加到桥接中，把占位符 <热点密码> 改成你选定的密码：

现在你已配置好了桥接，是时候激活它了。运行以下命令以激活桥接：

运行以下命令，开始发射你的无线网络：

你可以使用命令 nmcli device 来验证桥接、以太网接口和无线热点接口是否均处于活动状态。

技巧
可使用诸如之类的工具，检查在接入热点后，是否能访问父网络上的设备。

使用代理服务器

代理服务器是客户端设备和互联网之间的中介。要将你的树莓派配置为代理服务器客户端，请按照本节中的说明操作。

你将需要：

代理服务器的 IP 地址/主机名、端口
如果需要，为你的代理设置用户名和密码

配置你的树莓派

你需要设置三个环境变量（http_proxy、https_proxy、no_proxy），以便你的树莓派知道如何访问代理服务器。

打开终端，使用 nano 打开文件 /etc/environment：

将以下内容添加到文件 /etc/environment，以创建变量 http_proxy：

用代理的 IP 地址和端口分别替换占位符 <代理IP地址> 和 <代理端口>。

注意
如果你使用的代理需要用户名和密码，请使用以下格式：
把你用于验证代理的用户名和密码分别替换占位符 <用户名> 和 <密码>。

为环境变量 https_proxy 输入相同的信息：

创建环境变量 no_proxy，这是一个由逗号分隔的地址列表，你的树莓派不应该使用代理。

你的 /etc/environment 文件现在应该如下所示：

按 Ctrl + X 保存并退出。

更新 `sudoers` 文件

要在下载和安装软件等以 sudo 方式运行的操作中，使用代理环境变量，请更新 sudoers。

使用以下命令打开 sudoers：

将以下行添加到文件中，这样 sudo 就能使用你刚创建的环境变量：

按 Ctrl + X 保存并退出。

重启你的树莓派

重启你的树莓派以使修改生效。现在你应该能够通过代理服务器访问互联网了。

文件夹 `boot` 的内容

树莓派系统把引导文件放在存储卡上的首个分区中，该分区使用 FAT 文件系统。

所有型号的树莓派在启动时，都会先从启动分区加载文件，来启动所有的处理器核心，继而再加载 Linux 内核。

在启动时，Linux 会把启动分区挂载到 /boot/firmware/。

注意
在 Bookworm 之前的树莓派系统将启动分区放在 /boot/。自 Bookworm 以降，启动分区位于 /boot/firmware/。

`bootcode.bin`

在启动时，SoC 会加载引导加载程序（bootloader）。引导加载程序会执行一些最基本的设置，继而加载某个 start*.elf 文件。

树莓派 4、5 不使用 bootcode.bin。它们使用的引导代码位于中。

`start*.elf`

在二进制固件模块（start*.elf）被加载到 VideoCore GPU（Soc 中）后，引导过程将由这些固件模块接管。

start.elf

　　基本固件

start_x.elf

　　含附加编解码器

start_db.elf

　　用于调试

start_cd.elf 　　　　精简版固件，移除了对硬件模块（如编解码器和 3D）以及对调试日志支持的支持；它还施加了对初始帧缓冲区限制。当在 config.txt 中指定 gpu_mem=16 时，将自动调用精简固件。

start4.elf、start4x.elf、start4db.elf 和 start4cd.elf 是树莓派 4 系列（树莓派 4B、400，计算模块 4、4S）的专用固件文件。

要了解如何使用这些文件的详细信息，请参阅。

树莓派 5 不再采用这些 elf 文件。固件直接嵌入到了引导加载程序（EEPROM 中的 bootloader）。

`fixup*.dat`

与上节所列的 start*.elf 文件相对应的链接器文件。

`cmdline.txt`

，将传给引导时的内核。

`config.txt`

涉及许多用于设置树莓派的配置参数。有关更多信息，请参阅。

重要
树莓派 5 要求：在启动分区中，须有一个非空的 config.txt 文件。

`issue.txt`

文本格式的维护信息，包含发行版日期和 Git 提交 ID。

`initramfs*`

即初始内存盘。在挂载真实的根文件系统之前，先把临时根文件系统加载到内存上。

自 Bookworm 以降，树莓派系统默认内置了一个 initramfs 文件。要启用初始内存盘，请在中使用关键字进行配置。

`ssh`（`ssh.txt`）

若存在此文件，在启动时会开启 SSH。在默认情况下，没有该文件，因此会禁用 SSH。该文件内容随意，即使是空的也会启用 SSH。

DTB 文件（`*.dtb`）

DTB 文件涉及各种树莓派型号的硬件定义。这些文件将根据，在启动时设置内核。

内核文件（`*.img`）

适用于各种树莓派型号的镜像文件：

文件名

处理器

树莓派型号

注解

注意
在使用 32 位内核的系统上，lscpu 会把 CPU 架构报告成 armv7l；在使用 64 位内核的系统上，lscpu 会把 CPU 架构报告成 aarch64。对于 armv7l，l 指的是小端 CPU 架构（如 kernel7l.img 文件名所示），而非指 LPAE。

文件夹 `overlays`（叠加层）

包含设备树叠加层。用于配置各种硬件设备（如第三方声卡）。可使用 config.txt 中的条目对这些叠加层进行选择。更多有关信息，请参阅。

LED 警告指示灯

在大多数情况下，如果由于某种原因树莓派无法启动（或必须关机），LED 灯将闪烁特定次数以传达状态信息。LED 将发出特定次数（0 或更多）的长闪烁，然后发出短闪烁，以传达确切状态。在大多数情况下，重复间隔为两秒。

长闪烁

短闪烁

状态

配置串口

在树莓派上有两类串口可用—— 和 mini 串口。PL011 是一款功能强大、符合 16550 标准的串口，而 mini 串口则功能有所欠缺。

树莓派上的所有串口均仅支持 3.3V（接入 5V 会损坏）。可使用适配器转接到 5V 设备。此外，也可以使用各种第三方的廉价 USB 转 3.3V 串口转换器。

树莓派 Zero，树莓派 1、2、3

如下所示，树莓派 Zero，树莓派 1、2、3 均搭载了两个串口：

名称

类型

树莓派 4、400

树莓派 4B、400 搭载了另外四个 PL011，在默认情况下，它们已被禁用：

名称

类型

树莓派 5

树莓派 5 搭载了另外四个 PL011，这些在默认情况下也是被禁用的：

名称

类型

树莓派 5 没有 mini 串口。

CM1、CM3、CM3+ 和 CM4

计算模块 1、3、3+ 均搭载了两个串口，而计算模块 4 则有六个串口（如上所述）。

所有型号的计算模块，在默认情况下均禁用了串口，但可以通过使用设备树叠加层来显式启用。你还可以指定要使用的 GPIO 引脚，例如：

主串口

在树莓派上，使用 GPIO 14（TX）和 15（RX）的串口——就是主串口。在默认情况下，大概率也会同时把 Linux 控制台输出到该串口。请注意，在 GPIO 排针上，GPIO 14 是引脚 8，而 GPIO 15 是引脚 10。

在树莓派 5 上，调试接口就是主串口。

副串口

副串口通常并未接入 GPIO 连接器。在默认情况下，副串口连接至无线局域网/蓝牙控制器（复合）的蓝牙侧（如果该型号搭载了此控制器）。

主串口和副串口

以下表格总结了各种树莓派设备上串口的分配情况：

型号

主串口/控制台

副串口/蓝牙

树莓派系统上的 Linux 设备：

Linux 设备

说明

/dev/serial0 和 /dev/serial1 都是符号链接，各指向 /dev/ttyS0、/dev/ttyAMA0 其中之一。

在树莓派 5 上，/dev/serial0 是指向 /dev/ttyAMA10 的符号链接。

由于 Bookworm 的变更，在默认情况没有 /dev/serial1。你可以在 config.txt 中，设置以下参数再次启用 serial1：

技巧
该参数可能并不会兼容后续的所有型号。应仅在你的用例无其他替代方案时，才使用该参数。

mini 串口和 CPU 主频

注意
mini 串口默认已禁用。要启用，必须禁用蓝牙或者把 mini 串口设置成主串口。

为了使用 mini 串口，你需要配置树莓派，把 VPU 核心时钟设置为固定频率。这是因为 mini 串口时钟与 VPU 主频相关联，因此当主频发生变化时，串口的波特率也会同时改变。要修改 mini 串口的行为，可以将 enable_uart 和 core_freq 这些设置添加到 config.txt。以下表格总结了可能的情况：

mini 串口被设置为

主频

结果

参数 enable_uart 的默认状态取决于谁是主串口：

禁用 Linux 串口控制台

在默认情况下，主串口被分配给 Linux 控制台。如果你希望将主串口用于其他目的，你必须重新配置树莓派系统。可以使用来做到这一点：

启动 raspi-config：sudo raspi-config
选择 option 3 - Interface Options
选择 option P6 - Serial Port

启用 Linux 早期控制台（early console）

尽管在 Linux 内核启动过程中，相对较早地启动了串口，但仍比一些关键基础设备的配置要晚得多。如果无法得到这些早期阶段的内核日志信息，可能很难对那个时间段出现的故障进行诊断。要为其中某个串口启用 earlycon 支持，请根据所选的主串口，向 cmdline.txt 添加以下参数：

对于树莓派 5，earlycon 仅可通过以下设置输出至调试接口（3 针）：

对于树莓派 4、400 和计算模块 4：

对于树莓派 2、3 和计算模块 3：

对于树莓派 1，树莓派 Zero 和计算模块 1：

默认波特率为 115200bps。

注意
如果早期控制台配置错误，可能会有碍树莓派启动。

串口和设备树

在中，可以找到各种串口设备树叠加层定义。最有用的两个叠加层是和。

disable-bt 将禁用蓝牙设备，并把第一个 PL011（UART0）设置成主串口。你还必须禁用初始化调制解调器的系统服务，以防它连接到串口：可使用 sudo systemctl disable hciuart。

miniuart-bt 将蓝牙功能切换到 mini 串口，并将第一个 PL011（UART0）设置成主串口。请注意，这可能会降低最大可用波特率（请参阅下文有关 mini 串口限制的内容）。你还必须使用 force_turbo=1 或 core_freq=250 将 VPU 核心时钟设置为固定频率。

叠加层 uart2、uart3、uart4 和 uart5 用于在树莓派 4 上启用另外四个串口。在文件夹中还有其他特定于串口的叠加层。有关设备树叠加层的详细信息，请参考 /boot/firmware/overlays/README，或运行 dtoverlay -h overlay-name 查看描述和使用信息。

向 config.txt 文件添加一行以应用。请注意，请去掉文件名中的 -overlay.dts 部分。例如：

PL011 和 mini 串口

PL011 串口和 mini 串口有些不同。

mini 串口的 FIFO 存储比较小。再加上缺乏流量控制，导致在较高的波特率下更易丢失字符。它的功能通常也弱于 PL011，主要是因为其波特率与 VPU 时钟速度相关联。

与 PL011 相比，mini 串口的不足有：

没有中断检测
没有帧错误检测
没有奇偶校验位
没有接收超时中断

mini 串口和基于 BCM2835 的 PL011 实现均不支持 DCD、DSR、DTR 和 RI 信号。

可在中找到详细的 mini 串口文档。

设备树、叠加层和参数

树莓派内核和固件使用设备树（Device Tree，DT）来描述硬件。这些设备树可能涉及用于控制板载功能的设备树参数。设备树叠加层能描述和配置可选的外部硬件，还能支持更多的可调参数。

固件加载程序（start.elf 及衍生文件）负责加载 DTB（设备树模块——某种机器可读的设备树文件）。它根据主板的修订版本选择要加载的 DTB，并进行修改以进一步定制。这种运行时定制消除了大部分仅细微差异的 DTB 需求。

会在 config.txt 中识别用户设定的参数，以及所有叠加层及相关参数，然后应用。比如，加载程序会根据结果来设定要用于控制台的所有串口。最后，再启动内核，传递指向合并 DTB 的指针。

设备树

设备树（Device Tree，DT）是对设备硬件的描述。它应涉及基本 CPU 的名称、其内存配置以及所有外部和内部的外围设备。设备树不应用于描述软件——尽管通过枚举硬件模块，通常会触发加载驱动程序模块。

注意
切记，设备树应与操作系统无关，因此任何 Linux 的特定内容均不应出现在里面。

设备树是硬件配置，以节点层次结构的形式呈现。每个节点可包含属性和子节点。属性是由字节构成的命名数组，可包含字符串、数字（大端序，Big-Endian）、任意字节序列以及三者的任意组合。打个比方：在文件系统中，目录是节点，文件是属性。设备树中节点和属性的位置可以用路径表示，并使用斜杠作为分隔符，单个斜杠(/)代表根分区。

DTS 基础语法

设备树通常以一种名为设备树源代码（DTS）的文本形式编写，并存储在后缀为 .dts 的文件中。DTS 的语法和 C 语言类似：使用大括号分组，每行以英文分号结尾。请注意，DTS 需在右大括号后添加英文分号，可将其视为 C 语言中的 struct（结构体），而不要将其视作函数。编译后的二进制文件格式为 .dtb，名为扁平化设备树（Flattened Device Tree，FDT）或设备树 blob（DTB，Device Tree Blob）。

下面是个简单树，文件格式是 .dts：

此树包含：

必要的设备树头： /dts-v1/
对其他 DTS 文件的引用，传统上命名为 *.dtsi，类似于 C 语言中的 .h 头文件
单个根节点： /

属性是简单的键值对，其值可为空，亦可包含任意字节流。虽然在数据结构中没有规定数据类型，但在设备树源代码文件中，有一些代表基本数据的表示方式。

文本字符串（以 NUL 结尾），用英文双引号表示：

cell 由尖括号分隔，32 位无符号整数：

所有字节数据用方括号分隔，并以十六进制输入：

可以使用逗号把不同表示形式的数字连接起来：

亦可使用逗号来创建字符串列表：

关于 `/include/` 的补充说明

指令 /include/ 实现了简单的文本引用，类似 C 语言的 #include 指令，但是设备树编译器的特性造成了不同的使用方式。鉴于节点是被命名的，可能带有绝对路径，因此在 DTS 文件（及其引用文件）中，相同的节点可能会出现两次。当发生这种情况时，节点和属性将被合并，属性会根据需要进行替换和覆盖（后续值会覆盖先前的值）。

在以上示例中，第二次出现的 /node2 会把新属性添加到原始属性中：

因此，一个 .dtsi 可以覆盖树中的多个位置，或者为其提供默认值。

标签和引用

树中的一部分经常需要引用另一部分，有四种方法可以实现这一点：

Path string

　　类似于文件系统路径，如在 BCM2835、BCM2836 中，I²S 设备的完整路径是 /soc/i2s@7e203000。标准 API 不会创建到属性的路径（如 /soc/i2s@7e203000/status）。所以，你应先找到一个节点，然后选择该节点的属性。

Phandle

　　phandle 属性是分配给节点的，唯一的 32 位整数。由于历史原因，你可能还会看到一个多余的匹配 linux,phandle。Phandle 按顺序编号，从 1 开始（0 不是有效的 phandle）。它们通常由设备树编译器分配，当它在整数上下文中遇到对节点的引用时，通常以标签的形式。使用 phandle 引用节点的引用仅被编码为相应的整数（单元）值；没有标记表明它们应被解释为 phandle，因为这是应用程序定义的。

Label

　　如同 C 语言中的标签是为代码中的位置命名一样，设备树标签给层次结构中的节点分配名称。编译器获取标签的引用，并在字符串上下文(&node)中将其转换为路径，在整数上下文(<&node>)中将其转换为 phandle；原始标签不会出现在编译输出中。请注意，标签不包含结构；它们只是一个扁平的全局命名空间中的标记。

Aliases

　　和标签类似。不同之处在于，它们以索引形式出现在 FDT 输出。它们作为 /aliases 节点的属性进行存储，每个属性将别名名称映射到路径字符串。尽管别名节点出现在源中，但路径字符串通常显示为对标签的引用(&node)，而非完全写出。解析路径字符串为节点的设备树 API 通常查看路径的首字符，将不以斜杠开头的路径视为必须首先使用 /aliases 表转换为路径的别名。

设备树语义

如何构建设备树，以及如何最大程度地利用它来捕获一些硬件的配置，是一个庞大而复杂的主题。有许多可用资源，其中一部分列在下面，但有几点需要强调：

compatible 属性是硬件描述和驱动程序之间的中介。当操作系统遇到带有 compatible 属性的节点时，它会在其设备驱动程序数据库中查找最佳匹配项。在 Linux 中，通常会触发驱动程序模块的自动加载，前提是它已经被适当标记且未被列入黑名单。
status 属性指示启用还是禁用设备。如果 status 是 ok，okay 或空，则设备已启用。除此之外，status 应是 disabled，即禁用设备。将设备放置在某个 .dtsi 文件中，并将状态设置为 disabled 可能很有用。然后，派生配置可以引用该 .dtsi，并把所需设备的状态设置为 okay。

设备树叠加层

现代片上系统（System on a Chip，SoC）是非常复杂的设备；完整的设备树可能长达数百行。再进一步，将 SoC 放置在带有其他组件的主板上，只会让情况变得更加复杂。为了保持可管理性（特别是如果有共享组件的相关设备），将共用元素放入 .dtsi 文件，以便从可能的多个 .dts 文件中引用，这是有道理的。

像树莓派这种设备，如果还支持了可选的插件配件（如扩展板），问题就会变得更加棘手。最后，每种可能的配置都需要一个设备树来描述它，但假如考虑到所有不同的基本型号和大量可用的配件，组合的数量开始迅速增加。

需要一种方法来描述这些可选组件：使用部分设备树，然后通过采用基本的设备树，并添加了一些可选元素来构建完整的树。如果这样做，这些可选元素就被称为"叠加层"。

除非你想要学习如何为树莓派编写叠加层，否则你可能更喜欢跳转到。

片段

设备树叠加层包含多个片段，每个片段都针对一个节点及其子节点。尽管概念听起来十分简单，但刚开始的语法似乎非常奇怪：

字符串 compatible 标识是为 BCM2835 设计的，这是树莓派 SoC 的基本架构；如果叠加层使用了树莓派 4 的功能，则正确的值为 brcm,bcm2711。除此外，brcm,bcm2835 可用于所有树莓派叠加层。然后是第一个（在这种情况下是唯一的）片段。片段应从零开始编号。违反这点可能导致某些/全部片段被忽略。

每个片段都由两部分组成：一个 target 属性，用于标识要应用叠加层的节点；以及 __overlay__ 本身，其主体将添加到目标节点。如果它是这样编写的，上述的示例可以解释为：

若使用的 dtc 版本够新，你可以按照上述示例编写，可获得相同的输出，但某些自制工具尚不兼容这种格式。当下，应以旧格式编写所有你想将其包含在标准树莓派系统内核的叠加层。

将该叠加层与标准树莓派基础设备树（如 bcm2708-rpi-b-plus.dtb）合并的效果，前提是叠加层在之后加载，将启用 I²S 接口，将其状态修改为 okay。但是，如果尝试使用以下方式编译此叠加层：

……你将收到报错：

这并不怎么意外，因为没有提及基础文件 .dtb、.dts，编译器就找不到标签 i2s。

再试一次，这次使用原始示例，并添加参数 -@ 来允许未解决的引用（同时使用 -Hepapr 解决一些麻烦）：

如果 dtc 返回了有关第三行的报错，则它没有工作所需的扩展工具。请运行 sudo apt install device-tree-compiler，然后重试一次。这次，编译应能顺利完成。请注意，适当的编译器也可在内核树中作为 scripts/dtc/dtc 使用，当使用 dtbs make target 时构建：

转储 DTB 文件的内容，看看编译器生成了什么：

输出应类似如下：

在文件结构的详细描述之后，我们有了一个片段。但请仔细观察——我们在 &i2s 处写了什么，现在却写成了 0xffffffff，这表明发生了一些奇怪的事情（较旧版本的 dtc 可能会写成 0xdeadbeef）。编译器还添加了一个包含唯一（对于此叠加层而言）的小整数的 phandle 属性，以指示该节点具有标签，并用相同的小整数替换了对标签的所有引用。

在 fragment 之后有三个新节点：

__symbols__ 列出了叠加层中使用的标签（ test_label 在这里），以及带有标签节点的路径。这个节点是如何处理未解析符号的关键。
__fixups__ 包含一个属性映射列表，将未解析符号的名称映射到需要使用目标节点的 phandle 进行修补的片段内单元格路径列表。在这种情况下，路径是到 target 的 0xffffffff 值，但片段可能包含其他未解析引用，这将需要另外修复。

在中提到“原始标签不会出现在编译输出中”，但是当使用参数 -@ 时，情况并非如此。相反，每个标签都会导致节点 __symbols__ 中的一个属性，将标签映射到路径，就像节点 aliases 一样。实际上，机制如此相似，以至于在解析符号时，树莓派加载程序会在没有 __symbols__ 节点的情况下搜索“别名”节点。曾经，这非常有用，因为提供足够的别名可让非常老版本的 dtc 也能构建基本的 DTB 文件，但幸运的是，那已经是远古历史了。

设备树参数

为了减少大量的设备树叠加层产生的，外围设备用户修改 DTS 文件的需要，树莓派加载程序支持了一项新功能，设备树参数。这能使用命名参数对设备树进行小修改，类似于内核模块从 modprobe 和内核命令行接收参数的方式。参数可以由基本 DTB 和叠加层暴露，包括扩展板叠加层。

通过在根节点添加一个 __overrides__ 节点来定义参数。它包含属性，其名称是选择的参数名称，其值是一个序列，包括目标节点的 phandle（对标签的引用）和指示目标属性的字符串；支持字符串、整数（cell）和布尔属性。

字符串参数

字符串参数的声明方式如下：

其中 label 和 property 将被适当的值替换。字符串参数可能导致它们的目标属性增长、缩小或被创建。

请注意，名为 status 的属性被特殊对待；非零/true/yes/on 值将被转换为字符串 "okay"，而零/false/no/off 将变为 "disabled"。

整数参数

整数参数是这样声明的：

在这里，label、property 和 offset 将被适当的值替换；偏移量以字节为单位相对于属性的起始位置指定（默认为十进制），前面的分隔符指定参数的大小。与早期实现不同，整数参数可以引用不存在的属性或超出现有属性末尾的偏移量。

布尔参数

设备树将布尔值编码为零长度属性；如果存在，则该属性为 true；如果不存在，则该属性为 false。它们的定义如下：

通过不定义属性将其分配值 false。布尔参数的声明如下，用适当的值替换占位符 标签 和 属性 ：

倒置布尔在应用相同方式之前反转输入值，就像常规布尔一样；它们的声明方式类似，但使用 ! 表示反转：

布尔参数可以触发属性创建或删除，但它们不能删除基本 DTB 中已经存在的属性。

字节字符串参数

字节字符串属性是任意字节序列（如 MAC 地址）。它们接受十六进制字节的字符串，字节间的英文冒号可有可无。

选择 [ 是为了与声明字节字符串的设备树语法匹配：

具有多个目标的参数

在设备树中的某些情况下，能够在多个位置设置相同的值是很方便的。与创建多个参数的笨拙方法不同，可以通过将它们连接起来，将多个目标添加到单个参数中，就像这样：

（示例来自 w1-gpio 叠加层）

注意
甚至可以使用单个参数针对不同类型的属性。你可以合理地将“启用”参数连接到字符串 status、包含 0/1 的单元格以及适当的布尔属性。

文本分配

设备树参数机制能从同一参数中修补多个目标，但其效用受到限制，因为必须将相同的值写入所有位置（除了格式转换和从反转布尔值中获得的否定）。嵌入式文字分配的添加允许参数写入任意值，而不管用户提供的参数值如何。

分配出现在声明的末尾，并由 = 表示：

第 1、2 和 4 行相当明显，但第 3 行更有趣，因为该值显示为整数（单元）值。设备树编译器在编译时评估整数表达式，这可能很方便（特别是如果使用宏值），但该单元也可以包含对标签的引用：

应用叠加层时，标签将按照通常的方式针对基本 DTB 进行解析。最好将多部分参数拆分到多行，以便更容易阅读——随着单元值分配的增加，这变得更加必要。

请记住，除非应用了参数，否则参数不起作用（查找表中的默认值将被忽略），除非使用参数名称而不指定值。

查找表

查找表可在使用之前转换参数输入值。它们充当关联数组，有点像 switch/case 语句：

不含 =value 的键意味着把键作为值，不含键的 = 表示在没有匹配项的情况下是默认值，并且以逗号开始或结束列表（或在任意处使用 空键=值 对）表示未匹配的输入值应该保持不变；否则，找不到匹配项将会报错。

注意
在单元格整数值后的表字符串中，逗号分隔符是隐式的：显示添加一个会创建一个空对（见上文）。

注意
由于查找表操作的是输入值，而文字赋值会忽略它们，因此不可能将两者结合在一起：查找声明中 } 结束后的字符被视为错误。

叠加层/片段参数

描述中所述的设备树参数机制存在许多限制，包括缺乏创建整数数组的简便方法，以及无法创建新节点。克服其中一些限制的方法是有条件地包含或排除某些片段。

通过将 __overlay__ 节点重命名为 __dormant__，可以将片段从最终合并过程中排除（禁用）。参数声明语法已增补，以允许否则非法的零目标 phandle 指示以下字符串包含片段或叠加层范围的操作。到目前为止，已实现了四种操作：

例子：

叠加层 i2c-rtc 使用这种技术。

特殊属性

一些属性名称，在被参数定位时，会得到特殊处理。你可能已经注意到的一个——status：将布尔值转换为 okay 表示 true，disabled 表示 false。

分配给 bootargs 属性会将其附加到其末尾，而不是覆盖它。这是如何向内核命令行添加设置的方式。

reg 属性用于指定设备地址，即内存映射硬件块的位置，I²C 总线上的地址等。子节点的名称应该用十六进制地址加以限定，使用 @ 作为分隔符：

当分配给 reg 属性时，父节点名称的地址部分将被替换为分配的值。这可用于在多次使用相同叠加层时防止节点名称冲突，即这是 i2c-gpio 叠加层使用的技术。

name 属性是一个伪属性，即它不应出现在设备树中，但是对其赋值会导致其父节点的名称修改为分配的值。与 reg 属性一样，可用于给节点提供唯一的名称。

叠加层映射文件

随着树莓派 4（基于 BCM2711 SoC 构建）的问世，带来了许多变化；其中某些变化是附加的接口，另一些是对现有接口进行的修改（删除）。有一些专为树莓派 4 设计的新叠加层，这些叠加层在旧硬件上无意义（如启用新的 SPI、I²C 和串口的叠加层），哪怕是控制着新设备上仍相关的功能的其他叠加层，也不能正确应用。

因此，有必要针对具有不同硬件的多个平台定制叠加层方法。在单个 .dtbo 文件中支持它们将需要大量使用隐藏的（“休眠”）片段，并切换到按需符号解析机制，以便不带的丢失符号也不会导致失败。一个更简单的解决方案是添加一个功能，根据当前平台将叠加层名称映射到几个实现文件中的一个。

叠加层映射是固件在引导时加载的文件。它以 DTS 源代码格式编写为 overlay_map.dts，被编译为 overlay_map.dtb 并存放在叠加层目录。

这是当前映射文件的节选（请参阅）:

每个节点都有一个需要特殊处理的叠加层名称。每个节点的属性要么是平台名称，要么是少数几个特殊指令之一。当前支持的平台有：bcm2835，其中包括所有基于 BCM2835、BCM2836 和 BCM2837 SoC 构建的树莓派；bcm2711 适用于树莓派 4B、400 和 CM4；bcm2712 适用于树莓派 5 和 CM5。

不带值的平台名称（空属性）表示当前叠加层与该平台兼容；例如，uart5 兼容 bcm2711 平台。对于平台的非空值是要使用的替代叠加层的名称，请求在 BCM2712 上使用 disable-bt 会触发加载 disable-bt-pi5。未在叠加层节点中包含的任何平台都不兼容该叠加层。未在映射中提到的任何叠加层都推定与所有平台兼容。

第二个示例节点，disable-bt-pi5：可从 disable-bt 的内容中推断出，但这种智能是用于文件的构建，而不是用于其解释。

仅在 BCM2711 上使用 uart5 叠加层才有意义。

如果没有为叠加层列出平台，则可能适用其中某个特殊指令：

renamed 指令表示叠加层的新名称（应与原始名称基本兼容），但也会记录有关更名的警告。
deprecated 指令包含一个简要的解释性错误消息，在通用前缀 overlay '...' is deprecated: 之后将被记录。

链接重命名和特定于平台的实现是允许的，但要小心避免循环！

切记：只需列出异常——叠加层的节点缺失意味着应该为所有平台使用默认文件。

在中介绍了如何从固件中获取诊断消息。

dtoverlay 和 dtmerge 工具已增补，可支持映射文件：

dtmerge 从基础 DTB 中的兼容字符串中提取平台名称。
dtoverlay 从 live 设备树中读取兼容字符串位于 /proc/device-tree 处，但你可以使用参数 -p 来提供替代平台名称（在不同平台上进行干扰运行时很有用）。

它们都将错误、警告和所有调试输出发送到 STDERR。

示例

这里有一些不同类型的属性示例，带有修改它们的参数：

更多示例，请查看中托管的大量叠加层源文件。

导出标签

固件中的叠加层在处理和使用 dtoverlay 工具的运行时叠加层应用，将在叠加层中定义的标签视为私有于该叠加层。这样可以避免为标签发明全局唯一名称（使它们保持简短），并且允许同一叠加层多次使用而不发生冲突（前提是使用一些技巧，请参阅）。

有时，创建一个标签并从另一个叠加层中使用它非常有用。自 2020 年 2 月 14 日发布的固件具有将某些标签声明为全局的能力：__exports__ 节点：

当应用此叠加层时，加载程序会剥离除了已导出的符号之外的所有符号（在本例中为 public），并重新编写路径，使其相对于包含标签的片段的目标。然后加载在此之后的叠加层可以引用 &public。

叠加层应用程序顺序

在大多数情况下，片段应用的顺序无关紧要，但对于自身打补丁的叠加层（其中片段的目标是叠加层中的标签，称为叠加层内部片段），应用顺序非常重要。在旧固件上，片段严格按顺序从上到下应用。自 2020 年 2 月 14 日以降，固件把片段分两次应用：

首先应用并隐藏目标其他片段的片段。
然后应用常规片段。

这种拆分对于运行时叠加层特别重要，因为第一步在工具 dtoverlay 中执行，第二步由内核执行（无法处理内部叠加层片段）。

在树莓派上使用设备树

DTB、叠加层和 `config.txt`

在树莓派上，加载程序（如 start.elf 镜像）的任务是把叠加层与适当的基础设备树相结合，然后将完全解析的设备树传给内核。基础设备树位于 FAT 分区（Linux 在 /boot/firmware/）中与 start.elf 相邻，命名是 bcm2711-rpi-4-b.dtb、bcm2710-rpi-3-b-plus.dtb 等。请注意，某些型号（3A+，A，A+）将使用对应的“b”款等效型号（3B+，B，B+）。此选择是自动的，并允许在所有设备中使用相同的存储卡镜像。

注意
设备树、ATAG 相互斥，将 DTB 传给不支持它的内核将造成启动失败。可固件将始终尝试加载设备树，并将其传递给内核。因为自 rpi-4.4.y 以降，若没有 DTB，所有的内核都无法正常工作。你可以在 config.txt 中添加 device_tree= 来覆盖此设置，这将强制使用 ATAG，对于简单的裸机内核可能很有用。

当前的加载程序支持使用 bcm2835_defconfig 进行构建，该配置选择了上游 BCM2835 支持。这个配置将触发构建 bcm2835-rpi-b.dtb、bcm2835-rpi-b-plus.dtb。如果这些文件与内核一起被复制，那么加载程序将尝试默认加载其中某个 DTB。

为了管理设备树和叠加层，加载程序可使用一些 config.txt 指令：

这将触发加载程序在固件分区中查找 overlays/acme-board.dtbo。树莓派系统把固件分区挂载到了 /boot/firmware/。然后它会搜索参数 foo 和 level，并将指定的值分配给它们。

加载程序还将搜索附加扩展板（带有已编程 EEPROM），并从中加载们能用的叠加层：直接或通过“overlays”目录中的名称; 这一切都在没有任何用户干预的情况下进行。

有多种方法可以告诉内核正在使用设备树：

在引导过程中，“Machine model:”内核信息具有特定于主板的值，如“Raspberry Pi 2 Model B”，而非“BCM2709”。
有 /proc/device-tree，包含了与设备树的节点和属性完全相同的子目录和文件。

使用设备树，内核将自动搜索并加载支持指示启用设备的模块。因此，通过为设备创建适当的设备树叠加层，你可以使设备用户免于编辑 /etc/modules；所有配置都在 config.txt 中进行（如使用扩展板，甚至这一步都不需要做）。但是，请注意，诸如 i2c-dev 之类的分层模块仍然需要显式加载。

反过来，由于平台设备只有在 DTB 请求时才会被创建，因此不再需要黑名单模块，这些模块过去是由主板支持代码中定义的平台设备加载的结果。实际上，当前的树莓派系统镜像不包含黑名单文件（除了某些 WLAN 设备，其中有多个可用驱动程序）。

设备树参数

如上所述，设备树参数是一种方便的方式：可以对设备的配置进行小的修改。当前的基本 DTB 支持用于启用和控制板载音频、I²C、I²S 和 SPI 接口的参数，而无需使用专用叠加层。在使用中，参数看起来像这样：

注意
多个赋值可以放在同一行，但要确保未超过 80 个字符的限制。

如果你有一个定义了某些参数的叠加层，可在后续行上指定这些参数，就像这样：

…或者像这样将参数附加到叠加层行：

叠加层参数仅在加载下一个叠加层之前有效。如果同名参数同时被叠加层和基础导出，叠加层中的参数优先；但建议不要这么做。要暴露基础 DTB 导出的参数，可以结束当前叠加层范围：

特定于主板的标签和参数

树莓派开发板有两个 I²C 接口。他们通常区分为：一个用于 ARM，一个用于 VideoCore（GPU）。在几乎所有型号上，i2c1 属于 ARM，i2c0 属于 VC（用于控制摄像头并读取扩展板的 EEPROM）。然而，两个旧款的 B 型树莓派设定相反。

为了使所有树莓派都能使用同一组叠加层和设备树参数，固件创建了一些特定于主板的参数。这些是：

这些分别是 i2c0、i2c1、i2c0_baudrate 和 i2c1_baudrate 的别名。建议仅在必要时才使用 i2c_vc 和 i2c_vc_baudrate。比如，你正在编程扩展板的 EEPROM（最好使用 i2c-gpio 叠加层使用 I²C 软件总线）。启用 i2c_vc 可能会导致树莓派相机、树莓派触摸显示屏无法正常工作。

对于编写叠加层的人，相同的别名已应用于 I²C 设备树节点上的标签。因此，你应该编写：

所有基于数字衍生的叠加层将被修改为使用新的别名。

扩展板（HAT）和设备树

树莓派扩展板（HAT）是搭载了嵌入式 EEPROM 的扩展板，专为带有 40 脚 GPIO 排针的树莓派设计。EEPROM 包括启用板（或要从文件系统加载的叠加层的名称）所需的所有设备树叠加层，此叠加层还可以公开参数。但

扩展板叠加层在基本 DTB 之后由固件自动加载，因此其参数可在加载其他所有叠加层之前访问，或者在使用 dtoverlay= 结束叠加层范围之前访问。如果出于某种原因你想要抑制 HAT 叠加层的加载，请在任何其他 dtoverlay 或 dtparam 指令之前放置 dtoverlay=。

动态设备树

自 Linux 4.4 以降，树莓派内核可支持叠加层和参数的动态加载。兼容内核管理一个叠加层的堆栈，这些叠加层位于基本 DTB 之上。修改立即反映在 /proc/device-tree 中，可触发模块的加载，平台设备的创建与销毁。

上面提到的“堆栈”一词非常重要：叠加层只能在堆栈顶部添加和移除；修改堆栈中较低位置的内容需要首先移除其顶部的所有内容。

有一些用于管理叠加层的新命令：

命令 dtoverlay

dtoverlay 是一个命令行工具，可在系统运行时加载和移除叠加层，同时列出可用的叠加层并显示其帮助信息。

使用 dtoverlay -h 获取使用信息：

与 config.txt 等效，但有区别：所有叠加层的参数必须位于同一条命令行中：命令仅用于基本 DTB 的参数。

变更内核状态（如添加和删除内容）的衍生命令需要 root 权限，因此可能需要在命令前加上 sudo。只有在运行时应用的叠加层和参数可以被卸载——由固件应用的叠加层或参数会“固定”在系统中，因此不会被 dtoverlay 列出，也无法被移除。

命令 dtparam

dtparam 创建并加载一个叠加层，其效果基本与在 config.txt 中使用 dtparam 指令相同。在使用上，它与带有 - 的叠加层名称的 dtoverlay 基本等效，但存在一些差异： dtparam 将列出基础 DTB 的所有已知参数的帮助信息。仍然可使用 dtparam -h 获取有关 dtparam 命令的帮助。在指示要移除的参数时，只能使用索引号（而非名称）。并非所有的 Linux 子系统都会在运行时响应设备的添加：I²C、SPI 和声音设备可以工作，但有些则不行。

运行时可用叠加层的撰写指南

创建或删除设备对象是由添加或移除节点，或节点状态从禁用变为启用或反之触发的。"status"属性的缺失意味着节点已启用。

不要在将叠加层基础 DTB 中现有节点的片段内创建节点，因为内核将重命名新节点以使其唯一。如果要修改现有节点的属性，请创建一个针对它的片段。

ALSA 不会干预其编解码器和其他组件在使用时的卸载行为。如果要删除的编解码器正在被声卡所使用，删除其使用的叠加层可能会导致内核异常。实验发现设备在叠加层中以片段顺序的相反顺序被删除，因此将卡的节点放在组件节点之后允许有序关闭。

注意事项

在运行时加载叠加层是内核的一个最新功能，截至本文撰写时，无法从用户空间执行此操作。通过将此机制的细节隐藏在命令背后，用户可以在不同内核接口标准的情况下免受影响。

某些叠加层在运行时的效果比其他叠加层更好。某些设备树部分仅在引导时使用，所以使用叠加层修改它们是无效的。
应用或移除一些叠加层可能会触发意外行为，因此应谨慎进行。这就是需要 sudo 的原因之一。
卸载 ALSA 卡的叠加层可能会因为某些正在使用 ALSA 的活动而等待：LXPanel 音量滑块插件展示了这种效果。为了使声卡的叠加层能够被移除，lxpanelctl 工具已被赋予两个新参数：alsastop

支持的叠加层和参数

要获取受支持的叠加层及参数，请参阅 /boot/firmware/overlays 下，叠加层文件 .dtbo 附加的文件。它会不断地添加和修改，以保持最新。

固件参数

固件使用特殊的节点在引导加载程序及固件与操作系统之间传递参数。除非另有说明，否则每个属性都存储为 32 位整数。

overlay_prefix

　　（字符串）由 config.txt 选择的字符串。

os_prefix

　　（字符串）由 config.txt 选择的字符串。

rpi-boardrev-ext

　　来自的扩展板修订代码。

rpi-country-code

　　使用的区域码。仅适用于树莓派 400。

rpi-duid

　　（字符串）仅适用于树莓派 5。PCB 上二维码的字符串表示。

通用引导加载程序属性 `/chosen/bootloader`

除非另有说明，否则每个属性都存储为 32 位整数。

boot-mode

　　用于加载内核的引导模式。请参阅。

partition

　　引导过程中使用的分区号。如果加载了虚拟内存盘（ramdisk ）boot.img，则此引用的是虚拟内存盘中加载的分区，而不是虚拟内存盘内部的分区号。

pm_rsts

　　在引导过程中寄存器 PM_RSTS 的值。

tryboot

　　如果在启动时设置了参数 tryboot ，则置为 1。

电源适配器属性 `/chosen/power`

仅适用于树莓派 5。除非另有说明，否则每个属性均被存储为 32 位整数。

max_current

　　电源适配器可以提供的最大电流（以 mA 为单位）。固件报告的由 USB-C、USB-PD 或 PoE 接口指示的值。对于台式电源适配器（如接入 GPIO 针脚），请在引导加载程序配置中定义 PSU_MAX_CURRENT，来指示电源适配器的电流能力。

power_reset

　　仅适用于树莓派 5。一个位字段，指示电源管理（PMIC）被重置的原因。

位

原因

rpi_power_supply

　　（一对 32 位整数）树莓派官方 27W 电源适配器的 USB VID 和 Product VDO（如已接入）。

usb_max_current_enable

　　如果 USB 接口的电流限制器在启动时被设置为低限，则为 0；如果启用了高限，则为非 0 值。如果电源适配器报告其最大电流为 5A，或在 config.txt 中强制使用 usb_max_current_enable=1，则自动启用高电平。

usb_over_current_detected

　　如果在 USB 启动期间发生过 USB 过流事件，则为非 0 值。

usbpd_power_data_objects

　　（包含多个 32 位整数的二进制数据区块）引导加载程序在 USB-PD 协商期间接收到的原始二进制 USB-PD 对象（仅限固定供电）。要为错误报告捕获此内容，请运行 hexdump -C /proc/device-tree/chosen/power/usbpd_power_data_objects。

格式由规范定义。

BCM2711 和 BCM2712 特定的引导加载程序属性 `/chosen/bootloader`

以下属性特定于 BCM2711 和 BCM2712 的 SPI EEPROM 引导加载程序。除非另有说明，否则每个属性都存储为 32 位整数。

build_timestamp

　　EEPROM 引导加载程序的构建时间（UTC）。

capabilities

　　这个位字段描述了当前引导加载程序支持的功能。这可以用来在引导加载程序 EEPROM 配置中启用功能（例如 USB 启动）之前检查是否支持。

位

功能

update_timestamp

　　由 rpi-eeprom-update 设置的更新时间戳（UTC）。

signed

　　如启用安全启动，此位字段为非 0。每个位指示当前的安全启动配置。

位

说明

version

（字符串）用于引导加载程序的 Git 版本，是字符串。

BCM2711 和 BCM2712 USB 引导属性 `/chosen/bootloader/usb`

如果系统是从 USB 启动的，则定义以下属性。这些属性可用于唯一标识 USB 引导设备。每个属性存储为 32 位整数。

usb-version

　　USB 主协议版本（2 或 3）。

route-string

　　由 USB 3.0 规范定义的设备的 USB 路由字符串标识符。

root-hub-port-number

　　引导设备连接到的根集线器端口号：可能通过其他 USB 集线器连接。

lun

　　用于大容量存储设备的逻辑单元号。

NVMEM 节点

固件通过 NVMEM 子系统提供引导加载程序 EEPROM 部分的只读内存映射。

每个区域在 /sys/bus/nvmem/devices/ 下显示为一个 NVMEM 设备，在 /sys/firmware/devicetree/base/aliases 下显示为一个命名别名。

从读取 NVMEM 模式的示例 shell 脚本代码。

blconfig

　　别名，指向存储引导加载程序 EEPROM 配置文件副本的 NVMEM 设备。

blpubkey

　　别名，指向以二进制格式存储引导加载程序 EEPROM 公钥副本（如果已定义）的 NVMEM 设备。可以使用工具将数据转换为 PEM 格式，以便与 OpenSSL 一起使用。

有关更多信息，请参阅。

故障排除

调试

加载程序将跳过缺少的叠加层和错误参数，但如果存在严重错误，比如缺少或损坏的基本 DTB 或失败的叠加层合并，那么加载程序将退回到非设备树引导。如果发生这种情况，或者如果你的设置不符合你的期望，需要检查加载程序的警告或错误：

通过将 dtdebug=1 添加到 config.txt 可以启用其他的调试。

你可以这样创建当前设备树状态，以人类可读的形式表示：

这对于查看将叠加层合并到基础树上的效果可能很有用。

如果内核模块未按预期加载，请检查它们是否在 /etc/modprobe.d/raspi-blacklist.conf 中，即是否被列入了黑名单；在使用设备树时，不应该有黑名单的使用需求。如果没有发现任何异常，你还可以通过在 /lib/modules/<版本>/modules.alias 中搜索 compatible 值来检查模块是否导出了正确的别名。否则，你的驱动程序可能缺少以下内容之一：

要么：

如果失败，可能因为 depmod 失败，或者更新的模块尚未安装在目标文件系统上。

使用 `dtmerge`、`dtdiff` 和 `ovmerge` 测试叠加层。

除了命令 dtoverlay 和 dtparam，还有一款能把叠加层应用到 DTB 的工具：dtmerge。要使用它，你首先需要获取基本的 DTB，可以通过以下两种方式获取：

从 /proc/device-tree 中的实时设备树状态生成它：

将包含你迄今为止在 config.txt 中应用的所有叠加层和参数，或者通过在运行时加载它们，这可能是你想要的，也可能不是。或者：

从 /boot/firmware/ 中的源 DTB 复制它。这不会包括叠加层和参数，但也不会包括固件的一切其他修改。为了允许测试所有叠加层，dtmerge 工具将创建一些特定于板的别名（"i2c_arm" 等），但这意味着合并的结果将与原始 DTB 有更多差异。你可能期望的不同。解决此问题的方法是使用 dtmerge 进行复制：

( - 表示不存在的叠加层名称)。

你现在可以尝试应用叠加层/参数：

将返回：

你还可以比较不同的叠加层/参数。

要获得：

存储库包含了另一款设备树工具——ovmerge。与 dtmerge 不同，ovmerge 结合了文件并以源形式应用叠加层。由于叠加层从未被编译，标签得以保留，结果通常更易读。它还具有许多其他技巧，例如能够列出文件包含的顺序。

强制使用特定设备树

如果你有非常特定的需求，而默认 DTB 无法满足，或者你只是想尝试编写自己的设备树，请让加载程序加载指定的 DTB 文件，就像这样：

禁用设备树使用

树莓派的 Linux 内核需要使用设备树。对于裸机和其他操作系统，可通过添加以下内容来禁用设备树加载：

到 config.txt。

快捷方式和衍生的语法

加载程序使用的一些快捷方式：

可以简写成：

（ i2c 是 i2c_arm 的别名，=on 为默认）。它仍然接受长形式版本： device_tree_overlay 和 device_tree_param。

`config.txt` 中可用的其他设备树命令

device_tree_address

　　用于覆盖固件加载设备树的地址（不是 dt-blob）。在默认情况下，固件将选择一个合适的位置。

device_tree_end

　　将对加载的设备树设置（独占）限制。默认情况下，设备树可以增长到可用内存的末尾，这几乎肯定是所需的。

dtdebug

　　如果非 0，会打开固件的设备树处理的一些详细日志记录。

enable_uart

　　启用主/控制台（在树莓派 3、4、400，树莓派 Zero W 和 Zero 2 W 上为 ttyS0，在其他情况下为 ttyAMA0——除非与诸如 miniuart-bt 的叠加层交换）。如果主串口是 ttyAMA0，则 enable_uart 默认为 1（已启用），否则默认为 0（已禁用）。这是因为有必要阻止核心频率的变化，否则会使 ttyS0 无法使用，因此 enable_uart=1 意味着 core_freq=250（除非 force_turbo=1）。在某些情况下，这会影响性能，因此默认情况下关闭。

overlay_prefix

　　指定要从中加载叠加层的子目录/前缀。默认为 "overlays/"。请注意末尾的“/”。如果需要，你可以在最后一个“/”后添加内容以向每个文件添加前缀，尽管这可能不是必要的。

可以用设备树对端口进行进一步的控制。有关更多详细信息，请参阅。

修改默认引脚配置

注意
通过用户提供的 DTB 自定义默认引脚配置的方法，已弃用。

引导序列期间的设备引脚

在引导序列期间，GPIO 引脚经历了各种操作。

上电时，引脚默认为输入状态，并具有默认的上拉电阻、下拉电阻，这些在中有说明
由 bootrom 设置
通过 bootcode.bin 设置

在软重置时，该过程仍适用，除了默认的上拉电阻、下拉电阻（仅在上电复位时应用）。

可能需要几秒钟才能完成此过程。在此期间，GPIO 引脚的状态可能与附加外设的预期状态（由 dt-blob.bin 或 config.txt 定义）不同。由于不同的 GPIO 引脚，其默认上拉、下拉状态都不一样，你应对你的外设执行 某个操作：

选择在复位时，默认的 GPIO 引脚（具备外设所需的上拉、下拉电阻）
延迟外设启动，直到完成相关操作。
添加适当的上拉电阻、下拉电阻

使用自定义 DTB

为了将设备树源代码文件（.dts）编译成 DTB（.dtb）文件，必须安装设备树编译器，方法是运行 sudo apt install device-tree-compiler。然后可以使用 dtc 命令，如下：

同样，如有需要，可将 .dtb 文件转换回 .dts 文件。

`dt-blob` 的各个部分

dt-blob.bin 用于在启动时配置二进制区块（VideoCore）。Linux 内核目前不使用它。dt-blob 可以配置所有型号的树莓派（包括计算模块），以使用替代设置。dt-blob 中的以下部分有效：

`videocore`

本部分包含了 VideoCore 所有的二进制区块信息。所有后续部分必须被包含在此部分内。

`pins_*`

有许多单独的 pins_* 部分，基于特定型号的树莓派，即：

pins_rev1：Rev1 引脚设置。由于移动了 I²C 引脚，因此存在一些差异。
pins_rev2：Rev2 引脚设置。涉及 P5 上附加编解码器的引脚。
pins_bplus1：树莓派 1B+ 修订版 1.1，包括完整的 40 脚排针。

每个 pins_* 部分都可包含 pin_config 和 pin_defines 部分。

`pin_config`

pin_config 部分用于配置各个引脚。该部分中的每个项目必须是一个被命名的引脚部分，例如 pin@p32，表示 GPIO32。还有一个特殊部分 pin@default，其中包含未在 pin_config 部分中明确命名的所有内容的默认设置。

`pin@pinname`

该部分可以包含以下项目的任意组合：

polarity
- active_high
- active_low

　　驱动强度用于设置引脚的强度。请注意，你只能为该参数指定单个驱动强度。有效值为 <8>、<16>。

`pin_defines`

此部分用于将 VideoCore 的特定功能分配给指定引脚。这使用户能把摄像头电源使能引脚移动到其他位置，或改变 HDMI 热插拔位置：这些都是 Linux 无法控制的。请参考以下 DTS 示例文件。

时钟配置

可以通过此接口修改时钟的配置，但也许结果难以预测！时钟系统的配置异常复杂。有五个独立的锁相环（PLL），每个 PLL 都有自己的固定（PLLC 下可变）压控振荡器（VCO）频率。每个 VCO 然后有多个不同的通道，可以设置为 VCO 频率的不同分频。每个时钟目的地都可以设置为从某个时钟通道获取信号，但由于时钟信号源到目的地的映射有限，因此并非所有通道都能连接到所有时钟目的地。

这里有一些示例配置，你可以用来修改特定的时钟。当请求时钟配置时，我们将添加到此资源。

以上内容会把 PLLA 使用的 VCO 频率设置为 1.96608GHz（此 VCO 的频率范围是 600MHz-2.4GHz）；将 APER 通道设置为 4 分频，并让 GPCLK0 从 PLLA 获取信号源（通过 APER）。之所以要提供时钟 12288000 Hz，是为了便于音频编解码器生成频率 48000 Hz。

设备树源文件实例

固件存储库包含了，通常从中派生出其他内容。

树莓派硬件

介绍

树莓派推出了多种系列的计算机：

旗舰系列通常简称为“树莓派（Raspberry Pi）”，搭载了高性能硬件、完整的 Linux 操作系统及多种常见接口。其外形尺寸与信用卡大小相当。
Zero 系列搭载了完整的 Linux 操作系统和最基本的接口，价格实惠，体积小，功耗低。
计算模块（Compute Module） 系列，一般简称为 "CM"。计算模块系列搭载了高性能硬件和完整的 Linux 操作系统，适合工业和嵌入式的小尺寸用途。计算模块的硬件与相应旗舰型号相当，但接口较少，甚至未板载 GPIO 引脚。用户需将计算模块接到一块单独的基板上，基板提供了使用接口和引脚。

此外，树莓派还推出了 Pico 系列微型多用途微控制器开发板。Pico 系列不支持 Linux，也不支持可移动存储，只能以把二进制文件刷到板载闪存存储器的方式进行编程。

旗舰系列

B 代表其搭载了以太网口。A 代表低成本产品线——其体积较小，不带以太网口，内存也不大；因受开发版高度限制，USB 接口也较少。

型号

SoC

内存

GPIO

外设接口

更多有关旗舰系列树莓派接口的信息，请参阅原理图和机械图。

Zero 系列

带 H 后缀的型号在 GPIO 引脚上预先焊接了排针。不带 H 后缀的型号未在 GPIO 引脚上焊接排针——用户需要手动焊接排针或使用第三方排针套件。

所有 Zero 系列型号搭载了以下连接功能：

一个 microSD 卡槽
一个 CSI 摄像头接口 (最早由 Zero 1.3 引入)
一个 mini HDMI 端口
micro USB 端口 × 2（一个用于电源输入，另一个供外部设备使用）

型号

SoC

内存

GPIO

无线连接

计算模块系列

型号

SoC

内存

存储

外形尺寸

无线连接

注意
某些计算模块的外形尺寸与 DDR2 SO-DIMM 相同，但不兼容其电气规格。

更多有关树莓派计算模块的信息，请参阅计算模块文档。

Pico 微控制器

带 H 后缀的型号在 GPIO 引脚上预先焊接了排针。不带 H 后缀的型号未焊接到 GPIO 引脚的排针——用户必须手动焊接排针或使用第三方排针套件。

型号

SoC

内存

存储空间

GPIO

无线连接

有关各种树莓派 Pico 的更多信息，请参阅。

电路图和机械图纸

各式树莓派开发板的原理图：

树莓派 5

树莓派 5 的

树莓派 4B

树莓派 3B+

树莓派 3A+

树莓派 3B

树莓派 2B

树莓派 1B+

树莓派 1A+

注意
树莓派 3A+ 的机械图纸亦适用于树莓派 1A+。

树莓派 Zero 2 W

测试点

树莓派 Zero 2W 在生产过程中使用了许多测试点位置。

标签

功能

距原点 X（mm）

距原点 Y（mm）

树莓派 Zero W

树莓派 Zero

产品合规性和安全性

所有树莓派产品均通过了充分的合规测试。更多有关信息，请参阅产品信息网站。

阻燃等级

树莓派设备使用的 PCB 符合 UL94-V0 标准。

注意
仅适用于 PCB。

树莓派合规支持

依据树莓派在合规测试期间的实际测试情况，合规支持计划的目标是消除处理合规问题的负担，为公司更轻松地将新产品推向消费者提供支持。它为用户提供了与 UL 公司的专门团队联系的机会，他们借助对树莓派的深入了解，评估和测试用户的产品。

了解更多关于树莓派合规支持计划的信息。

由树莓派提供支持

由树莓派提供支持的 Powered by RaspberryPi 计划，为想要使用树莓派 logo 形式的公司提供了一个流程，涵盖了搭载树莓派计算机、芯片的产品，以及由树莓派提供的服务。如果你希望进行申请流程，可在线操作。

已审批的设计合作伙伴

我们已审批的设计合作伙伴名单提供了一组我们密切合作并支持的咨询公司，它们能够在硬件、软件和机械领域提供付费设计服务。

频率管理和发热控制

在重负荷情况下，所有款式的树莓派，都会进行一定程度的发热管理，以避免过热。SoC 内置了温度传感器，GPU 上的软件会进行轮询，以确保温度不会超过我们设定的上限，所有型号均为 85°C。可以将此值设定为较低值，但不能提高上限。当设备接近极限时，芯片（Arm、GPU）上各种频率和电压（有时）会下降。这将减少产生的热量，使温度维持在一定范围内。

当核心温度在 80°C 和 85°C 间，Arm 核心会逐渐降频。如果温度达到 85°C，那么 Arm 核心和 GPU 都会进行降频。

树莓派 3B+ 采用了新型 PCB 技术，能提供更好的散热性能，提高热质量。此外，还引入了软温度限制，旨在最大化延长设备在达到硬限制 85°C 之前的“高性能”时间。当达到软限制时，时钟速度从 1.4GHz 降至 1.2GHz，并略微降低操作电压。这减缓了温度升高的速度：我们以更长时间的 1.2GHz 代替了短暂运行的 1.4GHz。在默认情况下，软限制为 60°C：可通过 config.txt 中的参数 temp_soft_limit 进行更改。

树莓派 4B 沿用了树莓派 3B+ 的 PCB 技术，以帮助散热。目前尚未实施软限制。

使用 DVFS

注意
此 DVFS 讨论仅适用于树莓派 4B、400 和计算模块 4。

树莓派 4 采取了动态电压频率调节（DVFS）。该技术使树莓派 4 设备能在保持性能不变的同时降低运行温度。

固件会监控 SoC 内部的各种时钟（例如 Arm、Core、V3D、ISP、H264、HEVC），当它们未全速运行时，供给给这些时钟驱动的芯片部分的电压，将环比全速时略微降低。事实上，仅提供一定的电压就足以确保其以特定运行水准正常运行。这可以显著降低 SoC 的功耗，从而了削减了总发热量。

由于可能引发系统稳定性故障，特别是在使用电压降低固定时钟外设（例如 PCIe）时，存在潜在的系统稳定性故障。有三种 DVFS 模式，可在 /boot/firmware/config.txt 中配置，特征如下。大多数设备应使用 dvfs=3，不带显示的设备可能会因其较低功耗降低而从 dvfs=1 受益，但会面临 PCIe 稳定性问题的风险。

注意
树莓派 5 已经移除了这个参数，并将始终处于模式 3。

此外，还采用了更细粒度的 CPU 调度器，用来更精细地控制 ARM 核心频率，这意味着 DVFS 效果更佳。现在的步进频率为 600MHz、750MHz、1000MHz 和 1500MHz。这些步进在 SoC 限流时可能有益，意味着几乎不会完全降至 600MHz，从而大幅改善了全负载时的性能。

默认的 CPU 调度器是 ondemand。可以手动调用软件包 cpufrequtils 中的命令 cpufreq-set 更改调度器来减少空闲功耗：

测量温度

由于树莓派设备使用的 SoC 架构，若在树莓派系统发行版中使用了上游的温度监控代码（如基于 Linux 的温度测量），可能并不准确。但是，命令 vcgencmd 能够提供准确且即时的 SoC 温度的实时数值，因为 vcgencmd 同 GPU 直接通信：

添加散热片

由于内置节流功能，不用散热片也不会造成 SoC 过热损坏。不过，安装散热片和小型风扇可缓解发热限流，改善性能。要获得最佳气流，略微改善散热效果，可考虑把树莓派竖着放。

风扇套件

用于辅助散热，树莓派 5 有两款官方风扇可选：

这两款均应插入至主板右上方的风扇连接器（四针 JST-SH PWM），位于 40 引脚 GPIO 排针和 USB 2.0 之间。风扇连接器与 USB 外围设备一同受电流限额。我们建议超频用户使用主动散热器外壳，因为它有更好的散热能力。

以上两种可选官方配件均由树莓派固件主动控制。随着树莓派的温度升高，风扇的反应如下：

在 50°C 以下，风扇不会转动（0% 速度）
在 50°C 时，风扇缓慢转动（30% 速度）
在 60°C 时，风扇转速提高至中速（50% 速度）
在 67.5°C 时，风扇转速提高至高速（70% 速度）

温度下降时，应用相同的行为，伴有 5°C 的滞后性；当温度下降到低于上述每个阈值 5°C 时，风扇速度才会放缓。

在启动时，风扇会自动运转，以查看转速控制，并检查风扇是否旋转。如果可以，则启用设备树驱动 cooling_fan。在默认情况下，该驱动位于 bcm2712-rpi-5-b.dtb，但可以用 status=disabled 进行修改。

风扇连接器引脚图

风扇连接器是一个间距 1 mm 的 JST-SH 插座，包含以下四个引脚：

引脚

功能

电线颜色

树莓派启动 EEPROM

树莓派 4、400、5，计算模块 4、4S 计算机使用 EEPROM 启动系统。其他型号的树莓派计算机使用位于启动文件系统中的 bootcode.bin 文件。

注意
在 GitHub 存储库 rpi-eeprom 中，你可以找到用于创建 rpi-eeprom 的脚本和预编译的二进制文件。

诊断引导

如果在引导过程中出现错误，会用绿色 LED 灯传递故障信息。更新后的引导加载程序会在 HDMI 显示器上输出诊断信息。

更新引导程序

有多种方法来更新你树莓派的引导程序。

树莓派 5、树莓派 4、树莓派 400

树莓派操作系统会自动更新引导加载程序来进行重要的错误修复。要手动更新引导加载程序/更改启动顺序，请使用 raspi-config。

使用树莓派启动盘制作工具来更新引导加载程序

树莓派启动盘制作器提供了一个图形界面，用于更新引导加载程序并选择引导模式。

下载树莓派启动盘制作工具
选择一张未使用的存储卡（引导加载程序镜像会格式化整张卡）
启动树莓派启动盘制作工具
选择 选择操作系统（Choose OS）

为你的树莓派选择 Bootloader (树莓派 400 属于 4 系列)

选择引导模式：存储卡（建议）、USB、网络

选择 存储卡 然后 写入（Write）
单击 确认（Yes） 继续
使用新的镜像引导树莓派，请等待至少十秒钟

使用 `raspi-config` 来更新引导加载程序

要在树莓派系统上更改启动模式、变动引导加载程序版本，请运行 raspi-config。

更新树莓派系统，下载软件包 rpi-eeprom 的最新版本。
运行 sudo raspi-config。
选择 Advanced Options。

更新引导程序配置

引导加载程序 default 版本即最新的出厂默认固件镜像。它提供了关键的错误修复、硬件支持，并且特性均在 latest 版本中经过测试，然后定期更新。latest 版引导加载程序的更新更为频繁，包含了最新的修复和改进。

专业用户可以切换到 latest 版引导加载程序以获得最新功能。

运行以下命令启动 raspi-config。

切换到 Advanced Options，然后选择 Bootloader Version。选择 Latest 并选择 Yes 确认。选择 Finish 确认重启。重启后，再次打开命令提示符更新你的系统：

如运行 sudo rpi-eeprom-update，你将看到引导加载程序的更新版本是 latest 发行版。

现在，你可以更新你的引导加载程序。

重启，然后运行 sudo rpi-eeprom-update。现在你应该看到 CURRENT 的日期已更新为引导程序的最新版本之日期。

查阅当前引导程序配置

要查看当前运行的引导程序使用之配置，请运行以下命令：

从引导加载程序镜像中读取配置

要从引导加载程序镜像中读取配置：

编辑当前的引导加载程序配置

执行以下命令可将当前引导加载程序配置加载到文本编辑器。当关闭编辑器后，rpi-eeprom-config 将更新后的配置应用于最新的可用引导加载程序版本，并使用 rpi-eeprom-update 在系统重启时应用更新：

如果更新后的配置与原配置相同、或为空，则不会进行任何更改。

编辑器取决于环境变量 EDITOR。

应用已保存的配置

以下命令将 boot.conf 应用于最新可用的引导加载程序镜像，使用 rpi-eeprom-update 在系统重启时应用更新。

自动更新

rpi-eeprom-update 的 systemd 服务会在启动时运行，且在新镜像可用时应用更新，自动迁移当前的引导加载程序配置。

要禁用自动更新：

要重新启用自动更新：

注意
如果设置了 FREEZEVERSION 引导加载程序配置，则更新服务将跳过自动更新。这样可以避免在安装了多个操作系统、更换存储卡时逐个禁用更新服务的需要。

`rpi-eeprom-update`

树莓派操作系统使用脚本 rpi-eeprom-update 实现自动更新服务。该脚本还可以通过交互方式运行、进行封装，创建定制的引导加载程序更新服务。

读取当前引导加载程序版本：

检查是否有可用更新：

安装更新：

取消待定更新：

安装特定的引导程序镜像:

参数 -d 让 rpi-eeprom-update 使用指定的镜像文件中的配置，而不是自动迁移当前的配置。

打开自带文档:

引导加载程序发布状态

固件发布状态对应于引导加载程序固件镜像的特定子目录（ /lib/firmware/raspberrypi/bootloader/... ），可以更改以选择不同的发行版本。

default：用于支持新硬件、关键错误修复，并通过在 latest 版本测试过的新功能的定期更新。
latest：当新功能可用时进行更新

由于发布状态字符串仅是一个子目录名，因此你可以创建自己的发行版本，例如固定发行或自定义网络引导配置。

更改启动加载程序版本

注意
你可以通过编辑 /etc/default/rpi-eeprom-update 文件，把条目 FIRMWARE_RELEASE_STATUS 更改为适当的流来更改在更新过程中使用的发布版本。

更新启动加载器配置文件中的启动加载器镜像

以下命令将 pieeprom.bin 中的启动加载器配置替换为 boot.conf 并将新镜像写入 new.bin ：

`recovery.bin`

在开机时，BCM2711、BCM2712 上的 ROM 会在存储卡的启动分区的根目录中查找文件 recovery.bin。如果能找到一个有效的 recovery.bin，那么 ROM 就会执行这个文件，而非读取 EEPROM。该机制可确保始终能对引导加载程序闪存恢复出厂设置。

欲了解更多信息，请参阅 EEPROM 启动流程。

引导加载程序更新文件

文件名

目的

如果引导加载程序更新镜像为 pieeprom.upd，则更新完成后 recovery.bin 会被重命名为 recovery.000，然后系统会重启。由于检测不到 recovery.bin，ROM 将从 SPI 闪存加载新近更新的引导加载程序，然后正常启动操作系统。
如果引导加载程序更新镜像为 pieeprom.bin，那么更新完成后 recovery.bin：如更新成功，HDMI 显示绿屏，绿色状态 LED 快速闪烁；如果更新失败，HDMI 显示红屏，并且通过状态 LED 传递错误代码。

若要获取有关 rpi-eeprom-update 配置文件的更多信息，请参阅 rpi-eeprom-update -h。

EEPROM 写保护

引导加载程序和 VLI EEPROM 都支持硬件写保护。有关如何在更新 EEPROM 时启用此功能的更多信息，请参阅参数 eeprom_write_protect。

树莓派 4 的启动诊断

从树莓派 4 引导加载程序 2020-04-16 版本开始，诊断信息会出现在 HDMI 显示器上。要查看诊断信息，请关闭树莓派 4，拔掉存储卡，然后重启。在接入的显示器上应该会出现类似如下的诊断信息。

该诊断页面也会出现在以下情况：引导加载程序无法引导插入的存储卡、无法进行网络引导；可能因为：存储卡中没有可引导的镜像、存储卡是假冒伪劣产品、网络引导配置错误。

只要显示了诊断页面，就只能通过重新插拔设备电源（即拔掉然后重新插上电源）来重启。

诊断页面最顶部的一行说明了树莓派型号、内存容量。二维码是指向下载页面的链接。

诊断信息如下：

行

信息

可以使用参数 DISABLE_HDMI 禁用此显示器，请参阅引导加载程序配置。

注意
该功能仅用于诊断引导故障；它并非可交互的引导程序。如果你需要交互式引导程序，请考虑使用类似 U-Boot 的工具。

树莓派引导模式

树莓派有多种不同的引导阶段。本文档解释了引导模式的工作原理，以及哪些引导模式支持 Linux 引导。

特殊 `bootcode.bin` 专用启动模式

基于 BCM2837 的树莓派可从 USB 设备和以太网引导 - 也就是说，树莓派 2B v1.2，树莓派 3B 和树莓派 3B+（由于树莓派 3A+ 没有内置以太网接口，无法进行网络引导）。此外，所有早于树莓派 4 的树莓派型号可以使用仅 bootcode.bin 方法启用 USB 设备引导。

注意
自树莓派 4 以降，旗舰级设备不再使用 bootcode.bin 这个文件。因为这些设备使用了板载 EEPROM 芯片中的引导加载程序。更多信息，请参阅 EEPROM 引导流程和 SPI 引导 EEPROM 的文档。

把格式化存储卡为 FAT32，将最新的 bootcode.bin 复制到里面。把存储卡插入到树莓派中。从存储卡加载 bootcode.bin 以后，树莓派就能使用 USB 主机模式启动了。

这对于基于 BCM2835、BCM2836 芯片的树莓派 1、2 和 Zero 型号非常有用，在树莓派 3 无法启动的情况下（同烧录到 BCM2837A0 中的启动代码相比，最新的 bootcode.bin 为树莓派 3B 提供了额外的错误修复）。

若即使使用了这个 bootcode.bin，你的大容量存储设备还是无法使用，请在存储卡上新建一个名为“timeout”的文件。这将使其等待大容量存储设备初始化的时间延长到 6 秒。

启用 `bootcode.bin` 串口

注意
适用于在树莓派 4 发布前的开发板。

有关使用 EEPROM 引导加载程序启用串口的信息，请参阅引导加载程序配置文档。

可以启用早期阶段的串口来调试引导问题（与上述 bootcode.bin 仅引导模式非常有用）。要做到这一点，请确保你的固件版本是新的（包括 bootcode.bin）。要检查当前固件是否支持串口：

要从 bootcode.bin 启用串口：

接下来，将合适的 USB 串口线连接到计算机（尽管你可能会发现，最简单的方法就是使用 USB 串口线，因为它可以在无需设置烦人的 config.txt 的情况下直接使用树莓派）。在树莓派（计算模块）上使用单独的引脚 6、8 和 10（GND、GPIO14、GPIO15）。

然后在 Linux（macOS）上使用 screen。在 Windows 上使用 putty 来连接到串口。

设置串口接收速率为 115200-8-N-1，然后启动你的树莓派。你应该可即时从设备上获得 bootcode.bin 的串行输出。

USB 启动模式

USB 有两种独立的启动模式:

USB 设备启动
USB 主机启动

固件会根据 OTP 位在引导时选择两种模式中的一种。用两位控制 USB 引导。第一位启用 USB 设备引导，为默认设置；第二位启用 USB 主机引导。

如果设置了 USB 主机引导模式位，则处理器会读取 OTGID 引脚来决定是作为主机引导（驱动到零，就像在所有树莓派 A/B+ 上一样）还是作为设备引导（保持漂浮）。树莓派 Zero 通过 USB 连接器可以访问 OTGID 引脚；计算模块可以通过边缘连接器访问 OTGID 引脚。

其他某些 OTP 位可允许某些 GPIO 引脚选择引导模式。

USB 设备引导模式

注意
USB 引导适用于旗舰级的计算模块系列，Zero 系列和衍生的 A 款。

当启用此引导模式（通常在无法从存储卡引导后），树莓派将其置为 USB 设备模式，等待主机发送的 USB 重置。在 Github 上可以找到示例代码，展示主机需如何与树莓派进行通信。

主机首先通过控制端点 0 向设备发送一个结构。这包含了启动的大小和签名（未启用安全性，因此无需签名）。其次，代码通过端点 1 传输（bootcode.bin）。最后，设备将用以下代码之一回复：

0 - 成功
0x80 - 失败

USB 主机引导模式

注意
自树莓派计算模组 3、Zero 系列 2 W、树莓派 2B（1.2 版）、树莓派 3B 以及自树莓派 3B+ 以降，主机引导功能可在计算模块系列和所有旗舰系列设备上使用。树莓派 3A+ 支持大容量存储引导，但不支持网络引导。

USB 主机引导模式采用以下逻辑:

启用 USB 接口并等待 D+ 线拉高，表示连接了 USB 2.0 设备（我们只支持 USB2.0
如果设备是一款集线器：
- 启用所有集线器的下游接口的电源

在树莓派 3B，3A+ 和 3B+ 上，默认禁用主机引导。要启用 USB 主机引导，请将 program_usb_boot_mode=1 这一行添加到 /boot/firmware/config.txt 的末尾。

警告
任何对 OTP 的修改都是永久性的，无法撤销。。在树莓派 3A+ 上，将 OTP 位设置为启用 USB 主机引导模式将永久性地禁止其以 USB 设备模式启动。

USB 大容量存储启动

注意
自计算模块 3，Zero 2 W 起的 Zero 系列，以及自树莓派 2B（版本 1.2）起的所有旗舰系列设备均可使用。

USB 大容量存储启动能让你从 USB 大容量存储设备（如闪存驱动器、USB 磁盘）启动树莓派。在连接 USB 设备时（尤其是硬盘和 SSD），需要注意它们的功耗要求。接入多个磁盘通常需要额外的外部电源，可以是带电源的硬盘盒、带供电的 USB 集线器。

注意
树莓派 4B 之前的型号存在已知问题，导致可能无法从某些 USB 设备启动。

带有 EEPROM 引导加载程序的设备

树莓派 4 和更新款的旗舰系列设备以及自计算模块 4 和 4S 起，支持默认情况下的 USB 引导，只要在 BOOT_ORDER 配置中指定 USB 引导。

注意
早期版本的树莓派 4 可能需要更新引导加载程序才能从 USB 启动。

注意
计算模块 4 的早期版本可能需要更新引导加载程序才能从 USB 启动。

树莓派 3B+

树莓派 3B+ 支持开箱即用的 USB 大容量存储启动。

树莓派 2B，3A+，3B，CM3，CM3+，Zero 2 W

在树莓派 2B v1.2，3A+，3B，Zero 2 W 和计算模块 3 和 3+ 上，必须先启用 USB 主机启动模式。才能从 USB 大容量存储启动和网络启动。

注意
树莓派 3A+ 和 Zero 2 W 不支持网络启动。要启用这些设备的 USB 主机启动模式，请在 OTP（一次可编程）内存中设置 USB 主机位。要设置该位，请从包含以下行的存储卡引导 /boot/firmware/config.txt。设置该位后，你可以在没有存储卡的情况下从 USB 启动。

使用 OTP 启用 USB 主机启动模式

警告
对 OTP（一次可编程）内存所做的一切修改都是永久性的，无法撤销。。在树莓派 3A+ 上，设置 OTP 位来启用 USB 主机启动模式将永久禁止该树莓派以 USB 设备模式启动。

使用内置树莓派系统的存储卡来编程 OTP 位。

要启用 USB 主机启动模式，请将以下行添加到 config.txt 中：

然后使用 sudo reboot 重启你的树莓派。要检查 OTP 是否已正确编程，请运行以下命令：

如果输出显示 0x3020000a，则 OTP 已成功编程。如果看到不同的输出，请再次尝试编程过程。确保 config.txt 末尾没有空行。

你现在可以像从存储卡启动一样从 USB 大容量存储设备启动。有关更多信息，请参阅以下部分。

从 USB 大容量存储设备启动

过程与存储卡相同：把操作系统镜像写入 USB 存储设备。

存储设备准备就绪后，连接驱动器并启动树莓派，需注意外部驱动器的额外 USB 电源需求。

大约 5 到 10 秒后，树莓派应该开始启动了。如果接入的显示器上出现彩虹屏。请确定未将存储卡插入树莓派，因为倘若插入了存储卡，树莓派将优先从存储卡启动。

查阅引导模式文档可了解引导顺序和备选引导模式（网络、USB 设备、GPIO 或存储卡启动）。

已知问题

检查可引导 USB 设备的默认超时时间为 2 秒。某些闪存驱动器和硬盘启动速度过慢。可以将此超时时间延长到 5 秒（需在存储卡中新建文件 timeout），但要注意某些设备可能需要更长时间来响应。
某些闪存驱动器采用了极为罕见的协议，引导码无法处理，因此造成不兼容。

特殊 `bootcode.bin`——仅引导模式

对于树莓派 2B v1.2、3A+、3B 和 3B+，如果你无法使用特定的 USB 设备来启动，你可以使用 bootcode.bin 专用启动模式。树莓派仍会从存储卡启动，但只会从存储卡中读取 bootcode.bin；你操作系统的其余部分仍存储在 USB 设备。

硬件兼容性

在从 USB 大容量存储设备启动之前，请验证该设备在 Linux 下是否正常工作。使用存储卡引导，插入 USB 大容量存储设备。USB 设备应显示为可移动驱动器。这在使用 USB SATA 转换设备时尤其重要，该适配器可能由引导加载程序支持大容量存储模式，但如果 Linux 选择 USB 附加 SCSI-UAS 模式，则有概率不兼容。

使用硬盘驱动器（HDD）通常需要带供电的 USB 集线器。即使一切看起来正常，如果 USB 集线器没带电源，你可能仍会遇到间歇性故障。

多个可引导驱动器

在搜索可引导分区时，引导加载程序会同时扫描所有 USB 大容量存储设备，并选择首个响应的设备。如果引导分区没有找到合适的 start.elf 文件，则引导加载程序将尝试下一个可用设备。没有根据 USB 拓扑结构指定引导设备的方法；这将减缓引导速度，带来不必要的配置复杂性。

注意
可使用 config.txt 文件条件过滤器来选择复杂设备配置中的备用固件。

网络引导

本节描述了树莓派 3B、3B+ 和 2B v1.2 上的网络引导工作原理。

在树莓派 4 和树莓派 5 上，网络引导是在 EEPROM 中的第二阶段引导加载程序中实现的。更多信息，请参阅树莓派 4 引导加载程序配置。

我们还有关于设置网络引导系统的教程。

仅适用于上述型号树莓派中内置的有线适配器进行网络引导。无线局域网引导不受支持，也不支持从其他有线网络设备引导。

网络引导流程

要进行网络引导，引导 ROM 执行以下操作：

初始化板载以太网设备（Microchip LAN9500/LAN7500）
发送 DHCP 请求（使用厂商类别标识符 DHCP 选项 60 设置为 PXEClient:Arch:00000:UNDI:002001)
接收 DHCP 回复

从此刻开始，bootcode.bin 代码继续加载系统。它将尝试访问的第一个文件是 <serial_number>/start.elf。如果这不会导致错误，那么要读取的其他文件将会在前面加上 serial_number。这很有用，因为它使你能够为你的树莓派创建具有不同 start.elf /内核的独立目录。

要获取设备的序列号，你可以尝试使用这种引导模式，并查看使用 tcpdump / wireshark 访问的文件，或者你可以运行标准的树莓派系统存储卡和 cat /proc/cpuinfo。

如果你将所有文件放入 TFTP 目录的根目录中，那么随后所有的文件都将从那里访问。

调试网络引导模式

首先要检查的是 OTP 位是否被正确编程。为此，你需要将 program_usb_boot_mode=1 添加到 config.txt，然后重启（使用可以正确引导到树莓派系统的标准存储卡）。完成后，你应该可以执行以下操作：

如果第 17 行包含 3020000a，则 OTP 已正确编程。现在，你可以拔掉存储卡，插入以太网了，然后在树莓派上电约 5 秒后，以太网指示灯应该被点亮。

要在服务器上捕获以太网数据包，请在 tftpboot 服务器上（如果未使用，则在 DHCP 服务器上）使用 tcpdump。否则，你将无法看到发送的数据包，因为网络交换机不是集线器！

将从 eth0 写入文件 dump.pcap 中的所有内容。然后，你可以对数据包进行后处理或上传到 cloudshark 进行通信。

DHCP 请求/响应

至少你应该看到一个类似以下内容的 DHCP 请求和回复：

Vendor-Option Option 43 包含了回复的重要部分。这个部分必须包含字符串“Raspberry Pi Boot”。由于引导 ROM 中的一个错误，你可能需要在字符串末尾添加三个空格。

TFTP 文件读取

当供应商参数被正确指定时，你将看到随后发送的 TFTP RRQ 数据包。RRQ 可以通过第一个数据块或错误消息来回复，表明文件未找到。在少数情况下，他们甚至会收到第一个数据包，然后由树莓派中止传输（当检查文件是否存在时会发生这种情况）。下面的示例仅包括三个数据包：原始读取请求、第一个数据块（始终是包含一个标头和 512 B 数据的 516 B，尽管最后一个块始终少于 512 B 且可能为零长度），以及第三个数据包（包含与数据块中帧编号匹配的确认帧号）。

已知问题

以太网引导模式有一些已知问题。由于引导模式的实现在芯片本身，除了使用仅包含 bootcode.bin 文件的存储卡外，没有其他解决方法。

DHCP 请求在五次尝试后超时

树莓派将尝试进行五次 DHCP 请求，每次间隔五秒，总共持续 25 秒。如果服务器在此期间无法响应，树莓派将进入低功耗状态。除非使用存储卡上的 bootcode.bin，否则没有解决办法。

不支持在不同子网上的 TFTP 服务器

在树莓派 3B+ (BCM2837B0) 中已修复。

DHCP 中继故障

DHCP 检查还检查了跳数值是否为 1，而在 DHCP 中继情况下，它不会这样。

在树莓派 3A+ 中已修复。

树莓派启动字符串

在 DHCP 回复中，字符串“Raspberry Pi Boot”由于计算字符串长度的错误而需要占用额外三个空格。

在树莓派 3B+ 中已修复。

DHCP UUID 常量

DHCP UUID 设置为常量值。

已在树莓派 3A+ 修复；该值设置为 32 位序列号。

ARP 检查可能在 TFTP 事务中间无法响应

树莓派只会在初始化阶段响应 ARP 请求；一旦开始传输数据，它将无法继续响应。

已在树莓派 3 A+ 修复。

DHCP 请求/回复/确认序列未正确实现

在启动时，树莓派广播 DHCPDISCOVER 数据包。DHCP 服务器回复一个 DHCPOFFER 数据包。然后树莓派继续启动而不执行 DHCPREQUEST 或等待 DHCPACK。这可能导致两个不同设备被提供相同的 IP 地址并在未正确分配给客户端的情况下使用它。

不同的 DHCP 服务器在这种情况下有不同的行为。dnsmasq（取决于设置）将散列 MAC 地址以确定 IP 地址，并 ping 该 IP 地址以确保它尚未被使用。这减少了这种情况发生的机会，因为这需要在散列中发生碰撞。

GPIO 启动模式

注意
GPIO 引导模式仅适用于树莓派 3A+、3B、3B+，计算模块 3、3+。

老的树莓派可以配置：以在接通电源时使用连接到 GPIO 连接器的硬件选择启动模式。这是通过在 SoC 的 OTP 存储器中设置位来完成的。一旦设置了这些位，它们会永久性分配五个 GPIO，以便进行选择。只要设置了 OTP 位，就无法撤销。你应该仔细考虑是否启用此功能，因为这五个 GPIO 针脚将始终控制引导。尽管在树莓派引导后可以使用这些 GPIO 进行其他功能，但你必须进行额外设置，才能在树莓派引导时启用所需的启动模式。

要启用 GPIO 引导模式，请将以下行添加到 config.txt 文件中：

其中 n 是你希望使用的 GPIO 的 bank。然后重启树莓派一次，以使用此设置编程 OTP。Bank 1 是 GPIO 22-26，Bank 2 是 GPIO 39-43。除非你有一个计算模块，否则必须使用 bank 1：Bank 2 上的 GPIO 仅在计算模块上可用。由于 OTP 位的排列方式，如果你首先为 Bank 1 编程 GPIO 引导模式，那么稍后可以选择 Bank 2。反之不成立：一旦选择 Bank 2 作为 GPIO 引导模式，就无法选择 Bank 1。

一旦启用了 GPIO 引导模式，树莓派将不再启动。你必须拉高至少有关一个引导模式的 GPIO 引脚，才能启动树莓派。

引脚分配

树莓派 3B 和计算模块 3

引脚 1

引脚 2

启动类型

以上表格中的 USB 选项同时选择 USB 设备引导模式和 USB 主机引导模式。要使用 USB 引导模式，必须在 OTP 存储器中启用。有关更多信息，请参阅 USB 设备引导和 USB 主机引导。

后续的树莓派 3B（带金属盖的 BCM2837B0）、树莓派 3A+、3B+ 和计算模块 3+

引脚 1

引脚 2

引导类型

注意
各种启动模式按照 GPIO 线的数字顺序尝试，即 SD0，然后 SD1，然后 NAND 等等。

启动流程

SD0 是博通的存储卡/MMC 接口。当 SoC 内部的引导 ROM 运行时，SD0 将始终连接到内置的 microSD 卡。在带有 eMMC 设备的计算模块上，SD0 连接到该设备；在精简版（Lite）计算模块上，SD0 可用于边缘连接器，并连接到 CMIO 载板上的 microSD 卡。SD1 是 Arasan 存储卡/MMC 接口，亦支持 SDIO。所有具有内置无线局域网的树莓派都使用 SD1 通过 SDIO 连接到无线芯片。

GPIO 针脚的默认上拉电阻为 50KΩ，详见 BCM2835 ARM 外围设备数据表第 102 页。推荐使用 5KΩ 的上拉电阻将 GPIO 针脚拉高：这样既可使 GPIO 正常工作，同时不会产生太多功耗。

NVMe 固态硬盘引导

NVMe（非易失性快速存储器）是通过 PCIe 总线进行外部存储访问的标准。你可以通过计算模块 4（CM4）IO 板、树莓派 5 上的 PCIe 槽连接 NVMe 驱动器。再通过一些额外配置，你就可以从 NVMe 驱动器启动了。

准备工作

硬件

NVMe M.2 固态硬盘
一款 PCIe 转标准 M.2 的转接器
- 对于树莓派 5，我们推荐使用 M.2 HAT+，它能把树莓派的 PCIe FFC 槽转换为 M 键（Key）接口。

要检查你的 NVMe 驱动器是否正确连接，请从其他存储设备（如存储卡）引导你的树莓派，并运行 ls -l /dev/nvme*。示例输出如下所示。

软件

运行以下命令可查看你正在运行的固件版本：

对于树莓派 5，你需要使用 2023 年 12 月 6 日及之后发布的固件。

为了 CM4，NVMe 引导支持于 2021 年 7 月引入。你需要自那时起发布的以下版本的软件：

引导加载程序
VideoCore 固件
树莓派系统 Linux 内核

最新的树莓派系统发布包含你所需的一切。使用树莓派镜像制作工具可将树莓派系统镜像安装到你的驱动器上。

编辑 EEPROM 启动顺序

对于树莓派 5，你需要启动树莓派系统以编辑启动顺序。你可以从存储卡或 USB 驱动器启动树莓派来完成此步骤。即使更改启动设备，EEPROM 配置也会持久保留，因为 EEPROM 配置存储在板上本身。

使用树莓派配置命令行界面来更新启动加载程序：

在 Advanced Options > Bootloader Version 下，选择 Latest。然后，单击 Finish 或按 Escape 键 可退出 raspi-config。

运行以下命令可将固件更新至最新版本：

然后，使用 sudo reboot 重启。你的树莓派 5 应该会从 NVMe 启动。

对于 CM4，请使用 rpiboot 更新引导加载程序。你可以在 USB 启动 GitHub 存储库中找到构建 rpiboot 并配置 IO 板切换 ROM 到 usbboot 模式的说明。

对于搭载了 eMMC 的 CM4 版本，请确保你已将 NVMe 设置为引导顺序中的第一项。请记住在 recovery/boot.conf 中将 NVMe 引导模式 6 添加到 BOOT_ORDER 中。

当 SD 卡插槽为空时，CM4 Lite 会自动从 NVMe 引导。

NVMe `BOOT_ORDER`

EEPROM 配置中的 BOOT_ORDER 设置控制引导行为。对于 NVMe 引导，请使用引导模式 6。有关更多信息，请参见树莓派引导加载程序配置。

例子

以下是引导加载程序检测到 NVMe 驱动器时的串口输出示例：

然后它将找到一个 FAT 分区并加载 start4.elf ：

然后加载内核并引导操作系统：

在 Linux 中，SSD 显示为 /dev/nvme0，而在“namespace(命名空间）”中显示为 /dev/nvme0n1。将会有两个分区 /dev/nvme0n1p1 （FAT）和 /dev/nvme0n1p2 （EXT4）。使用 lsblk 来检查分区分配：

故障排除

如果引导过程失败，请在 GitHub 存储库 rpi-eeprom 上提交问题，确保附上控制台输出以及引导过程中所有屏幕显示的内容。

HTTP 引导

网络安装功能使用以太网上的 HTTP 引导树莓派进入嵌入式树莓派启动盘制作工具。

除了网络安装，你还可能用 HTTP 下载的文件显式引导设备启动，即使禁用引导，网络安装也能用。

例如，你可以将这添加到你的 BOOT_ORDER 作为备用引导方法，或者将其放在 GPIO 条件后，在 GPIO 引脚拉低时从你自己的服务器启动 HTTP 引导。

例如，如果将以下内容添加到你的 EEPROM 配置中，且 GPIO 8（默认状态为 1 或高电平）被拉低，将下载文件、。如果启用开机网络安装，则会使用相同的网址。如果 GPIO 8 未被拉低，则行为将保持不变。

boot.img 和签名文件 boot.sig 是个包含引导文件系统的内存盘。详情请参阅 boot_ramdisk。

如果启用安全启动并且未设置 HTTP_HOST，则将忽略 BOOT_ORDER 中的 HTTP。

要求

要使用 HTTP 引导，请更新至 2022 年 3 月 10 日和后续版本的引导程序。HTTP 引导需要有线以太网连接。

要使用定制 CA 证书，请更新至 2024 年 4 月 5 日和后续版本的引导程序。只有运行 BCM2712 CPU 的设备支持才定制 CA 证书。

键

所有 HTTP 下载必须签名。引导加载程序包含一个用于默认主机 fw-download-alias1.raspberrypi.com 上文件的公钥。除非设置了 HTTP_HOST，并在 EEPROM 中内置公钥，否则该密钥将用于验证网络安装镜像。这能让你在自己的服务器上托管树莓派网络安装镜像。

警告
使用你自己的网络安装镜像将需要你对镜像进行签名，并将你的公钥添加到 EEPROM。如果你后续进行了公版 EEPROM 更新，你的密钥将丢失，并且需要重新添加。

USBBOOT 包含了编程公钥所需的全部工具。

使用以下命令将你的公钥添加到 EEPROM。boot.conf 包含你的修改：

使用以下命令可为你的 EEPROM 生成签名：

然后，使用以下命令使用你的私钥对网络安装镜像进行签名：

最后，将 boot.img 和 boot.sig 放在你的网络服务器上，以使用自己签名的网络安装镜像。

证书

为了安全起见，网络安装使用 HTTPS 从树莓派网站下载操作系统镜像。此功能使用我们在引导程序中内置的自有 CA 根证书来验证主机。

你可以将你自己的定制 CA 证书添加到设备的 EEPROM，以安全地从你自己的网站下载镜像。使用工具 rpi-eeprom-config 的参数 --cacertder 能添加 DER 编码的证书。你必须在 EEPROM 配置设置中放置证书的哈希值，以确保证书未经篡改。

运行以下命令生成 DER 编码的证书：

然后，运行以下命令生成证书的 SHA-256 哈希：

应该会看到类似如下输出：

接下来，更新 boot.conf 以包含证书的哈希值：

在 [gpio8=0] 部分配置以下设置，替换为：

将 <你的网站> 替换为你的网站，例如 yourserver.org
将 <文件路径> 替换为托管在你的网站上的操作系统镜像的路径，例如 path/to/files

当你指定 HTTP_CACERT_HASH 时，网络安装将通过 HTTPS 下载镜像。没有哈希时，网络安装将使用 HTTP 下载镜像。

最后，使用以下命令将所有内容加载到 EEPROM 中：

在网络启动过程中，你的树莓派应该使用 HTTPS 而非 HTTP。要查看由网络安装解析的完整的 HTTPS 下载链接，请查看引导输出：

安全启动

如果启用了安全启动，则树莓派只能运行由客户私钥签名的代码。因此，如果你想要在安全启动的情况下使用网络安装、HTTP 启动模式，你必须使用自己的密钥签署 boot.img 并生成 boot.sig，并在某处托管这些文件供下载。EEPROM 中的公钥将用于验证镜像。

如果启用安全启动且未设置 HTTP_HOST，则网络安装和 HTTP 引导将被禁用。

有关安全启动的更多信息，请参阅 USBBOOT。

引导顺序

重要
此启动顺序仅适用于基于 BCM2837、BCM2837B0 的树莓派。在此之前的型号，树莓派将尝试存储卡引导，然后是 USB 设备模式引导。有关树莓派 4 和树莓派 5 的引导顺序，请参阅 EEPROM 引导流程部分。

树莓派 3 上的 USB 引导默认取决于所使用的版本。如果默认未启用 USB 引导模式，请参阅此页面获取有关启用 USB 引导模式的信息。

当 BCM2837 引导时，它使用两个不同的来源来确定要启用哪些引导模式。首先，会检查一次性可编程（OTP）存储器块，看哪些引导模式已启用。如果启用了 GPIO 引导模式设置，则会测试相关的 GPIO 线，以选择应尝试哪个已在 OTP 中启用的引导模式。请注意，GPIO 引导模式仅可用于选择已在 OTP 中启用的引导模式。有关配置 GPIO 引导模式的详细信息，请参阅 GPIO 引导模式。在默认情况下，GPIO 引导模式已禁用。

接下来，启动 ROM 会在每个启动源中检查名为bootcode.bin的文件；如果找到，它会将代码加载到本地 128K 缓存并跳转到该代码。总体启动模式过程如下：

BCM2837 启动
读取 OTP 以确定启用哪些启动模式
如果启用了 GPIO 启动模式，请使用 GPIO 启动模式来细化启用的启动模式列表
如果启用：检查 GPIO 48-53 上的主 SD 是否存在 bootcode.bin

注意
如果没有插入存储卡，SD 引导模式将在 5 秒钟后失败。为了缩短这个时间并更快地切换到 USB 模式，你可以插入空白的存储卡，或者使用上面描述的 GPIO 引导模式 OTP 设置，仅启用 USB。GPIO 的默认拉取在 ARM 外围设备数据手册的第 102 页上有定义。如果引导时的值不等于默认拉取值，则启用该引导模式。USB 枚举是一种使下游设备在集线器上获取电源，然后等待设备拉动 D+ 和 D- 线以指示其是 USB 1 还是 USB 2 的方法。这可能需要一段时间：对于某些设备，硬盘驱动器可能需要长达 3 秒的时间来启动并开始枚举过程。因为这是唯一能检测硬件连接的方法，所以我们必须等待的最短时间为两秒。如果设备在最大超时时间后仍未响应，则可以使用 program_usb_boot_timeout=1 在 config.txt 中增加超时时间至五秒。大容量存储引导优先于以太网引导。不再需要第一个分区是 FAT 分区，因为大容量存储引导将继续搜索第一个分区之外的 FAT 分区。引导 ROM 现在还支持 GUID 分区，并已测试过使用 Mac、Windows 和 Linux 分区的硬盘。使用供应商 ID 0x0424 和产品 ID 0xec00 可以检测 LAN951x，这与独立的 LAN9500 设备不同，后者的产品 ID 是 0x9500/0x9e00。要使用独立的 LAN9500，需要添加 I²C EEPROM 以更改这些 ID 以匹配 LAN951x。

主要存储卡引导模式默认设置为 GPIO 49-53。可以在第二组引脚上从次要存储卡引导，即将次要存储卡连接到 GPIO 引脚。但是，我们尚未启用此功能。

NAND 引导和 SPI 引导模式的确能用，尽管它们还未完全支持 GPU。

USB 设备引导模式在出厂时默认启用，但 USB 主机引导模式只有在 program_usb_boot_mode=1 时才启用。一旦启用，处理器将使用处理器上的 OTGID 引脚的值来在这两种模式之间做出决定。在所有树莓派 B/B+ 上，OTGID 引脚被驱动为 0，因此一旦启用，就只能通过主机模式引导（无法再使用设备模式引导，因为 LAN951x 设备阻挡了路径）。

如果将 OTGID 引脚浮置（例如，插入 PC），则树莓派 Zero 或计算模块将作为 USB 设备引导启动，因此你可以将 bootcode.bin 推入设备中。相关 usbboot 代码可在 GitHub 上找到。

EEPROM 引导流程

自树莓派 4 起，树莓派旗舰设备使用 EEPROM 启动加载程序。与以前的产品相比，主要区别在于第二阶段启动加载程序是从 SPI 闪存 EEPROM 加载，而不是像以前的产品一样从 bootcode.bin 文件加载。

第一阶段启动加载程序

ROM（第一阶段）的引导流程如下：

SoC 上电
读取 OTP（一次性可编程存储器）以确定是否配置了 nRPIBOOT GPIO
如果 nRPIBOOT GPIO 为高电平或 OTP 未定义 nRPIBOOT GPIO

注意
recovery.bin 是一款用于更新引导加载程序 SPI EEPROM 镜像的最小第二阶段程序。

第二阶段引导程序

本节介绍了第二阶段引导程序的高级流程。

请参阅页面以获取有关每种引导模式的更多信息，以及页面以了解此阶段加载的 GPU 固件文件的描述。

初始化时钟和 SDRAM
读取 EEPROM 配置文件
检查 PM_RSTS 寄存器以确定是否请求 HALT

树莓派 5 的不同

电源按钮用于从 PMIC STANDBY、HALT 唤醒，而非 GPIO 3。
固件加载 start.elf 而不是 start.elf。实际上，引导加载程序内置了嵌入版本的 start.elf。
连接到 3A 电源时，默认禁用 USB 启动。在 /boot/firmware/config.txt

引导加载程序更新

如果找到 pieeprom.upd 文件，固件启动之前也可以更新引导加载程序。有关引导加载程序更新的更多信息，请参阅引导加载程序 EEPROM 页面。

安全模式操作系统更新（tryboot ）

引导加载程序/固件提供了一个一次性标志，如果设置了该标志，会清除，但会导致加载 tryboot.txt 而不是 config.txt。这种备用配置将指定待处理的操作系统更新固件、cmdline、内核和 os_prefix 参数。因为在启动固件之前清除了该标志，所以崩溃或重置会导致在下次重启时加载原始的 config.txt 文件。

要设置 tryboot 标志，请在 reboot 命令中的分区号后添加 tryboot。通常，分区号默认为 0。但如果要添加额外的参数，则必须指定分区号。传递参数给 reboot 时始终使用引号：它只接受一个参数：

所有树莓派型号都支持 tryboot，但是在树莓派 4 A 1.0 版本和 1.1 版本上，EEPROM 不能被写保护。这是因为旧款树莓派 4B 设备必须重置电源供应（会丢失 tryboot 状态），而这些信息正存储在 EEPROM。

若启用安全启动，则 tryboot 模式将导致加载 tryboot.img 而不是 boot.img。

`tryboot_a_b` 模式

如果 autoboot.txt 中的 tryboot_a_b 属性设置为 1，则加载的是 config.txt 而不是 tryboot.txt。这是因为在更高级别（分区）已经进行了 tryboot 切换，因此在备用分区本身内部不需要具有 tryboot.txt 文件。

当从内置的 boot.img 镜像加载文件，tryboot_a_b 属性会被隐式设置为 1。

树莓派引导加载程序配置

编辑配置

在编辑引导加载程序配置之前，请更新你的系统以获取 rpi-eeprom 软件包的最新版本。

要查看当前的 EEPROM 配置，请运行以下命令：

要编辑当前的 EEPROM 配置并将更新应用于最新的 EEPROM 版本，请运行以下命令：

关于 EEPROM 更新过程的更多信息，请参阅启动 EEPROM。

配置属性

本节描述引导加载程序中所有可用的配置项。语法与 config.txt 相同，但属性是特定于引导加载程序的。条件过滤器也受支持，除了 EDID 之外。

`BOOT_UART`

如果 1 则启用 GPIO 14 和 15 上的 UART 调试输出。将接收调试终端配置为 115200bps，8 位，无奇偶校验位，1 个停止位。

默认: 0

`UART_BAUD`

仅适用于树莓派 5。

更改引导加载程序 UART 的波特率。

支持的值: 9600、19200、38400、57600、115200、230400、460800、921600

默认: 115200

`WAKE_ON_GPIO`

若为 1 则 sudo halt 将在较低功耗模式下运行，直到 GPIO3 或 GLOBAL_EN 短接至地。

在树莓派 5 上，此设置并不相关，因为专用电源按钮可以始终用于唤醒来自 HALT 或 STANDBY。

默认: 1

`POWER_OFF_ON_HALT`

如果 1 和 WAKE_ON_GPIO=0，那么 sudo halt 将关闭所有电源管理芯片（PMIC）输出。这是 halt 的最低功耗状态，但可能会导致某些扩展板出现问题，因为 5V 仍将处于开启状态。GLOBAL_EN 必须短接地来启动。

树莓派 400 有一个专用的电源按钮，即使处理器关闭也能工作。这个功能默认启用，但可设置 WAKE_ON_GPIO=2 来使用外部 GPIO 电源按钮，而不是专用电源按钮。

在树莓派 5 上，这将把 PMIC 置于 STANDBY 模式，其中所有输出都被关闭。无需设置 WAKE_ON_GPIO，按下专用电源按钮将启动设备。

默认: 0

`BOOT_ORDER`

BOOT_ORDER 设置能对不同启动模式的优先级进行灵活配置。它表示为一个 32 位无符号整数，其中每个半 B 代表一个启动模式。启动模式按照从最低有效半 B 到最高有效半 B 的顺序尝试。

BOOT_ORDER 字段

BOOT_ORDER 属性定义了不同引导模式的顺序。它是从右到左读取的，最多可以定义八位数字。

值

模式

说明

RPIBOOT 与计算模块 4 同时使用，加载自定义调试镜像（例如，Linux RAM-disk）而不是正常的引导。这应该是最后的引导选项，因为它目前不支持超时或重试。

BOOT_ORDER 示例

`MAX_RESTARTS`

如果遇到 0xf 重启 ( RESTART ) 引导模式超过 MAX_RESTARTS 次数，则会触发看门狗复位。不建议一般使用这个，但在需要完全重置以解决硬件/网络接口故障的测试和远程系统上可能会有用。

默认值： -1 (无限)

`SD_BOOT_MAX_RETRIES`

在移动到由 BOOT_ORDER 定义的下一个引导模式之前，在 SD 引导失败后重试的次数。

-1 意味着无限重试。

默认值: 0

`NET_BOOT_MAX_RETRIES`

失败后在移动到下一个由 BOOT_ORDER 定义的引导模式之前，网络引导将重试的次数。

-1 表示无限重试。

默认： 0

`DHCP_TIMEOUT`

整个 DHCP 序列在失败当前迭代之前的超时时间（毫秒）。

最小值: 5000

默认值: 45000

`DHCP_REQ_TIMEOUT`

DHCP DISCOVER 或 DHCP REQ 重试之前的超时时间（毫秒）。

最小值: 500

默认值: 4000

`TFTP_FILE_TIMEOUT`

通过 TFTP 单个文件下载的超时时间（毫秒）。

最小值: 5000

默认值: 30000

`TFTP_IP`

可选的点分十进制 IP 地址（例如 192.168.1.99）用于 TFTP 服务器，覆盖来自 DHCP 请求的服务器 IP。

在家庭网络上，可能会发现这很有用，因为可以使用 tftpd-hpa 代替 dnsmasq，其中宽带路由器是 DHCP 服务器。

默认： ""

`TFTP_PREFIX`

为了让每个树莓派都有唯一 TFTP 启动目录，引导加载程序会将文件名前缀添加到特定于设备的目录。如果在带前缀的目录中找不到 start4.elf/start.elf，则会清除前缀。

在早期型号上，序列号被用作前缀，但在树莓派 4 和 5 上，MAC 地址不再由序列号生成，这使得通过检查 DHCPDISCOVER 包自动创建 tftpboot 目录在服务器上变得困难。为了方便，TFTP_PREFIX 可以定义为 MAC 地址、固定值或序列号（默认）。

值

描述

默认值: 0

`TFTP_PREFIX_STR`

当 TFTP_PREFIX 设置为 1 时，指定用于自定义目录前缀的字符串。例如：TFTP_PREFIX_STR=tftp_test/

默认值: ""

最大长度：32 个字符

`PXE_OPTION43`

使用不同的字符串覆盖 PXE Option43 匹配字符串。通常最好将定制应用于 DHCP 服务器，而不是更改客户端行为，但在无法进行更改的情况下提供此选项。

默认：Raspberry Pi Boot

`DHCP_OPTION97`

在之前的版本中，客户端 GUID（Option97）只是将序列号重复四次。默认情况下，新的 GUID 格式为四字符码（FourCC）的串联（RPi4 0x34695052 适用于树莓派 4 或 RPi5 0x35695052 适用于树莓派 5），板子版本（例如 0x00c03111、0x00d04170）（4 B），MAC 地址的最低有效 4 B 以及 4 B 的序列号。这旨在是独一无二的，同时也向 DHCP 服务器提供结构化信息，使得可以识别树莓派 4 和 5 计算机，而无需依赖以太网 MAC OUID。

指定 DHCP_OPTION97=0 可恢复旧行为，或指定非零十六进制值以指定自定义的 4 字节前缀。

默认值： 0x34695052

`MAC_ADDRESS`

用给定的值覆盖树莓派以太网 MAC 地址。例如 dc:a6:32:01:36:c2

默认： ""

`MAC_ADDRESS_OTP`

使用存储在客户 OTP 寄存器中的值覆盖树莓派以太网 MAC 地址。

例如，要使用存储在 Customer OTP 的行 0 和 1 中的 MAC 地址。

第一个值（例如中的第 0 行）包含 OUI 和 MAC 地址的最高 8 位。第二个值（例如中的第 1 行）存储 MAC 地址的剩余 16 位。这与在制造时用于树莓派 MAC 地址的格式相同。

可以选择并以任意顺序组合任意两个客户行。

Customer OTP 行是 OTP 寄存器 36 到 43，在 vcgencmd otp_dump 输出中，所以如果前两行被编程如下，则 MAC_ADDRESS_OTP=0,1 就会给出一个 MAC 地址为 e4:5f:01:20:24:7e。

默认值： ""

静态 IP 地址配置

如果设置了 TFTP_IP 和以下选项，则跳过 DHCP，并应用静态 IP 配置。如果 TFTP 服务器与客户端在同一子网上，则可省略网关（GATEWAY）。

CLIENT_IP

客户端的 IP 地址，例如 192.168.0.32

默认： ""

SUBNET

子网地址掩码，例如 255.255.255.0

默认： ""

GATEWAY

如果 TFTP 服务器位于不同子网上，则要使用的网关地址，例如 192.168.0.1

默认： ""

`DISABLE_HDMI`

如果 DISABLE_HDMI=1，HDMI 启动诊断显示将被禁用。其他非零值保留供将来使用。

默认： 0

`HDMI_DELAY`

跳过 HDMI 诊断显示，最多 N 秒（默认值 5）,除非发生致命错误。默认行为旨在避免在正常 SD/USB 引导时，引导加载程序诊断屏幕短暂出现。

默认: 5

`ENABLE_SELF_UPDATE`

启用引导加载程序从 TFTP/USB 大容量存储设备（MSD）引导文件系统中更新自身。

如果自更新已启用，则引导加载程序将在引导文件系统中查找更新文件（.sig/.upd）。如果更新镜像与当前镜像不同，则应用更新并重置系统。否则，如果 EEPROM 镜像是逐字节相同的，则引导将继续正常进行。

注：

2021 年之前的引导加载程序版本不支持 self-update。
2022 年之前，SD 启动中未启用自更新功能。在树莓派 4 上，ROM 已经可以从存储卡加载 recovery.bin。在 CM4 上，自更新和 recovery.bin 均不生效，需要使用 USB 启动（请参阅计算模块 EEPROM 引导程序文档）。

默认值: 1

`FREEZE_VERSION`

以前，此属性仅由 rpi-eeprom-update 脚本检查。但是，现在自更新已启用，引导加载程序还将检查此属性。如果设置为 1，则将覆盖 ENABLE_SELF_UPDATE 以停止自动更新。要禁用 FREEZE_VERSION，你必须使用带有 recovery.bin 的存储卡引导。

自定义 EEPROM 更新脚本也必须检查此标志。

默认： 0

`HTTP_HOST`

如果启动网络安装或 HTTP 引导，则会从此服务器下载 boot.img 和 boot.sig。

无效的主机名将被忽略。它们应仅包含小写字母数字字符和 - 或 .。如果设置了 HTTP_HOST，则将禁用 HTTPS 并改用普通的 HTTP。你可以指定 IP 地址以避免 DNS 查找的需要。在主机名中不要包含 HTTP 方案及正斜杠。

默认: fw-download-alias1.raspberrypi.com

`HTTP_PORT`

你可以使用此属性来更改用于网络安装和 HTTP 引导的端口。当使用默认主机 fw-download-alias1.raspberrypi.com 时，启用 HTTPS。如果更改了 HTTP_HOST，则禁用 HTTPS 并使用普通 HTTP。

当禁用 HTTPS 时，即使将 HTTP_PORT 更改为 443，仍将使用普通 HTTP。

默认值：如果启用 HTTPS，则为443，否则为80

`HTTP_PATH`

用于网络安装和 HTTP 引导的路径。

区分大小写。路径分隔符使用正斜杠（Linux 样式）。前导和尾部的正斜杠不是必需的。

如果未设置 HTTP_HOST，则忽略 HTTP_PATH，URL 将为 https://fw-download-alias1.raspberrypi.com:443/net_install/boot.img。如果设置了 HTTP_HOST，URL 将为 http://<HTTP_HOST>:<HTTP_PORT>/<HTTP_PATH>/boot.img

默认值：net_install

`IMAGER_REPO_URL`

嵌入式树莓派制造者应用程序会在启动时下载一个 JSON 文件进行配置。

你可以更改内嵌的树莓派制作程序应用程序使用的 JSON 文件的网址，以便提供你自己的镜像。你可以通过参数 --repo 传递网址来测试标准的树莓派制作程序应用程序。

默认： http://downloads.raspberrypi.org/os_list_imagingutility_v3.json

`NET_INSTALL_ENABLED`

当启用网络安装时，如果检测到了键盘，引导加载程序会在启动时显示网络安装界面。

为了启用网络安装，请添加 NET_INSTALL_ENABLED=1，或者为了禁用网络安装，请添加 NET_INSTALL_ENABLED=0。

如果设置 DISABLE_HDMI=1，则此设置将被忽略，网络安装将被禁用。

为了检测键盘，网络安装必须初始化 USB 控制器并枚举设备。这会增加约 1 秒的启动时间，因此在某些嵌入式应用中禁用网络安装可能更为有利。

在树莓派 4 和树莓派 400 上默认为 1，在计算模块 4 上为 0。

`NET_INSTALL_KEYBOARD_WAIT`

如果启用了网络安装，则引导加载程序会尝试检测键盘和按 SHIFT 键以启动网络安装。你可以使用此属性更改此等待时间的长度（以毫秒为单位）。

将此设置为 0 将禁用对键盘的等待，尽管如果找不到引导文件且 USB 引导模式为 4 且处于 BOOT_ORDER 中，则仍可以启动网络安装。

注意
测试表明检测键盘和 SHIFT 至少需要 750 毫秒。

默认: 900

`NETCONSOLE` - 高级日志记录

NETCONSOLE 复制调试消息到网络接口。IP 地址和接口由 NETCONSOLE 字符串定义。

注意
NETCONSOLE 阻塞，直到以太网连接建立或超时发生。超时值为 DHCP_TIMEOUT，尽管除非请求网络引导，否则不会尝试 DHCP。

格式

有关更多信息，请参阅 Netconsole 文档。

为了简化解析，引导加载程序要求每个字段分隔符都存在。必须指定源 IP 地址，但以下字段可以留空并分配默认值。

src_port - 6665
dev_name - "" (设备名称始终被忽略)
dst_port - 6666
dst_ip - 255.255.255.255

通过将测试树莓派 4 连接到运行 WireShark 的另一个树莓派，并选择“udp.srcport == 6665”作为过滤器，然后选择分析 → 跟随 → UDP 数据流以 ASCII 日志形式查看数据的一种方式。

默认情况下不应启用 NETCONSOLE，因为这可能会导致网络问题。可以通过 GPIO 过滤器按需启用。

默认: "" (未启用)

最大长度: 32 个字符

`PARTITION`

如果未显式地由 reboot 命令 (例如 sudo reboot N) 或 boot_partition=N 在 autoboot.txt 中设置，则可以使用 PARTITION 选项来指定引导分区号。用户可以按下按钮来从救援分区启动。

默认值: 0

`PSU_MAX_CURRENT`

仅适用于树莓派 5。

如果设置，该参数指示固件跳过 USB 供电握手，并假定连接到了具有给定电流等级的电源。通常设置为 3000（小电流电源）或 5000（大电流电源）。

默认: ""

`USB_MSD_EXCLUDE_VID_PID`

一个包含最多四个 VID/PID 对的列表，指定引导加载程序应忽略的设备。如果这与 HUB 匹配，则该 HUB 不会被枚举，导致所有下游设备被排除。这旨在允许在引导枚举期间忽略有问题的设备（例如，枚举速度非常慢）。这是引导加载程序特有的，并不传递给操作系统。

格式是一个以 VID 为最高有效半字节的十六进制值的逗号分隔列表。不允许有空格。例如 034700a0,a4231234

默认值： ""

`USB_MSD_DISCOVER_TIMEOUT`

如果在此超时期间未找到 USB 大容量存储设备，则停止 USB-MSD 并选择下一个引导模式。

最小值： 5000 （5 秒）

默认: 20000 (20 秒)

`USB_MSD_LUN_TIMEOUT`

在前进到下一个 LUN 之前等待的毫秒数，例如多槽 SD-CARD 读卡器。这仍在调整中，但可能有助于加快启动速度，如果连接了旧、慢设备以及包含 OS 的快速 USB-MSD 设备。

最小值: 100

默认: 2000 (2 秒)

`USB_MSD_PWR_OFF_TIME`

仅适用于树莓派 4。

在树莓派重启时，硬件会关闭 USB 电源。短暂的断电时间可能会导致某些 USB 设备出现问题，因此可以使用此参数强制执行较长的断电时间，就像在物理上拔掉电线一样。

在树莓派 4 版本 1.3 及更早版本上，要配置长关机需要启用 XHCI 控制器，因此实际上会先进行短关机，然后是较长的可配置关机。通过将此参数设置为 0，可以跳过较长的可配置关机。

在更新的版本中，硬件会确保 USB 电源在重启后关闭，引导加载程序仅在此经过超时后才启用电源。这是在内存初始化后发生的，确保 USB 电源至少被断开 2 秒。因此，此参数一般对新的硬件版本没有影响。

最小值： 0

最大值: 5000

默认值: 1000 (1 秒)

`USB_MSD_STARTUP_DELAY`

如果定义了，那么在 USB 主控制器初始化后，延迟给定的超时时间进行 USB 枚举。如果 USB 硬盘驱动器需要很长时间初始化，随即触发 USB 超时，那么可以使用此延迟给驱动程序额外的初始化时间。可能还需要增加总体 USB 超时时间 ( USB_MSD_DISCOVER_TIMEOUT )。

最小值: 0

最大值: 30000 (30 秒)

默认值: 0

`VL805`

仅适用于计算模块 4。

如果 VL805 属性设置为 1，则引导加载程序将搜索 VL805 PCIe XHCI 控制器，并尝试使用嵌入在引导加载程序 EEPROM 中的 VL805 固件进行初始化。这使得工业设计可以使用 VL805 XHCI 控制器而无需提供专用的 SPI EEPROM 来存储 VL805 固件。

在计算模块 4 上，引导加载程序永远不会写入专用的 VL805 SPI EEPROM。此选项仅配置控制器从 SDRAM 加载固件。
如果 VL805 XHCI 控制器有专用的 EEPROM，请勿使用此选项。它将无法初始化，因为 VL805 ROM 将尝试使用专用的 SPI EEPROM（如果已安装）。
嵌入式 VL805 固件假定与树莓派 4B 相同的 USB 配置（两个 USB 3.0 端口和四个 USB 2.0 端口）。不支持加载替代的 VL805 固件镜像，应该改用专用的 VL805 SPI EEPROM 来替换这样的配置。

默认: 0

`XHCI_DEBUG`

此属性是一个位字段，用于控制 USB 调试消息在大容量存储引导模式下的冗长程度。启用所有这些消息会生成大量日志数据，会降低启动速度，甚至可能导致启动失败。对于详细日志，最好使用 NETCONSOLE。

值

日志

要合并值，请将它们相加。例如：

默认： 0x0 （未启用 USB 调试消息）

`[config.txt]` 部分

在读取 config.txt GPU 固件 start4.elf 后，读取引导加载程序 EEPROM 配置并检查是否存在名为 [config.txt] 的部分。如果 [config.txt] 部分存在，则将从此部分开头到文件末尾的内容附加到内存中，以便与从引导分区读取的 config.txt 文件的内容组合。这可用于自动应用设置到每个操作系统，例如 dtoverlays。

警告
如果你配置引导加载程序时出现无法引导的无效配置，则必须重新刷新引导加载程序 EEPROM 为有效配置以引导。

技巧
一些配置属性存储在 config.txt 中。有关这些属性的更多信息，请参阅配置属性。

显示并行接口 (DPI)

在树莓派上使用 DPI 显示器

40 针通用输入/输出（GPIO）连接器可用于将显示并行接口（DPI）显示器连接到树莓派设备，作为使用专用显示串行接口（DSI）或高清多媒体接口（HDMI）的替代方案。

所有带有 40 针排针和计算模块的树莓派板都提供了高达 24 位并行 RGB 接口。此接口允许将并行 RGB 显示器连接到树莓派的 GPIO，无论是在 RGB24（每种红、绿和蓝色各 8 位）还是 RGB666（每种颜色 6 位）或 RGB565（5 位红色，6 位绿色和 5 位蓝色）模式下。

此接口由 GPU 固件控制，并可以通过用户通过特殊 config.txt 参数和启用正确的 Linux 设备树叠加层来进行编程。

GPIO 引脚

树莓派 GPIO 的 Bank 0 上可选择的一个替代功能是 DPI（显示并行接口），这是一个简单的时钟并行接口（最多可提供 R、G 和 B 的 8 位；时钟、使能、水平同步和垂直同步）。此接口在 GPIO Bank 0 上作为替代功能 2（ALT2）可用：

GPIO

ALT2

注意
DPI 输出引脚上的颜色值可以以 565、666 或 24 位模式显示（请参阅下表和参数 output_format 的 dpi_output_format 部分）的多种方式：

禁用其他 GPIO 外设

必须禁用使用冲突 GPIO 引脚的所有其他外设叠加层。在 config.txt 中，请注意注释/关闭所有已启用的 I²C/SPI dtparams：

配置显示器

内核模式设置（KMS）通用显示接口使输出能够接入任意显示器，只要你有合适的驱动程序。

自动检测

自动检测能让你的树莓派与显示器连接，而无需手动配置设备树叠加层。在默认情况下已启用自动检测。你可以通过将以下行添加到 config.txt 来启用显示器自动检测：

用 0 替换 1 可禁用自动检测。当你连接启用自动检测的官方树莓派显示器时，KMS 会自动确定显示器，配置适当的显示设置。

手动配置显示器

注意
在树莓派系统 Bookworm 及更高版本中，先前用于设置 DPI 的 dpi_output_format 和 dpi_timings 条目已被叠加层 vc4-kms-dpi-generic 取代。

要使用除树莓派官方显示屏之外的其他显示屏，必须在配置文件中指定 dtoverlay 条目。面板制造商应在 Linux 内核代码中配置你的显示屏的时序，并提供叠加层来启用这些设置。请参阅 Adafruit Kippah 显示屏条目获取示例。以下示例演示如何在你的 txt 文件中为 Kippah 显示屏设置 dtoverlay 条目：

显示是时序通常在内核中定义，但你也可以在提供的 BSD 驱动程序中定义它们。如果你的面板在内核代码中缺乏定义的叠加层，则可以使用 BSD 驱动程序将显示定时定义为参数。这使你能够为显示屏手动配置设备树条目。

以下示例演示如何使用设备树参数定义定时：

注意
设备树行长度不得超过 80 个字符。当设置的行需要超过 80 个字符时，请将该参数的赋值拆分为多行。

参数显示树定义支持以下参数:

选项

说明

GPIO 和 40 脚排针

你可以在所有当前的树莓派主板上找到一个 40 脚 GPIO（通用输入/输出）排针。主板上所有的 GPIO 排针间距均为 0.1 英寸（2.54 mm）。

注意
有 “H”后缀的 Zero 和 Pico 不带排针。

通用 I/O (GPIO) 引脚可配置为通用输入、通用输出，或者最多六种特殊交替设置之一，其功能取决于引脚。

注意
GPIO 引脚编号方案不按数字顺序排列。GPIO 引脚 0 和 1 位于板上（物理引脚 27 和 28），但保留供高级用途。

输出

作为输出引脚指定的 GPIO 引脚可以设置为高电平（3.3V）/低电平（0V）。

输入

作为输入引脚指定的 GPIO 引脚可以读取为高电平（3.3V）/低电平（0V）。使用内部上拉/下拉电阻器可以更轻松地实现其功能。GPIO2 和 GPIO3 引脚内置上拉电阻器，但对于其他引脚，可以在软件中进行配置。

查看树莓派的 GPIO 引脚布局

可以通过打开终端窗口并运行命令 pinout 在树莓派上访问 GPIO 参考。此工具由 GPIO Zero Python 库提供，在树莓派系统中预装。

警告
尽管把简单的组件接入 GPIO 引脚是安全的，但要小心线路的连接方式。应该用电阻限制流经 LED 的电流。不要给 3.3V 的组件用 5V。不要把电机直连到 GPIO 引脚，应该使用 H 桥电路、电机控制板。

权限

为了使用 GPIO 接口，你的用户必须是 gpio 组的成员。默认用户账户已经如此，但对于其他用户，你须使用以下命令手动加入：

GPIO 引脚

BCM2835 封装的 GPIO 在外设数据表中有时被称为“pads”，这是一个半导体设计术语，即“连接到外部世界的芯片”。

这些 pads 是可配置的 CMOS 推挽输出驱动器/输入缓冲器。可用于寄存器控制设置的包括：

内部上拉/下拉使能/失能
输出驱动强度
输入施密特触发器滤波

上电状态

所有 GPIO 引脚在上电复位时恢复为通用输入。还应用了默认拉电状态，详细信息请参阅 Arm 外设数据手册中的备用功能表。大多数 GPIO 引脚都应用了默认拉电。

中断

每个 GPIO 引脚在配置为通用输入时，可以配置为 Arm 的中断源。可配置多个中断产生源：

边沿敏感（高/低）
上升/下降沿
异步上升/下降沿

水平中断会保持中断状态，直到系统软件清除该中断（例如通过处理产生中断的附加外围设备）。

普通的上升/下降沿检测在检测中内置了少量的同步。在系统时钟频率下，引脚在三个周期窗口内采样，生成中断的标准是在稳定的转换中，即记录为 1 0 0 或 0 1 1。异步检测绕过此同步，以便检测非常窄的事件。

备用功能

几乎所有的 GPIO 引脚的功能都能被修改。SoC 内部的外设模块可以选择出现在一组 GPIO 引脚中的一个及多个上，例如，I²C 总线可以配置为至少三个独立位置之一。当引脚配置为替代功能时，例如，控制驱动强度或施密特触发器等仍然适用。

大部分功能适用于所有引脚，个别仅适用于特定引脚：

PWM（脉冲宽度调制）
- 所有引脚都支持软件 PWM
- GPIO12、GPIO13、GPIO18、GPIO19 支持硬件 PWM

电压规格

主板上有两个 5V 针脚、两个 3.3V 针脚，以及一些接地针脚（GND），这些不能被重新配置。剩余的针脚都是通用的 3.3V 针脚，意味着输出被设置为 3.3V，输入是 3.3V 兼容的。

下表列出了针对 BCM2835、BCM2836、BCM2837 和 RP3A0 系列产品（例如树莓派 Zero 或树莓派 3+）的 GPIO 针脚的各种电压规格。有关计算模块的信息，请参阅相应的数据表。

符号

参数

条件

最小

典型

最大

单元

①: 滞后效应已启用

②: 默认驱动强度 (8mA)

③: 最大驱动强度 (16mA)

下表显示了 BCM2711 系列产品（例如树莓派 4、400）上 GPIO 引脚的电压规格。有关计算模块的信息，请参阅相关数据表。

符号

参数

条件

最小值

典型

最大

单元

①: 滞后效应已启用

②: 默认驱动强度 (4mA)

③: 最大驱动强度 (8mA)

GPIO 控制器

GPIO 驱动强度并不表示最大电流，仅表示在此电流下 pad 仍将符合规范。你应该设置 GPIO 驱动强度以匹配所连接的设备，以便设备能够正常工作。

控制驱动强度

在 pad 内部有多个并联驱动器。如果将驱动强度设置为低（0b000），则大多数驱动器将处于三态状态，因此不会对输出电流产生影响。如果增加驱动强度，则会并联更多驱动器。图表显示了该行为。

警告
对于树莓派 4、400，计算模块 4，当前级别是图表中显示数值的一半。

当前数值

当前数值指定了在此电路板仍能满足规范的最大电流。

当前值不是垫片将提供的电流，也不是电流限制。

触点片输出是一个电压源：

如果设置为高电平，触点片将尝试将输出驱动到电源电压（3.3V）

该触点将尝试将输出引至高电平/低电平。成功取决于所连接设备的要求。如果该触点短接至地线，则无法输出高电平。它将尽可能输送尽可能多的电流，电流仅受内部电阻限制。

如果该触点输出高电平且短接至地线，在一段时间后将损坏。如果你将其连接至 3.3V 并输出低电平同样也是如此。

符合规格是由保证的电压水平确定的。由于引脚是数字的，因此有两个电压级别，高电平和低电平。I/O 接口有两个处理输出电平的参数：

Vᴏʟ，最大低电平电压（在 3.3V VDD IO 时为 0.14V）
Vᴏʜ，最小高电平电压（在 3.3V VDD IO 时为 3.0V）

Vᴏʟ=0.14V 意味着如果输出为低电平，则电压将 <= 0.14V。Vᴏʜ=3.0V 意味着如果输出为高电平，则电压将 >= 3.0V。

例如，驱动强度为 16mA 表示如果你将端口设置为高电平，可以吸收高达 16mA 电流，并且输出电压保证 >=Vᴏʜ。这也意味着，如果你将驱动强度设置为 2mA，但吸收了 16mA 电流，则电压将不会达到 Vᴏʜ，而会更低。事实上，可能不足以被外部设备识别为高电平。

GPIO 引脚的物理特性有更多信息。

注意
在计算模块设备上，可以将 VDD IO 从标准的 3.3V 更改。在这种情况下，Vᴏʟ 和 Vᴏʜ 将根据 GPIO 部分的表格进行更改。

树莓派的 3.3V 电源为每个 GPIO 引脚的设计最大电流是 ~3mA。如果你将每个引脚的负载设定为 16mA，则总电流为 272mA。在此负载水平下，3.3V 电源将崩溃。会引发大电流脉冲，特别是如果有电容负载。脉冲将在附近的其他引脚之间反弹。这可能会对存储卡乃至内存行为造成干扰。

安全电流

所有的键盘的电子元件均设计为 16mA。这是一个安全值，在此范围内你不会损坏设备。即使你将驱动强度设置为 2mA，然后负载为 16mA，也不会损坏设备。除此之外的最大安全电流都不保证。

GPIO 地址

0x 7e10 002c PADS (GPIO 0-27)
0x 7e10 0030 PADS（GPIO 28-45）
0x 7e10 0034 PADS（GPIO 46-53）

位

字段名称

说明

类型

复位

请当心同时切换输出（SSO）限制，这些限制取决于设备以及 PCB 的质量和布局，去耦电容器的数量和质量，触点子上的负载类型（电阻，电容）以及树莓派无法控制的其他因素。

驱动强度列表

0 = 2mA
1 = 4mA
2 = 6mA
3 = 8mA

树莓派的工业用途

树莓派经常被用作其他产品的组件。本文档介绍了一些额外的功能，以便于使用你树莓派的其他功能。

一次性可编程设置

在树莓派开发板计算机上使用一次性可编程内存

所有树莓派单板计算机（SBC）都内置了一次编程（OTP）存储器区域，实际上是主片上的一部分。正如其名称（one-time，一次性）暗示的那样，OTP 存储器只能被写入一次（即二进制 0 只能改为 1）。一旦某位置 1，就永远无法恢复为 0。可将 OTP 的每一位都视为一根保险丝。对其进行编程即代表有意地熔断保险丝：这是一种不可逆的过程，因为你无法进入芯片内部去替换它！

本白皮书假定树莓派正在运行树莓派操作系统（OS），并且已完全更新最新固件和内核。

有许多可以使用的 OTP 值。要查看所有 OTP 值的列表，请运行以下命令：

这个转储中的一些有趣的行：

28 - 序列号
29 - 序列号的补码
30 - 板子修订号码

此外，从 36 到 43（包括 36 和 43），有八行 32 位供客户使用。

注意
在 BCM2712 设备上，这些数字是不同的。第 31 行是序列号，第 32 行是板子修订号码。客户行是 77 到 84（包括 77 和 84）。

一些这些行可以使用 vcmailbox 进行编程。这是一个 Linux 驱动程序界面，用于处理行的编程。要执行此操作，请参考文档和 vcmailbox 示例应用程序。

vcmailbox 应用程序可以直接在树莓派系统的命令行上使用。一个示例用法是：

...会返回类似于：

以上使用邮箱属性接口 GET_BOARD_SERIAL，请求大小为 8 B，响应大小为 8 B（发送两个整数作为请求 0,0）。对此的响应将是两个整数（0x00000020 和 0x80000000），后跟标签代码、请求长度、响应长度（第 31 位设为 1 表示它是响应），然后是 64 位序列号（其中最高 32 位始终为 0）。

编写和读取客户 OTP 值

警告
OTP 值是一次性可编程的。一旦将位从 0 更改为 1，则无法改回。

要设置定制 OTP 值，你需要使用 SET_CUSTOMER_OTP (0x38021) 标签如下：

start_num = 要从 0-7 编程的第一行
number = 要编程的行数
value = 每个值到程序

因此，要将 OTP 客户行 4、5 和 6 编程为分别为 0x11111111、0x22222222、0x33333333，你将使用：

然后将会编程第 40、41、42 行。

要读回值，你可以使用：

这应该显示：

如果你想将此功能集成到你自己的代码中，你应该能够通过使用 vcmailbox.c 代码作为示例来实现这一点。

在非 BCM2712 设备上锁定 OTP

可以锁定 OTP 更改，以避免它们再次被编辑。

这可以通过使用带有 OTP 写邮箱的特殊参数来完成。

只要锁定，客户 OTP 值就无法修改。请注意，这个锁定操作是不可逆的。

在 BCM2712 设备上锁定 OTP

可以使用以下命令将客户区域标记为只读。

一次性密码仅在设备重置前锁定，因此每次启动时都需要重新应用一次性密码锁定。

使非 BCM2712 设备上的客户一次性密码位不可读

可以完全阻止读取客户一次性密码位。这可以通过在一次性密码写邮箱中使用特殊参数来实现：

这个操作对于绝大多数用户来说可能没有什么用处，并且是不可逆的。

定制 MAC 地址对于 BCM2712 设备

在 BCM2712 设备上，以太网、Wi-Fi 和蓝牙 MAC 地址在 OTP 存储器中设置。这些值可以随客户值而改变。

获取客户端的 MAC 地址 vcmailbox 0x00030082/3/4 6 6 0 0，其中 2 是以太网，3 是 WiFi，4 是蓝牙：

要设置客户端的 MAC 地址，必须按正确顺序将其发送为两个 32 字的单词。你可以运行一个命令来检查它是否格式正确：

检查日志以查看 MAC 地址是否符合你的预期：

多播地址不被视为有效。MAC 地址中最高位的最低有效位是多播位，因此确保这个位未设置。

然后可以使用命令 vcmailbox 0x00038082/3/4 6 6 <row1> <row0> 设置客户 MAC 地址：

如果客户 MAC 地址设置为 ff:ff:ff:ff:ff:ff，则将被忽略。

设备特定的私钥

使用 Broadcom BCM2712 处理器的设备具有 16 行 OTP 数据（512 位），用于支持文件系统加密。不使用 BCM2712 的设备具有可用于设备特定的私钥的 8 行 OTP（256 位）。

可以使用类似于管理客户 OTP 行所使用的相似 vcmailbox 命令来编程和读取这些行。如果不需要安全引导 / 文件系统加密，则可以使用设备私钥行来存储通用信息。

设备专用密钥行只能通过命令 vcmailbox 读取，该命令需要访问 /dev/vcio，该访问权限仅限于树莓派系统上的 video 组。
树莓派计算机没有硬件保护密钥存储。建议将此功能与安全启动结合使用，以限制对这些数据的访问。
树莓派系统不支持加密根文件系统。

有关开源磁盘加密的更多信息，请参见 Cryptsetup。

使用 `rpi-otp-private-key` 将密钥编程到 OTP 中。

rpi-otp-private-key 脚本包装设备私钥 vcmailbox API，使得更容易以 OpenSSL 格式读取和写入密钥。

注意
usbboot 库包含你需要的所有工具，rpi-eeprom 作为 Git 子模块。

把这个 32 字节的密钥读取为 64 个字符的十六进制数：

示例输出：

将 32 字节的随机生成数字写入设备私钥。

警告
此操作无法撤销。

注意
要指定要使用的 OTP 行数，请传参 -l <word count>。要指定密钥存储中的起始位置，请传参 -o <word offset>。

读取/写入密钥的邮箱 API

读取所有行。

示例输出：

将所有行写入（用密钥数据替换末尾的八个零）：

写入前一个示例中显示的密钥：

OTP 寄存器和位定义

所有树莓派范围使用的 SoC 都具有内置的一次可编程（OTP）存储器块。少数位置具有出厂程序化的数据。

OTP 存储器大小：

非 BCM2712 设备：66 个 32 位值
BCM2712 设备：192 个 32 位值

要显示 OTP 的内容，请运行以下命令：

针对非 BCM2712 设备的 OTP 寄存器

此列表包含关于寄存器的公开信息。如果某个寄存器或位未在此定义，则表示它未公开。

16 OTP 控制寄存器 - BCM2711

第 26 位：禁用 VC JTAG
位 27: 禁用 VC JTAG 17 引导模式寄存器
位 1: 将振荡器频率设置为 19.2MHz
位 3: 启用 SDIO 引脚上的上拉电阻

注意
在 BCM2711 上，引导模式由引导加载程序 EEPROM 配置而不是 OTP 定义。

18 启动模式寄存器的副本 28 序列号 29 ~(序列号) 30 修订代码 ① 33 电路板修订扩展 - 意义取决于电路板型号。这通过设备树在 /proc/device-tree/chosen/rpi-boardrev-ext 中提供，并且可以通过在 config.txt 中设置 board_rev_ext 来临时覆盖测试目的中的 OTP 值。

*计算模块 4

位 30：计算模块是否安装了 WiFi 模块
- 0 - Wi-Fi
- 1 - 没有 Wi-Fi

47-54 SHA256 RSA 公钥的安全引导

55 安全启动标志（由引导加载程序保留使用）

56-63 256 位设备特定私钥

64-65 MAC 地址；如果设置，系统将优先使用此地址，而不是基于序列号自动生成的地址

66 高级启动寄存器（非 BCM2711）

位 0-6：ETH_CLK 输出引脚的 GPIO
位 7：启用 ETH_CLK 输出
位 8-14：LAN_RUN 输出引脚的 GPIO
位 15：启用 LAN_RUN 输出

①还包含禁用过压、OTP 编程和 OTP 读取的位。

BCM2712 设备上的 OTP 寄存器

此列表包含关于寄存器的公开信息。如果此处未定义寄存器或位，则表示其非公开。

22 引导模式寄存器

第 1 位：从存储卡启动
第 2-4 位：从 SPI EEPROM 启动（以及哪些 GPIO）
位 10: 禁止从存储卡引导
位 11: 禁止从 SPI 引导

23 引导模式寄存器的副本

29 高级引导模式

0-7 位：SD 卡检测的 GPIO
位 8-15：用于 RPIBOOT 的 GPIO

序列号的低 32 位为 31

32 板上修订版本

33 板属性 - 其含义取决于板。这可通过设备树在 /proc/device-tree/chosen/rpi-boardrev-ext 中获取

35 序列号的高 32 位全 64 位序列号可在 /proc/device-tree/serial-number 中获取

50-51 以太网 MAC 地址这会传递到操作系统中的设备树中，例如 /proc/device-tree/axi/pcie@120000/rp1/ethernet@100000/local-mac-address

52-53 Wi-Fi MAC 地址这将传递给操作系统中的设备树，例如 /proc/device-tree/axi/mmc@1100000/wifi@1/local-mac-address

54-55 蓝牙 MAC 地址这将传递给操作系统中的设备树，例如 /proc/device-tree/soc/serial@7d50c000/bluetooth/local-bd-address

77-84 客户 OTP 值

86board 区域 - piwiz 使用的默认键盘区域代码。如果设置，则可通过设备树在 /proc/device-tree/chosen/rpi-country-code 中获取。

87-88 客户以太网 MAC 地址。如果设置，将覆盖 OTP 行 50-51。

89-90 客户 WiFi MAC 地址。如果设置，将覆盖 OTP 行 52-53。

89-90 客户蓝牙 MAC 地址如果设置，将覆盖 OTP 行 54-55

109-114 工厂设备 UUID 目前是一个 16 位数字 id，应与设备上的条形码匹配。使用零字符填充并进行 c40 编码。

此项信息可通过设备树在 /proc/device-tree/chosen/rpi-duid 中获取。

树莓派连接器用于 PCIe

树莓派 5 在主板的右侧有一个 FPC 连接器。该连接器提供了 PCIe Gen 2.0 ×1 接口，用于连接高速外设。

将 PCIe HAT+ 设备连接到树莓派。你的树莓派应该会自动检测到该设备。要连接非 HAT+ 设备，请将其连接到树莓派，然后手动启用 PCIe。

有关 PCIe FPC 连接器引脚分配和创建第三方设备、配件和扩展板所需的其他详细信息，请参阅树莓派 PCIe 标准文档。建议同时阅读树莓派 HAT+ 规格说明。

注意
目前无法枚举位于在交换机后的 PCIe 设备。

启用 PCIe

默认情况下，除非连接到了 HAT+ 设备，否则不会启用 PCIe 连接器。要启用连接器，请将以下行添加到 /boot/firmware/config.txt ：

使用 sudo reboot 重启以使配置更改生效。

注意
你还可以使用别名 nvme。

从 PCIe 启动

默认情况下，树莓派设备不会从 PCIe 存储启动。要启用从 PCIe 启动，请更改引导加载程序配置中的 BOOT_ORDER。使用以下命令编辑 EEPROM 配置：

将 BOOT_ORDER 行替换为如下行：

若要从非 HAT+ 设备启动，还需添加以下行：

保存更改后，使用 sudo reboot 重启你的树莓派以更新 EEPROM。

PCIe 3.0

警告
树莓派 5 未获 3.0 速度认证。PCIe 3.0 连接可能不稳定。

通过 `config.txt`

连接已被认证符合 Gen 2.0 速度（5 GT/sec），但你可以强制使用 Gen 3.0（10 GT/sec）速度。要启用 PCIe Gen 3.0 速度，请向 /boot/firmware/config.txt 添加以下行：

重启你的树莓派，可使用 sudo reboot 使这些设置生效。

通过 `raspi-config`

运行以下命令打开树莓派配置 CLI：

完成以下步骤以启用 PCIe Gen 3.0 速度：

选择 Advanced Options。
选择 PCIe Speed。
选择 Yes 以启用 PCIe Gen 3 模式。

使用 sudo reboot 重启你的树莓派，以使这些设置生效。

电源按钮

注意
本小节仅适用于带有电源按钮的树莓派型号，如树莓派 5。

当你首次将树莓派插入电源时，不用按按钮，它可以自动引导并启动到操作系统。

如果你运行着桌面版树莓派，你可以通过短按电源按钮来执行彻底的关机。一个窗口将出现：询问你是否要关机、重启还是注销。

可选择菜单选项或者再次按下电源按钮，直接执行彻底关机。

注意

如果你运行着桌面版树莓派，则可以通过快速连按两下电源按钮来关闭计算机。如果你运行着无桌面界面的树莓派操作系统精简版，则按一下电源按钮即可触发关机流程。

重启

如果树莓派主板已关闭但仍接入电源，按下电源按钮可重启。

注意
重置电源管理芯片（PMIC）也可以重启。连接扩展板会重置 PMIC。在连接扩展板之前，应始终断开设备与电源的连接。

硬关机

要强制执行硬关机，请长按电源按钮。

添加你自己的电源按钮

J2 跳线帽

J2 跳线帽位于 RTC 电池连接器和主板边缘间。在此引出可以让你向树莓派 5 添加自己的电源按钮，方法是添加一个常开 (NO) 瞬时开关，将两个焊盘连接起来。短按此开关将执行与板载电源按钮相同的操作。

电源供应

不同款式的树莓派电源供应要求有所不同。所有型号都需要 5.1V 供应，但通常根据型号需要提高电流。到树莓派 3 为止的所有型号需要一个 micro USB 电源连接器，而树莓派 4、树莓派 400 和树莓派 5 使用 USB-C 连接器。

每个树莓派消耗的电流取决于连接的外围设备。

以太网供电（PoE）连接器

树莓派 5 PoE 扩展版

树莓派 5 上的以太网插孔支持 PoE +，符合 IEEE 802.3at-2009 PoE 标准。

树莓派 4B 和 3B+ 上的以太网插孔支持 PoE，符合 IEEE 802.3af-2003 PoE 标准。

所有具有 PoE 兼容以太网插孔的树莓派型号都需要通过以太网端口绘制电源的扩展板。对于支持 PoE 的型号，我们建议使用 PoE 扩展板。对于支持 PoE + 的型号，我们建议使用 PoE + 扩展板。

典型功率要求

产品

推荐的电源适配器电流容量

最大总 USB 外设电流吸收

典型裸板活动电流消耗

注意
当连接到 5A，+5V（25W）的电源能力的适配器时，树莓派 5 可为下游 USB 外设提供 1.6A 的电源。当连接到其他兼容的电源时，树莓派 5 将限制下游 USB 设备的电源为 600mA。

大多数树莓派能提供足够的电流给 USB 外设，可供应大多数 USB 设备，如键盘、鼠标和适配器。然而，某些设备需要额外的电流，比如调制解调器、外置磁盘和大功率天线。如果要连接某 USB 设备，但是其电力需求超过了上表中指定的数值，请使用带外部供电的 USB 集线器。

如果你在树莓派上使用各种接口，其电力需求会增加。GPIO 引脚总共可安全供给 50mA；每个引脚最多可单独供给 16mA。HDMI 使用 50mA。相机模块需要 250mA。USB 键盘和鼠标可消耗从 100mA 到 1000mA 不等的电流。请检查你准备连接到树莓派的设备的功率，并相应购买适配器。如不确定，请使用带外部供电的 USB 集线器。

运行以下命令检查输出到 USB 的电力状态：

以下表格总结了不同树莓派型号在各种工作负载期间所绘制的功率（A）量：

树莓派 1B+

树莓派 2B

树莓派 3B

树莓派 Zero

树莓派 4B

注意
这些测量基于标准的树莓派系统镜像（截至 2016 年 2 月 26 日，对于树莓派 4 为 2019 年 6 月），室温，树莓派接入了 HDMI 显示器、USB 键盘和 USB 鼠标。树莓派 3A 接入到了无线局域网接入点，树莓派 4 连接到了以太网。所有这些功耗测量均为近似值，并未考虑来自额外 USB 设备的功耗；如果接入了多个额外 USB 设备和扩展板，功耗很容易超过这些测量值。

树莓派 4 和计算模块 4 上的额外电源管理功能

树莓派 4 和 CM4 上采用了多种不同的电源管理芯片（PMIC）。所有这些电源管理芯片（PMIC）都提供了额外的功能，除了电压供应之外。本文档概述了如何在软件中使用这些功能。

降低树莓派 5 关机后的功率

在默认情况下，树莓派 5 关机后仍会消耗电力，约 1 至 1.4 瓦。可以减少这种功率消耗：手动编辑 EEPROM 配置：即 sudo rpi-eeprom-config -e。将设置更改为以下内容：

在关机后，功耗应该会降至约 0.01 W。

电源供应警告

自树莓派 B+（2014 年）以降的所有型号，除了 Zero 系列，均配备了低电压检测电路，如检测到供电电压低于 4.63 V（±5%），将在内核日志中打印一行信息。

如果你看到警告，请切换到更高质量的电源适配器和充电线。劣质电源会损坏存储设备甚至诱发树莓派产生未知行为。

电压会因多种原因而降低：你可能已将太多高需求的 USB 设备插入；电源适配器供应可能不足；接入适配器的充电线可能过细。

创建更具弹性的文件系统

树莓派设备经常用作数据存储和监控设备，通常在可能发生意外断电的地方使用。与所有计算设备一样，电力中断可能造成存储损坏。

本白皮书提供了一些参数，介绍了如何通过选择适当的文件系统和设置来防止在以上以及其他情况下的数据损坏，以确保数据完整性。

电源和树莓派系统

引导加载程序通过设备树 /proc/device-tree/chosen/power 传递有关电源供应的信息。用户通常不会直接阅读此信息。

max_current 最大电流（单位：mA）

PDO 转储——高级用户的调试

是否将电流限制器设置为高或低

在将控制权转移给操作系统之前，启动期间是否发生过 USB 过电流

重置事件电源管理芯片（PMIC）重置原因，如看门狗、过压或欠压、过温

电源管理芯片（PMIC）带有内置 ADC，可以测量供电电压 EXT5V_V 等等。使用以下命令查看 ADC 测量值：

你无法看到 USB 电流或其他直接连接到 5V 的设备，因为这将绕过电源管理芯片（PMIC）。你不应该期望这些值加起来等于电源供应的瓦（w）数。但是，监视核心电压等事项可能很有用。

反向供电

USB 规范要求 USB 设备不能向上游设备供电。如果 USB 设备向上游设备供电，则称为反向供电。通常是因为连接了劣质的带供电的 USB 集线器，并且会导致带电 USB 集线器向主机的树莓派供电。不建议这么做，因为通过集线器向树莓派供电会绕过树莓派中内置的保护电路，使其在发生电涌时易受损坏。

实时时钟（RTC）

树莓派 5 内置了一个 RTC 模块。它通过位于 Type-C 电源连接器右侧，主板上的 J5（BAT）连接器接入电池供电。

J5 电池连接器

你可以设置唤醒闹钟，将主板切换至极低功耗状态（约 3mA）。达到闹钟时间时，主板将重新上电。这对像延时摄像这样的周期性任务非常有用。

编辑引导加载程序配置以支持唤醒警报的低功率模式：

添加以下两行。

你可以使用以下方式测试功能：

将会使板子进入极低功耗状态，然后在 10 分钟后唤醒并重启。

RTC 还提供了启动时的时间，如 dmesg，适用于缺乏 NTP 访问权限的用例：

注意
即使备用电池未接入 J5 连接器，RTC 仍然可用。

添加备用电池

锂锰可充电 RTC 电池

官方电池配件是一枚可充电的锂锰硬币电池，配有预装的两针 JST-SH 插头和粘性安装触点。适用于在主板的主电源断开时为 RTC 供电。由于关机时的电流吸收为个位数 µA，可使用时间为几个月。

注意
我们不建议使用一次性（不可充电）的锂电池为 RTC 提供电源。RTC 的备用电流消耗比大多数专用 RTC 模块更高，这将导致电池的使用寿命缩短。

警告
不要使用锂离子电池作为 RTC 的电源。

启用电池充电

RTC 配备了恒流（3mA）恒压充电器。

默认情况下，已禁用电池充电。sysfs 文件显示了充电电压和限制：

要设定电压为电池充电，请添加 rtc_bbat_vchg 到 /boot/firmware/config.txt：

sudo reboot 重启来使用新的电压设置。检查 sysfs 文件，确保已正确设置充电电压。

禁用电池充电

要停止充电，请在 config.txt 删除所有 rtc_bbat_vchg 相关行。

串行外围设备接口（SPI）

树莓派计算机配备多个 SPI 总线。SPI 可用于连接各种外围设备：显示器、网络控制器（以太网、CAN 总线）、UART 等。这些设备最好由内核设备驱动程序支持，但 spidev API 允许用多种语言编写用户空间驱动程序。

SPI 硬件

树莓派 Zero, 1, 2 和 3 都有三个 SPI 控制器：

SPI1，在所有树莓派的引脚上都有两个硬件芯片选择信号；还有一种仅适用于 Compute 模块的备用映射。
SPI2，在除早期树莓派 1 A 和 A 之外的所有树莓派型号上都有三个硬件芯片选择信号。
SPI2，也具有三个硬件芯片选择器，仅在计算模块 1、3 和 3+ 上可用。

在树莓派 4、400，计算模块 4 上，还有四个额外的 SPI 总线：SPI3 到 SPI6，每个总线都有两个硬件芯片选择器。这些额外的 SPI 总线可通过某些 GPIO 引脚的替代功能分配来使用。有关更多信息，请参阅 BCM2711 Arm 外围设备数据表。

BCM2835 Arm 外围设备数据表的第 10 章介绍了主控制器。第 2.3 章说明了辅助控制器。

引脚/GPIO 映射

SPI0

SPI 功能

排针引脚

博通引脚名称

博通引脚功能

SPI0 备用镜像（仅限计算模块，不包括 CM4）

SPI 功能

博通引脚名称

博通引脚功能

SPI1

SPI 功能

排针引脚

博通引脚名称

博通引脚功能

SPI2（仅适用于计算模块，不含 CM4）

SPI 功能

博通引脚名称

博通引脚功能

SPI3（仅限 BCM2711）

SPI 功能

排针引脚

博通引脚名称

博通引脚功能

SPI4（仅限 BCM2711）

SPI 功能

排针引脚

博通引脚名称

博通引脚功能

SPI5（仅限 BCM2711）

SPI 功能

排针引脚

博通引脚名称

博通引脚功能

SPI6（仅限 BCM2711）

SPI 功能

排针引脚

博通引脚名称

博通引脚功能

主模式

信号名称缩写:

SCLK 串行时钟

CEchip 启用（通常称为芯片选择）

MOSI 主发送从接收

MISO 主接收从发送

MOMI 主在主出

标准模式

在标准 SPI 模式下，外设实现标准三线串行协议（SCLK，MOSI 和 MISO）。

双向模式

在双向 SPI 模式中，实现了相同的 SPI 标准，只是使用单根导线传输数据（MOMI），而不是标准模式下使用的两根导线（MISO 和 MOSI）。在这种模式下，MOSI 引脚充当 MOMI 引脚。

低速串行接口（LoSSI）模式

LoSSI 标准允许向外围设备（LCD）发出命令并在它们之间传输数据。LoSSI 命令和参数均为 8 位长，但额外的一位用于指示 B 是命令还是参数/数据。数据时此额外位设置为高位，命令时设置为低位。最终的 9 位值被串行化输出。LoSSI 常与 MIPI DBI 类型 C 兼容的 LCD 控制器一起使用。

注意
某些命令会触发 SPI 控制器自动读取，因此该模式不能用作多功能的 9 位 SPI。

传输模式

轮询
中断
DMA

速度

CLK 寄存器的时钟分频器 (CDIV) 字段设置了 SPI 时钟速度:

SCLK 核心时钟 / CDIV

如果 CDIV 设置为 0，则除数为 65536。除数必须是 2 的倍数，奇数向下舍入。请注意，由于模拟电气问题（上升时间、驱动强度等），并非所有可能的时钟速率都可用。

查看 Linux 驱动程序部分获取更多信息。

芯片选择

在 DMA 模式下操作时，与 CS 线的自动断言和取消断言相关的建立时间和保持时间如下：

CS 线将在传输的第一个字节的 msb 之前至少提前三个核心时钟周期。
CS 线将在最后的时钟脉冲的下降沿后至少延迟一个核心时钟周期取消断言。

SPI 软件

Linux 驱动程序

默认的 Linux 驱动程序是 spi-bcm2835。

在默认情况下，SPI0 已被禁用。要启用，请使用 raspi-config，或确保 dtparam=spi=on 在 /boot/firmware/config.txt 中没有被注释掉。默认情况下，它使用两个芯片选择线，但可以使用 dtoverlay=spi0-1cs 将其减少到一个。还有 dtoverlay=spi0-2cs；没有任何参数时，它等效于 dtparam=spi=on。

要启用 SPI1，你可以使用 1、2 或 3 个芯片选择线。将适当的线添加到 /boot/firmware/config.txt 中：

类似的叠加层也适用于 SPI2、SPI3、SPI4、SPI5 和 SPI6。

驱动程序不使用硬件片选线，因为某些限制。相反，它可以使用任意数量的 GPIO 作为软件/GPIO 片选。这意味着你可以选择任何多余的 GPIO 作为 CS 线，所有这些 SPI 叠加层都包括该控制：详情请见 /boot/firmware/overlays/README，或运行（例如） dtoverlay -h spi0-2cs （可能有助于列出所有这些）。

速度

该驱动程序支持所有是核心时钟的偶数整除数的速度，尽管如上所述，并非所有这些速度都将支持数据传输，因为 GPIO 和连接的设备存在限制。作为经验法则，任何大于 50MHz 的速度都不太可能工作，但具体情况可能有所不同。

支持的模式位

SPI_CPOL 时钟极性

SPI_CPHA 时钟相位

SPI_CS_HIGH 芯片选择高电平

SPI_NO_CS1 每总线一个设备，无芯片选择

SPI_3WIRE 双向模式，数据输入输出引脚共享

双向模式，也称为 3 线模式，由 spi-bcm2835 内核模块支持。请注意，在此模式下，spi_transfer 结构体的 tx 或 rx 字段必须是 NULL 指针之一，因为只支持半双工通信。否则，传输将失败。spidev_test.c 的源代码未正确考虑此情况，因此在 3 线模式下根本无法工作。

支持的每字比特数

8 - 正常
9 - 支持使用 LoSSI 模式

传输模式

所有 SPI 总线均支持中断模式。SPI0 和 SPI3-6 还支持 DMA 传输。

SPI 驱动延迟

此线程讨论延迟问题。

spidev

spidev 提供了一个基于用户空间的单个 SPI CS 线接口。设备树用于指示 CS 线是由内核驱动模块驱动还是由 spidev 代表用户管理；不能同时两者都做。请注意，树莓派自己的内核对于使用设备树启用 spidev 更为宽松——上游内核会打印关于此类用法的警告，最终可能会彻底阻止之。

在 C 语言中使用 spidev

Linux 文档中有一个环回测试程序，可用作起点。请参阅故障排除部分。

在 Python 中使用 spidev

有几个 Python 库能访问 spidev，包括 spidev ( pip install spidev：参见 https://pypi.org/project/spidev/) 和 SPI-Py ( https://github.com/lthiery/SPI-Py)。

使用 spidev 从像 bash 这样的 shell

以下命令写入二进制 1、2 和 3：

其他 SPI 库

还有其他用户空间库可以通过直接操作硬件来提供 SPI 控制：这并不推荐。

故障排除

回环测试

这可以用来测试 SPI 发送和接收。在 MOSI 和 MISO 之间放一根电线。它未不测试 CE0 和 CE1。

上述部分内容是从 elinux SPI 页面复制而来的，该页面也引用了这里。两者都受 CC-SA 许可协议保护。

通用串行总线（USB）

一般来说，所有 Linux 支持的设备，树莓派都能用，尽管在树莓派 4 之前的型号上有一些限制。

最大功率输出

与所有计算机一样，树莓派上的 USB 端口提供的功率有限。USB 设备通常因电力问题而出现故障。要排除电力不足引发问题的可能性，请使用带供电的集线器把 USB 设备接入树莓派。

型号

USB 端口的最大功率输出

① 对于旧款树莓派 1 A，每端口限制为各 100mA。

树莓派 5

树莓派 5 需要高质量 Type-C 电源适配器才能启动，最低为 +5V 3A（15W）。然而，用这样的电源适配器会限制外部设备的电流。如果你在首次启动时没有使用 +5V 5A 的电源适配器，操作系统会告警，将外部设备的电流限制为 600mA。

如果用户希望驱动大功率外设（如硬盘和固态硬盘），同时维持面对峰值工作负载仍有余量。应使用能够提供 +5V 5A（25W）的 USB-PD 电源适配器。如果树莓派 5 固件检测到了这样的电源适配器，它会把外设的 USB 电流限制缓解至 1.6A，为下游 USB 设备提供额外 5W 电力，同时为主板上电力预算提供额外的 5W 电力。

注意
USB 和风扇接口共用一笔电力预算。

树莓派 4

树莓派 4 提供了两个 USB 3.0 接口和两个 USB 2.0 端口，它们连接至 VL805 USB 控制器。四个接口上所有的 USB 2.0 均连接到了 VL805 内的单个 USB 2.0 集线器。这限制了 USB 1.1 和 USB 2.0 设备的总可用带宽，即与单个 USB 2.0 端口是一样的。

旧版树莓派 4 上的 USB Type C 接口使用的 USB 控制器，在默认情况下已被禁用。

树莓派 Zero，1，2 和 3

树莓派 1 代 B+、树莓派 2 和树莓派 3 主板提供了四个 USB 2.0 端口。树莓派 Zero 主板配备一个 micro USB on-the-go (OTG) 端口。

树莓派 4 之前的型号上的 USB 控制器仅对某些设备提供基本支持，这会带来较高的软件处理开销。它仅支持一个根 USB 接口：所有连接设备的流量都通过此单一总线传输，该总线的最大速度为 480Mbps。

USB 2.0 规范定义了三种设备速度：低速、全速和高速。大多数鼠标和键盘是低速设备，大多数 USB 声音设备是全速设备，而大多数视频设备（网络摄像头/视频捕捉器）是高速设备。

若把多个高速 USB 设备同时接入树莓派，一般没有问题。

与低速和全速设备通信时产生的软件开销意味着同时活动的低速和全速设备数量会受限制。连接少量这些类型设备到树莓派不会造成问题。

已知的 USB 故障

与 USB 3.0 集线器的互操作性

在使用全速/低速设备（如大多数鼠标和键盘）时，与 USB 3.0 集线器一起使用的问题。大多数 USB 3.0 集线器硬件中存在的一个错误：意味着在连接到 USB 3.0 集线器的全速/低速设备时，树莓派 4 之前的型号无法与这些设备通信。

在通过 USB 3.0 集线器接入时，USB 2.0 高速设备（包括 USB 2.0 集线器）可正确运行。

避免将低速/全速设备连接到 USB 3.0 集线器。作为解决方法，将 USB 2.0 集线器插入 USB 3.0 集线器的下游端口，然后将低速设备连接，或者在树莓派和 USB 3.0 集线器之间使用 USB 2.0 集线器，然后将低速设备插入 USB 2.0 集线器。

USB 1.1 网络摄像头

旧的网络摄像头可能是全速设备。因为这些设备传输大量数据并产生额外的软件开销，无法保证可靠运行。作为解决方法，请尝试通过分辨率调用摄像头。

Esoteric USB 声卡

昂贵的发烧友级声卡通常会占用大量的 USB 带宽。不能保证 96kHz/192kHz DAC 的可靠性。作为一种解决方法，可强制输出流为 CD 音质（44.1kHz/48kHz 16 位），把带宽降低到可靠水平。

单个 TT USB 集线器

USB 2.0 和 3.0 集线器具有一种机制，用于与连接到其下游接口的全速/低速设备通信，即事务转换器 (TT)。此设备可缓冲来自主机的高速请求，并将它们以全速/低速传输给下游设备。USB 规范允许两种集线器配置：单个 TT (所有接口共用一个 TT) 和多个 TT (每端口一个 TT)。由于硬件限制，如果将大量全速/低速设备插入单个 TT 集线器，这些设备可能会表现的不大稳定。建议使用多个 TT 集线器与多个全速/低速设备进行接口处理。作为一种解决方法，可将全速和低速设备分散放置在树莓派自己的 USB 端口和单个 TT 集线器之间。

树莓派修订代码

每个不同款的树莓派修订版都有一个唯一的修订代码。你可以通过运行以下命令，查找树莓派的修订代码：

最后三行显示了硬件类型、修订代码和树莓派的唯一序列号。例如：

注意
所有树莓派计算机都报告为 BCM2835，即使是搭载 BCM2836、BCM2837、BCM2711 和 BCM2712 处理器的也一样。你不应该使用此字符串来检测处理器。可使用下面的信息解码修订代码，或 cat /sys/firmware/devicetree/base/model。

旧式修订代码

树莓派的第一批型号从 0002 到 0015 分配了顺序十六进制修订代码：

代码

型号

修订版本

RAM

制造商

新式修订代码

随着使用树莓派 2 的推出，引入了新样式的修订代码。不同于顺序的是，十六进制代码的每一位都代表修订码的一部分信息：

部分

代表

选项

① 编程 OTP 位的信息。

② 在树莓派 4 上从未设置过保修位。

使用新样式的修订代码

注意
此列表不是详尽无遗的：可能有正在使用的，但未出现在此表中的代码。请参阅下一节，了解如何使用修订代码来识别板子的最佳实践。

代码

型号

修订版本

RAM

制造商

使用修订代码进行板卡识别

在命令行，我们可以使用以下命令获取板卡的修订代码：

在以上示例，我们有一个十六进制的修订代码 c03111。将其转换为二进制，我们得到 0 0 0 000 0 0 1 100 0000 0011 00010001 0001。上表已插入空格，为显示修订代码的各部分之间的边界。

从最低阶位开始，底部的四位（0-3）是板子的修订号，所以这块板子的修订号是 1。接下来的八位（4-11）是板子类型，在这种情况下是二进制 00010001，十六进制 11，所以这是个树莓派 4B。使用相同的过程，我们可以确定处理器是 BCM2711，板子由索尼英国制造，并且内存为有 4GB。

在你的程序中获取修订代码

很明显，有如此多的编程语言，不可能为所有的语言都举例，但这里有两个简单的例子，分别面向 C 和 Python。这两个例子都使用系统调用，运行一个 bash 命令，获取 cpuinfo 将结果传送给 awk 来还原所需的修订代码。然后，它们使用位操作来提取代码中的 New、Model 和 Memory 字段。

同样的 Python 代码：

使用修订代码的最佳实践

为了避免在创建新的板卡版本时出现问题，请不要使用版本代码（例如 c03111 ）。

一个天真的实现是使用支持的版本代码列表，将检测到的代码与该列表进行比较，以决定该设备是否受支持。当出现新的板卡版本或者生产地点发生变化时，这种方法就会失效：每次都会创建新的版本代码时，都不在支持的版本代码列表中。这将导致同一板卡类型的新版本被拒绝，尽管它们始终保持向后兼容。每当出现新版本时，你都必须发布一个包含新版本代码的新支持的版本代码列表——这是一项繁重的开发负担。

还请使用若干以下方法：