跳到主要内容

系统配置

Raspberry Pi 的关键设置会在使用 Raspberry Pi Imager 进行初始化配置的过程中完成，具体方法详见 使用 Imager 安装。安装完成后，您可以更改现有设置并配置其他选项；根据您的使用场景和技术水平，可通过多种方式进行操作，具体方法详见 配置方法。

配置方法​

配置树莓派设置有多种方法。虽然每种方法使用的界面不同，但它们通常都是通过修改 /boot/firmware/config.txt 及其他相关配置文件来实现的。主要有三种配置方法：

如果您的系统包含桌面环境，您可以通过桌面 GUI 配置常用设置。若需更精细的控制，或者您正在使用 Raspberry Pi OS Lite 系统，或是采用 无显示器设置，Raspberry Pi OS 提供了交互式 raspi-config TUI，这是一款基于终端的配置工具，用于管理常见的系统设置。

桌面图形界面（GUI）是最用户友好的，但您选择的方法取决于多种因素，例如您是否在使用无显示器计算机（未连接显示器的树莓派），以及您对命令行的熟悉程度。例如，如果您使用的是未连接显示器的无显示器树莓派，则无法访问图形桌面环境。在这种情况下，您必须使用 raspi-config 配置工具，或通过命令行手动编辑相关配置文件。

某些其他设置只能通过命令行或控制台模式进行配置。尽管这些设置不会出现在桌面图形界面或 raspi-config TUI 中，但本页的相关分类中仍会对其进行说明。

桌面图形界面​

如果您的系统包含桌面环境，桌面图形用户界面（GUI）将为 Raspberry Pi OS 提供可视化交互层。连接显示器后，该界面允许您通过图标、菜单、窗口和指针来控制 Raspberry Pi。

大多数设置通过 树莓派配置 管理，但部分选项可在桌面的其他位置进行配置。例如，您可以通过 Raspberry Pi 桌面系统托盘右上角的无线图标配置 Wi-Fi。

要打开树莓派配置工具，请选择系统托盘左上角的树莓派图标，然后进入 首选项 > 树莓派配置。

控制中心菜单选项

如何从树莓派桌面访问控制中心

备注

树莓派操作系统 Bookworm 版本使用名为 树莓派配置 的配置工具。旧版本使用 控制中心。

交互式 raspi-config 文本用户界面 (TUI)​

树莓派操作系统包含 raspi-config，这是一个基于终端的配置工具，用于管理常见的系统设置。它提供了一个结构化的菜单式界面，您可以通过键盘进行导航。

raspi-config 主界面

raspi-config 文本用户界面 (TUI) 的主菜单

在以下情况下，您可能需要使用 raspi-config TUI：

  • 您希望或需要比桌面图形界面 (GUI) 更精细的控制。
  • 您正在使用 Raspberry Pi OS Lite。
  • 您的 Raspberry Pi 运行在无显示器环境中。

要打开 raspi-config 工具，请在 Raspberry Pi 设备上启动终端，然后输入 sudo raspi-config。接着：

  • 要在设置列表中导航，请使用键盘上的上下箭头键。
  • 要选择高亮显示的设置，请按键盘上的 Enter 或 *Return 键。您也可以使用右箭头键或 Tab 键将光标移至 <Select> 处，然后按 Enter 或 Return 键进行选择。
  • 要返回设置列表，请使用键盘上的左箭头键或 *Tab 键。
  • 要按字母顺序跳转，请输入相应的字母。例如，输入 E 可在时区列表中跳转至 Europe。
  • 要关闭 raspi-config，请使用键盘上的右箭头键或 Tab 键选择 <Finish>，然后按键盘上的 Enter 或 Return 键。

直接使用命令行界面 (CLI)​

您可以通过编辑系统文件，或在终端或控制台模式下运行命令，手动配置某些设置。其他更高级的设置（例如配置自定义全屏启动画面），只能通过 CLI 手动进行配置。

音频和视频输出​

Raspberry Pi OS 支持多种音频输出和显示模式。本节概述了如何在 Raspberry Pi 上配置音频和显示设置，包括以下内容：

更改音频输出​

Raspberry Pi OS 支持多种音频输出模式供您选择：HDMI、3.5 毫米耳机插孔（如果您的设备有此接口）以及 USB 音频设备。默认情况下，树莓派会将音频输出至首个检测到的 HDMI 设备。若未检测到 HDMI 设备，系统会自动将音频路由至耳机插孔或已连接的 USB 设备。您可通过桌面图形界面或命令行更改音频播放源。

树莓派桌面上的音频输出选择器允许您在连接至树莓派的多个音频设备之间进行选择。在较新的树莓派设备上，这可能包括通过其中一个 HDMI 端口或 USB 端口输出的音频。

如果您通过树莓派显示器背面的插孔连接了音频设备，它仍会在列表中显示为 HDMI，因为显示器连接到了树莓派的 HDMI 端口。

通过桌面更改音频输出目标：

  1. 右键单击桌面系统托盘右上角的音量图标。这将打开音频输出选择器。
  2. 选择您想要使用的设备的音频输出。

选择音频设备配置文件​

设备配置文件定义了音频设备的配置方式及其提供的功能。不同的配置文件针对不同的使用场景进行了优化。您可以在桌面上选择设备配置文件，在较新的树莓派设备上，也可以通过命令行进行选择。

  1. 右键单击桌面系统托盘右上角的音量图标。
  2. 选择 设备配置文件。
  3. 从以下选项中进行选择：
    • 关闭。关闭树莓派的音频输出。
    • 数字立体声。输出标准的双声道（左声道和右声道）音频。这是默认配置文件，适用于大多数扬声器、耳机和显示器。
    • 专业音频。在所有音频设备上提供最大数量的声道，从而对信号路由进行更精细的控制。除非您需要对音频输出进行精细调整，否则不建议选择此设备配置文件。有关专业音频配置文件的更多信息，请参阅 PipeWire 的常见问题解答。

显示设置​

对于大多数 HDMI 显示器，Raspberry Pi OS 会使用您的 Raspberry Pi 和显示器支持的最高分辨率和刷新率。请在开启 Raspberry Pi 之前连接好线缆。

Raspberry Pi 各型号的显示能力

型号HDMI 类型线缆适配器最大显示器数最大分辨率
Raspberry Pi Zero、Zero W 和 Zero 2 WMini HDMI需使用 mini-HDMI 转 HDMI 线缆或转接头1取决于显示器；通常最高支持 1920 x 1080 像素
Raspberry Pi 4B、400 及 Compute Module 4双 micro HDMI每连接一台显示器均需使用 micro-HDMI 转 HDMI 线缆或转接头2（CM4S除外）两台4K显示器（30 Hz）或一台4K显示器（60 Hz）
Raspberry Pi 5、500、500+ 及 Compute Module 5双 micro HDMI每连接一台显示器均需使用 micro-HDMI 转 HDMI 线缆或转接头2两台 4K 显示器（60 Hz）

Raspberry Pi 4B、400 及计算模块 4 支持以下任一配置：

  • 两台分辨率最高为 3840 × 2160 像素（4K；超高清）且刷新率为 30 Hz 的显示器。
  • 一台分辨率最高为 1920 × 1080 像素（全高清）且刷新率为 60 Hz 的显示器，这是大多数显示器的标准配置。
  • 一台分辨率最高为 3840 × 2160 像素 （4K；超高清），刷新率为 60 Hz，前提是将显示器连接至 HDMI0 端口，并在 /boot/firmware/config.txt 中设置 hdmi_enable_4kp60=1 标志。

Raspberry Pi 5、500、500+ 以及 Compute Module 5 支持两台显示器，分辨率最高可达 3840 × 2160 像素（4K；超高清），刷新率为 60 Hz，无需额外配置。 您可以通过桌面环境或控制台调整显示分辨率和屏幕方向。

备注

Raspberry Pi OS Bookworm 是最后一个支持使用 raindrop 或 arandr 配置显示行为的版本。

以下命令行说明专门适用于 Raspberry Pi OS Lite 或未运行图形桌面环境的系统。如果您使用的是桌面 GUI，请改按桌面操作指南进行设置。

在没有桌面环境的系统（运行于控制台模式）上，必须手动配置显示设置。最新版本的 Raspberry Pi OS 允许您使用内核模式设置 (KMS) 来配置显示设置。具体操作是在内核命令行文件（cmdline.txt）中添加 video= 参数。有关此文件的更多信息，请参阅 配置内核命令行。

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 屏幕 选项卡。
  3. 通过以下任一方法选择要配置的屏幕：
    • 右键单击代表目标屏幕的方框。
    • 打开 *屏幕 下拉菜单，然后选择要配置的屏幕。
  4. 选择以下任一属性进行配置： 分辨率。选择屏幕分辨率（例如 1920 × 1080）。 频率。选择刷新率（例如 60 Hz）。 方向。在 正常、左、倒置 和 右 之间进行选择。 缩放比例。在 1.0、1.5、2.0 和 3.0 倍（相对于原始屏幕的缩放比例）之间进行选择。
  5. 在 控制中心 的右下角选择 应用。您的更改将显示 10 秒，系统会要求您确认更改是否正确后再继续。
  6. 要确认更改，请选择 确定。如果您不确认更改，屏幕将恢复到之前的设置。

配置屏幕休眠​

您可以将树莓派设置为在一段时间内无操作后自动休眠。启用屏幕休眠功能后，Raspberry Pi OS 默认会在无操作十分钟后使屏幕变黑。

您可以通过桌面图形界面、使用 raspi-config 文本界面，或通过命令行来配置屏幕休眠。

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 显示 选项卡。
  3. 使用开关按钮开启或关闭 屏幕休眠。
  4. 点击 控制中心 右下角的 关闭。

配置视频输出​

对于树莓派的旗舰机型，您可以使用交互式 raspi-config TUI 将视频输出配置为复合视频或 HDMI。启用复合视频输出将禁用除树莓派 5 以外所有机型的 HDMI 输出。要使用交互式 raspi-config TUI 启用或禁用复合视频输出：

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航至并选择 2 显示选项 > D4 复合视频。
  3. 在 是否启用复合视频输出？ 提示中选择 是 或 否。
  4. 选择 <确定> 以确认此选项。
  5. 完成后选择 <完成>。
  6. 重启树莓派以使更改生效。

配置屏幕键盘​

您可以通过桌面图形界面或交互式 raspi-config 文本用户界面（TUI），将树莓派配置为显示屏幕键盘，并选择该键盘显示在哪个屏幕上。在 raspi-config TUI 中，以下设置需分别配置：

  • 转至 D6 屏幕键盘 以启用或禁用屏幕键盘。
  • 转至 D7 键盘 以指定屏幕键盘的显示屏幕。
  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 显示 选项卡。
  3. 从 屏幕键盘 下拉菜单中选择以下选项之一：
    • 始终启用，这意味着键盘始终显示在屏幕上。
    • 检测到触摸屏时启用，表示当树莓派连接了触摸屏时，键盘才会显示在屏幕上。
    • 禁用，表示键盘不会显示在屏幕上。
  4. 若树莓派连接了多个屏幕，请从 屏幕键盘位置 下拉菜单中选择一个屏幕来显示键盘。
  5. 在 控制中心 的右下角选择 *关闭。

网络​

Raspberry Pi OS 提供了灵活的选项来配置网络设置。本节概述了如何管理和自定义 Raspberry Pi 的网络配置，包括以下内容：

  • 主机名，通过桌面界面以及交互式 raspi-config TUI 设置。
  • DHCP IP，根据您的具体使用场景，采用手动方法设置 。
  • 网络优先级，通过桌面界面和命令行设置 。
  • 可预测名称，通过交互式 raspi-config TUI 设置。这是一项高级选项，默认处于关闭状态。
  • 本地连接，通过交互式 raspi-config TUI 设置。这是一项高级选项，默认处于关闭状态。
  • 代理服务器，通过交互式 raspi-config TUI 设置。这是一项高级选项，默认处于关闭状态。

更改主机名​

设置主机名具有以下优势：

  • 设置主机名（例如 my-pi）后，您可以通过 mDNS 访问您的树莓派，而无需使用较长且易变的 IP 地址。例如，您可以使用 ssh pi@my-pi.local 代替 ssh pi@192.168.1.42。
  • 如果您在同一网络上有多个树莓派设备，可以通过使用唯一的主机名（例如 my-pi、pi-hole 和 retro-pi）来确保始终连接到正确的树莓派。

主机名不区分大小写，且仅可包含：

  • ASCII 字母 a 至 z。
  • 数字 0 至 9。
  • 连字符 (-)。

不允许使用其他符号、标点或空格。

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 系统 选项卡。
  3. 选择 更改主机名。
  4. 在 输入新主机名 字段中输入新主机名。
  5. 点击窗口右下角的 确定。
  6. 在 控制中心 窗口的右下角点击 关闭。

管理 DHCP 和静态 IP​

在典型的家庭网络中，DHCP（动态主机配置协议）由路由器管理。当设备连接时，它会自动为设备分配 IP 地址和其他网络设置（如网关和 DNS 服务器）。

使用 DHCP 可让您的树莓派（通过 Wi-Fi 或以太网）连接到网络，而无需手动配置 IP 地址和其他网络设置。

默认情况下，IP 地址是临时性的，随着路由器根据需要重新分配，它们可能会随时间变化。如果您在树莓派上运行服务（如 Web 服务器或 SSH 访问），建议该设备始终保持相同的 IP 地址。主要有两种实现方式：

  • DHCP 预留（推荐）。有时也称为静态租约，DHCP 预留需在路由器上进行配置。它能确保树莓派根据其 MAC 地址始终获得相同的 IP 地址，并将所有 IP 管理集中于路由器。具体设置步骤因路由器厂商和界面而异。
  • 在设备上设置静态 IP。您可以使用 nmcli 直接在树莓派上手动配置静态 IP 地址。这需要手动设置 IP 地址、子网掩码、网关和 DNS。我们不建议这样做，因为配置错误可能会导致连接问题。您必须确保所选 IP 地址不在路由器的 DHCP 地址池范围内，且不会与其他设备冲突。

设置网络优先级​

当树莓派检测到多个已知网络时，默认情况下它会尝试连接其中任意一个。您可以通过设置网络优先级来控制树莓派优先连接的网络。若设置了网络优先级，树莓派将尝试连接优先级最高（非负数）的可用网络：

  • 数字越大的网络优先级越高；树莓派会优先尝试连接正数最大的网络。
  • 优先级设为 0 的网络为中性优先级，这是默认设置。当存在其他正数优先级更高的网络时，优先级设为 0 的网络会被排在最后选择。
  • 优先级为负数的网络优先级较低；只有在没有其他已知网络可用时，树莓派才会连接到负优先级的网络。

例如，考虑以下四个网络：

  • Snake (-1)
  • Rabbit (0)
  • Dog (1)
  • Cat (100)

如果上述所有网络都在覆盖范围内，您的树莓派将首先尝试连接 Cat 网络。如果连接失败，它将依次尝试连接 Dog 网络和 Rabbit 网络。如果树莓派未检测到其他已知网络，它将尝试连接 Snake 网络。

  1. 点击右上角系统托盘中的无线图标。该图标会显示当前连接的 Wi-Fi 信号强度，并打开 网络管理器。
  2. 选择 高级选项 > 编辑连接。这将打开 网络连接 窗口。
  3. 找到并选择您想要设为优先的网络。
  4. 点击窗口底部的蓝色齿轮图标。
  5. 打开 常规 选项卡。
  6. 确保已选中 优先自动连接。
  7. 设置数值优先级。这将决定当有多个已知网络可用时，您的树莓派优先连接哪个网络。
  8. 点击窗口右下角的 保存，然后关闭 网络连接 窗口。

启用或禁用可预测的网络接口名称​

您可以启用或禁用更具体的接口名称，以确保网络设备命名在重启和硬件变更后保持一致。这是一项高级用户选项，默认处于关闭状态，因为它会在某些设备上替换传统的 eth0 和 wlan0 命名方案。命名行为可能因树莓派型号和配置而异。

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航至并选择 6 高级选项 > A2 网络接口名称。
  3. 在 是否启用可预测的网络接口名称？ 提示中选择 是 或 否。
  4. 选择 <OK> 确认此选项，完成后选择 <Finish>。
  5. 重启树莓派以使更改生效。

启用或禁用链路本地地址回退​

您可以启用或禁用链路本地地址回退功能，以分配临时 169.254.x.x 地址。即使有 DHCP 服务器可用，系统仍可能分配此地址：系统会先分配一个链路本地地址，然后在获得 DHCP 租约后将其替换。若未收到 DHCP 响应，则继续使用链路本地地址。

这是一项高级用户选项，默认处于关闭状态，因为它可能会干扰网络配置，且在大多数可使用 DHCP 的网络中通常不需要。仅当您理解此行为时才启用此选项。

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航至并选择 6 高级选项 > A14 链路本地地址回退。
  3. 在 是否启用链路本地回退？ 提示中选择 是 或 否。
  4. 选择 <确定> 确认此选项，完成后选择 <完成>。
  5. 重启树莓派以使更改生效。

配置树莓派使用代理服务器​

代理服务器充当客户端设备与互联网之间的中介。要配置树莓派使用代理服务器，您需要：

  • 代理服务器的 IP 地址或主机名及端口。
  • 代理服务器的用户名和密码（如需）。

这是一项高级配置，仅当您的网络需要代理时才应进行配置（例如，在受管、企业或受限环境中）。

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航至并选择 6 高级选项 > A3 网络代理设置。
  3. 配置代理使用的环境变量。根据您的需求选择以下一项或多项选项。每个选项必须单独配置，这意味着您需要针对每个要配置的选项从步骤 1 开始：
    • P1 All 将相同的代理设置应用于所有网络流量。
    • P2 HTTP 将所有 HTTP 流量通过代理发送。
    • P3 HTTPS 将所有 HTTPS（安全）流量通过代理发送。
    • P4 FTP 将所有 FTP 流量通过代理发送。
    • P5 例外 指定应绕过代理的地址。
  4. 选择 <OK>，然后再次选择 <OK>。
  5. 完成后选择 <Finish>。
  6. 重启树莓派以使更改生效。

对于选项 P1 至 P4，请按以下格式输入代理信息，将 <proxy_ip_address> 替换为您的代理 IP 地址，将 <proxy_port> 替换为您的代理端口：

http://<proxy_ip_address>:<proxy_port>`

如果您的代理需要用户名和密码，请按以下格式添加，并将 <username> 和 <password> 替换为您用于代理身份验证的用户名和密码。

http://<username>:<password>@<proxy_ip_address>:<proxy_port>

对于选项 P5，请输入以逗号分隔的地址列表，这些地址可绕过代理。根据需要添加其他域名或 IP 范围。

no_proxy="localhost,127.0.0.1"

无线连接​

本节介绍如何：

  • 配置 Wi-Fi 连接，具体包括：
    • 无线网络国家，这是连接无线网络的先决条件，您可通过桌面环境或交互式 raspi-config TUI 进行设置。
    • 查找网络，以查找可连接的网络，您可通过桌面环境或命令行进行操作。
    • 连接到无线网络，可通过桌面环境或命令行完成。
    • WLan强度，这是通过交互式 raspi-config TUI 设置的高级选项。
  • 蓝牙，例如鼠标或键盘，可通过桌面环境完成。

Wi-Fi 连接需要 Raspberry Pi 具备内置无线连接功能，或插入无线 USB 适配器。

启用无线网络（设置 WLAN 国家/地区）​

在配备双频无线功能的树莓派设备上，出于安全考虑，网络功能会在设置无线局域网（WLAN）国家/地区之前自动禁用。此规则适用于树莓派 3B+ 及更高版本、Compute Module 4 及更高版本，以及所有带键盘的计算机（树莓派 400、500 和 500+）。

设置 WLAN 国家/地区用于指定您使用树莓派的位置。这使您的树莓派能够为 5 GHz 网络选择正确的频段。指定 WLAN 国家/地区后，您即可使用树莓派设备内置的无线网络模块。除非您想更改，否则只需设置一次 WLAN 国家/地区。

重要提示：选择正确的 Wi-Fi 监管区域至关重要，因为它决定了可用信道、发射功率和整体网络性能；错误的设置可能导致法律问题、增加干扰、降低容量以及连接质量下降。

通常，当您使用 Imager 将操作系统安装到启动介质时，会设置 WLAN 国家/地区，但您也可以稍后通过桌面图形界面或终端（通过 raspi-config 文本界面及 nmcli 命令）进行设置或更改。

  1. 选择左上角的树莓派图标。
  2. 选择 首选项 > 控制中心。
  3. 打开 本地化 选项卡。
  4. 在列表底部选择 设置 WLAN 国家/地区。
  5. 从 国家/地区 下拉菜单中选择您的国家/地区。
  6. 选择 确定，然后选择 关闭。

查找网络​

在连接无线网络之前，您必须先查找或指定一个可用的网络。在 Raspberry Pi OS 上，您可以通过桌面 GUI 中的 网络管理器 或通过命令行查看附近的 Wi-Fi 网络。

要在桌面上查看可用的 Wi-Fi 网络，请选择右上角系统托盘中的无线图标。该图标显示当前连接的 Wi-Fi 信号强度，并可打开 网络管理器。从 Raspberry Pi OS Bookworm 版本起，网络管理器已成为默认的网络配置工具。

网络管理器会显示可用无线网络的列表。每个可用网络旁边的图标表示：

  • 该网络是否运行在 5 GHz 频段（5G 图标）。
  • 网络是否受保护（挂锁图标）。
  • 网络的信号强度（四格 Wi-Fi 图标）。
wifi2

无线网络管理器菜单

如果出现提示信息称未找到接入点（AP），例如“未找到 AP - 正在扫描”，请等待几秒钟，让网络管理器找到您的网络。

如果您的无线网络因 SSID 被隐藏而未出现在菜单中，请按照 连接到无线网络 中的说明操作。

连接到无线网络​

您可以通过桌面界面或使用 nmcli（NetworkManager 命令行界面）命令来设置无线连接。

nmcli 是一种通过命令行配置系统网络设置的方法。下文概述的命令行操作仅使用了少数几个 nmcli 命令。不过，nmcli 提供了大量命令，这些命令在管理无线连接时可能会对您有所帮助。如需了解更多信息，请参阅 nmcli 网络管理器文档。

备注

以下说明适用于 WEP、WPA、WPA2 和 WPA3 网络，但可能不适用于企业网络。

若要在桌面图形界面中更改或添加无线网络，请按照 查找网络 中的说明打开网络管理器，如果要连接的无线网络未被隐藏：

  1. 选择相应的无线网络。如果您的无线网络因处于隐藏状态而未列出，请改按隐藏网络的操作说明进行。
    • 如果您尚未选择无线网络，或之前已将其关闭，请选择 开启无线局域网。然后，从菜单中选择一个无线网络。
    • 如果您已连接到某个无线网络，请从菜单中选择另一个网络。
  2. 若系统提示，请输入该无线网络的密码。
key

连接安全无线网络时的密码提示

  1. 点击窗口右下角的 连接。

启用或禁用 WLAN 省电模式​

WLAN 省电模式是 raspi-config 中的高级选项，除非得到 Raspberry Pi 工程师的指示，否则我们不建议进行设置。禁用省电模式的设置会立即生效，并适用于未来的连接。启用此设置时请谨慎；它可能会提高连接稳定性，但也会增加功耗。

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航至并选择 6 高级选项 > A13 WLAN 省电模式。
  3. 在 是否启用 WLAN 省电模式？* 的提示中选择 是 或 否。
  4. 选择 <确定> 确认此选项，完成后选择 <完成>。

连接蓝牙外设​

如果您的蓝牙设备未附带 USB 适配器，可通过桌面图形界面进行连接。要发现并配对蓝牙键盘或鼠标：

  1. 从顶部菜单中，选择 Wi-Fi 图标左侧的蓝牙图标。
  2. 选择 添加设备。这将打开 添加新设备 窗口。
  3. 等待设备出现在窗口中，然后选择它。
  4. 选择窗口右下角的 配对。
  5. 选择 确定 以确认您希望与该设备配对。

系统与本地化​

本节介绍如何：

  • 浏览器。可在 Chromium 或 Firefox 之间进行选择；若在安装过程中未进行选择，默认浏览器为 Chromium。
  • 配置本地化设置，包括如何：
    • 区域，即全系统的语言和区域设置（国家/地区及字符集）。
    • 时区，由用于设置本地时间的地理区域和城市决定。
    • 键盘，通过指定键盘的物理型号、语言布局和按键变体。
  • 配置高级系统设置，包括如何：
    • 扩展文件系统，如果您已将操作系统克隆到更大的存储设备上，且所用操作系统不会自动扩展文件系统以利用该空间，此功能可能很有用。
    • 日志，用于设置日志的存储位置。
    • 测试版，如果您是 Raspberry Pi OS 的自愿测试用户，可以开启此选项。
    • Wayland。我们不建议切换到 X11，因为我们已不再为其开发。

默认浏览器和本地化设置均可通过桌面环境或交互式 raspi-config 终端界面进行配置。高级设置仅可通过交互式 raspi-config 终端界面进行配置。

如果您正在寻找关于如何在树莓派上设置 WLAN 国家/地区的说明，请参阅 启用无线网络。设置 WLAN 国家/地区的说明位于 无线连接 部分，因为这是连接无线网络的先决条件。

更改默认浏览器​

新安装系统的默认浏览器是 Chromium，但您可以选择将 Chromium 或 Firefox 设为默认浏览器。

无论您将哪个浏览器设为默认，另一个浏览器仍可在 互联网 系统菜单中使用。

要更改默认浏览器：

  1. 选择系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 系统 选项卡。
  3. 在 Chromium 和 Firefox 之间进行选择。
  4. 点击 控制中心 右下角的 关闭。

配置区域设置​

区域设置（Locale）是一种用于在多种语言和地区之间切换的框架。它允许您的树莓派显示您首选的语言、日期格式、货币符号和字符集。新安装系统默认选择 UTF-8 区域设置。此外还提供 C、C.UTF-8 和 POSIX 区域设置，您也可以根据需要生成其他区域设置。

配置区域设置时，您正在设置全系统默认的区域设置，这将更改树莓派所有用户的语言。

在桌面环境中配置区域设置需要分别设置以下内容：

  • 语言，例如 en 表示英语。
  • 地区（国家），例如 GB 表示英国。
  • 字符集（现代 Web 和操作系统的字符编码标准），例如 UTF-8 表示支持 Unicode。

使用 raspi-config 文本用户界面 (TUI) 配置区域设置时，需通过一个字符串同时设置语言、地区和字符集。例如，en_GB.UTF-8 将区域设置为英国英语，并采用 UTF-8 字符编码。

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 本地化 选项卡。
  3. 点击 区域设置 旁边的 设置区域设置。
  4. 从 语言 下拉菜单中选择您的语言，例如 en (英语)。
  5. 从 国家/地区 下拉菜单中选择您的国家/地区，例如 GB (英国)。
  6. 从 字符集 下拉菜单中选择一个可用的字符集，例如 UTF-8。
  7. 在 区域设置 窗口的右下角点击 确定。
  8. 在 控制中心 的右下角点击 关闭。
  9. 重启树莓派以使更改生效。

配置时区​

配置时区首先需要选择一个地理区域（例如 Europe），然后根据城市所在位置选择与您的时区对应的城市（例如 London）。选择正确的时区可自动处理夏令时转换。

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 本地化 选项卡。
  3. 在 时区 旁边选择 设置时区。
  4. 从 区域 下拉菜单中选择相应的地理区域。例如，如果您居住在英国，请选择 欧洲。
  5. 选择与您的时区相对应的城市。例如，如果您居住在英国，请选择 伦敦。
  6. 在 时区 窗口的右下角选择 确定。
  7. 在 控制中心 的右下角点击 关闭。

配置键盘​

您可以通过更改以下任一设置来自定义和配置键盘：

  • 型号：设备的物理硬件设计和按键数量。例如，如果您使用的是带数字小键盘的标准全尺寸键盘，请选择 通用 105 键 PC。
  • 布局：键盘按键所分配的主要语言及符号排列方式。例如，若需使用与美式键盘相比“”和“@”符号位置互换的布局，请选择 英语（英国）。
  • 变体：仅通过桌面控制中心提供。针对专用硬件或区域偏好对布局进行的特定修改。例如，对于 Alt 和 Cmd 键被重新映射的 Apple 键盘，请选择 英语（英国，Macintosh）。如果您没有特定的修改，则变体与布局相同。
  • 备用布局：仅通过桌面控制中心提供。一种可通过切换键切换的替代键盘布局。例如，您可以选择 英语（美国） 作为备用布局。
  • 替代变体：仅通过桌面控制中心提供。针对专用硬件或区域偏好对布局进行的特定修改。例如，选择 切罗基语 即可使用切罗基语英语。
  • 切换键：仅通过桌面控制中心可用。用于在当前布局与您已设置的任何替代布局之间切换的按键，或按键组合（如 Ctrl + Alt）。
  • 指示灯：仅通过桌面控制中心可用。当替代布局处于活动状态时会点亮的可选键盘 LED 指示灯。通常为 Caps、Num 或 Scroll 键。
  • AltGr：仅通过终端中的 sudo raspi-config 可用。这是一个修饰键，用于输入键盘布局语言中不常见的字符，例如外币符号和带重音的字母。

由于桌面 控制中心 和 sudo raspi-config 各自拥有独立的配置设置，您可能需要同时执行这两个步骤才能完成键盘自定义。

配置键盘的方法：

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 本地化 选项卡。
  3. 点击 键盘 旁边的 设置键盘。
  4. 从 型号 下拉菜单中选择合适的键盘型号。
  5. 从 布局 下拉菜单中，选择合适的键盘布局。
  6. 从 变体 下拉菜单中，选择合适的键盘变体。
  7. 可选：选择 添加备用键盘。这将显示另外四个下拉菜单。
    1. 从 备用布局 下拉菜单中，选择备用键盘的布局。
    2. 从 备用变体 下拉菜单中，选择备用键盘的变体。
    3. 在 切换键 菜单中，选择用于在键盘配置之间切换的按键或按键组合，例如 左 Alt + Caps。
    4. 如果您使用的键盘带有指示灯，请从 指示灯 下拉菜单中选择在备用键盘激活时点亮的键盘 LED：无、Caps、Num 或 Scroll。
    备注

    请勿在树莓派独立 USB 键盘或树莓派 400 上将指示灯设为 Num。否则会导致键盘右侧按键输出的内容变为字母而非数字。

  8. 在 键盘 窗口的右下角点击 确定。
  9. 在 控制中心 窗口的右下角选择 关闭。
  10. 重启树莓派以使更改生效。

扩展文件系统​

扩展文件系统是一项高级选项，通常仅在您迁移至更大容量的启动介质且未使用 Raspberry Pi OS 时才需要。扩展操作系统分区可让您的 Raspberry Pi 充分利用新启动介质的全部容量。

在大多数情况下，Raspberry Pi OS 会在首次启动时自动执行扩展操作。

注意

此操作没有确认步骤。当您选择扩展文件系统时，分区扩展将立即开始。

若要使用交互式 raspi-config 文本用户界面 (TUI) 扩展文件系统：

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航至并选择 6 高级选项 > A1 扩展文件系统。
  3. raspi-config 会自动调整根分区大小，随后显示确认信息，提示文件系统将在下次重启时进行扩展。
  4. 完成后，选择 <OK> 然后选择 <Finish>。
  5. 重启树莓派以使更改生效。

配置日志记录​

日志记录是一项高级选项，通常仅在需要更改系统日志数据的存储或管理方式时才需使用，例如为了减少磁盘写入、在重启后保留日志，或出于性能考虑禁用日志记录。

若要使用交互式 raspi-config TUI 配置日志记录：

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航至并选择 6 高级选项 > A12 日志记录。
  3. 从以下选项中选择一项：
    • 1 默认，使用系统的默认日志配置。
    • 2 易失性，仅将日志存储在 RAM 中，通常位于 /run/log/journal 目录下。日志为临时数据，重启后将被清除。
    • 3 持久，将日志存储在磁盘上，通常位于 /var/log/journal 目录下，这意味着如果需要长期用于故障排除，日志在重启后仍会保留。此模式还支持为每个用户创建独立的日志文件（日志拆分）。
    • 4 自动，根据系统配置和可用存储空间自动确定合适的日志记录行为。若 /var/log/journal 目录存在，则使用持久日志记录；若不存在，则使用易失性日志记录。
    • 5 无，关闭系统日志记录。
  4. 选择 <OK>，然后再次选择 <OK>。
  5. 完成后选择 <Finish>。

启用或禁用 beta 访问​

Beta 访问允许您使用仍在测试中的较新预发布软件包和引导加载程序更新。此选项适用于希望尝试最新功能并协助排查问题的高级用户。

备注

这与使用 rpi-update 不同，后者提供未经测试的固件更新，仅应在明确建议时使用。Beta 访问是一种更安全、需主动选择的测试方式，可从专用软件库中测试较新软件。

若要通过交互式 raspi-config 终端用户界面 (TUI) 启用或禁用 Beta 访问权限：

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航至并选择 6 高级选项 > A6 Beta 访问权限。
  3. 选择以下选项之一：
    • B1 Beta 软件，此选项将启用 Beta 软件仓库，允许安装较新的预发布软件包和最新的引导加载程序更新。
    • B1 Beta 软件，使用标准、稳定的软件仓库，推荐给大多数用户。
  4. 选择 <OK>，然后再次选择 <OK>。
  5. 在新的终端中，使用 sudo apt update 更新软件包列表以应用更改。

在 Wayland 和 X11 之间切换​

从 Raspberry Pi OS Bookworm 版本起，所有 Raspberry Pi 机型默认使用 labwc 运行 Wayland。

注意

我们不建议从 Wayland 切换到 X，因为我们已不再积极开发 X11。

若要通过交互式 raspi-config TUI 在 Wayland 和 X11 之间切换：

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航至并选择 6 高级选项 > A7 Wayland。
  3. 选择以下选项之一：
    • W1 X11（不推荐）。
    • W2 Labwc（Wayland，推荐）。
  4. 选择 <OK>，然后再次选择 <OK>。
  5. 完成后选择 <Finish>。

用户访问与管理​

本节介绍如何在树莓派上管理用户和密码，包括：

用户访问与管理快速参考：​

以下是本节操作流程中提及的部分命令简要列表。

功能命令
列出所有现有用户。ls -l /home
检查当前用户的组权限。groups
添加新用户。sudo adduser
切换到其他用户。sudo su - \<username>
删除用户及其主目录。sudo deluser --remove-home \<username>
更改当前用户的密码。sudo passwd
打开配置中心。sudo raspi-config

获取用户列表​

要获取所有现有用户及其主目录的列表，请运行以下命令：

ls -l /home

您可以使用以下命令导航至此处列出的任何用户的主目录，将 <username> 替换为该用户的用户名：

cd /home/<username>
ls -la

添加用户​

要在树莓派上添加新用户：

  1. 输入以下命令，将 <username> 替换为新用户的用户名： 
    sudo adduser <username>
  2. 系统提示时，请输入新用户的密码。
  3. 可选：输入新用户的其他信息，例如全名、房间号等。若不需输入这些信息，请按键盘上的 Enter 或 Return 键跳过。
  4. 按 Y 键，然后按 Enter 或 Return 键，表示信息正确。

创建新用户时，其主目录会自动创建在 /home/<username>。

要查看新用户的主目录，请运行以下命令：/home/<username>，将 <username> 替换为用户的用户名。

返回结果类似于：

-bash: /home/<username>: Is a directory

授予用户访问权限​

您可以授予用户访问系统组的权限。

备注

在以下列表中包含 sudo 将授予该用户超级用户权限。

要授予用户权限，请运行以下命令，并将 <username> 替换为新用户的用户名。

sudo usermod -a -G adm,dialout,cdrom,sudo,audio,video,plugdev,games,users,input,render,netdev,lpadmin,gpio,i2c,spi <username>

您可以通过切换到该用户账户并检查权限来验证操作是否成功。

切换用户​

要切换到其他用户，请运行以下命令，并将 <username> 替换为该用户的用户名：

sudo su - <username>

检查权限​

要查看用户所属的组，请切换到该用户，然后运行以下命令：

groups

删除用户​

要删除用户，请输入以下命令，并将 <username> 替换为该用户的用户名：

备注

此操作将同时删除用户及其主目录。若要保留用户的主目录，请勿使用 --remove-home 选项。

sudo deluser --remove-home <username>

请按键盘上的 Y 键，然后按 Enter 或 Return 键，以确认信息无误。

更改密码​

若要更改当前用户的密码，或在用户创建时未设置密码的情况下为其添加密码，请执行以下任一操作：

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 系统 选项卡。
  3. 选择 更改密码。
  4. 在 输入新密码 字段中，输入新密码。
  5. 在 确认新密码 字段中，再次输入相同的密码。
  6. 选择 控制中心 右下角的 关闭。
  7. 重启树莓派以应用新密码。

启动时要求输入密码​

您可以通过关闭 自动登录 功能，要求用户在启动树莓派时输入密码。

由于您可以通过桌面访问控制台，系统会提示您选择是否要求输入密码才能登录 控制台，以及是否要求输入密码才能登录 桌面。

  1. 选择系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 系统 选项卡。
  3. 若要配置树莓派在启动至控制台时要求输入密码，请使用相应的开关关闭 控制台自动登录。
  4. 若要配置树莓派在启动至桌面时要求输入密码，请使用相应的开关关闭 桌面自动登录。
  5. 在 控制中心 的右下角选择 关闭。
  6. 重启树莓派以应用更改。

关闭超级用户命令的密码验证​

在树莓派中，在命令前添加 sudo 可在超级用户（管理员）权限下运行该命令。

默认情况下，树莓派操作系统在执行 sudo 命令时会要求您输入密码。这可防止未经授权的用户在您的设备上运行 sudo 命令。

您可以在使用 Imager 安装时覆盖此设置，也可以在安装完成后通过桌面环境或交互式 raspi-config 文本用户界面（TUI）进行设置。

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 系统 选项卡。
  3. 使用 管理员密码 旁边的切换按钮，关闭 sudo 命令的密码要求。
  4. 点击 控制中心 右下角的 关闭。
  5. 重启树莓派以应用更改。

远程访问​

本节介绍如何在不直接接触 Raspberry Pi 的情况下，通过另一台计算机对其进行控制。具体而言，本节将介绍以下内容：

  • ssh 远程访问 Raspberry Pi 的命令行。您可以通过桌面环境、交互式 raspi-config TUI 以及手动在命令行中进行操作。
  • connect，这是一项树莓派服务，无需手动配置网络即可提供对树莓派桌面和终端的远程访问。您可以在桌面环境中、通过交互式 raspi-config TUI，或手动在命令行中启用此功能。
  • vnc（虚拟网络计算），用于远程访问树莓派的桌面。您可以在桌面环境中或通过交互式 raspi-config TUI 实现此操作。

启用或禁用 SSH​

启用 SSH 后，您可以从另一台计算机远程访问树莓派的命令行。您可以在桌面环境中通过交互式 raspi-config TUI 启用 SSH，也可以在命令行中手动启用。此外，您还可以在使用 Imager 进行安装时将其作为安装流程的一部分启用 SSH。有关更多信息，请参阅 使用 Imager 安装。

启用 SSH 后，下一步是使用 SSH 客户端从另一台计算机连接到树莓派。有关更多信息，请参阅 远程访问 文档。

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 接口 选项卡。
  3. 使用 SSH 旁边的开关来启用或禁用该功能。
  4. 点击 控制中心 右下角的 关闭。
  5. 重启树莓派以应用更改。

启用或禁用 Connect​

Raspberry Pi Connect 允许您从另一台计算机远程访问树莓派的桌面。您可以通过桌面、交互式 raspi-config TUI 以及命令行手动启用 Raspberry Pi Connect。

启用 Raspberry Pi Connect 后，下一步是关联树莓派设备。有关更多信息，请参阅 远程访问 和 树莓派连接 文档。

树莓派连接可通过桌面 GUI 右上角系统托盘中的树莓派连接图标进行启用和禁用。树莓派连接图标由两个小方块通过一个圆圈连接而成。

  • 若要在桌面端启用 Raspberry Pi Connect，请点击系统托盘右上角的 Raspberry Pi Connect 图标，然后选择 开启 Raspberry Pi Connect。
  • 若要在桌面端禁用 Raspberry Pi Connect，请点击系统托盘右上角的 Raspberry Pi Connect 图标，然后选择 关闭 Raspberry Pi Connect。

启用或禁用 VNC​

启用 VNC 后，您可以从另一台计算机访问树莓派的桌面。您可以在桌面上通过交互式 raspi-config TUI 启用 VNC。

启用 VNC 后，下一步是使用 VNC 客户端从另一台计算机连接到树莓派。有关更多信息，请参阅 远程访问 文档。

  1. 选择系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 接口 选项卡。
  3. 使用 VNC 旁边的开关来启用或禁用该功能。
  4. 点击 控制中心 右下角的 关闭。

硬件通信​

本节介绍如何在树莓派上启用硬件通信协议，以便树莓派能够与外部设备（如传感器、显示屏和微控制器）进行交互。具体而言，本节涵盖以下内容：

  • spi：用于与外设（如小型显示屏）进行高速通信。您可以在桌面环境中通过交互式 raspi-config TUI 完成此操作。
  • ic2：用于与传感器、RTC 模块及部分 HAT 等低速设备通信。您可以在桌面环境中操作，也可通过交互式 raspi-config TUI 进行设置。
  • one-wire：用于与温度传感器和 LED 等设备进行简单通信。您可以在桌面环境中操作，也可通过交互式 raspi-config TUI 进行设置。
  • serial-port：用于与其他设备进行 UART 通信。您可以在桌面环境中操作，也可以通过交互式 raspi-config TUI 进行设置。
  • uarts：用于多种用途，例如选择用于通信的 UART 以及调整串行设置。其中大部分操作需要使用命令行。

启用或禁用 SPI​

启用 SPI（串行外设接口）可让您的树莓派通过高速同步协议与兼容设备进行通信。具体而言，启用 SPI 会实现以下两点：

  • 开启树莓派上的 SPI 接口。
  • 在启动时加载 SPI 内核模块，以便连接的设备能够进行通信。

您可以在桌面环境中通过交互式 raspi-config TUI 启用 SPI。

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 接口 选项卡。
  3. 使用 SPI 旁边的开关来启用或禁用它。
  4. 点击 控制中心 右下角的 关闭。

启用或禁用 I2C​

启用 I2C（集成电路间通信）可让您的树莓派与低速外设（如传感器和实时时钟）进行通信。具体而言，启用 I2C 会实现以下两点：

  • 开启树莓派上的 I2C 接口。
  • 在启动时加载 I2C 内核模块，以便连接的设备能够进行通信。

您可以在桌面环境中，通过交互式 raspi-config 文本用户界面 (TUI) 启用 I2C。

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 接口 选项卡。
  3. 使用 I2C 旁边的开关来启用或禁用该功能。
  4. 在 控制中心 的右下角选择 关闭。

启用或禁用1-Wire接口​

启用1-Wire接口后，您的树莓派即可与温度传感器等简单设备进行通信。您可以在桌面环境中，或通过交互式 raspi-config 终端用户界面（TUI）来启用或禁用1-Wire接口。

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 接口 选项卡。
  3. 使用 1-Wire 旁边的开关来启用或禁用该功能。
  4. 点击 控制中心 右下角的 关闭。
  5. 重启树莓派以使更改生效。

启用或禁用串行端口​

启用串行端口后，树莓派即可通过 UART（通用异步收发器）与其他设备（如微控制器）进行通信。共有两项独立的串行设置，分别控制以下功能：

  • 串口硬件。启用用于通信的 UART 引脚（TX/RX）。
  • 串口控制台。通过串口连接发送内核启动信息并提供登录 shell。

您可以在桌面端或通过交互式 raspi-config 文本用户界面（TUI）分别启用和禁用这些串口选项。对于大多数硬件项目，建议启用串口硬件并禁用串口控制台。

  1. 点击系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 接口 选项卡。
  3. 根据需要使用切换按钮启用以下设置：
    • 串口，用于启用或禁用 UART 硬件。
    • 串行控制台，用于启用或禁用通过串口登录的 shell。
  4. 在 控制中心 的右下角选择 关闭。
  5. 重启树莓派以使更改生效。

配置 UART​

UART（通用异步收发器）是一种用于串行通信的硬件通信协议。树莓派设备上的 UART 允许您与外围设备通信，并通过串行控制台访问 Linux 终端。

前置信息​

要在树莓派上使用 UART，必须确保已启用正确的 UART，将其分配给相应的引脚，并且不会与其他系统服务（如串行控制台或蓝牙）发生冲突。

UART 类型​

树莓派支持两种 UART：

  • PL011：功能完整、兼容 16550 的 UART，提供由硬件计时的串行通信。
  • Mini UART：轻量级 UART，提供简单而高效的串行接口。

与 PL011 不同，mini UART 没有断点检测、帧错误检测、奇偶校验位以及接收超时中断。mini UART 的 FIFO 也更小。加上缺少流控制，mini UART 在较高波特率下更容易丢失字符。此外，mini UART 通常能力也不如 PL011，主要是因为它的波特率与 VPU 时钟频率相关。更多关于 mini UART 的信息，请参阅 SoC 外设文档。

mini UART 与 BCM2835 版本的 PL011 均不具备 DCD、DSR、DTR 和 RI 信号。

警告

所有 UART 都工作在 3.3V；接入 5V 系统会造成损坏。对于 5V 系统，请使用电平转换器或 USB 转 3.3V 串行适配器。

可用的 UART 接口因树莓派型号而异。下表汇总了常见树莓派设备的默认 UART 配置。

按树莓派型号区分的 UART

型号UART
树莓派 Zero、1、2、3；Compute Module 1、3 和 3+UART0：PL011
UART1：mini UART
树莓派 4、400 和 Compute Module 4、4SUART0：PL011
UART1：mini UART
UART2 至 UART5：PL011（默认禁用）
树莓派 5、500、500+ 和 Compute Module 5UART0 至 UART4：PL011（默认禁用）
没有 mini UART

在 Compute Module 上，所有 UART 默认都被禁用，可以通过设备树覆盖启用，例如：

dtoverlay=uart1,txd1_pin=32,rxd1_pin=33
主 UART 和辅助 UART​

主 UART 是树莓派对外暴露的主要串行接口。当您连接外部设备并用于 Linux 串行控制台时，通常就是使用这个 UART。除了树莓派 5 之外，所有树莓派的主 UART 都被路由到特定的 GPIO 引脚：

  • GPIO 14（发送）对应 GPIO 排针上的 8 号引脚。
  • GPIO 15（接收）对应 GPIO 排针上的 10 号引脚。

在树莓派 5 上，主 UART 改为通过专用的调试排针对外暴露。

辅助 UART 是系统内部另一个可用的串行接口；默认情况下通常不通过 GPIO 排针对外暴露。在带有内置无线功能的型号上，该 UART 通常在内部连接到蓝牙控制器，使系统在不使用外部 GPIO 引脚的情况下与蓝牙硬件通信。

主 UART 和辅助 UART

型号主 UART（Linux 控制台）辅助 UART（带无线的树莓派上的蓝牙）
树莓派 ZeroUART0UART1
树莓派 Zero W 和 Zero 2 WUART1UART0
树莓派 1 和 2UART0UART1
树莓派 3 和 4UART1UART0
树莓派 5UART10专用 UART
Compute Module 1、3、3+ 和 4UART0UART1
Linux 设备名​

在 Linux 中，UART 通过 /dev/ 下的文件进行访问。每个 UART 都表现为一个设备节点。这些节点作为接口，使软件能够通过读写文件来发送和接收数据。

UART 的 Linux 设备节点

设备节点类型说明
/dev/ttyS0硬件Mini UART
/dev/ttyAMA0硬件第一个 PL011（UART0）
/dev/ttyAMA10硬件树莓派 5 上的调试 UART
/dev/serial0符号链接主 UART：根据型号不同，指向 /dev/ttyS0、/dev/ttyAMA0 或 /dev/ttyAMA10（树莓派 5）
/dev/serial1符号链接辅助 UART：指向 /dev/ttyAMA0 或 /dev/ttyS0

因为不同树莓派型号的主串口使用了不同的硬件，树莓派 OS 会创建符号链接以指向正确的硬件端口。

对于 Bookworm 及更高版本，/dev/serial1 可能默认不存在。要启用它，请在 config.txt 中添加：

dtparam=krnbt=off

此选项将来可能在所有型号上都不再可用。只有在没有其他替代方案时才使用此选项。

Mini UART 与核心频率​

由于 mini UART 的时钟来自 VPU 核心时钟，核心频率动态变化时其可靠性会受影响；核心时钟频率变化时，UART 波特率也会随之变化。当核心频率可变时，如果 mini UART 作为主 UART 或蓝牙关闭，系统会禁用 mini UART。若要启用它，需要设置固定的 VPU 时钟：

enable_uart=1

下表总结了不同配置下（mini UART 是主还是辅、核心时钟是固定还是可变）的行为。

Mini UART 配置与核心时钟行为

Mini UART 设为核心时钟结果
主 UART可变Mini UART 禁用
主 UART固定（enable_uart=1）Mini UART 启用；核心固定在 250 MHz（或强制时为睿频频率）
辅助 UART可变Mini UART 禁用
辅助 UART固定（core_freq=250）Mini UART 启用

系统会根据哪种硬件类型被指定为主 UART 自动决定是否启用 UART。如果主接口是 PL011，系统默认"开启"；如果主接口是更敏感的 mini UART，除非显式覆盖，否则系统默认"关闭"，以避免动态频率缩放带来的问题。

按主 UART 类型区分的默认 enable_uart 行为

主 UART默认 enable_uart
Mini UART0
PL011（UART0 或 UART10）1

禁用 Linux 串行控制台​

默认情况下，主 UART 分配给了 Linux 控制台。如果您希望用主 UART 连接其他串行设备，必须在保持 UART 启用的同时禁用控制台。您可以通过桌面或交互式 raspi-config TUI 进行此操作：

  1. 选择系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 Interfaces（接口）标签页。
  3. 使用 Serial Port 旁的切换开关打开串行端口硬件。
  4. 使用 Serial Console 旁的切换开关关闭串行控制台。
  5. 选择 控制中心 右下角的 Close。
  6. 重启树莓派以使更改生效。

为 Linux 启用早期控制台​

在进行内核调试或监控早期启动阶段时，Linux 控制台可能尚不可用。为其中一个 UART 启用早期控制台支持有助于诊断启动问题和硬件初始化问题。

要启用早期控制台支持，请根据树莓派型号和 UART 在 cmdline.txt 中添加相应的 earlycon 参数。

注意

earlycon=uart8250 通过 mini UART 输出；earlycon=pl011 通过完整的 PL011 UART 输出。

按型号区分的早期控制台配置参数

型号参数字符串（添加到 cmdline.txt）
树莓派 5（通过调试排针）earlycon=pl011,0x107d001000,115200n8
树莓派 4、400、Compute Module 4 和 4Searlycon=uart8250,mmio32,0xfe215040
earlycon=pl011,mmio32,0xfe201000
树莓派 2、3、3+、Zero 2 W、Compute Module 3 和 3+earlycon=uart8250,mmio32,0x3f215040
earlycon=pl011,mmio32,0x3f201000
树莓派 1、Zero、Zero W 和 Compute Module 1earlycon=uart8250,mmio32,0x20215040
earlycon=pl011,mmio32,0x20201000

默认波特率为 115200 bps。

警告

选错早期控制台可能导致树莓派无法启动。

为 UART 配置设备树覆盖​

您可以使用设备树覆盖来配置 UART 功能，例如启用额外的 UART、在 PL011 与 mini UART 之间切换蓝牙，或重新映射 UART 使用的 GPIO 引脚。

在 config.txt 中指定覆盖时，只使用覆盖的名称，源文件名中的 -overlay.dts 后缀要省略。

您可以在 内核 GitHub 中找到各种 UART 设备树覆盖的定义。两个最有用的覆盖是：

禁用蓝牙并将 UART0 设为主 UART​

要禁用蓝牙调制解调器初始化服务并将第一个 PL011（UART0）设为主 UART：

  1. 禁用蓝牙调制解调器服务：

    sudo systemctl disable hciuart

  2. 打开配置文件：

    sudo nano /boot/firmware/config.txt

  3. 将覆盖添加到配置文件：

    dtoverlay=disable-bt

  4. 保存文件（Ctrl+O）并退出（Ctrl+X）。

  5. 重启树莓派以使更改生效。

将蓝牙切换到使用 mini UART，并将 UART0 设为主 UART​

要保留蓝牙功能但将其重新分配到 mini UART，同时将第一个 PL011（UART0）设为主 UART：

  1. 打开配置文件：

    sudo nano /boot/firmware/config.txt

  2. 通过在配置文件中添加下列之一来固定 VPU 核心时钟：

    • force_turbo=1（将时钟锁定到最大值）
    • core_freq=250（将时钟锁定到标准速度）

  3. 将覆盖添加到配置文件：

    dtoverlay=miniuart-bt

  4. 保存文件（Ctrl+O）并退出（Ctrl+X）。

  5. 重启树莓派以使更改生效。

这可能会降低蓝牙可用的最大波特率。

在树莓派 4、400、CM4 和 CM4S 上启用额外 UART​

覆盖 uart2、uart3、uart4 和 uart5 用于启用树莓派 4、400、Compute Module 4 和 Compute Module 4S 上的 4 个额外 UART。

在树莓派 5、500、500+ 和 Compute Module 5 上，对应使用 uart0-pi5、uart1-pi5、uart2-pi5、uart3-pi5 和 uart4-pi5 覆盖。

要查看这些 UART 可用的引脚和选项，使用下面的帮助命令，将 uartx 中的 x 替换为您想查询的 UART 编号：

dtoverlay -h uartx

也可以查看 /boot/firmware/overlays/README 获取设备树覆盖的详细信息。

之后，要应用某个覆盖，将它添加到 config.txt：

  1. 打开配置文件：

    sudo nano /boot/firmware/config.txt

  2. 将覆盖添加到 config.txt，把 uartx 中的 x 替换为对应的 UART 编号：

    dtoverlay=uartx

  3. 保存文件（Ctrl+O）并退出（Ctrl+X）。

  4. 重启树莓派以使更改生效。

外部存储​

您可以将外置硬盘、固态硬盘或 U 盘连接到树莓派的任意 USB 端口，并挂载文件系统以访问其中存储的数据。

默认情况下，树莓派会在 /media/pi/<HARD-DRIVE-LABEL> 位置自动挂载 FAT、NTFS 和 HFS+ 等常用文件系统。

注意

树莓派OS Lite 不支持自动挂载。

要设置存储设备使其始终挂载到您选择的特定位置，必须手动挂载。

挂载存储设备​

您可以将存储设备挂载到特定文件夹位置。常规做法是在 /mnt 文件夹中进行挂载，例如 /mnt/mydisk。注意，文件夹必须为空。

将存储设备插入树莓派的 USB 端口，使用以下命令列出树莓派上的所有磁盘分区：

sudo lsblk -o UUID,NAME,FSTYPE,SIZE,MOUNTPOINT,LABEL,MODEL

树莓派使用挂载点 / 和 /boot/firmware/。您的存储设备将与其他已连接的存储设备一起显示在此列表中。

使用 SIZE、LABEL 和 MODEL 列来确定指向存储设备的磁盘分区名称。例如，sda1。FSTYPE 列包含文件系统类型。如果存储设备使用 exFAT 文件系统，请安装 exFAT 驱动程序：

sudo apt update
sudo apt install exfat-fuse

如果存储设备使用 NTFS 文件系统，则只能对其进行只读访问。如果想写入设备，可以安装 ntfs-3g 驱动程序：

sudo apt update
sudo apt install ntfs-3g

运行以下命令获取磁盘分区的位置：

sudo blkid

例如，/dev/sda1。

创建目标文件夹作为存储设备的挂载点。本例中使用的挂载点名称是 mydisk。您可以指定一个自己喜欢的名称：

sudo mkdir /mnt/mydisk

在创建的挂载点挂载存储设备：

sudo mount /dev/sda1 /mnt/mydisk

列出存储设备的内容，验证是否已成功挂载：

ls /mnt/mydisk

自动挂载存储设备​

您可以修改 fstab 文件，定义树莓派启动时自动挂载存储设备的位置。在 fstab 文件中，磁盘分区由通用唯一标识符（UUID）标识。

获取磁盘分区的 UUID：

sudo blkid

从列表中找到磁盘分区并记下 UUID。(例如，5C24-1453。）使用命令行编辑器（如 nano）打开 fstab 文件：

sudo nano /etc/fstab

在 fstab 文件中添加以下一行：

UUID=5C24-1453 /mnt/mydisk fstype defaults,auto,users,rw,nofail 0 0

将 fstype 替换为文件系统的类型，即在执行上述步骤时找到的类型，例如：ntfs。

如果文件系统类型是 FAT 或 NTFS，请在 nofail 后添加 ,umask=000 - 这将允许所有用户对存储设备上的每个文件进行完全读/写访问。

既然已经在 fstab 中设置了条目，就可以在连接或不连接存储设备的情况下启动树莓派了。在拔出设备之前，您必须关闭树莓派或手动卸载它。

注意

如果在树莓派启动时没有连接存储设备，启动时间将增加 90 秒。你可以在 nofail 后添加 ,x-systemd.device-timeout=30 来缩短时间。这将把超时时间改为 30 秒，意味着系统只等待 30 秒就会放弃挂载磁盘的尝试。

有关每个 Linux 命令的更多信息，请使用 man 命令参阅特定的手册页面。例如，man fstab。

卸载存储设备​

当树莓派关机时，系统会卸载存储设备，以便安全地拔下插头。如果你想手动卸载设备，可以使用以下命令：

sudo umount /mnt/mydisk

如果收到 "目标忙" 的错误提示，这意味着存储设备没有卸载。如果没有显示错误，则可以安全地拔下设备。

处理 'target is busy' (目标繁忙)​

目标繁忙信息意味着存储设备上有文件正在被程序使用。要关闭文件，请使用以下步骤。

关闭存储设备上打开文件的任何程序。如果你打开了终端，请确保你不在安装存储设备的文件夹中，也不在其子文件夹中。

如果仍无法卸载存储设备，可以使用 lsof 工具检查设备上打开文件的程序。首先，你需要使用 apt 安装 lsof：

sudo apt update
sudo apt install lsof

使用 lsof：

lsof /mnt/mydisk

固件​

本节介绍如何：

更改启动顺序​

启动顺序决定树莓派尝试从哪里启动。在树莓派 4 及更高型号上，当未检测到 SD 卡或 SSD 时，您可以指定是从 USB 还是网络启动。默认情况下，系统会首先从 SD 卡启动。

使用 raspi-config TUI 更改启动顺序：

  1. 打开终端并运行 sudo raspi-config。
  2. 导航并选择 6 Advanced Options > A4 Boot Order。
  3. 从以下选项中选择：
    • B1 SD Card Boot（推荐）优先从 SD 卡启动系统。如果没有找到可启动的 SD 卡，引导加载程序会接着尝试 NVMe，然后是 USB。
    • B2 NVMe/USB Boot 优先从 NVMe 存储启动。如果没有找到可启动的 NVMe 设备，引导加载程序会接着尝试 USB，然后是 SD 卡。
    • B3 Network Boot 优先从 SD 卡启动。如果没有找到可启动的 SD 卡，引导加载程序会尝试通过网络启动 (PXE)。
  4. 终端会短暂运行一些代码，然后返回 TUI 确认您的选择已实施。选择 <OK>，然后选择 <Finish>。

更新引导加载程序​

在 Raspberry Pi OS 上，当发布重要的错误修复和改进时，引导加载程序版本会自动更新。CM4 和 CM4S 不支持自动引导加载程序更新，因为它们的启动 ROM 无法从 eMMC 加载 recovery.bin 文件。对于这些型号，建议使用 rpiboot 和 flashrom 等手动更新工具。详情请运行：

rpi-eeprom-update -h

在树莓派 4 及更高型号上，您可以手动切换到最新的启动 ROM 软件，或者还原到出厂默认版本。具体来说，以下机型支持引导加载程序版本更新：

  • 自树莓派 4B 起的旗舰型号。
  • 自 CM5 起的 Compute Module。
  • 所有键盘型电脑（树莓派 400、500 和 500+）。

您可以使用 raspi-config TUI 在最新版本和默认版本之间切换来更新引导加载程序。或者，使用命令行在不切换的情况下更新引导加载程序。

如果您不是要更新引导加载程序版本，而是要重置引导加载程序，请参阅 重置引导加载程序。

首先，打开终端并运行以下代码更新 Raspberry Pi OS，获取 rpi-eeprom 包的最新版本：

sudo apt update && sudo apt full-upgrade

然后：

  1. 使用键盘导航并选择 6 Advanced Options > A5 Bootloader Version。
  2. 选择以下发布轨道之一：
    • E1 Latest 获取最新的引导加载程序发布版本和新的引导加载程序功能。此选项更适合想要尝试最新但未经充分测试功能的高级用户。
    • E2 Default 使用稳定的出厂默认设置。此选项提供关键的错误修复、硬件支持和经过测试的最新功能。
  3. 选择 Yes 确认您的选择。
  4. 重启树莓派以应用更改。

管理引导加载程序配置​

本节提供从命令行读取引导加载程序版本和管理引导加载程序配置的说明。开发人员和系统管理员可以在 rpi-eeprom GitHub 仓库 中找到用于创建 rpi-eeprom 映像的脚本和预编译的二进制文件。

检查引导加载程序版本和配置​

运行以下命令检查当前引导加载程序版本：

sudo rpi-eeprom-update

输出会告诉您树莓派当前已安装的版本 (CURRENT)、最新可用版本 (LATEST) 和系统使用的发布轨道 (RELEASE)。例如：

*** UPDATE AVAILABLE ***
BOOTLOADER: update available
   CURRENT: Thu 18 Jan 13:59:23 UTC 2024 (1705586363)
    LATEST: Mon 22 Jan 10:41:21 UTC 2024 (1705920081)
   RELEASE: latest (/lib/firmware/raspberrypi/bootloader-2711/latest)
            Use raspi-config to change the release.

  VL805_FW: Using bootloader EEPROM
     VL805: up to date
   CURRENT: 000138c0
    LATEST: 000138c0

读取当前引导加载程序配置​

运行以下命令查看当前运行的引导加载程序所使用的配置：

rpi-eeprom-config

运行以下命令从引导加载程序映像中读取配置：

rpi-eeprom-config pieeprom.bin

编辑引导加载程序配置​

以下命令会将当前引导加载程序配置加载到文本编辑器中。文本编辑器由 EDITOR 环境变量选定。

关闭编辑器后，rpi-eeprom-config 会将更新后的配置应用到最新可用的引导加载程序发布版本，并使用 rpi-eeprom-update 计划在系统重启时更新：

sudo -E rpi-eeprom-config --edit
sudo reboot

如果更新后的配置相同或为空，引导加载程序将保持不变。

应用已保存的配置​

运行以下命令将保存的配置文件（例如 boot.conf）应用到最新的引导加载程序发布版本。

sudo rpi-eeprom-config --apply boot.conf
sudo reboot

这将使更改在重启后生效。

启用或禁用网络安装 UI​

网络安装的用户界面 (UI) 控制当未检测到本地启动介质时，树莓派是否显示基于网络的 OS 安装菜单。在树莓派 4 及更高型号上，启用此选项可以让您与引导加载程序交互以执行网络安装 (PXE 启动)。禁用此选项则会隐藏网络安装流程。

使用交互式 raspi-config TUI 更改网络安装 UI 设置：

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航并选择 6 Advanced Options > A9 Network Install UI。
  3. 从以下选项中选择：
    • B1 Always：通电后总是在几秒钟内显示网络安装 UI。
    • B2 On demand：当按下键盘上的 Shift 键或发生错误时显示网络安装 UI。
  4. 完成后选择 <OK>，然后选择 <Finish>。

启动行为​

启动行为决定了树莓派在开机时加载什么。您可以将其配置为启动完整的桌面图形用户界面 (GUI)，也可以让它启动到基于文本的命令行界面 (CLI，也称为控制台模式)。相关操作请参见 启动到控制台或桌面。

您还可以控制启动期间显示什么。具体来说，您可以打开或关闭标准 Plymouth 启动画面，也可以用自定义的早期启动画面替换默认的早期启动树莓派画面。相关操作请参见 配置启动画面。

本节还介绍了内核命令行，它是在启动过程中向 Linux 内核传递底层指令的主要机制。引导加载程序通过 config.txt 初始化硬件，而内核命令行则通过 cmdline.txt 定义操作系统接管后的行为。相关操作请参见 配置内核命令行。

注意

如果您在寻找自动登录相关信息，请参阅 启动时要求输入密码。

启动到控制台或桌面​

您可以选择树莓派启动时进入控制台还是桌面，操作方式包括桌面和交互式 raspi-config TUI。

  1. 选择系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 System（系统）标签页。
  3. 在 Boot（启动）旁选择 To desktop（进入桌面）或 To CLI（进入命令行）。选择 To CLI 会关闭桌面自动登录，若未来改回 To desktop 则需要输入密码。
  4. 选择 控制中心 右下角的 Close。
  5. 重启树莓派以应用更改。

配置启动画面​

Raspberry Pi OS 在启动过程中可以显示两种启动画面：

  • 标准 Plymouth 启动画面。这是一个图形化启动画面，可以开启或关闭。若关闭标准 Plymouth 启动画面，系统会改为显示基于文本的控制台日志信息。
  • 自定义早期启动画面。一张在标准 Plymouth 启动画面之前显示的全屏图像，用于替换树莓派标志。

显示或移除 Plymouth 启动画面​

您可以使用桌面 GUI 或交互式 raspi-config TUI 来选择是否在启动时显示树莓派图形启动画面，而不是显示控制台日志消息（文本）。

  1. 选择系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 System（系统）标签页。
  3. 使用 Splash Screen 旁的切换开关在启动时添加或移除图形启动画面。
  4. 选择 控制中心 右下角的 Close。

自定义早期启动画面​

早期启动画面是一张在启动过程最初几秒显示的全屏图像，出现在标准 Plymouth 启动画面之前。它提供系统正在加载的可视反馈；您可以选择是否显示此屏幕并可自定义它。

文件要求​

全屏启动画面图像必须满足以下文件要求：

  • 最大尺寸。1920 × 1080 像素。
    • 如果图像小于屏幕，图像周围的剩余区域会使用图像左上角像素 (0, 0) 的纯色填充。
    • 不会应用缩放。如果屏幕小于图像，图像会被裁剪并居中显示。
  • 最大颜色数。224 种独特颜色。
  • 色深。24 位（每通道 8 位，无 alpha 通道）。
  • 格式。未压缩的 TGA。

您可以使用 ImageMagick 的 convert 命令将图像转换为内核期望的 TGA 格式。例如，将 image.png 转换为格式合适的 splash-image.tga 文件：

sudo apt install imagemagick
convert image.png -colors 224 -depth 8 -type TrueColor -alpha off -compress none -define tga:bits-per-sample=8 splash-image.tga

在树莓派上启用全屏启动图像有两种方式。根据您的技术熟练程度，您可以：

  • 使用 APT 包。此方法较为简单，允许您以最少的配置启用启动画面。您安装一个预制的软件包（rpi-splash-screen-support），它会自动完成大部分设置：复制图像、设置内核参数并配置系统。
  • 编辑 cmdline.txt 系统文件。此方法技术性更强，但让您可以控制每一步。您需要手动在命令行中配置启动图像，然后更新 initramfs 以包含该启动图像。
使用 APT 包​

安装 rpi-splash-screen-support 包以简化全屏启动图像的设置。该包提供 configure-splash 工具，可设置必要的内核参数并更新您的 initramfs。

  1. 使用以下命令安装软件包：

    sudo apt install rpi-splash-screen-support

  2. 安装 APT 包后，运行以下命令配置您的启动图像，将 <splash-image.tga> 替换为图像文件的名称或路径，该路径可以是相对或绝对路径：

    sudo configure-splash <splash-image.tga>

  3. 运行以下命令重启树莓派以查看启动图像：

    sudo reboot

如果启动时图像显示颠倒，请编辑 convert 命令，在 splash-image.tga 之前添加 -flip 标志。然后运行 configure-splash 以正确方向更新图像。

编辑 cmdline.txt 系统文件​

以下方法需要编辑系统文件并手动更新 initramfs。

  1. 以管理员身份使用以下命令在文本编辑器中打开 /boot/firmware/cmdline.txt：

    sudo nano /boot/firmware/cmdline.txt

  2. 禁用屏幕上的控制台消息，防止启动消息覆盖启动画面。编辑 cmdline.txt 移除以下内容：

    • console=tty1。
    • quiet（如果存在）。

  3. 编辑 cmdline.txt 添加以下参数：

    • fullscreen_logo_name=logo.tga fullscreen_logo=1 启用全屏启动画面。
    • vt.global_cursor_default=0 移除启动画面中的闪烁光标。

    您的条目末尾应该类似这样：

    fullscreen_logo_name=logo.tga fullscreen_logo=1 vt.global_cursor_default=0

  4. 将图像文件放在正确位置。

    • 内核期望图像文件位于 /lib/firmware。
    • 启动时会从 initramfs 读取 TGA 文件。
    • 文件名必须与 cmdline.txt 中的 fullscreen_logo_name 匹配。

有关在 initramfs 中嵌入 TGA 图像的示例代码，请参阅 GitHub 中的 树莓派启动画面支持工具。

注意

步骤 2 不会阻止 getty 启动登录提示符。您的启动图像会在启动过程中显示，但当系统准备好登录时，控制台会接管，启动画面会消失。当系统就绪时，getty 会清除启动画面并在其上方写入登录提示符。

配置内核命令行​

当树莓派（或任何 Linux 系统）启动时，内核会接收一组名为 内核命令行 的启动参数。内核命令行允许您配置系统的各个方面，从排查 USB 延迟问题到自定义显示分辨率。

访问和编辑 cmdline.txt​

Linux 内核在启动时会接受一个命令行参数的集合。在树莓派上，该命令行定义在启动分区中一个名为 cmdline.txt 的文件中。使用以下命令修改启动参数：

sudo nano /boot/firmware/cmdline.txt
重要

cmdline.txt 中的所有参数必须保持在同一行。不要使用换行符，不要在命令之间按键盘上的 Enter 或 Return，因为内核会忽略第一行之后的任何内容。

查看当前设置​

使用以下命令查看 Linux 内核当前的启动参数：

cat /proc/cmdline

这会读取 /proc 中一个反映内核实时状态的特定文件。它可能与您原始的 cmdline.txt 不完全一致，因为树莓派固件会在启动内核前更改内核命令行。

定义核心参数​

以下标准条目定义了树莓派如何识别其硬件并加载操作系统。

标准条目说明备注
console定义启动消息发送到的位置。通常有两个条目：
console=serial0,115200（串行模式）
console=tty1（主屏幕）
root定义根文件系统的位置（操作系统所在位置）。例如 root=/dev/mmcblk0p2 表示多媒体卡块设备 0 的第 2 个分区（microSD 卡上的第 2 个分区）。
rootfstype指定分区的格式（rootfs 使用的文件系统类型）。例如 rootfstype=ext4。
quiet将默认的内核日志级别设置为 KERN_WARNING。这会在启动过程中抑制除非常严重的日志消息之外的所有内容。

其他内核命令行条目​

本节包含一些可在内核命令行中使用的其他条目。此列表并非详尽无遗。

条目说明
splash告诉启动程序通过 Plymouth 模块使用启动画面。
plymouth.ignore-serial-consoles通常情况下，Plymouth 会在串行控制台上抑制启动消息。此条目强制 Plymouth 忽略串行控制台，使启动消息保持可见。
dwc_otg.lpm_enable=0禁用处理器 USB 控制器所使用的 dwc_otg USB 驱动中的链接电源管理 (LPM)。在树莓派 4 及以后型号上，此控制器仅影响 USB-C 电源输入，不影响 USB-A 端口。
dwc_otg.speed=1将 USB 控制器速度设置为全速 (USB 1.0)。对于排查 USB 问题有用，但比高速 (USB 2.0) 慢。仅在诊断问题时使用此条目。
smsc95xx.turbo_mode仅适用于树莓派 1B、1B+、2B、3B 和 3B+。启用或禁用有线以太网驱动的涡轮模式。设置 smsc95xx.turbo_mode=N 会禁用涡轮模式。
usbhid.mousepoll调整鼠标轮询间隔。设置 usbhid.mousepoll=0 可能有助于解决无线鼠标缓慢或不稳定的问题。
drm.edid_firmware=HDMI-A-1:edid/your_edid.bin使用位于 /usr/lib/firmware/edid/ 中的自定义 EDID 文件覆盖显示器的内置 EDID。

本地化树莓派​

您可以将树莓派设置为符合您的地区设置。语言、键盘布局和时区都可以通过 raspi-config 工具进行更改。

运行安全​

本节汇总了提高树莓派安全性的常用方法。如果您需要密码相关的说明，请参阅用户访问与管理。

更新树莓派OS​

为获取最新的安全特性，我们建议您及时更新软件。更多信息请参阅 树莓派操作系统 页面中的 更新当前的树莓派软件。

只有树莓派 OS 的最新主版本才包含所有最新的安全修复。因此，当新的主版本发布后（例如从 Bookworm 升级到 Trixie），我们也建议您升级到最新主版本。这与 更新 树莓派 OS 有所不同：更新只会在当前主版本内安装最新的软件包与安全修复，而不会切换到新的主版本。关于如何升级操作系统，请参阅 升级到新的主版本。

自动升级 SSH Server​

如果你使用 SSH 连接到你的 Raspberry Pi，添加一个专门更新 SSH 服务器的 cron 作业是值得的。下面的命令也许可以作为每天的 cron 作业运行，确保你能及时获得最新的 SSH 安全修复，而不受正常更新进程的影响。

apt install openssh-server

提高SSH安全性​

SSH 是远程访问 Raspberry Pi 的常用方法。默认情况下，SSH 需要用户名和密码。要使 SSH 更加安全，请使用 基于密钥的身份验证。

启用和禁用 SSH 用户​

您还可以通过更改 sshd 配置来allow(允许) 或 deny(拒绝)特定用户。

sudo nano /etc/ssh/sshd_config

在文件末尾添加、编辑或追加以下一行，其中包含你希望允许登录的用户名：

AllowUsers alice bob

也可以使用 DenyUsers 来阻止某些用户名登录：

DenyUsers jane john

更改后，使用以下命令重启 sshd 服务，使更改生效：

sudo systemctl restart ssh

使用防火墙​

防火墙是一种网络安全系统，它根据一组定义好的安全规则，监视和控制传入与传出的网络流量。本节介绍 Uncomplicated Firewall (UFW)，一种通过简化的命令行界面控制网络流量的防火墙工具。

Uncomplicated Firewall (UFW)​

网络流量通过端口号进行组织：端口号是数字化的标签，用于将数据引导到特定的应用程序。防火墙通过开放或关闭特定端口来允许或阻止某些类型的通信。

在 Linux 系统中，网络流量通过内核的防火墙子系统 netfilter 过滤。Netfilter 实现了数据包过滤：它根据数据包的源 IP 地址、目标 IP 地址、端口号、协议和方向等因素，阻止或允许数据包通过系统。

系统管理员可以通过 iptables 与 netfilter 交互，iptables 是定义数据包过滤规则的主要命令行工具。然而 iptables 可能较为复杂。UFW（Uncomplicated Firewall） 是 Ubuntu 的默认防火墙工具，它简化了防火墙的配置和管理。UFW 相当于 iptables 的封装，允许系统管理员在无需直接使用复杂的 iptables 命令的前提下设置防火墙规则。

UFW 命令​

UFW 是一个用于定义防火墙访问规则的命令行程序。UFW 命令的典型语法为：sudo ufw [--dry-run] <command> [rule]。

  • 所有 ufw 命令都需要超级用户权限，因此必须以 sudo 开头。
  • 可选地，您可以添加 --dry-run 来模拟执行 ufw 命令而不实际做出更改。
  • <command> 是您想执行的主要操作，例如 allow。
  • 根据命令的不同，您可以选择指定一个 rule，例如 allow 22。

例如，sudo ufw --dry-run allow 22 会显示开启 22 端口允许流量后的结果，包括规则变更后的全部规则集合。

安装并启用 UFW​

要使用 UFW，您必须先将其安装到树莓派设备上。安装后，UFW 已存在但处于禁用状态，这意味着它尚未阻止任何流量。这样可以让您在不被锁定的情况下配置默认访问规则。如果您正通过 SSH（或任何远程方式）连接到树莓派设备，这一点尤其重要：为避免被锁定，您必须在启用 UFW 之前允许远程访问。

如果您通过 SSH 连接，建议的操作流程如下：

步骤说明命令
1更新软件包列表。sudo apt-get update
2安装 UFW。启用之前，输出会显示 UFW 处于非活动状态。sudo apt install ufw
3通过检查状态来验证安装。关于此命令的更多信息，请参阅 规则管理。sudo ufw status
4可选（但推荐）：配置默认策略，例如拒绝所有入站流量。默认策略会全局生效。sudo ufw default deny incoming
5为保持远程访问，在启用 UFW 之前允许 SSH，可以通过服务名（ssh）或默认端口（22/tcp）指定。sudo ufw allow ssh 或 sudo ufw allow 22/tcp
6可选：如果您正在运行 Web 服务器，允许 HTTP 和 HTTPS 流量，可通过服务名（http 和 https）或对应默认端口（80/tcp 和 443/tcp）指定。sudo ufw allow http 和 sudo ufw allow https，或 sudo ufw allow 80/tcp 和 sudo ufw allow 443/tcp
7启用 UFW 以激活防火墙，并配置其开机自启。sudo ufw enable
8验证防火墙状态并查看已配置的规则。关于此命令的更多信息，请参阅 规则管理。sudo ufw status verbose

您可以随时禁用 UFW，这会阻止它开机自启。使用以下命令禁用 UFW 防火墙：

sudo ufw disable

使用 allow 和 deny 规则​

本节列出了通过指定服务名、端口和服务来允许和拒绝流量的基本命令。allow 和 deny 命令的 ufw 通用语法为：

  • 允许访问特定端口或服务：sudo ufw allow [rule]
  • 拒绝访问特定端口或服务：sudo ufw deny [rule]

下表提供了具体示例。

命令说明
sudo ufw allow 22允许通过防火墙访问端口 22。这会为所有协议（TCP 和 UDP）开放该端口。
sudo ufw allow 22/tcp仅在端口 22 上允许 TCP。
sudo ufw allow ssh允许 SSH 服务而无需指定端口（SSH 通常为 22/tcp）。
sudo ufw deny 22拒绝通过防火墙访问端口 22。这会为所有协议（TCP 和 UDP）关闭该端口。
sudo ufw deny 22/tcp仅在端口 22 上拒绝 TCP。
sudo ufw deny ssh拒绝 SSH 服务而无需指定端口（SSH 通常为 22/tcp）。

UFW 高级规则​

UFW 不仅能做基本的允许和拒绝规则，还可以：

关于这些选项的更多信息，请运行命令 man ufw。这会在终端中显示 UFW 手册页，其中包含关于 UFW 语法、选项、规则格式及示例的文档。

允许或阻止特定 IP 地址​

您可以允许或拒绝特定 IP 地址访问特定端口。这在您想阻止可疑主机或只允许可信主机时很有用。例如，以下命令拒绝 IP 地址 192.168.2.1 访问端口 30：

sudo ufw deny from 192.168.2.1 to any port 30
指定流量方向​

要控制系统如何发送或接收网络流量，例如阻止对系统的威胁（入站）或保护系统资源（出站），您可以阻止单向或双向流量。具体来说，您可以在下列命令之一后添加 out（出站流量）或 in（入站流量）：

  • allow：允许流量在指定方向上流动。
  • deny：静默丢弃在指定方向上流动的流量。
  • reject：主动拒绝在指定方向上流动的流量。

例如，以下命令阻止所有通过 SMTP 端口（通常为 25/TCP）的出站流量：

sudo ufw reject out smtp
限制连接尝试速率​

为防御暴力破解和 DDoS 攻击，limit 命令会临时阻止在短时间内尝试建立过多连接的 IP 地址（大约 30 秒内 6 次或更多）。例如，以下命令会监视 IP 地址尝试打开新的 SSH 连接（通常为端口 22/tcp）的频率，并应用速率限制：

sudo ufw limit ssh/tcp
指定网络接口​

您可以设置只应用于特定网络连接的防火墙规则（有线网络为 eth0，Wi-Fi 为 wlan0）。例如，以下命令仅在 eth0 网络接口上允许对端口 80 的入站 TCP 流量：

sudo ufw allow in on eth0 to any port 80 proto tcp

规则管理​

UFW 按顺序处理规则，因此规则的顺序很重要。下表列出了一些有用的命令，帮助您检查当前的防火墙配置并在必要时删除规则。

命令说明
sudo ufw status显示 UFW 是否处于活动状态，并列出防火墙当前的所有设置（允许或拒绝了哪些端口和服务）。
sudo ufw status verbose显示更多细节，例如默认策略和日志设置。
sudo ufw show added仅显示用户添加的规则（不包括内部和系统规则）。这在您想查看变更或跨系统对比配置时很有用。
sudo ufw status numbered显示带有分配索引号的规则。这在您想删除特定规则时很有用。
sudo ufw delete <number>根据分配的索引号删除您指定的规则。UFW 随后会重新编号剩余条目。您可以再次运行 sudo ufw status numbered 来确认规则已被删除。

使用 fail2ban 阻止可疑活动​

将树莓派用作服务器时，您必须在防火墙上有意开辟漏洞以允许服务器流量通过。Fail2ban 可以帮助确保服务器安全。Fail2ban 会检查日志文件并检查可疑活动，如多次暴力登录尝试。它能帮你省去手动检查日志文件，然后更新防火墙（通过 iptables ）来阻止入侵尝试的麻烦。

要安装 fail2ban，请运行以下命令：

sudo apt install fail2ban

安装时，Fail2ban 会创建 /etc/fail2ban/jail.conf。要启用 Fail2ban，请将 jail.conf 复制到 jail.local：

$ sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local

该配置文件包含一组默认选项，以及用于检查特定服务异常的选项。要检查用于 ssh 的规则，请在编辑器中打开 jail.local：

sudo nano /etc/fail2ban/jail.local

如果 [ssh] 部分还不存在，则创建该部分，并在该部分中添加以下行：

[ssh]
enabled  = true
port     = ssh
filter   = sshd
backend  = systemd
maxretry = 6

这将启用 Fail2ban 检查可疑的 ssh 活动，包括系统日志检查，并允许在阻止活动前重试六次。

同一文件中的 [default] 部分定义了默认禁止操作 iptables-multiport，当达到检测阈值时，该操作将运行 /etc/fail2ban/action.d/iptables-multiport.conf 文件：

# 默认禁止操作（如 iptables、iptables-new、
# iptables-multiport, shorewall, etc) 用于定义
# action_* 变量。可全局或每个节
# 在 jail.local 文件中
banaction = iptables-multiport

多端口禁止所有端口的所有访问。action.d 文件夹包含许多可供选择的动作配置文件，您可以用它们来定制服务器对可疑活动的反应。

例如，要在尝试三次失败后永久禁止一个 IP 地址，可将 [ssh] 部分中的 maxretry 值改为 3，并将 bantime 设为负数：

[ssh]
enabled  = true
port     = ssh
filter   = sshd
backend  = systemd
maxretry = 3
bantime  = -1

设置无显示器树莓派​

无显示器(headless)树莓派无需显示器、键盘或鼠标即可运行。要无显示器运行树莓派，你需要一种从另一台电脑访问它的方法。要远程访问树莓派，您需要将树莓派连接到网络，并通过网络访问树莓派。

要将树莓派连接到网络，您可以通过以太网将设备插入有线连接或配置无线网络。

要通过网络访问树莓派，请使用 SSH。通过 SSH 连接后，如果你喜欢图形桌面环境，可以使用 raspi-config 启用VNC。

如果你要从头开始设置树莓派，请在建立映像过程中设置无线网络和 SSH。如果你已经安装了树莓派，可以使用 raspi-config 配置 SSH。

警告

根据您使用的树莓派型号和 SD 卡类型，您的树莓派首次启动和连接到无线网络可能需要长达五分钟的时间。

连接有线网络​

要在首次启动时连接到有线网络，请通过以太网插入无显示器树莓派，如果您的树莓派型号不包含以太网端口，则使用以太网适配器。您的树莓派会自动连接到网络。

连接到无线网络​

要在无显示器的树莓派首次启动时配置无线网络访问，请在树莓派映像工具的自定义 > Wi-Fi选项卡中输入网络信息。输入您首选无线网络的SSID和密码。树莓派将在首次启动时使用这些凭据连接网络。部分无线适配器和某些树莓派主板不支持5 GHz网络；请查阅您的无线模块文档以确保与首选网络兼容。

提示

旧版树莓派操作系统曾通过wpa_supplicant.conf配置文件实现无线网络设置（该文件需放置于启动目录）。此功能自树莓派操作系统_Bookworm_版本起已不再可用。

远程访问​

由于没有键盘或显示器，你需要一种方法来远程控制你的无显示器树莓派。首次启动时，唯一的选择就是 SSH。要在新安装的树莓派OS 上启用 SSH，请选择以下方法之一：

  • 在 Raspberry Pi Imager 的 自定义 > 远程访问 选项卡中启用 SSH，选择身份验证机制，并提供用户名和密码或公钥。
  • 在 SD 卡首分区（标记为 bootfs）的根目录下创建名为 ssh 的文件，然后根据后续章节说明使用 userconf.txt 手动配置用户。

更多信息，请参阅设置 SSH 服务器。通过 SSH 连接后，如果喜欢图形桌面环境，可以使用 raspi-config 启用 VNC。

手动配置用户​

在 SD 卡第一分区的根目录下（文件系统标记为 bootfs），创建一个名为 userconf.txt 的文件。

该文件应包含一行文本，其中包括 <用户名>:<密码>：您希望使用的用户名，紧接着是冒号，然后是您希望使用的密码的加密表示。

注意

<用户名> 必须只包含小写字母、数字和连字符，并且必须以字母开头。长度不得超过 31 个字符。

要生成加密密码，请在另一台计算机上使用 OpenSSL。打开终端并输入以下内容：

openssl passwd -6

出现提示时，输入密码并验证。然后，该命令将输出所提供密码的加密版本。

从树莓派上托管无线网络​

树莓派可以使用无线模块托管自己的无线网络。如果你通过以太网端口（或第二个无线模块）将树莓派连接到互联网，其他连接到无线网络的设备就可以通过你的树莓派访问互联网。

考虑使用 10.x.x.x IP 块的有线网络。您可以将树莓派连接到该网络，并在使用另一个 IP 块（如 192.168.x.x）的独立网络上为无线客户端提供服务。

在下图中，请注意笔记本电脑与路由器和有线客户端存在不同的 IP 块：

托管网络

通过这种网络配置，无线客户端都可以通过树莓派路由器相互通信。但是，无线网络上的客户端不能直接与有线网络上除树莓派之外的客户端进行交互；无线客户端存在于与服务有线客户端的网络相分离的专用网络中。

注意

Raspberry Pi 5、4、3、Zero W 和 Zero 2 W 可以使用内置无线模块托管无线网络。没有内置模块的 Raspberry Pi 型号可使用单独的无线加密狗支持该功能。

启用热点​

要在命令行上创建托管无线网络，请运行以下命令，用自己的值替换 <example-network-name> 和 <example-password> 占位符：

sudo nmcli device wifi hotspot ssid <示例网络名称> password <示例密码>

使用其他无线客户端（如笔记本电脑或智能手机）连接网络。查找 SSID 与 <示例网络名称> 匹配的网络。输入网络密码，就可以成功连接到网络。如果你的树莓派可以通过以太网连接或第二个无线适配器访问互联网，那么你应该可以访问互联网。

禁用热点​

要禁用热点网络并恢复将 Pi 用作无线客户端，请运行以下命令：

sudo nmcli device disconnect wlan0

禁用网络后，运行以下命令重新连接到另一个 Wi-Fi 网络：

sudo nmcli device up wlan0
提示

有关连接无线网络的更多信息，请参阅配置网络。

将树莓派用作网络桥接器​

默认情况下，树莓派托管的无线网络与通过以太网连接的父网络是分开的。在这种安排下，连接到父网络的设备无法与连接到树莓派托管的无线网络的设备直接通信。如果希望连接的无线设备能与父网络上的设备通信，可以将树莓派配置为网络桥接器。有了网络桥接器，每个连接到 Pi-hosted 无线网络的设备都会在父网络中分配到一个 IP 地址。

在下图中，笔记本电脑与路由器和有线客户端存在于同一个 IP 块中：

桥接网络

下面的步骤描述了如何在树莓派上设置网络桥接器，以实现无线客户端与父网络之间的通信。

首先，创建一个网桥接口：

sudo nmcli connection add type bridge con-name 'Bridge' ifname bridge0

然后，将设备与父网络的以太网连接添加到网桥：

sudo nmcli connection add type ethernet slave-type bridge \
    con-name 'Ethernet' ifname eth0 master bridge0

最后，将无线热点连接添加到网桥。你可以添加现有的热点接口，也可以创建一个新接口：

  • 如果你已经使用上述说明创建了无线热点连接，请使用以下命令将现有接口添加到网桥中：
sudo nmcli connection modify 'Hotspot' master bridge0
  • 如果尚未创建无线热点连接，请创建一个新界面，并用一条命令将其添加到网桥中，分别用自己选择的网络名称和密码替换<hotspot-ssid>和<hotspot-password>占位符：
sudo nmcli connection add con-name 'Hotspot' \
    ifname wlan0 type wifi slave-type bridge master bridge0 \
    wifi.mode ap wifi.ssid <hotspot-ssid> wifi-sec.key-mgmt wpa-psk \
    wifi-sec.proto rsn wifi-sec.pairwise ccmp \
    wifi-sec.psk <hotspot-password>

现在您已经配置好网桥，是时候激活它了。运行以下命令激活网桥：

sudo nmcli connection up Bridge

然后运行以下命令开始托管无线网络：

sudo nmcli connection up Hotspot

你可以使用 nmcli device 命令来验证网桥、以太网接口和无线热点接口是否都已激活。

提示

使用 arp-scan 等工具检查父网络上的设备在连接到热点后是否可以访问。

使用代理服务器​

代理服务器是客户端设备和互联网之间的中介。 要将 Raspberry Pi 配置为代理服务器客户端，请按照本节的说明操作。

您需要

  • 代理服务器的 IP 地址或主机名和端口
  • 代理服务器的用户名和密码（如需要）

配置您的树莓派​

您需要设置三个环境变量（http_proxy、https_proxy 和 no_proxy），以便树莓派知道如何访问代理服务器。

打开终端窗口，使用 nano 打开 /etc/environment 文件：

sudo nano /etc/environment

在 /etc/environment 文件中添加以下内容，创建 http_proxy 变量：

export http_proxy="http://<proxy_ip_address>:<proxy_port>"

用代理的 IP 地址和端口替换 <proxyipaddress> 和 <proxyport>。

注意

如果代理需要用户名和密码，请使用以下格式添加：

export http_proxy="http://<username>:<password>@proxyipaddress:proxyport"

将 <username> 和 <password>占位符替换为您用来与代理进行身份验证的用户名和密码。

为环境变量 https_proxy 输入相同的信息：

export https_proxy="http://username:password@proxyipaddress:proxyport"

创建 no_proxy 环境变量，这是一个以逗号分隔的地址列表，树莓派不应使用代理的地址：

export no_proxy="localhost, 127.0.0.1"

现在，你的 /etc/environment 文件应该是这样的：

export http_proxy="http://username:password@proxyipaddress:proxyport"
export https_proxy="http://username:password@proxyipaddress:proxyport"
export no_proxy="localhost, 127.0.0.1"

按 Ctrl + X 保存并退出。

更新sudoers文件​

要在下载和安装软件等以 sudo 运行的操作中使用代理环境变量，请更新 sudoers。

使用以下命令打开 sudoers：

sudo visudo

在文件中添加以下一行，以便 sudo 使用你刚刚创建的环境变量：

Defaults	env_keep+="http_proxy https_proxy no_proxy"

按 Ctrl + X 保存并退出。

重启树莓派​

重新启动树莓派使更改生效。现在您应该可以通过代理服务器访问互联网了。

boot 文件夹​

树莓派OS将启动文件存储在 SD 卡的第一个分区中，格式为 FAT 文件系统。

启动时，每个树莓派都会从启动分区加载各种文件，以便在 Linux 内核启动前启动各种处理器。

启动时，Linux 会将启动分区挂载为 /boot/firmware/。

注意

在使用 Bookworm 之前，树莓派OS将引导分区存储在 /boot/。从 Bookworm 开始，启动分区位于 /boot/firmware/。

bootcode.bin​

bootloader，由 SoC 在启动时加载。它执行一些非常基本的设置，然后加载其中一个 start*.elf 文件。

树莓派4 和 5 不使用 bootcode.bin。取而代之的是 板载EEPROM 中的启动代码。

start*.elf​

加载到 SoC 中 VideoCore GPU 上的二进制固件块，然后接管启动过程。

  • 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、Pi 400、CM4 和 CM4S）专用的等效固件文件。

有关如何使用这些文件的更多信息，请参阅 config.txt 文档。

树莓派5 不使用 elf 文件。固件自包含在bootloader EEPROM 中。

fixup*.dat​

与上一节中列出的 start*.elf 文件配对的链接器文件。

cmdline.txt​

启动时传入内核的内核命令行。

config.txt​

包含许多用于设置树莓派的配置参数。有关详细信息，请参阅 config.txt文档。

重要

树莓派5 启动分区中需要一个非空的 config.txt 文件。

issue.txt​

基于文本的内务信息，包含发行版的日期和 git 提交 ID。

initramfs*​

初始 ramdisk 的内容。在挂载真正的根文件系统之前，它会将临时根文件系统加载到内存中。

从Bookworm开始，树莓派OS默认包含一个 initramfs 文件。要启用初始 ramdisk，请在 config.txt 中使用 auto_initramfs 关键字进行配置。

ssh或ssh.txt​

如果存在该文件，则在启动时启用 SSH。否则 SSH 默认为禁用。文件内容并不重要。即使是空文件也能启用 SSH。

设备树blob文件(*.dtb)​

设备树 blob 文件包含各种型号树莓派的硬件定义。这些文件根据检测到的树莓派型号在启动时设置内核。

内核文件(*.img)​

与树莓派型号相对应的各种内核映像文件：

文件名处理器树莓派型号备注
kernel.imgBCM2835Pi Zero、Pi 1、CM1
kernel7.imgBCM2836, BCM2837Pi Zero 2 W、Pi 2、CM3、Pi 3+、CM3+Pi 2 的后期版本使用 BCM2837
kernel7l.imgBCM2711Pi 4、CM4、CM4S、Pi 400大物理地址扩展 (LPAE)
kernel8.imgBCM2837、BCM2711、BCM2712Pi Zero 2 W、Pi 2（后期修订版）、Pi 3、CM3、Pi 3+、CM3+、Pi 4、CM4、CM4S、Pi 400、CM5、Pi 5、Pi 500、Pi 500+64位内核。早期版本的 Raspberry Pi 2（带 BCM2836）不支持 64 位内核。
kernel_2712.imgBCM2712Pi 5、CM5、Pi 500、Pi 500+Pi 5 优化过的 64位内核。
注意

运行 32 位内核的系统，lscpu 报告 CPU 架构为 armv7l；运行 64 位内核的系统，lscpu 报告 CPU 架构为 aarch64。armv7l 中的 l 指的是小端 CPU 架构，而不是 kernel7l.img 文件名中的 l 所表示的 LPAE。

覆盖文件夹​

包含设备树覆盖图。它们用于配置各种硬件设备，如第三方音效卡。config.txt 中的条目会选择这些覆盖。更多信息，请参阅设备树、覆盖和参数。

性能​

本节介绍如何：

  • 在树莓派 1 或 2 上 配置 CPU 超频。可以使用 raspi-config TUI 完成。
  • 为装有内置风扇的树莓派 4 机箱 设置机箱风扇行为。可以通过桌面和 raspi-config TUI 进行配置。
  • 为连接到树莓派 5、500 或 500+ 的大功率 USB 设备 启用或禁用 USB 电流限制。可以通过桌面和 raspi-config TUI 启用或禁用此设置。
  • 启用或禁用覆盖文件系统 来对存储设备写保护，使树莓派变为只读。可以通过桌面和 raspi-config TUI 完成。
  • 为树莓派 5 设置 PCIe 端口速度，这是一个高级选项，可以使用 raspi-config TUI 和命令行进行设置。
  • 配置关机行为，仅适用于树莓派 4 和 5 系列设备，是一个用于在树莓派关闭时节省电量的高级选项。可以使用 raspi-config TUI 进行配置。

配置 CPU 超频​

您可以在树莓派 1 或 2 上配置 CPU 超频，以提升 CPU 密集型任务的性能。超频会增加发热量和功耗。

使用交互式 raspi-config TUI 在树莓派 1 或 2 上配置 CPU 超频：

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航并选择 4 Performance Options > P1 Overclock。
  3. 选择一个超频预设：
    • 对于树莓派 1，可从以下选项中选择：
      • None：CPU 运行在 700 MHz，GPU 250 MHz，RAM 400 MHz，不加额外电压。
      • Modest：CPU 800 MHz，GPU 250 MHz，RAM 400 MHz，不加额外电压。
      • Medium：CPU 900 MHz，GPU 250 MHz，RAM 450 MHz，加 2 级过压。
      • High：CPU 950 MHz，GPU 250 MHz，RAM 450 MHz，加 6 级过压。
      • Turbo：CPU 1000 MHz，GPU 500 MHz，RAM 600 MHz，加 6 级过压。
    • 对于树莓派 2，可从以下选项中选择：
      • None：CPU 900 MHz，GPU 250 MHz，RAM 450 MHz，不加额外电压。
      • High：CPU 1000 MHz，GPU 500 MHz，RAM 500 MHz，加 2 级过压。
  4. 完成后选择 <OK>，然后选择 <Finish>。
  5. 重启树莓派以使更改生效。

设置机箱风扇行为​

以下说明仅适用于配备官方机箱（内置风扇）的树莓派 4。

  1. 选择系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 Performance（性能）标签页。
  3. 使用 Case Fan（机箱风扇）旁的切换开关将其打开。
  4. 在 FAN GPIO 后输入一个数字，指定风扇所连接的 GPIO。例如，如果风扇插在 GPIO 14 上，输入 14。
  5. 在 Fan Temperature（风扇温度）后输入一个数字，指定风扇开启时的摄氏温度。例如，如果希望风扇在 80 ℃ 开始工作，输入 80。
  6. 选择 控制中心 右下角的 Close。
  7. 重启树莓派以使更改生效。

启用或禁用 USB 电流限制​

仅当不使用官方树莓派 5 电源时才适用，USB 电流限制控制向树莓派 USB 端口提供多少电力。取消限制后可以使用更大功率的 USB 设备。该设置适用于树莓派 5、500 和 500+。

警告

如果连接的 USB 设备所需功率超过电源能够安全提供的功率，禁用 USB 电流限制可能导致系统不稳定、崩溃或数据丢失。

  1. 选择系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 Performance（性能）标签页。
  3. 使用 Disable USB Current Limit 旁的切换开关在开/关之间切换。
  4. 选择 控制中心 右下角的 Close。
  5. 重启树莓派以使更改生效。

启用或禁用覆盖文件系统​

覆盖文件系统通过使用 RAM 替代较慢的存储，改善写入密集型工作负载下的性能。但是树莓派重启或关机时，所有更改都会丢失。

覆盖文件系统有两个独立的设置，控制不同的内容：

  • 将根文件系统设置为只读。这使用一个临时的、存储在 RAM 中的覆盖层。系统运行期间对 /boot 之外的文件所做的任何更改都不会永久保存，关机或重启后就会消失。
  • 写保护启动分区。阻止对 /boot 目录的任何修改，该目录包含启动树莓派所需的固件和配置文件。
  1. 选择系统托盘左上角的树莓派图标，然后进入 首选项 > 控制中心。
  2. 在左侧菜单中打开 Performance（性能）标签页。
  3. 在 Overlay File System 旁选择 Configure。
  4. 根据需要使用切换开关启用以下设置：
    1. Use Overlay：启用只读的根文件系统覆盖。
    2. Write-protect Boot Partition：阻止对 /boot 的修改。
  5. 在 Overlay File System 窗口右下角选择 OK。
  6. 在 控制中心 右下角选择 Close。
  7. 重启树莓派以使更改生效。

设置 PCIe 端口速度​

设置 PCIe 端口速度仅适用于树莓派 5。这是 raspi-config 中的一个高级选项，除非 PCIe HAT 要求，否则不建议设置。因为树莓派 5 的 PCIe Gen 2.0 速度已经过认证，而 PCIe Gen 3.0 默认禁用。如果所连接的 HAT 或排线无法承受更高频率，强制提高速率可能导致数据损坏或系统不稳定。

使用交互式 raspi-config TUI 启用 PCIe Gen 3：

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航并选择 6 Advanced Options > A8 PCIe Speed。
  3. 针对 Would you like PCIe Gen 3 to be enabled? 选择 Yes 或 No。
  4. 选择 <OK> 继续。
  5. 重启树莓派以使更改生效。

配置关机行为​

这是 raspi-config 中用于在树莓派关闭时节省电量的高级选项。默认值取决于树莓派型号。

  • 在树莓派 400、500、500+ 和 Compute Module 5 上，默认值为 Full power off。
  • 在树莓派 4B、5 和 Compute Module 4 上，默认值为 VPU sleep mode。

使用交互式 raspi-config TUI 配置关机行为：

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航并选择 6 Advanced Options > A11 Shutdown Behaviour。
  3. 在以下选项中选择：
    • B1 Full power off
    • B2 VPU sleep mode
  4. 选择 <OK> 继续，完成后选择 <Finish>。
  5. 重启树莓派以使更改生效。

LED 行为​

树莓派设备上的板载 LED 提供了一种简单的方式来监控系统状态和诊断问题。不同型号的 LED 用于指示电源状态、SD 卡活动和故障情况，部分型号还提供额外的可配置性以满足自定义用途。

前置信息​

不同型号的树莓派使用不同的 LED 硬件配置，其具体行为和可配置性也相应不同。

  • 树莓派 1（A、B、A+ 和 B+ 型号）、2、3 和 4 使用两个独立的 LED：
    • 红色电源灯（PWR），表示在稳定的 5V 电源供应下正常工作。当出现欠压时，红色 LED 会熄灭或闪烁。
    • 绿色存储活动灯（ACT），熄灭时表示无存储活动，闪烁时表示正在访问存储卡；在执行 sudo poweroff 之后会出现一系列短闪，表示此时可以安全拔掉 USB 电源线。
  • 树莓派 Zero、Zero W 和 Zero 2 W 只使用一个绿色 LED，它同时代表电源和存储活动。您可以按照 在树莓派 Zero 上更改 LED 行为 中的说明重新配置 LED，让它优先指示电源或存储活动。
    • 开发板上电时 LED 点亮。
    • 存在存储活动时 LED 会短暂熄灭。
  • 树莓派 400 和 500 将状态 LED 集成在同一个透镜下。树莓派 5 和 500+ 的电源按钮将状态 LED 集成到了电源按钮键中。
    • 红色
      • 树莓派 400：正在供电，设备按预期运行。
      • 树莓派 5 和 500+：设备处于低功耗待机状态。
    • 绿色闪烁表示存储活动。
    • 橙色表示电源和活动同时出现。
注意

树莓派 5、500 和 500+ 上的电源按钮允许计算机进入软关机状态。在此状态下，CPU 和大部分系统活动都会停止，但电源轨仍保持通电，可通过再次按下电源按钮或像正常那样断电再上电来重新启动系统。

在树莓派 Zero 上更改 LED 行为​

树莓派 Zero、Zero W 和 Zero 2 W 只有一个电源 LED，用于指示电源和存储活动。

您可以使用交互式 raspi-config TUI 来更改树莓派 Zero、Zero W 或 Zero 2 W 上电源 LED 的行为。

也可以选择 LED 是优先在磁盘活动时闪烁，还是在设备开启期间始终点亮。

使用交互式 raspi-config TUI 更改电源 LED 优先级：

  1. 打开终端并运行 sudo raspi-config。
  2. 使用键盘导航并选择 1 System Options > S8 Power LED。
  3. 针对 Would you like the power LED to flash during disk activity? 这个问题选择 Yes 或 No。
    • 选择 Yes 优先让 LED 在存储活动时闪烁。
    • 选择 No 则在开发板通电时保持 LED 常亮。
  4. 选择 <OK> 确认，然后在完成后选择 <Finish>。

配置键盘型树莓派的 LED​

树莓派 400 和 500 有三个 LED。

在 树莓派 400 上，这些 LED 为：

  • 数字锁定 LED，图标为方框中的数字 1。
  • 大写锁定 LED，图标为方框中的大写字母 A。
  • 一个双功能状态 LED（详见 前置信息）。

在 树莓派 500 上，这些 LED 为：

  • 用户可编程 LED，图标由圆形、方形和三角形组成。其功能没有硬连线绑定到系统事件，这意味着您可以将 LED 用作自定义项目的状态灯，例如通知提示和进度指示。
  • 大写锁定 LED，图标为方框中的大写字母 A。
  • 一个双功能状态 LED（详见 前置信息）。

用户可配置的 LED 可以通过 pinctrl 工具控制，该工具用于与 GPIO 引脚及外设交互。

  • pinctrl USER_LED op dh 打开用户 LED。
  • pinctrl USER_LED op dl 关闭用户 LED。

您也可以使用 Python 调用 pinctrl：

import subprocess
from time import sleep

while True:
    subprocess.run(['pinctrl', 'USER_LED', 'op', 'dh'])
    print("On")
    sleep(1)
    subprocess.run(['pinctrl', 'USER_LED', 'op', 'dl'])
    print("Off")
    sleep(1)

查看 LED 警告闪烁代码​

如果树莓派设备无法启动或意外关机，板载 LED 通常会以特定的闪烁模式给出诊断信号。长闪总是出现在表示具体问题的短闪之前；有时完全没有长闪。在大多数情况下，闪烁模式会在停顿两秒后重复。

长闪短闪状态
03一般启动失败
04未找到 start*.elf
07未找到内核映像
08SDRAM 故障
09SDRAM 不足
010处于 HALT 状态
12检测到 SD 卡过流
21分区不是 FAT
22从分区读取失败
23扩展分区不是 FAT
24文件签名/哈希值不匹配（树莓派 4 和 5）
31SPI EEPROM 错误（树莓派 4 和 5）
32SPI EEPROM 受写保护（树莓派 4 和 5）
33I2C 错误（树莓派 4 和 5）
34安全启动配置无效
43未找到 RP1
44不支持的电路板类型
45固件致命错误
46A 型电源故障
47B 型电源故障

设备树、覆盖和参数​

Raspberry Pi 内核和固件使用设备树（DT）来描述硬件。这些设备树可能包括用于控制板上功能的 DT 参数。DT 覆盖层允许对可选的外部硬件进行描述和配置，它们还支持更多控制参数。

固件加载器（start.elf 及其变体）负责加载 DTB（设备树 Blob，一种机器可读的 DT 文件）。它根据电路板版本号选择加载哪个文件，并进行修改以进一步定制。这种运行时定制功能可避免使用许多只有细微差别的 DTB。

用户在 config.txt 中提供的参数，以及任何覆盖层及其参数都会被扫描，然后应用。加载程序会检查结果，以了解（例如）哪个 UART（如果有）将用于控制台。最后，它会启动内核，并传递一个指向合并后 DTB 的指针。

设备树​

设备树 (DT) 是对系统硬件的描述。它应包括基本 CPU 的名称、内存配置和任何外设（内部和外部）。DT 不应用于描述软件，尽管列出硬件模块通常会导致加载驱动模块。

注意

请记住，DT 应该是操作系统中立的，因此任何 Linux 专用的内容都不应该出现在 DT 中。

设备树将硬件配置表示为节点的层次结构。每个节点都可能包含属性和子节点。属性是以字节命名的数组，可包含字符串、数字（big-endian）、字节的任意序列以及它们的任意组合。与文件系统类似，节点是目录，属性是文件。节点和属性在树中的位置可以用路径来描述，斜线作为分隔符，单斜线 (/) 表示根节点。

基本DTS语法​

设备树通常以文本形式编写，称为设备树源代码（DTS），并存储在后缀为 .dts 的文件中。DTS 语法类似于 C 语言，使用大括号分组，每行末尾使用分号。请注意，DTS 要求在大括号后使用分号：就像 C struct 而不是函数。编译后的二进制格式称为扁平化设备树（FDT）或设备树 Blob（DTB），存储在 .dtb 文件中。

下面是一个 .dts 格式的简单树：

/dts-v1/;
/include/ "common.dtsi";

/ {
    node1 {
        a-string-property = "A string";
        a-string-list-property = "first string", "second string";
        a-byte-data-property = [0x01 0x23 0x34 0x56];
        cousin: child-node1 {
            first-child-property;
            second-child-property = <1>;
            a-string-property = "Hello, world";
        };
        child-node2 {
        };
    };
    node2 {
        an-empty-property;
        a-cell-property = <1 2 3 4>; /* each number (cell) is a uint32 */
        child-node1 {
            my-cousin = <&cousin>;
        };
    };
};

/node2 {
    another-property-for-node2;
};

这棵树包含

  • 必需的标头： /dts-v1/
  • 包含另一个 DTS 文件，通常命名为 *.dtsi，类似于 C 语言中的 .h 头文件
  • 一个根节点 /
  • 几个子节点：节点 1 和节点 2
  • 节点 1 的一些子节点：node1 和 node2
  • 一个标签（cousin）和对该标签的引用（&cousin）
  • 分布在树中的几个属性
  • 重复节点 (/node2)

属性是简单的键值对，其值可以为空，也可以包含任意字节流。虽然数据结构中没有对数据类型进行编码，但有几种基本的数据表示方式可以在设备树源文件中表达。

文本字符串（NUL 结尾）用双引号表示：

string-property = "a string";

单元格是 32 位无符号整数，用角括弧分隔：

cell-property = <0xbeef 123 0xabcd1234>;

任意字节数据用方括号分隔，以十六进制输入：

binary-property = [01 23 45 67 89 ab cd ef];

不同表示形式的数据可以用逗号连接起来：

mixed-property = "a string", [01 23 45 67], <0x12345678>；

逗号还可用于创建字符串列表：

string-list = "red fish", "blue fish"；

关于/include/的旁白​

/include/ 指令产生简单的文本包含，就像 C 的 #include 指令一样，但 Device Tree 编译器的一个特性导致了不同的使用模式。由于节点是以绝对路径命名的，因此同一节点有可能在 DTS 文件（及其包含文件）中出现两次。出现这种情况时，节点和属性会根据需要交错组合并覆盖属性（后面的值会覆盖前面的值）。

在上面的示例中，/node2 的第二次出现导致在原来的基础上增加了一个新属性：

/node2 {
    an-empty-property;
    a-cell-property = <1 2 3 4>; /* each number (cell) is a uint32 */
    another-property-for-node2;
    child-node1 {
        my-cousin = <&cousin>;
    };
};

因此，一个 .dtsi 可以覆盖树中的多个地方，或为多个地方提供默认值。

标签和引用​

树的一个部分经常需要引用另一个部分，有四种方法可以做到这一点：

  • 路径字符串：与文件系统路径类似，例如 /soc/i2s@7e203000 是 BCM2835 和 BCM2836 中 I2S 设备的完整路径。标准 API 不会创建类似 /soc/i2s@7e203000/status这样的属性路径：而是首先找到一个节点，然后选择该节点的属性。
  • phandle指针：分配给节点 phandle 属性的唯一 32 位整数。由于历史原因，你可能还会看到一个多余的、匹配的 linux,phandle。phandle 按顺序编号，从 1 开始；0 不是有效的 phandle。当 DT 编译器在整数上下文中遇到对节点的引用时，通常会以标签的形式分配它们。使用 phandle 对节点的引用会被简单地编码为相应的整数（单元格）值；没有标记来表明它们应被解释为 phandle，因为这是由应用程序定义的。
  • 标签：就像 C 语言中的标签给代码中的一个位置命名一样，DT 标签也给层次结构中的一个节点命名。编译器在字符串上下文 (&node) 和整数上下文 (<&node>) 中使用标签引用时，会将其转换为路径；原始标签不会出现在编译输出中。请注意，标签不包含任何结构；它们只是全局名称空间中的标记。
  • 别名：与标签类似，只是它们作为一种索引形式出现在 FDT 输出中。别名存储为 /aliases 节点的属性，每个属性将别名映射为路径字符串。虽然别名节点出现在源代码中，但路径字符串通常是作为标签 (&node) 的引用出现，而不是全部写出。将路径字符串解析为节点的 DT API 通常会查看路径的第一个字符，将不以斜线开头的路径视为别名，必须首先使用 /aliases 表将其转换为路径。

设备树语义​

如何构建设备树，以及如何最好地使用设备树来捕捉某些硬件的配置，是一个庞大而复杂的课题。有许多资源可供使用，下面列出了其中一些，但有几点值得强调：

  • compatible(兼容) 属性是硬件描述与驱动软件之间的纽带。当操作系统遇到具有 compatible 属性的节点时，它会在设备驱动程序数据库中查找，以找到最佳匹配。在 Linux 中，这通常会导致驱动模块被自动加载，前提是该模块已被适当标注且未列入黑名单。
  • status(状态) 属性表示设备是启用还是禁用。如果 status 为 ok、okay 或 absent，则表示设备已启用。否则，status 应为 disabled(禁用)，这样设备就被禁用了。将状态设置为 disabled 的设备放入 .dtsi 文件中可能很有用。派生配置可以包含该 .dtsi 文件，并将所需设备的状态设置为 okay。

设备树覆盖​

现代片上系统（SoC）是一种非常复杂的设备；完整的设备树可能长达数百行。再进一步，将 SoC 与其他组件一起放置在电路板上，只会使问题更加复杂。为了便于管理，尤其是在相关设备共享组件的情况下，将通用元素放在 .dtsi 文件中，并从可能的多个 .dts 文件中包含这些元素是合理的。

当树莓派这样的系统还支持 HAT 等可选插件配件时，问题就更大了。最终，每种可能的配置都需要一个设备树来描述，但一旦考虑到所有不同的基本型号和大量可用配件，组合的数量就会开始迅速倍增。

我们需要的是一种使用部分 "设备树" 描述这些可选组件的方法，然后通过使用基本 DT 并添加大量可选元素来构建完整的设备树。您可以这样做，这些可选元素被称为 "覆盖层"。

除非你想学习如何为树莓派s 编写覆盖层，否则你最好跳到 第3部分：在树莓派上使用设备树。

片段​

DT 覆盖由许多片段组成，每个片段针对一个节点及其子节点。虽然概念听起来很简单，但语法初看起来却相当奇怪：

// Enable the i2s interface
/dts-v1/;
/plugin/;

/ {
    compatible = "brcm,bcm2835";

    fragment@0 {
        target = <&i2s>;
        __overlay__ {
            status = "okay";
            test_ref = <&test_label>;
            test_label: test_subnode {
                dummy;
            };
        };
    };
};

compatible 字符串表明它适用于 BCM2835，这是树莓派 SoC 的基本架构；如果覆盖层使用了树莓派4的功能，那么 brcm,bcm2711 就是正确的值，否则 brcm,bcm2835 就可以用于所有树莓派覆盖层。然后是第一个（在本例中也是唯一的）片段。片段应从 0 开始按顺序编号。如果不遵守这一点，可能会导致部分或全部片段丢失。

每个片段由两部分组成：一个 target 目标属性，用于标识要应用覆盖的节点；以及 __overlay__ 本身，其主体被添加到目标节点上。上面的示例可以这样理解

/dts-v1/;
/plugin/;

/ {
    compatible = "brcm,bcm2835";
};

&i2s {
    status = "okay";
    test_ref = <&test_label>;
    test_label: test_subnode {
        dummy;
    };
};

如果 dtc 的版本足够新，你可以完全按照上面的方法编写示例，并获得相同的输出，但有些自制工具还不能理解这种格式。任何您希望包含在标准树莓派操作系统内核中的覆盖层，目前都应使用旧格式编写。

将该覆盖层与标准的树莓派基本设备树（例如 bcm2708-rpi-b-plus.dtb）合并后，如果覆盖层在之后被加载，其效果将是通过将 I2S 接口的状态更改为 OK 来启用该接口。但如果尝试使用以下方法编译该覆盖层

dtc -I dts -O dtb -o 2nd.dtbo 2nd-overlay.dts

...就会出现错误：

Label or path i2s not found

这并不出乎意料，因为编译器并没有引用基础 .dtb 或 .dts 文件来查找 i2s 标签。

再试一次，这次使用原来的示例，并添加 -@ 选项以允许未解决的引用（以及 -Hepapr 以消除一些杂乱）：

dtc -@ -Hepapr -I dts -O dtb -o 1st.dtbo 1st-overlay.dts

如果 dtc 返回关于第三行的错误信息，说明它没有覆盖工作所需的扩展。运行 sudo apt install device-tree-compiler 再试一次，这次编译应该能成功完成。请注意，内核树中的 scripts/dtc/dtc 中也有合适的编译器，在 dtbs 编译目标时使用：

make ARCH=arm dtbs

转储 DTB 文件的内容，查看编译器生成了什么：

fdtdump 1st.dtbo

输出结果应与下面类似：

/dts-v1/;
// magic:		0xd00dfeed
// totalsize:		0x207 (519)
// off_dt_struct:	0x38
// off_dt_strings:	0x1c8
// off_mem_rsvmap:	0x28
// version:		17
// last_comp_version:	16
// boot_cpuid_phys:	0x0
// size_dt_strings:	0x3f
// size_dt_struct:	0x190

/ {
    compatible = "brcm,bcm2835";
    fragment@0 {
        target = <0xffffffff>;
        __overlay__ {
            status = "okay";
            test_ref = <0x00000001>;
            test_subnode {
                dummy;
                phandle = <0x00000001>;
            };
        };
    };
    __symbols__ {
        test_label = "/fragment@0/__overlay__/test_subnode";
    };
    __fixups__ {
        i2s = "/fragment@0:target:0";
    };
    __local_fixups__ {
        fragment@0 {
            __overlay__ {
                test_ref = <0x00000000>;
            };
        };
    };
};

在文件结构的冗长描述之后，就是我们的片段。但请仔细看--在我们写 &i2s 的地方，现在显示的是 0xffffffffff，这说明发生了一些奇怪的事情（旧版本的 dtc 可能会显示 0xdeadbeef）。编译器还添加了一个 phandle 属性，其中包含一个唯一的（对该覆盖层而言）小整数，用来表示节点有一个标签，并用相同的小整数替换了所有对标签的引用。

在片段之后有三个新节点：

  • __symbols__ 列出了叠加中使用的标签（此处为 test_label），以及通向标签节点的路径。这个节点是如何处理未解决符号的关键。
  • __fixups__ 包含一个属性列表，它将未解决符号的名称映射到片段中需要用目标节点的 phandle 进行修补的单元格的路径列表，一旦找到目标节点。在本例中，路径指向 target 的 0xffffffff 值，但片段可能包含其他需要额外修复的未解决引用。
  • __local_fixups__ 保存了覆盖层中存在的任何标签引用的位置--即 test_ref 属性。之所以需要这样做，是因为执行合并的程序必须确保 phandle 编号是连续和唯一的。

在第 1.3节 中提到，"原始标签不会出现在编译输出中"，但使用 -@ 开关时并非如此。相反，每个标签都会在 __symbols__ 节点中产生一个属性，将标签映射到路径，这与 aliases 节点完全相同。事实上，这种机制非常相似，以至于在解析符号时，如果没有 __symbols__ 节点，树莓派载入器就会搜索 aliases 节点。这曾一度很有用，因为提供足够的别名可以使用非常旧版本的 dtc 来构建基础 DTB 文件，但幸运的是，这已经成为历史了。

设备树参数​

为了避免大量设备树覆盖，并减少外设用户修改 DTS 文件的需要，树莓派载入器支持一项新功能--设备树参数。这允许使用命名参数对 DT 进行小改动，类似于内核模块从 modprobe 和内核命令行接收参数的方式。基本 DTB 和覆盖层（包括 HAT 覆盖层）都可以公开参数。

参数是通过在 DTS 根节点上添加 __overrides__ 节点来定义的。它包含名称为所选参数名称的属性，其值是由目标节点的 phandle（对标签的引用）和表示目标属性的字符串组成的序列；支持字符串、整数（单元）和布尔属性。

字符串参数​

字符串参数是这样声明的：

name = <&label>,"property";

其中 label 和 property 用合适的值代替。字符串参数可导致其目标属性增长、缩小或创建。

请注意，名为 status 的属性会被特殊处理；非 0/true/yes/on 的值会被转换为字符串 "okay"，而 0/false/no/off 则会被转换为 "disabled"。

整数参数​

整数参数的声明如下

name = <&label>, "property.offset"; // 8 位
name = <&label>, "property;offset"; // 16 位
name = <&label>, "property:offset"; // 32 位
name = <&label>, "property#offset"; // 64 位

在这里，label(标签) 、property(属性) 和 offset(偏移量)由合适的值代替；偏移量以字节为单位指定，相对于属性的起始值（默认为十进制），前面的分隔符决定了参数的大小。与以前的实现方式不同，整数参数可以指向不存在的属性或超出现有属性末尾的偏移量。

布尔参数​

设备树将布尔值编码为零长度属性；如果存在，则属性为真，否则为假。它们的定义如下

boolean_property; // 设置 "boolean_property "为 true

如果不定义一个属性，该属性就会被赋值为 false。布尔参数也是这样声明的，用合适的值代替 label 和 property 占位符：

name = <&label>, "property?"；

反转布尔在应用之前会反转输入值，其方式与普通布尔相同；它们的声明方式类似，但使用 ! 表示反转：

name = <&label>,"property!";

布尔参数可以创建或删除属性，但不能删除基础 DTB 中已存在的属性。

字节字符串参数​

字节字符串属性是任意的字节序列，如 MAC 地址。它们接受十六进制字节的字符串，字节之间有无冒号均可。

mac_address = <&ethernet0>,"local_mac_address[";

选择 [ 是为了与 DT 声明字节字符串的语法相匹配：

local_mac_address = [aa bb cc dd ee ff]；
具有多个目标的参数​

在某些情况下，在设备树的多个位置设置相同的值会很方便。与创建多个参数这种不方便的方法相比，我们可以通过串联的方式为单个参数添加多个目标，如下所示：

    __overrides__ {
        gpiopin = <&w1>,"gpios:4",
                  <&w1_pins>,"brcm,pins:0";
        ...
    };

(取自 w1-gpio 覆盖层的示例）

注意

甚至可以用一个参数针对不同类型的属性。您可以合理地将 enable 参数连接到 status 字符串、包含 0 或 1 的单元格以及适当的布尔属性。

字面赋值​

DT 参数机制允许对同一参数的多个目标进行修补，但由于必须向所有位置写入相同的值（格式转换和反布尔运算中的否定除外），因此实用性受到限制。增加嵌入式字面赋值后，参数可以写入任意值，而与用户提供的参数值无关。

赋值出现在声明的末尾，用 = 表示：

str_val  = <&target>,"strprop=value";              // 1
int_val  = <&target>,"intprop:0=42"                // 2
int_val2 = <&target>,"intprop:0=",<42>;            // 3
bytes    = <&target>,"bytestr[=b8:27:eb:01:23:45"; // 4

第 1、2 和 4 行相当明显，但第 3 行更有趣，因为其值显示为整数（单元格）值。DT 编译器会在编译时对整数表达式进行求值，这可能很方便（尤其是在使用宏值的情况下），但单元格也可以包含对标签的引用：

// 强制 LED 使用内部 GPIO 控制器上的 GPIO。
exp_led = <&led1>,"gpios:0=",<&gpio>,
          <&led1>,"gpios:4";

应用叠加时，标签将以常规方式与基本 DTB 相对应。像这样将多部分参数分成多行是个好主意，这样更容易阅读--增加单元格值赋值后，这一点变得更加必要。

请记住，除非应用参数，否则参数不起任何作用--查找表中的默认值将被忽略，除非使用参数名称而不赋值。

查找表​

查找表允许参数输入值在使用前进行转换。它们就像关联数组，类似于 switch/case 语句：

phonetic = <&node>,"letter{a=alpha,b=bravo,c=charlie,d,e,='tango uniform'}";
bus      = <&fragment>,"target:0{0=",<&i2c0>,"1=",<&i2c1>,"}";

没有 =value 的键表示使用该键作为值，前面没有键的 = 表示在没有匹配的情况下使用默认值，以逗号（或任何地方的空 key=value 对）开始或结束列表表示应使用未匹配的输入值，否则，找不到匹配值就是错误。

注意

单元格整数值后的表格字符串中的逗号分隔符是隐式的，显式添加逗号分隔符会创建空值对（见上文）。

注意

由于查找表对输入值进行操作，而字面赋值会忽略输入值，因此无法将两者结合起来--查找声明中关闭 } 后的字符会被视为错误。

覆盖/片段参数​

所描述的 DT 参数机制有许多局限性，包括缺乏创建整数数组的简便方法，以及无法创建新节点。克服其中一些限制的方法之一是有条件地包含或排除某些片段。

通过将 __overlay__ 节点重命名为 __dormant__ ，可以将某个片段排除在最终合并过程之外（禁用）。对参数声明语法进行了扩展，允许使用原本不合法的零目标 phandle 来表示下面的字符串包含片段或覆盖范围内的操作。到目前为止，已经实现了四种操作：

+<n> // 启用片段 <n
-<n> // 禁用片段 <n>
=<n> // 如果指定的参数值为真，则启用片段 <n>，否则禁用它
!<n> // 如果分配的参数值为假，则启用片段 <n>，否则禁用它

示例

just_one    = <0>,"+1-2"; // 启用 1，禁用 2
conditional = <0>,"=3!4"; // 如果参数值为真，则启用 3，禁用 4、
                          // 否则禁用 3，启用 4。

i2c-rtc 叠加使用了这种技术。

特殊属性​

当参数指向一些属性名时，它们会得到特殊处理。其中一个你可能已经注意到了 -status 会将布尔值转换为 okey(是) 或 disabled(否) 。

赋值给 bootargs 属性时，会追加而不是覆盖它--这就是将设置添加到内核命令行的方法。

reg 属性用于指定设备地址--内存映射硬件块的位置、I2C 总线上的地址等。子节点的名称应以十六进制地址限定，并使用 @ 作为分隔符：

        bmp280@76 {
            reg = <0x77>;
            ...
        };

为 reg 属性赋值时，父节点名称的地址部分将被赋值所取代。当多次使用同一覆载时，这可用于防止节点名称冲突--i2c-gpio 覆载就使用了这种技术。

name 属性是一个伪属性--它不应出现在 DT 中，但对其赋值会导致其父节点的名称更改为赋值。与 reg 属性一样，该属性可用于赋予节点唯一的名称。

叠加地图文件​

围绕 BCM2711 SoC 构建的树莓派4 的推出带来了许多变化；其中一些变化是新增的接口，另一些则是对现有接口的修改（或删除）。有一些专为树莓派4 设计的新覆盖层在旧硬件上没有意义，例如启用新 SPI、I2C 和 UART 接口的覆盖层，但其他覆盖层即使控制的功能与新设备仍然相关，也无法正确应用。

因此，需要一种方法来定制覆盖层，使其适用于具有不同硬件的多个平台。要在单个 .dtbo 文件中支持所有平台，就需要大量使用隐藏（"休眠"）片段，并改用按需符号解析机制，这样不需要的缺失符号就不会导致故障。一个更简单的解决方案是，根据当前平台的不同，添加将覆盖层名称映射到多个实现文件之一的功能。

覆盖图是固件在启动时加载的文件。它以 DTS 源格式（overlay_map.dts）编写，编译为 overlay_map.dtb，并存储在 overlays 目录中。

这是当前地图文件的摘录（见 完整版）：

/ {
	disable-bt {
		bcm2835;
		bcm2711;
		bcm2712 = "disable-bt-pi5";
	};

	disable-bt-pi5 {
		bcm2712;
	};

	uart5 {
		bcm2711;
	};

	pi3-disable-bt {
		renamed = "disable-bt";
	};

	lirc-rpi {
		deprecated = "use gpio-ir";
	};
};

每个节点都有一个需要特殊处理的覆盖层名称。每个节点的属性要么是平台名称，要么是少数特殊指令之一。覆盖图支持以下平台名称：

  • bcm2835 用于所有围绕 BCM2835、BCM2836、BCM2837 和 RP3A0 SoC 构建的 Raspberry Pis
  • 用于 Raspberry Pi 4B、CM4、CM4S 和 Pi 400 的 bcm2711
  • 用于 Raspberry Pi 5、CM5、Pi 500 和 Pi 500+ 的 bcm2712

没有值的平台名称（空属性）表示当前覆盖层与该平台兼容；例如，uart5与bcm2711平台兼容。平台的非空值是替代所请求的覆盖层的名称；在 BCM2712 上请求disable-bt，结果是载入disable-bt-pi5。任何未包含在覆盖节点中的平台都与该覆盖不兼容。地图中未提及的任何覆盖都被假定为与所有平台兼容。

第二个示例节点 -disable-bt-pi5- 可以从 disable-bt 的内容中推断出来，但这一情报将用于文件的构建，而不是文件的解释。

uart5 覆盖只有在 BCM2711 上才有意义。

如果某个平台未被列入覆载，则可能需要使用其中一条特殊指令：

  • renamed(重命名) 指令指明覆盖层的新名称（应与原名称基本兼容），但也会记录重命名警告。
  • deprecated(废弃) 指令包含一条简短的错误解释信息，该信息将在通用前缀 overlay '...' is deprecated:.。

可以采用链式重命名和特定平台实现，但要注意避免循环！

记住：只需列出例外情况--没有覆盖节点意味着所有平台都应使用默认文件。

从固件访问诊断信息在调试中有所介绍。

dtoverlay 和 dtmerge 实用程序已扩展到支持映射文件：

  • dtmerge 从基本 DTB 中的兼容字符串中提取平台名称。
  • dtoverlay 从位于 /proc/device-tree 的实时设备树中读取兼容字符串，但可以使用 -p 选项提供另一个平台名称（对于在不同平台上的模拟运行非常有用）。

它们都会将错误、警告和任何调试输出发送到 STDERR。

示例​

下面是一些不同类型属性的示例，并附有用于修改它们的参数：

/ {
    fragment@0 {
        target-path = "/";
        __overlay__ {

            test: test_node {
                string = "hello";
                status = "disabled";
                bytes = /bits/ 8 <0x67 0x89>;
                u16s = /bits/ 16 <0xabcd 0xef01>;
                u32s = /bits/ 32 <0xfedcba98 0x76543210>;
                u64s = /bits/ 64 < 0xaaaaa5a55a5a5555 0x0000111122223333>;
                bool1; // Defaults to true
                       // bool2 defaults to false
                mac = [01 23 45 67 89 ab];
                spi = <&spi0>;
            };
        };
    };

    fragment@1 {
        target-path = "/";
        __overlay__ {
            frag1;
        };
    };

    fragment@2 {
        target-path = "/";
        __dormant__ {
            frag2;
        };
    };

    __overrides__ {
        string =      <&test>,"string";
        enable =      <&test>,"status";
        byte_0 =      <&test>,"bytes.0";
        byte_1 =      <&test>,"bytes.1";
        u16_0 =       <&test>,"u16s;0";
        u16_1 =       <&test>,"u16s;2";
        u32_0 =       <&test>,"u32s:0";
        u32_1 =       <&test>,"u32s:4";
        u64_0 =       <&test>,"u64s#0";
        u64_1 =       <&test>,"u64s#8";
        bool1 =       <&test>,"bool1!";
        bool2 =       <&test>,"bool2?";
        entofr =      <&test>,"english",
                      <&test>,"french{hello=bonjour,goodbye='au revoir',weekend}";
        pi_mac =      <&test>,"mac[{1=b8273bfedcba,2=b8273b987654}";
        spibus =      <&test>,"spi:0[0=",<&spi0>,"1=",<&spi1>,"2=",<&spi2>;

        only1 =       <0>,"+1-2";
        only2 =       <0>,"-1+2";
        enable1 =     <0>,"=1";
        disable2 =    <0>,"!2";
    };
};

有关更多示例，树莓派Linux GitHub 存储库中有大量覆盖源文件。

导出标签​

固件中的叠加处理和使用 dtoverlay 实用程序的运行时叠加应用程序将叠加中定义的标签视为该叠加的私有标签。这样就不必为标签起全局唯一的名称（使标签保持简短），而且可以多次使用同一覆盖层而不会发生冲突（前提是使用了一些技巧--请参阅特殊属性）。

有时，用一种覆盖层创建标签，再从另一种覆盖层使用，这样做非常有用。自 2020 年 2 月 14 日起发布的固件可以将某些标签声明为全局标签 - __exports__ 节点：

    ...
    public: ...

    __exports__ {
        public; // 导出标签 "public "到基础 DT
    };
};

应用此覆盖层时，加载器会删除除已导出符号（本例中为 public）以外的所有符号，并重写路径，使其相对于包含标签的片段的目标。在此之后加载的覆盖层可以引用 &public。

覆盖层应用顺序​

在大多数情况下，片段的应用顺序并不重要，但对于自行打补丁的覆盖层（片段的目标是覆盖层中的一个标签，称为覆盖层内片段）来说，这就变得很重要了。在旧固件中，片段严格按照从上到下的顺序应用。在 2020 年 2 月 14 日发布的固件中，片段分两次应用：

  • 首先应用并隐藏针对其他片段的片段。
  • 然后再应用常规片段。

由于第一步在 dtoverlay 实用程序中进行，而第二步由内核执行（内核无法处理重叠内的片段），因此这种分割对运行时重叠尤为重要。

在树莓派上使用设备树​

DTB、覆盖层和config.txt​

在树莓派上，加载器（start.elf 镜像之一）的工作是将覆盖层与适当的基本设备树相结合，然后将完全解析的设备树传递给内核。基本设备树与 start.elf 位于 FAT 分区（Linux 中为 /boot/firmware/）中，名为 bcm2711-rpi-4-b.dtb、bcm2710-rpi-3-b-plus.dtb 等。请注意，某些型号（3A+、A、A+）将分别使用与 "b" 对应的型号（3B+、B、B+）。这种选择是自动的，允许在各种设备中使用相同的 SD 卡映像。

注意

DT 和 ATAG 相互排斥，将 DT blob 传递给不理解它的内核会导致启动失败。固件会一直尝试加载 DT 并将其传递给内核，因为自 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 指令：

dtoverlay=acme-board
dtparam=foo=bar,level=42

这将导致加载器在固件分区中查找 overlays/acme-board.dtbo，树莓派OS 将固件分区挂载在 /boot/firmware/ 上。然后，加载器将搜索参数 foo 和 level，并为其分配指定值。

加载器还会搜索已编程 EEPROM 的附加 HAT，并从那里加载支持的覆盖层--可以直接加载，也可以从 "overlays" 目录中按名称加载；这一切都无需用户干预。

有多种方法可以判断内核正在使用设备树：

  • 启动时的内核信息 "Machine model:"（机器型号：） 有一个特定板卡的值，如 "树莓派2B"，而不是 "BCM2709"。
  • 存在 /proc/device-tree，其中包含的子目录和文件与 DT 的节点和属性完全一致。

有了设备树，内核就会自动搜索并加载支持指定启用设备的模块。因此，通过为设备创建适当的 DT 覆盖层，设备的用户就不必再编辑 /etc/modules；所有的配置都将在 config.txt 中进行，而对于 HAT，甚至连这一步都不需要。不过需要注意的是，i2c-dev 等分层模块仍需明确加载。

反过来说，由于除非 DTB 请求，否则平台设备不会被创建，因此应该不再需要将过去由于电路板支持代码中定义的平台设备而加载的模块列入黑名单。事实上，当前的树莓派操作系统镜像文件中没有黑名单文件（除了某些 WLAN 设备有多个驱动程序）。

DT参数​

如上所述，DT 参数是对设备配置进行微小更改的便捷方法。当前的基本 DTB 支持启用和控制板载音频、I2C、I2S 和 SPI 接口的参数，而无需使用专用的覆盖层。使用时，参数如下所示：

dtparam=audio=on,i2c_arm=on,i2c_arm_baudrate=400000,spi=on
注意

可以在同一行放置多个指定，但要确保不超过 80 个字符的限制。

如果您有一个定义了某些参数的覆盖层，可以像这样在随后的行中指定这些参数：

dtoverlay=lirc-rpi
dtparam=gpio_out_pin=16
dtparam=gpio_in_pin=17
dtparam=gpio_in_pull=down

...或者像这样附加到覆盖行：

dtoverlay=lirc-rpi,gpio_out_pin=16,gpio_in_pin=17,gpio_in_pull=down

叠加参数只在下一次叠加加载之前有效。如果覆盖层和基本层都导出了同名参数，则覆盖层中的参数优先；建议避免这样做。要暴露基础 DTB 导出的参数，请使用以下命令结束当前覆盖作用域

dtoverlay=

特定于电路板的标签和参数​

树莓派主板配备两个I2C接口。这些接口通常被划分：一个用于Arm CPU，另一个用于VideoCore GPU。在几乎所有型号中，i2c1属于CPU，i2c0属于GPU，用于控制摄像头和读取HAT扩展板的EEPROM。然而，早期版本的Model B中有两个型号将这两者的角色进行了互换。

为了在所有树莓派上使用同一套覆盖层和参数，固件创建了一些特定于电路板的 DT 参数。这些参数是

i2c/i2c_arm
i2c_vc
i2c_baudrate/i2c_arm_baudrate
i2c_vc_baudrate

这些是 i2c0、i2c1、i2c0_baudrate 和 i2c1_baudrate 的别名。建议只在确实需要时才使用 i2c_vc 和 i2c_vc_baudrate，例如，在对 HAT EEPROM 进行编程时（最好使用软件 I2C 总线，使用 i2c-gpio 覆盖层）。启用 i2c_vc 会导致树莓派摄像头或树莓派触摸显示器无法正常工作。

对于编写覆盖层的人来说，I2C DT 节点上的标签也采用了同样的别名。因此，您应该编写

fragment@0 {
    target = <&i2c_arm>;
    __overlay__ {
        status = "okay";
    };
};

任何使用数字变体的覆盖层都将被修改为使用新的别名。

HAT和设备树​

树莓派HAT 是一种带有嵌入式 EEPROM 的附加电路板，专为带有 40 针接头的树莓派设计。EEPROM 包括启用电路板所需的任何 DT 覆盖层（或从文件系统加载的覆盖层名称），该覆盖层还可以显示参数。

固件会在基本 DTB 之后自动加载 HAT 覆盖层，因此在加载任何其他覆盖层或使用 dtoverlay= 结束覆盖层范围之前，都可以访问其参数。 如果出于某种原因想要抑制 HAT 覆盖层的加载，请在任何其他 dtoverlay 或 dtparam 指令之前加上 dtoverlay=。

动态设备树​

从 Linux 4.4 开始，树莓派内核支持动态加载覆盖层和参数。兼容的内核可管理应用于基础 DTB 上的覆盖层堆栈。变化会立即反映在 /proc/device-tree 中，并可能导致模块加载以及平台设备的创建和销毁。

上面使用的 "堆栈" 一词很重要--覆盖层只能在堆栈顶部添加和移除；要更改堆栈下层的内容，必须先移除堆栈顶部的内容。

有一些新命令用于管理覆盖层：

dtoverlay命令​

dtoverlay 是一个命令行工具，可以在系统运行时加载和删除覆盖层，还可以列出可用的覆盖层并显示其帮助信息。

使用 dtoverlay -h 可获取使用信息：

使用方法：

Usage:
  dtoverlay <overlay> [<param>=<val>...]
                           Add an overlay (with parameters)
  dtoverlay -D [<idx>]     Dry-run (prepare overlay, but don't apply -
                           save it as dry-run.dtbo)
  dtoverlay -r [<overlay>] Remove an overlay (by name, index or the last)
  dtoverlay -R [<overlay>] Remove from an overlay (by name, index or all)
  dtoverlay -l             List active overlays/params
  dtoverlay -a             List all overlays (marking the active)
  dtoverlay -h             Show this usage message
  dtoverlay -h <overlay>   Display help on an overlay
  dtoverlay -h <overlay> <param>..  Or its parameters
    where <overlay> is the name of an overlay or 'dtparam' for dtparams
Options applicable to most variants:
    -d <dir>    Specify an alternate location for the overlays
                (defaults to /boot/firmware/overlays or /flash/overlays)
    -v          Verbose operation

与 config.txt 命令不同的是，覆盖层的所有参数必须包含在同一命令行中，dtparam 命令只适用于基本 DTB 的参数。

更改内核状态（添加和删除内容）的命令变量需要 root 权限，因此可能需要在命令前加上 sudo。只有在运行时应用的覆盖层和参数才能被卸载，固件应用的覆盖层或参数会被 "嵌入"，因此不会被 dtoverlay 列出，也无法移除。

dtparam命令​

dtparam 创建并加载一个覆盖层，其效果与在 config.txt 中使用 dtparam 指令大致相同。在用法上，它与覆盖名为 - 的 dtoverlay 大致相同，但也有一些不同之。dtparam 命令将列出基本 DTB 所有已知参数的帮助信息。dtparam 命令的帮助信息仍可使用 dtparam -h。在指明要删除的参数时，只能使用索引号（不能使用名称）。并非所有 Linux 子系统都能在运行时对添加的设备做出响应，I2C、SPI 和声音设备可以工作，但有些则不行。

编写支持运行时的覆盖程序指南​

设备对象的创建或删除是由节点的添加或删除、节点状态从禁用变为启用或反之触发的。如果没有 "status" 属性，则表示节点已启用。

不要在片段中创建会覆盖基础 DTB 中现有节点的节点，内核会重命名新节点使其独一无二。如果要更改现有节点的属性，请创建一个针对该节点的片段。

ALSA 不会阻止其编解码器和其他组件在使用中被卸载。如果删除的编解码器仍被声卡使用，那么删除覆盖层就会导致内核异常。实验发现，设备的删除顺序与覆载中片段的删除顺序相反，因此将声卡节点放在组件节点之后，可实现有序关闭。

注意事项​

在运行时加载覆盖层是内核最近新增的功能，在撰写本文时还没有从用户空间实现这一功能的公认方法。通过将这一机制的细节隐藏在命令后面，用户可以避免在不同的内核接口标准化后发生变化。

  • 有些覆盖层在运行时比其他覆盖层更好用。设备树的部分内容只在启动时使用，使用覆盖层更改这些内容不会产生任何影响。
  • 应用或删除某些覆盖层可能会导致意想不到的行为，因此应谨慎操作。这也是需要 sudo 的原因之一。
  • 如果有东西正在使用 ALSA，卸载 ALSA 卡的覆盖层可能会导致停滞，LXPanel 音量滑块插件就演示了这种效果。为了能移除声卡的覆盖层，lxpanelctl 工具新增了两个选项：alsastop 和 alsastart，分别在加载或卸载覆盖层之前和之后从辅助脚本 dtoverlay-pre 和 dtoverlay-post 中调用。
  • 移除覆盖层不会导致已加载模块被卸载，但可能会导致某些模块的引用计数降为零。运行两次 rmmod -a 会导致卸载未使用的模块。
  • 必须以相反的顺序移除覆盖层。命令允许您移除较早的覆盖层，但所有中间覆盖层都将被移除并重新应用，这可能会产生意想不到的后果。
  • 只有位于树顶层的设备树节点和总线节点的子节点才会被探测。对于运行时添加的节点，还有一个限制条件，即总线必须注册以接收添加和删除子节点的通知。不过，也有一些例外情况会打破这一规则并造成混乱：内核会明确扫描整个树中的某些设备类型（时钟和中断控制器是两个主要类型），以便（对于时钟）提前初始化和/或（对于中断控制器）按特定顺序初始化。这种搜索机制只在启动过程中进行，因此对运行时由覆盖层添加的节点不起作用。因此，建议覆盖层将固定时钟节点放在树的根部，除非能保证覆盖层在运行时不会被使用。

支持的覆盖和参数​

有关支持的覆盖层和参数列表，请参阅 README 文件，该文件与覆盖层 .dtbo 文件一起位于 /boot/firmware/overlays。该文件会根据添加和更改的内容不断更新。

固件参数​

固件使用特殊的 /chosen 节点在引导加载程序和/或固件与操作系统之间传递参数。

  • 每个属性默认以32位无符号整数形式存储，除非另有说明。
  • 设备树中的数字以二进制形式存储，且采用大端序。

读取32位无符号整数属性的示例shell命令：

printf "%d" "0x$(od "/proc/device-tree/chosen/bootloader/partition" -v -An -t x1 | tr -d ‘ ’ )"

overlay_prefix - 字符串。config.txt 选择的 overlay_prefix 字符串。

s_prefix - 字符串。由 config.txt 选定的 os_prefix 字符串。

rpi-boardrev-ext - OTP第33行 的扩展电路板修订代码。

rpi-country-code - 3PiWiz 使用的国家代码，仅限键盘型号。

rpi-duid - 字符串。仅限树莓派5。PCB 上 QR 码的字符串表示。

rpi-serial64 - 字符串。64 位序列号的字符串表示。在 Raspberry Pi 5 之后的旗舰型号上，这与普通序列号（/proc/device-tree/serial-number）相同。在早期型号上，默认序列号仍然是 32 位，但在更新的固件中，现在可以使用 64 位序列号，并可通过此节点查看。

常用引导加载器属性/chosen/bootloader​

boot-mode - 用于加载内核的引导模式。有关可能的引导模式值列表，请参阅 BOOT_ORDER 文档。

partition - 引导时使用的分区号。如果加载了 boot.img ramdisk，则指的是加载 ramdisk 的分区，而不是 ramdisk 中的分区号。

pm_rsts - 启动过程中 PM_RSTS 寄存器的值。

tryboot - 如果启动时设置了 tryboot 标志，则设置为 1。

启动变量 /chosen/bootloader​

仅适用于 Raspberry Pi 5。

arg1 - 上次启动时用户定义的重启参数的值。参见 xref:config_txt.adoc#boot_arg1[boot_arg1]

count - 操作系统启动时 8 位 boot_count 变量的值。参见 xref:config_txt.adoc#boot_count[boot_count]

电源属性 /chosen/power​

仅限 Raspberry Pi 5。

max_current - 电源可提供的最大电流（毫安）。固件会报告 USB-C、USB-PD 或 PoE 接口指示的值。对于台式电源（例如连接到 GPIO 头），在引导加载程序配置中定义 PSU_MAX_CURRENT，以指示电源电流能力。 power_reset - 仅适用于树莓派5。表示 PMIC 复位原因的位字段。

位原因
0电压过高
1电压过低
2温度过高
3启用信号
4看门狗

rpi_power_supply - 2 个 32 位整数。Raspberry Pi 27W 官方电源的 USB VID 和产品 VDO（如果已连接）。

usb_max_current_enable - 如果 USB 端口电流限制器在启动期间设置为低限，则为零；如果启用了高限，则为非零。如果电源要求最大电流为 5A 或在 config.txt 中强制设置 usb_max_current_enable=1，则会自动启用高电平。

usb_over_current_detected - 如果 USB 启动过程中发生 USB 过流事件，则为非零。

usbpd_power_data_objects - 二进制 blob（多个 32 位整数）。USB-PD 协商期间引导加载程序接收到的原始二进制 USB-PD 对象（仅限固定电源）。要捕获这些信息以用于错误报告，请运行 hexdump -C /proc/device-tree/chosen/power/usbpd_power_data_objects。

格式由 USB Power Delivery 规范定义。

BCM2711和BCM2712特定引导加载程序属性 /chosen/bootloader​

以下属性是 BCM2711 和 BCM2712 SPI EEPROM 引导加载程序特有的属性。

build_timestamp - EEPROM 引导加载程序的 UTC 生成时间。

capabilities - 该位字段描述当前引导加载程序支持的功能。在引导加载程序 EEPROM 配置中启用某项功能（如 USB 启动）之前，可以用它来检查该功能是否受支持。

位特性
0使用 VLI USB 主机控制器进行 USB 启动
1网络启动
2TRYBOOT_A_B 模式
3TRYBOOT
4使用 BCM2711 USB 主机控制器进行 USB 启动
5RAM 磁盘 - boot.img
6NVMe 启动
7安全启动

update_timestamp - 由 rpi-eeprom-update 设置的 UTC 更新时间戳。

signed - 如果启用了安全启动，则该位字段将非零。各个位表示当前的安全启动配置。

位说明
0已在 EEPROM 配置文件中定义 SIGNED_BOOT。
1保留
2ROM 开发密钥已被撤销。请参阅 revoke_devkey。
3客户公钥摘要已写入 OTP。参见 program_pubkey。
4..31保留

version - 字符串。bootloader的 Git 版本字符串。

BCM2711和BCM2712 USB启动属性/chosen/bootloader/usb​

如果系统从 USB 启动，则定义以下属性。这些属性可用于唯一标识 USB 启动设备。

usb-version - USB 主要协议版本（2 或 3）。

route-string - USB 3.0 规范定义的设备 USB 路由字符串标识符。

root-hub-port-number - 启动设备连接的根集线器端口号，可能通过其他 USB 集线器连接。

lun - 大容量存储设备的逻辑单元编号。

NVMEM节点​

固件通过 NVMEM 子系统提供bootloader EEPROM 部分的只读内存副本。

每个区域在 /sys/bus/nvmem/devices/ 下显示为一个 NVMEM 设备，在 /sys/firmware/devicetree/base/aliases 下有一个命名别名。

从 rpi-eeprom-update 读取 NVMEM 模式的 shell 脚本代码示例：

blconfig_alias="/sys/firmware/devicetree/base/aliases/blconfig"
blconfig_nvmem_path=""

if [ -f "${blconfig_alias}" ]; then
   blconfig_ofnode_path="/sys/firmware/devicetree/base"$(strings "${blconfig_alias}")""
   blconfig_ofnode_link=$(find -L /sys/bus/nvmem -samefile "${blconfig_ofnode_path}" 2>/dev/null)
   if [ -e "${blconfig_ofnode_link}" ]; then
      blconfig_nvmem_path=$(dirname "${blconfig_ofnode_link}")
      fi
   fi
fi

blconfig：别名指的是存储bootloader EEPROM 配置文件副本的 NVMEM 设备。

blpubkey：别名指向一个 NVMEM 设备，该设备存储二进制格式的bootloader EEPROM 公钥副本（如果定义）。可使用 rpi-bootloader-key-convert 实用程序将数据转换为 PEM 格式，以便与 OpenSSL 配合使用。

更多信息请参阅：secure-boot

故障排除​

调试​

加载程序会跳过丢失的覆盖层和错误的参数，但如果出现严重错误，如丢失或损坏的基础 DTB 或覆盖层合并失败，加载程序就会退回到非 DTB 启动。如果出现这种情况，或者您的设置与预期不符，值得检查加载器是否发出警告或出现错误：

sudo vclog --msg

在 config.txt 中添加 dtdebug=1 可启用额外调试。

您可以像这样创建 DT 当前状态的可读表述：

dtc -I fs /proc/device-tree

这有助于查看将覆盖合并到底层树上的效果。

如果内核模块未按预期加载，请检查它们是否在 /etc/modprobe.d/raspi-blacklist.conf 中被列入黑名单；使用设备树时，应该不需要列入黑名单。如果没有发现异常，还可以搜索 /lib/modules/<version>/modules.alias 中的 compatible(兼容) 值，检查模块是否导出了正确的别名。否则，您的驱动程序很可能缺少以下任一项：

.of_match_table = xxx_of_match,

或

MODULE_DEVICE_TABLE(of, xxx_of_match);

如果失败，则说明 depmod 已失效，或者目标文件系统中尚未安装更新的模块。

使用dtmerge、dtdiff和ovmerge测试覆盖结果​

除了 dtoverlay 和 dtparam 命令外，还有一个将覆盖应用到 DTB 的实用程序 - dtmerge。要使用它，首先需要获取基础 DTB，获取方式有两种：

从 /proc/device-tree 中的实时 DT 状态生成：

dtc -I fs -O dtb -o base.dtb /proc/device-tree

这将包括您迄今为止在 config.txt 中或在运行时加载的任何覆盖层和参数，这可能是您想要的，也可能不是。另一种方法是

从 /boot/firmware/ 中的源 DTB 复制。这不包括覆盖层和参数，但也不包括固件的任何其他修改。为了测试所有覆盖层，dtmerge 工具将创建一些特定于板卡的别名（"i2c_arm" 等），但这意味着合并后的结果与原始 DTB 之间的差异将超出预期。解决方法是使用 dtmerge 进行复制：

dtmerge /boot/firmware/bcm2710-rpi-3-b.dtb base.dtb -

(- 表示没有覆盖名称)。

现在您可以尝试应用叠加或参数：

dtmerge base.dtb merged.dtb - sd_overclock=62
dtdiff base.dtb merged.dtb

将返回

--- /dev/fd/63  2016-05-16 14:48:26.396024813 +0100
+++ /dev/fd/62  2016-05-16 14:48:26.396024813 +0100
@@ -594,7 +594,7 @@
                };

                sdhost@7e202000 {
-                       brcm,overclock-50 = <0x0>;
+                       brcm,overclock-50 = <0x3e>;
                        brcm,pio-limit = <0x1>;
                        bus-width = <0x4>;
                        clocks = <0x8>;

您还可以比较不同的覆盖层或参数。

dtmerge base.dtb merged1.dtb /boot/firmware/overlays/spi1-1cs.dtbo
dtmerge base.dtb merged2.dtb /boot/firmware/overlays/spi1-2cs.dtbo
dtdiff merged1.dtb merged2.dtb

得到

--- /dev/fd/63  2016-05-16 14:18:56.189634286 +0100
+++ /dev/fd/62  2016-05-16 14:18:56.189634286 +0100
@@ -453,7 +453,7 @@

                        spi1_cs_pins {
                                brcm,function = <0x1>;
-                               brcm,pins = <0x12>;
+                               brcm,pins = <0x12 0x11>;
                                phandle = <0x3e>;
                        };

@@ -725,7 +725,7 @@
                        #size-cells = <0x0>;
                        clocks = <0x13 0x1>;
                        compatible = "brcm,bcm2835-aux-spi";
-                       cs-gpios = <0xc 0x12 0x1>;
+                       cs-gpios = <0xc 0x12 0x1 0xc 0x11 0x1>;
                        interrupts = <0x1 0x1d>;
                        linux,phandle = <0x30>;
                        phandle = <0x30>;
@@ -743,6 +743,16 @@
                                spi-max-frequency = <0x7a120>;
                                status = "okay";
                        };
+
+                       spidev@1 {
+                               #address-cells = <0x1>;
+                               #size-cells = <0x0>;
+                               compatible = "spidev";
+                               phandle = <0x41>;
+                               reg = <0x1>;
+                               spi-max-frequency = <0x7a120>;
+                               status = "okay";
+                       };
                };

                spi@7e2150C0 {

Utils 软件源中还有另一个 DT 工具 - ovmerge。与 dtmerge 不同，ovmerge 以源代码形式合并文件并应用覆盖。由于叠加不需要编译，因此标签得以保留，结果通常也更易读。它还有一些其他技巧，如列出文件包含顺序的功能。

强制使用特定的设备树​

如果你有默认 DTB 不支持的特殊需求，或者你只是想尝试编写自己的 DTB，你可以告诉加载器加载另一个 DTB 文件，如下所示：

device_tree=my-pi.dtb

禁用设备树​

树莓派Linux 内核需要使用设备树。对于裸机和其他操作系统，可以通过添加

device_tree=

到 config.txt。

快捷语法变体​

加载器可理解一些快捷方式：

dtparam=i2c_arm=on
dtparam=i2s=on

可简写为

dtparam=i2c,i2s

(i2c 是 i2c_arm 的别名，而 =on 是假定的）。它也仍然接受长格式版本：device_tree_overlay 和 device_tree_param。

config.txt中的其他DT命令​

device_tree_address：用于更改固件加载设备树（而非 dt-blob）的地址。默认情况下，固件会选择一个合适的位置。

device_tree_end：此项为加载的设备树设置（排他性）限制。默认情况下，设备树可以增长到可用内存的尽头，这几乎肯定是需要的。

dtdebug：如果非零，则为固件的设备树处理开启一些额外的日志记录。

enable_uart：启用 主/控制台 UART。如果主 UART 为 ttyAMA0，则 enable_uart 默认为 1（启用），否则默认为 0（禁用）。这将阻止内核频率发生变化，从而使 ttyS0 无法使用。因此，enable_uart=1意味着core_freq=250（除非force_turbo=1）。在某些情况下，这会影响性能，因此默认关闭。

overlay_prefix：指定加载覆盖层的子目录/前缀，默认为 "overlay/"。注意尾部的"/"。如果需要，您可以在最后的"/"后面添加一些内容，为每个文件添加一个前缀，但这不大可能需要。

更多端口可由 DT 控制。详情请参见 第3节。

更多帮助​

如果您已经阅读了本文档，但仍未找到设备树问题的答案，我们可以提供帮助。通常可以在树莓派论坛，尤其是设备树论坛找到作者。

更改默认引脚配置​

注意

通过用户提供的设备树 blob 自定义默认引脚配置已被弃用。

启动序列期间的设备引脚​

在启动序列期间，GPIO 引脚会经历各种操作。

  • 上电 - 引脚默认为具有默认拉力的输入，这在数据手册中有描述
  • 由 bootrom 设置
  • 由 bootcode.bin 设置
  • 由 dt-blob.bin 设置（本页）
  • 通过 config.txt 中的 GPIO命令 设置
  • 附加固件引脚（如 UARTS）
  • 内核/设备树

在软复位时，除了默认值外，其他步骤相同，默认值只在开机复位时应用。

整个过程可能需要几秒钟。在此期间，GPIO 引脚可能不会处于所连接外设（如 dt-blob.bin 或 config.txt 中定义）预期的状态。由于不同的 GPIO 引脚有不同的默认拉力，因此应为外设采取以下措施之一：

  • 选择一个 GPIO 引脚，该引脚在复位时默认为外设所需的拉力
  • 延迟外设启动，直到操作完成
  • 添加适当的上拉/下拉电阻器

提供自定义设备树blob​

要将设备树源文件（.dts）编译为设备树 blob 文件（.dtb），必须运行 sudo apt install device-tree-compiler 安装设备树编译器。然后就可以使用 dtc 命令了：

sudo dtc -I dts -O dtb -o /boot/firmware/dt-blob.bin dt-blob.dts

同样，如果需要，也可以将 .dtb 文件转换回 .dts 文件。

dtc -I dtb -O dts -o dt-blob.dts /boot/firmware/dt-blob.bin

dt-blob的各部分​

dt-blob.bin 用于在启动时配置二进制 blob（VideoCore）。Linux 内核目前不使用它。dt-blob 可以配置树莓派的所有版本，包括计算模块，以使用替代设置。以下部分在 dt-blob 中有效：

videocore​

本部分包含所有 VideoCore blob 信息。随后的所有部分都必须包含在本部分中。

pins_*​

根据特定的树莓派型号，有许多独立的 pins_* 部分，即

  • pins_rev1：Rev1 引脚设置。由于移动了 I2C 引脚，因此存在一些差异。
  • pins_rev2：Rev2 引脚设置。其中包括 P5 上的额外编解码器引脚。
  • pins_bplus1：树莓派1B+ rev 1.1，包括完整的 40 针连接器。
  • pins_bplus2：树莓派1B+ rev 1.2，交换了低功耗和 lan-run 引脚。
  • pins_aplus：树莓派1A+，缺少以太网。
  • pins_2b1：树莓派2B rev 1.0；通过 I2C0 控制 SMPS。
  • pins_2b2:树莓派2B rev 1.1；通过 42 和 43 上的软件 I2C 控制 SMPS。
  • pins_3b1：树莓派3B rev 1.0
  • pins_3b2:树莓派3B rev 1.2
  • pins_3bplus：树莓派3B+
  • pins_3aplus：树莓派3A+
  • pins_pi0:树莓派Zero
  • pins_pi0w：树莓派Zero W
  • pins_pi02w：树莓派Zero 2 W
  • pins_cm：树莓派CM1。这是芯片的默认值，因此它是有关芯片默认上拉/下拉的有用信息来源。
  • pins_cm3：树莓派CM3
  • pins_cm3plus：树莓派CM3+
  • pins_cm4s：树莓派CM4S
  • pins_cm4:树莓派CM4

每个 pins_* 部分都可以包含 pin_config 和 pin_defines 部分。

pin_config​

pin_config 部分用于配置各个引脚。该部分中的每一项都必须是已命名的引脚部分，例如 pin@p32，表示 GPIO32。还有一个特殊的 pin@default 部分，其中包含了 pin_config 部分中没有特别命名的所有引脚的默认设置。

pin@pinname​

该部分可包含以下项目的任意组合（不包括中文）：

  • polarity (极性)

    • active_high (高电瓶)
    • active_low (低电平)

  • termination (终止)

    • pull_up (上拉)
    • pull_down (下拉)
    • no_pulling (无拉)

  • startup_state (启动状态)

    • active (激活)
    • inactive (非活动)

  • function (功能)

    • input (输入)
    • output (输出)
    • sdcard (SD卡)
    • i2c0 (以下懒得译了)
    • i2c1
    • spi
    • spi1
    • spi2
    • smi
    • dpi
    • pcm
    • pwm
    • uart0
    • uart1
    • gp_clk
    • emmc
    • arm_jtag

  • drive_strength_mA 驱动强度用于设置引脚的强度。请注意，您只能为Bank指定一个驱动强度。<8> 和 <16> 均为有效值。

引脚定义​

本节用于为特定引脚设置特定的 VideoCore 功能。这样，用户就可以将摄像头电源启用引脚移动到不同的位置，或移动 HDMI 热插拔位置：这些都是 Linux 无法控制的。请参阅下面的 DTS 文件示例。

时钟配置​

通过该界面可以更改时钟的配置，但很难预测结果！时钟系统的配置非常复杂。有五个独立的 PLL，每个 PLL 都有自己的固定（或可变，在 PLLC 的情况下）VCO 频率。然后，每个 VCO 都有若干不同的通道，可以对 VCO 频率进行不同的分频设置。每个时钟目的地都可以配置为来自其中一个时钟通道，不过源到目的地的映射是有限制的，因此并非所有通道都能路由到所有时钟目的地。

以下是几个配置示例，可用于更改特定时钟。如有时钟配置请求，我们将添加到本资源中。

clock_routing {
   vco@PLLA  {    freq = <1966080000>; };
   chan@APER {    div  = <4>; };
   clock@GPCLK0 { pll = "PLLA"; chan = "APER"; };
};

clock_setup {
   clock@PWM { freq = <2400000>; };
   clock@GPCLK0 { freq = <12288000>; };
   clock@GPCLK1 { freq = <25000000>; };
};

上述操作将 PLLA 设置为运行于 1.96608GHz 的源 VCO（该 VCO 的限制频率为 600MHz - 2.4GHz），将 APER 通道更改为 /4，并将 GPCLK0 配置为通过 APER 从 PLLA 获取。这将为音频编解码器提供产生 48000 频率范围所需的 12288000Hz 频率。

设备树源文件示例​

固件资源库包含一个 主树莓派blob，其他的通常都是从它衍生出来的。

中文翻译版以英文版相同知识授权方式共享：CC-BY-SA 4.0。交流 Q群：498908352

最后于 更新