Raspberry Pi OS
简介
在 GitHub 上修改
Raspberry Pi OS 是基于 Debian 的免费操作系统，针对 Raspberry Pi 硬件进行了优化。Raspberry Pi OS 支持超过 35,000 个 Debian 软件包。我们推荐大多数 Raspberry Pi 使用 Raspberry Pi OS。
由于 Raspberry Pi OS 源自 Debian，它遵循 Debian发布周期的交错版本。大约每两年发布一次。
最新版本的 Raspberry Pi OS 基于 Debian Bookworm。之前的版本基于 Debian Bullseye。
您可以在 raspberrypi.com/software/operating-systems/ 上找到 Raspberry Pi OS 的镜像。
更新软件
在 GitHub 上修改
始终将 Raspberry Pi 上运行的软件更新到最新版本。这将确保您的设备免受 漏洞 的威胁，并确保您获得最新的错误修复。
使用 APT 管理软件包
高级软件包工具(APT)是在 Raspberry Pi 操作系统中安装、更新和删除软件的推荐方法。您可以通过 apt CLI 访问 APT。
安装更新
apt 会在文件 /etc/apt/sources.list 中存储软件源列表。安装软件前，请运行以下命令，使用 /etc/apt/sources.list 更新 本地软件包列表：
$ sudo apt update运行以下命令，将所有已安装的软件包升级到最新版本：
$ sudo apt full-upgrade|
Tip
|
与 Debian 不同，Raspberry Pi OS 正在持续开发中。因此，软件包依赖关系有时会发生变化，所以你应该始终使用 full-upgrade 而不是标准的 upgrade。
|
定期运行这些命令以保持软件最新。使用 apt 保持 Raspberry Pi OS 的最新版本，也能保持 Linux 内核和固件的最新版本，因为 Raspberry Pi 将它们作为 Debian 软件包发布。
当 Raspberry Pi 发布新的 Raspberry Pi OS 主版本时，上述命令不会将你的操作系统升级到新的主版本。要升级到新的主版本，请遵循我们的 操作系统升级说明。
搜索软件
要搜索存档软件包，请向 apt-cache search 传递搜索关键字：
$ apt-cache search <keyword>例如，下面是对关键字 "raspi" 的搜索：
$ apt-cache search raspi
raspi3-firmware - Raspberry Pi 2 and 3 GPU firmware and bootloaders
libcamera-apps - libcamera-apps
libcamera-apps-lite - libcamera-apps-lite
python-picamera - Pure Python interface to the Raspberry Pi's camera module.
python-picamera-docs - Documentation for the Python interface to the RPi's camera module.
python3-picamera - Pure Python interface to the Raspberry Pi's camera module.
raspi-config - Raspberry Pi configuration tool
raspi-gpio - Dump the state of the BCM270x GPIOs
raspi-gpio-dbgsym - debug symbols for raspi-gpio
raspinfo - Dump information about the Pi
rc-gui - raspi-config GUI
raspi-copies-and-fills - ARM-accelerated versions of selected functions from string.h
raspi-copies-and-fills-dbgsym - debug symbols for raspi-copies-and-fills搜索会返回多个名称或描述包含关键字的软件包。
使用以下命令查看软件包的详细信息：
$ apt-cache show <package-name>例如，下面是对 "raspi-config" 软件包的查询：
$ apt-cache show raspi-config
Package: raspi-config
Version: 20210212
Architecture: all
Maintainer: Serge Schneider <serge@raspberrypi.org>
Installed-Size: 121
Depends: whiptail, parted, lua5.1, alsa-utils, psmisc, initramfs-tools
Recommends: triggerhappy, iw
Priority: optional
Section: utils
Filename: pool/main/r/raspi-config/raspi-config_20210212_all.deb
Size: 27976
SHA256: 772d4fd3c6d8c9da47ac56012b74e7828b53c8521ff1c47266bb38ec71750c10
SHA1: 08254c976a8260bde914c2df72f92ffb9317fef6
MD5sum: 80aaac13be6a9b455c822edb91cf8ea2
Description: Raspberry Pi configuration tool
A simple configuration tool for common Raspberry Pi administrative tasks
Description-md5: 19630c04463bfe7193152448b53d85a0使用此命令可验证软件包的维护者、版本和大小是否符合您的预期。
安装软件包
要在 Raspberry Pi 上安装软件包，请在以下命令中输入软件包的名称：
$ sudo apt install <package-name>apt 将显示软件包将占用的磁盘空间。输入 Y，然后按 Enter 确认软件包的安装。在上述命令中添加 -y 标志可跳过这一确认步骤。
将操作系统升级到新的主要版本
|
Warning
|
在尝试主要版本升级之前，请先进行备份。 |
要在 Raspberry Pi 上将操作系统升级到新的主要版本，请将新版本映像到第二张 SD 卡上。使用 USB SD 读卡器或网络存储设备将当前安装的文件和配置复制到新的 SD 卡上。然后，将新的 SD 卡插入 Raspberry Pi 的插槽并启动。
升级固件
|
Warning
|
在尝试固件升级之前，请先进行备份。 |
|
Warning
|
不保证预发布版本的软件可以正常工作。除非得到 Raspberry Pi 工程师的建议，否则不要在任何系统上使用 rpi-update。这会导致系统不可靠或损坏。请勿将 rpi-update 用作任何定期更新过程的一部分。
|
要将 Raspberry Pi 上的固件更新到最新版本，请使用 rpi-update。
rpi-update 会下载最新预发布版本的 Linux 内核、其匹配模块、设备树文件和最新版本的 VideoCore 固件。然后将这些文件安装到现有的 Raspberry Pi OS 安装中。
rpi-update` 使用的所有源数据都来自 rpi-firmware 资源库。该版本库包含 官方固件版本库中数据的子集。
以根用户身份运行 rpi-update 启动更新。更新完成后，重启 Raspberry Pi 以使更改生效：
$ sudo rpi-update
$ sudo reboot将固件降级到上一个稳定版本
如果您将固件更新到最新版本，但遇到问题，请使用以下命令返回到上一个稳定固件版本：
$ sudo apt update
$ sudo apt install --reinstall raspi-firmware|
Note
|
如果仍在运行 Raspberry Pi OS Bullseye，则必须使用以下命令重新安装 使用 |
播放音频和视频
在 GitHub 上修改
Raspberry Pi OS 预装了 VLC 媒体播放器。您可以使用 VLC 播放视频和音频文件。VLC 在 Raspberry Pi OS 中使用硬件加速，支持许多流行的音频和视频文件格式。
VLC 媒体播放器
VLC GUI
要从 Raspberry Pi Desktop 播放音频或视频文件，请在文件管理器中双击文件。这会自动启动 VLC 播放该文件。或者，从 Sound & Video 菜单，启动 VLC Media Player。然后，从 Media 菜单中选择 Open File…，并导航到要播放的文件。
默认情况下，Raspberry Pi OS 通过 HDMI 将音频发送到显示器。要将音频输出到耳机插孔或 USB 扬声器等不同接口，请右键单击系统托盘中的扬声器图标并选择一个选项。
vlc CLI
你也可以通过命令行启动 VLC。在下面的示例中，我们使用了 Big Buck Bunny 的一个短片。要从 Raspberry Pi 上下载该短片，请运行以下命令：
$ wget --trust-server-names http://rptl.io/big-buck-bunny要在 VLC 中通过命令行播放片段，请运行以下命令：
$ vlc big-buck-bunny-1080p.mp4要防止 VLC GUI 在文件播放完毕后继续打开，请添加 --play-and-exit 标记：
$ vlc --play-and-exit big-buck-bunny-1080p.mp4要以全屏模式播放视频（在某些情况下播放会更流畅），请添加 --fullscreen 标记：
$ vlc --play-and-exit --fullscreen big-buck-bunny-1080p.mp4在 Raspberry Pi OS Lite 上播放音频和视频
与完整版的 Raspberry Pi OS 不同，Raspberry Pi OS Lite 没有预装 VLC。要在 Raspberry Pi OS Lite 上使用 VLC 播放视频和音频，请安装所需的软件包，以便在没有桌面的情况下播放：
$ sudo apt install --no-install-recommends vlc-bin vlc-plugin-base在下面的示例中，我们使用了一段简短的音频片段。要从 Raspberry Pi 上下载这个片段，请运行以下命令：
$ wget --trust-server-names http://rptl.io/startup-music要在 VLC 中通过命令行播放片段，请运行以下命令：
$ cvlc --play-and-exit computer-startup-music.mp3指定音频输出设备
要强制将音频输出到特定设备，可在 -A 选项中加入 alsa 值以使用 ALSA 音频输出，并在 --alsa-audio-device 选项中指定音频输出设备：
$ cvlc --play-and-exit -A alsa --alsa-audio-device <alsa-device> computer-startup-music.mp3用以下选项之一替换 <alsa-device> 占位符：
| ALSA device | Description |
|---|---|
|
The headphone jack |
|
The HDMI output on devices with a single HDMI port (Zero models, CM4S, Compute Modules prior to CM4, and Flagship models prior to Raspberry Pi 4) |
|
The HDMI0 output on Flagship models since Raspberry Pi 4B, Compute Modules since CM4, and Keyboard models |
|
The HDMI1 output on Flagship models since Raspberry Pi 4B, Compute Modules since CM4, and Keyboard models |
|
Tip
|
使用以下命令获取 Raspberry Pi 上所有 ALSA 设备的列表： |
指定视频输出设备
要强制将视频输出到特定设备，请使用 --drm-vout-display 选项指定视频输出设备：
$ cvlc --play-and-exit --drm-vout-display <drm-device> big-buck-bunny-1080p.mp4用以下选项之一替换 <drm-device> 占位符：
| DRM device | Description |
|---|---|
|
The HDMI output on a Raspberry Pi Zero, or Raspberry Pi Model 1, 2 or 3; or the HDMI0 output on a Raspberry Pi 4, 5, or 400 |
|
The HDMI1 output on Flagship models since Raspberry Pi 4B, Compute Modules since CM4 (including CM4S), and Keyboard models |
|
The Raspberry Pi Touch Display or Raspberry Pi Touch Display 2 |
|
The second DSI output for models with multiple DSI ports (Flagship models since Raspberry Pi 5, and Compute Module models since CM5) |
|
Tip
|
使用以下命令获取 Raspberry Pi 上所有 DRM 设备的列表： |
实用程序
在 GitHub 上修改
Raspberry Pi OS中预装了几个有用的命令行实用程序。
kmsprint
kmsprint 工具可用于列出连接到Raspberry Pi的显示器支持的显示模式。使用 kmsprint 查看连接到Raspberry Pi的显示器的详细信息，使用 kmsprint-m 查看每个显示器支持的所有显示模式的列表。您可以在 Github 上找到 kmsprint 实用程序的源代码。
=== vclog
vclog 可从 Arm 上运行的 Linux 中显示来自 VideoCore GPU 的日志信息。它需要以 root 用户身份运行。
sudo vclog --msg 会打印信息日志，而 sudo vclog --assert 则会打印断言日志。
vcgencmd
vcgencmd 工具用于从Raspberry Pi上的 VideoCore GPU 输出信息。您可以在GitHub上找到 vcgencmd 源代码。
要获取 vcgencmd 支持的所有命令的列表，请使用 vcgencmd commands 。下面列出了一些有用的命令及其所需参数。
get_throttled
返回系统的节流状态。这是一个位模式。正在设置的位表示以下含义：
| 位 | 十六进制值 | 意义 |
|---|---|---|
0 |
|
检测到欠压 |
1 |
|
ARM频率上限 |
2 |
|
当前节流 |
3 |
|
软温度限制活动 |
16 |
|
已发生欠压 |
17 |
|
达到Arm频率上限 |
18 |
|
节流已经发生 |
19 |
|
已触发软温度限制 |
measure_clock [clock]
返回指定时钟的当前频率。接受以下时钟值：
| clock | Description |
|---|---|
|
ARM core(s) |
|
GPU core |
|
H.264 block |
|
Image Sensor Pipeline |
|
3D block |
|
UART |
|
PWM block (analogue audio output) |
|
SD card interface |
|
Pixel valves |
|
Analogue video encoder |
|
HDMI |
|
Display Parallel Interface |
例如 vcgencmd measure_clock arm
measure_volts [block]
显示特定程序块使用的当前电压。接受以下区块值：
| block | Description |
|---|---|
|
VC4 core voltage |
|
SDRAM Core Voltage |
|
SDRAM I/O voltage |
|
SDRAM Phy Voltage |
otp_dump
显示 SoC 内部 OTP（一次性可编程）存储器的内容。这些内容为 32 位值，索引范围从 8 到 64。详情请参阅 OTP 位页面。
get_config [configuration item|int|str]
显示指定配置设置的值：或者，指定 int （整数）或 str（字符串）以查看给定类型的所有配置项。例如，以下命令以 MB 为单位返回设备的总内存：
$ vcgencmd get_config total_mem
get_mem type
报告 Arm 和 GPU 可寻址的内存量。要显示 Arm 可寻址的内存量，请使用 vcgencmd get_mem arm；要显示 GPU 可寻址的内存量，请使用 vcgencmd get_mem gpu。在内存超过 1GB 的设备上，arm 参数将始终返回 1GB 减去`gpu`内存值，因为 GPU 固件只知道前 1GB 内存。要获得设备总内存的准确报告，请参阅上文的 total_mem 配置项和 get_config 部分。
无障碍选项
在 GitHub 上修改
视觉辅助工具
有视觉障碍的 Raspberry Pi 操作系统用户可以在 Recommended Software 菜单中找到有用的工具。
我们提供 Orca屏幕阅读器，以方便 Raspberry Pi 桌面的导航。此外，我们还提供屏幕放大镜，以提高用户界面和屏幕元素的可读性。
在 Raspberry Pi 上使用 Python
在 GitHub 上修改
Raspberry Pi 操作系统预装了 Python 3。干扰系统 Python 安装会给操作系统带来问题。安装第三方 Python 库时，请务必使用正确的软件包管理工具。
在 Linux 上，您可以通过两种方式安装 python 依赖项：
-
使用
apt安装预配置的系统包 -
使用
pip在虚拟环境中使用 Python 的依赖关系管理器安装库。Important从 Raspberry Pi OS Bookworm 开始，您只能使用 pip安装到 Python 虚拟环境 (venv)。这一更改是由 Python 社区引入的，而不是由 Raspberry Pi 引入的：欲了解更多信息，请参阅 PEP668。
使用 apt 安装 Python 软件包
通过 apt 安装的软件包是专为 Raspberry Pi 操作系统打包的。这些软件包通常经过预编译，因此安装速度更快。由于 apt 会管理所有软件包的依赖关系，因此使用此方法安装时会包含运行软件包所需的所有子依赖关系。而且 apt` 还能确保在卸载时不会破坏其他软件包。
例如，要安装支持 Raspberry Pi 的 Python 3 库 Build HAT，请运行以下命令：
$ sudo apt install python3-build-hat要查找使用 apt 发布的 Python 软件包，请使用 apt search。在大多数情况下，Python 软件包使用前缀 python- 或 python3-：例如，你可以用 python3-numpy 这个名字找到 numpy 软件包。
使用 pip 安装 Python 库
Bookworm 对 pip 安装的更改
在旧版本的 Raspberry Pi OS 中，可以使用 pip 将库直接安装到 Python 的系统版本中。从 Raspberry Pi OS Bookworm 开始，用户不能直接将库安装到 Python 的系统版本中。
取而代之的是 将库安装到虚拟环境 (venv)。要在系统级别为所有用户安装库，请使用 使用 apt 安装。
尝试在全系统安装 Python 包时，会输出类似下面的错误：
$ pip install buildhat
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to
install.
If you wish to install a non-Debian-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
sure you have python3-full installed.
For more information visit http://rptl.io/venv
NOTE: 如果您认为这是一个错误，请联系您的 Python 安装或操作系统发行提供商。您可以通过 --break-system-packages 来覆盖此选项，但这有可能破坏您的 Python 安装或操作系统。
提示：详细规范请参见 PEP 668。长期以来，Python 用户一直在处理操作系统软件包管理器（如 apt）与 Python 特定的软件包管理工具（如 pip）之间的冲突。这些冲突包括 Python级 API 的不兼容性和文件所有权的冲突。
从 Raspberry Pi OS Bookworm 开始，通过 pip 安装的软件包 必须安装到 Python 虚拟环境 (venv)。虚拟环境是一个容器，您可以在其中安全地安装第三方模块，这样它们就不会干扰您的系统 Python。
在虚拟环境中使用 pip
要使用虚拟环境，需要创建一个容器来存储环境。根据你使用 Python 的方式，有几种方法可以做到这一点。
-
per-project environments
-
单独用户环境
许多用户为每个Python项目创建单独的虚拟环境。在每个项目的根文件夹中找到虚拟环境，通常使用 env 之类的共享名称。从每个项目的根文件夹中运行以下命令以创建虚拟环境配置文件夹：
$ python -m venv env在项目上工作之前，从项目根目录运行以下命令开始使用虚拟环境：
$ source env/bin/activate然后您会看到类似下面的提示：
(env) $完成项目工作后，可以在任意目录运行以下命令离开虚拟环境：
(env) $ deactivate您可以为您的用户帐户创建一个虚拟环境，而不是为每个Python项目创建一个虚拟环境。在运行任何Python代码之前激活该虚拟环境。这种方法对于跨项目共享许多库的工作流来说更方便。
在整个用户帐户中为多个项目创建虚拟环境时，请考虑在主目录中定位虚拟环境配置文件。默认情况下，将配置存储在 folder whose name begins with a period 中以隐藏文件夹，防止它弄乱主文件夹。
使用以下命令在当前用户主目录的隐藏文件夹中创建虚拟环境：
$ python -m venv ~/.env从任意目录运行以下命令开始使用虚拟环境：
$ source ~/.env/bin/activate然后，您应该会看到类似于以下内容的提示：
(.env) $要离开虚拟环境，请从任何目录运行以下命令：
(.env) $ deactivateCreate a virtual environment
运行以下命令创建虚拟环境配置文件夹，将 <env-name> 替换为您希望用于虚拟环境的名称（例如 env）：
$ python -m venv <env-name>|
Tip
|
在文件夹名称前传递 --system-site-packages 标志以将系统Python安装中所有当前安装的包预加载到虚拟环境中。
|
Enter a virtual environment
然后，执行虚拟环境配置文件夹中的 bin/activate 脚本进入虚拟环境：
$ source <env-name>/bin/activate然后，您应该会看到类似于以下内容的提示：
(<env-name>) $(<env-name>) 命令提示符前缀表示当前终端会话位于名为 <env-name> 的虚拟环境中。
要检查您是否处于虚拟环境中，请使用 pip list 查看已安装软件包的列表：
(<env-name>) $ pip list
Package Version
---------- -------
pip23.0.1
SetupToks66.1.1该列表应该比系统 Python 中安装的软件包列表短得多。现在可以安全地使用 pip 安装软件包了。在虚拟环境中使用 pip 安装的软件包只能安装到该虚拟环境。在虚拟环境中，python 或 python3 命令会自动使用虚拟环境的 Python 版本和安装的软件包，而不是系统 Python。
使用 Thonny 编辑器
我们推荐使用 Thonny 在 Raspberry Pi 上编辑 Python 代码。
默认情况下，Thonny 使用系统 Python。不过，您可以点击 Thonny 窗口右下角的 interpreter menu，切换到使用 Python 虚拟环境。选择已配置的环境，或使用 Configure interpreter… 配置新的虚拟环境。
从 Python 使用 GPIO
在 GitHub 上修改
使用 GPIO Zero 库可以轻松地用 Python 控制 GPIO 设备。该库在 gpiozero.readthedocs.io 上有全面的文档说明。
有关 GPIO 硬件的信息，请参阅 GPIO 硬件。
LED 控制
以下示例代码可控制连接到 GPIO17 的 LED：
from gpiozero import LED
from time import sleep
led = LED(17)
while True:
led.on()
sleep(1)
led.off()
sleep(1)在 Thonny 等 IDE 中运行此代码，LED 将反复闪烁。
LED 方法包括 on()、 off()、 toggle() 和 blink() 。
读取按键状态
要读取连接到 GPIO2 的按钮的状态：
from gpiozero import Button
from time import sleep
button = Button(2)
while True:
if button.is_pressed:
print("Pressed")
else:
print("Released")
sleep(1)按钮功能包括属性 is_pressed 和 is_held ；回调 when_pressed、 when_released 和 when_held ；以及方法 wait_for_press() 和 wait_for_release 。
使用按钮控制LED
以下示例代码读取连接到 GPIO2 的按钮的状态，并在按下按钮时点亮连接到 GPIO17 的 LED：
from gpiozero import LED, Button
led = LED(17)
button = Button(2)
while True:
if button.is_pressed:
led.on()
else:
led.off()或者：
from gpiozero import LED, Button
led = LED(17)
button = Button(2)
while True:
button.wait_for_press()
led.on()
button.wait_for_release()
led.off()或者：
from gpiozero import LED, Button
led = LED(17)
button = Button(2)