本文档是 Raspberry Pi Documentation 的简体中文翻译版本。

本项目开源地址：https://github.com/taophilosophy/rpicn

点击此处可浏览目录

警告

当前正在施工，具体进度请参考编辑日志。

PDF 文档

PDF 文档

• 使用由 safreya 提供的脚本：

https://github.com/FreeBSD-Ask/gitbook-pdf-export

可用于导出本书的 PDF 文档。该脚本使用 Python 3 编写，仅在 Windows 10、FreeBSD 14 上测试过。

具体使用方法见该项目的 README。

关于我们

本项目由 FreeBSD 中文社区发起。

如有问题请 PR 或 Issue。

• 微信公众号: rpicn2025 （扫码关注）

版本说明

目前已校对章节指向 2024.9.8 的树莓派官方文档。

其他内容的版本指向 2024.9.8 的树莓派官方文档。

更新需求请看贡献指南文件

版权说明

树莓派官方文档使用 Creative Commons Attribution-ShareAlike 4.0 International（CC BY-SA 4.0，署名-相同方式共享 4.0 国际）授权。非常抱歉，根据协议要求，本项目也只能使用 Creative Commons Attribution-ShareAlike 4.0 International（CC BY-SA 4.0，署名-相同方式共享 4.0 国际）及兼容的协议（兼容协议要求与该协议基本相同）进行授权。该协议要求您：

• 您必须给出适当的署名 ，提供指向本许可协议的链接，同时标明是否（对原始作品）作了修改。树莓派官方英文文档项目位于 https://github.com/raspberrypi/documentation。我们特别授予所有人免于对本项目进行署名及链接的权利。但是您仍然需要遵守树莓派文档项目本身的许可协议。

• 相同方式共享 — 如果您再混合、转换或者基于本作品进行创作，您必须基于与原先许可协议相同的许可协议分发您贡献的作品。

Raspberry Pi documentation is copyright © 2012-2024 Raspberry Pi Ltd and is licensed under a Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA) licence.

Some content originates from the eLinux wiki, and is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported licence.

The terms HDMI, HDMI High-Definition Multimedia Interface, HDMI trade dress and the HDMI Logos are trademarks or registered trademarks of HDMI Licensing Administrator, Inc

警告

当前施工中断，具体进度请参考编辑日志。 若需维护请提供资金赞助。赞助请联系 [email protected]

树莓派

配件

微控制器

服务

我们是 FreeBSD 中文社区，如有问题请 PR。

树莓派官方英文文档使用 Creative Commons Attribution-ShareAlike 4.0 International（CC BY-SA 4.0，署名-相同方式共享 4.0 国际）授权。非常抱歉，根据协议要求，本项目也只能使用 Creative Commons Attribution-ShareAlike 4.0 International（CC BY-SA 4.0，署名-相同方式共享 4.0 国际）及兼容的协议（兼容协议要求与该协议基本相同）进行授权。该协议要求你：

• 你必须给出适当的署名，提供指向本许可协议的链接，同时标明是否（对原始作品）作了修改。树莓派官方英文文档项目位于 https://github.com/raspberrypi/documentation。我们特别授予所有人免于对本项目进行署名及链接的权利。但是你仍然需要遵守树莓派文档项目本身的许可协议。

• 相同方式共享 — 如果你再混合、转换或者基于本作品进行创作，你必须基于与原先许可协议相同的许可协议分发你贡献的作品。

Raspberry Pi documentation is copyright © 2012-2024 Raspberry Pi Ltd and is licensed under a Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA) licence.

Some content originates from the eLinux wiki, and is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported licence.

The terms HDMI, HDMI High-Definition Multimedia Interface, HDMI trade dress and the HDMI Logos are trademarks or registered trademarks of HDMI Licensing Administrator, Inc

• 2024.6.5 同步至

• 2024.6.5-2024.7.11 完全重译“树莓派启动盘制作工具”

• 2024.7.11 同步至

• 2024.7.11 “入门”校对完成

• 2024.7.12 “树莓派系统（Raspberry Pi OS）”校对完成

• 2024.7.16 对 16 个树莓派系统部件进行了翻译，已合并 15 个。1 个项目已弃用

• 2024.6.5-2024.7.16 改正了官方文档原文中的两个错误，补充了一个摄像机型号。已合并

• 2024.7.21 "系统配置"校对完成

• 2024.8.1

  • “config.txt”校对完成

  • “RP1”校对完成

• 2024.8.9 同步至官方文档的 2024.8.9 版本

• 2024.8.15 实现代码高亮

• 2024.9.4

  • 同步至官方文档的 2024.9.4 版本。

  • “旧版 config.txt 参数”校对完成

  • 将发现的一个命令错误，一个排版问题提交到树莓派上游，已合并

• 2024.9.7 请求树莓派上游更新树莓派启动盘制作工具的版本以包含最新的简中翻译，

• 2024.9.8 同步至官方文档的 。

• 2024.9.12

  • 树莓派上游发布了树莓派启动盘制作工具v1.9.0

  • 测试了树莓派启动盘制作工具v1.9.0

  • 将本项目的翻译、图片同步到树莓派启动盘制作工具v1.9.0

  • 修正了关于树莓派启动盘制作工具v1.9.0 翻译的几处小错误 ，已经合并，预计随 v1.9.1 分发

  • “Linux 内核”校对完成

• 2024.9.14 “远程访问”图片本地化

开始使用你的键盘

我们的官方键盘包括三个主机 USB 接口，可用于连接外部设备，如 USB 鼠标，USB 存储设备和其他 USB 控制设备。

该产品的 Micro USB 用于连接树莓派（通过键盘内置的 USB 集线器），可由树莓派控制并为键盘的三个 USB Type A 接口供电。

按键功能

树莓派键盘有三个锁定键: Num Lock, Caps Lock, 和 Scroll Lock。顶部右侧有三个 LED 指示灯，指示着哪些锁定已启用。

Num Lock 能使用字母键上标有的红色数字键，有效地创建数字键盘。通过按下 Num Lock 键 来启用/禁用此模式。

Caps Lock 能输入大写字母；按 Shift 键 可在该模式下输入小写字母。通过按 Caps Lock 键 可启用/禁用此模式。

Scroll Lock (ScrLk) 能使用光标键浏览网页和电子表格，无需鼠标。通过按住 Fn 键，同时按 ScrLk 键 可启用/禁用此模式。

开始使用鼠标

我们的官方鼠标有三个按钮，可以激活高质量的微动开关。滚轮用于在浏览文档和网页时快速滚动。

在使用鼠标时，请始终将其放在平坦稳定的表面上。鼠标在放置的平面上使用光学检测移动。在光滑的平面上（例如 PVC 和亚克力桌面）鼠标检测不到移动。当你在这样的平面上工作时，请把鼠标放在鼠标垫上。

把所有东西连接起来

这是我们推荐的配置，可同时使用你的树莓派、官方键盘和集线器以及官方鼠标。键盘上的集线器可确保轻松访问 USB 设备，鼠标线很长，足以让你的左右手使用鼠标。

注意

重要的是，把电源适配器接入树莓派，再把键盘连接到树莓派。如果把电源适配器接入键盘，再通过键盘为树莓派供电，那么键盘将无法正常工作。

创建树莓派账号

要使用树莓派服务，你首先需要创建一个。

在浏览器中访问 。

输入电子邮件和密码。点击 注册 按钮来创建你的账户。

创建账户后，你将收到一封验证电子邮件。

在邮件中点击 验证电子邮件 按钮，来验证你的电子邮件地址以完成账户创建。

创建树莓派账号后，你就可以使用 使用树莓派账号登录 按钮登录树莓派服务。

启用双因素身份验证

与大多数现代网络服务类似，树莓派账号支持使用基于时间的一次性密码 (TOTP) ，即双因素身份验证 (2FA)。

双因素身份验证增加了额外的一层保护。除了密码外，2FA 还需要另外的信息来登录。你应该基于 你拥有的东西（如智能手机）或 你的生物特征信息 来作为第二因素。

本指南使用你的智能手机作为认证的第二因素。

安装双因素认证应用

首先，在你的手机上下载一个生成 TOTP 的应用程序。安装一款 2FA 应用程序，如 或 Google Authenticator。

启用双因素身份验证

要启用双因素身份验证，请在登录到你的 后点击 双因素身份验证 选项。

在你的手机上打开 2FA 应用程序。使用你的树莓派账号提供的 QR 码扫描你的 2FA 应用程序以开始生成令牌。

输入你 2FA 软件生成的六位数字 TOTP，来注册 2FA 应用程序与你的树莓派 ID。

将出现确认屏幕，其包含恢复代码。请将恢复代码存储到安全的地方。这是在你丢失手机及 2FA 软件后，唯一能绕过 2FA的方法。

你现在已经配置了树莓派账号需要使用手机上 2FA 应用程序生成的 TOTP 进行登录。

BCM2835

BCM2835 是博通（Broadcom）芯片，应用于树莓派 1A、A+、B、B+、树莓派 Zero、树莓派 Zero W 和树莓派计算模块 1。它内置了一颗 ARM1176JZF-S 单核处理器。可在外设规格文档中找到芯片的一些详细信息。

注意

外设规格文档中有一些错误。但是有个已知勘误表。 可在以下文档找到处理器的其他信息;

• GPU 文档和开源驱动程序

• ARM1176JZF-S

BCM2836

这是树莓派 2B 中使用的博通芯片。BCM2836 的底层架构与 BCM2835 相同。唯一的显著区别是删除了 ARM1176JZF-S 处理器，并用四核 Cortex-A7 簇进行替换。

你应该参考：

• BCM2836 ARM 原生外设设备

• Cortex-A7 MPcore 处理器参考手册

BCM2837

这是在树莓派 3B、2B 后续型号以及树莓派计算模块 3 中使用的博通芯片。BCM2837 的底层架构与 BCM2836 相同。唯一明显的区别是用四核 ARM Cortex A53（ARMv8）簇替换了四核 ARMv7 簇。

ARM 核心运行在 1.2GHz，使设备比树莓派 2 快约 50%。VideoCore IV 运行在 400MHz。

请参考如下 BCM2836 文档，了解 ARM 外设设备规格的详细信息，该规格同样适用于 BCM2837。

• BCM2836 ARM 原生外设设备

• Cortex-A53 MPCore 处理器技术参考手册

BCM2837B0

这是在树莓派 3B+、B+ 和树莓派计算模块 3+ 中使用的博通芯片。BCM2837B0 的底层架构与其他版本的树莓派中使用的 BCM2837 芯片相同。ARM 核心硬件相同，但主频更高。

ARM 核心可运行于高达 1.4GHz，使 3B+/3A+ 比旧款树莓派 3 快约 17%。VideoCore IV 运行在 400MHz。ARM 核心为 64 位，但 VideoCore IV 是 32 位的。

BCM2837B0 芯片的封装和 BCM2837 略有不同，并且最明显的是附带了散热片，能获得更好的热管理。这使得更高的时钟频率成为可能，并且能更准确地监控和控制芯片的温度。

树莓派博客上的这篇文章详细介绍了 BCM2837B0 芯片。

BCM2711

这是在树莓派 4B、树莓派 400 和树莓派计算模块 4 中使用的博通芯片。BCM2711 的架构是对旧版树莓派中 SoC 使用的架构的大幅升级。它延续了 BCM2837 的四核 CPU 设计，但使用了更强大的 ARM A72 核心。它带有巨大改进的 GPU 功能集，由于 USB 2 和 USB 3 使用了 PCIe 通道，并且带有局域网连接的以太网控制器，因此输入/输出速度更快。它能够应用的内存也比以前采用的 SoC 更大。

ARM 核心可运行高达 1.5 GHz，使树莓派 4 比 3B+ 快约 50%。新的 VideoCore VI 3D 单元现在最高运行速度为 500 MHz。ARM 核心为 64 位，但 VideoCore 为 32 位，然而有一个新的内存管理单元，这意味着它的可用内存比以前的 SoC 更大。

BCM2711 芯片沿用自 BCM2837B0 以降的散热技术，提供了更好的热管理。

处理器：四核 Cortex-A72（ARM v8）64 位 SoC @ 1.5 GHz。

内存：视型号而定，最高可使用 8GB LPDDR4-2400 SDRAM

缓存：每个核心有 32kB 数据 + 48kB 指令 L1 缓存。1MB L2 缓存。

多媒体：H.265（4Kp60 解码）；H.264（1080p60 解码，1080p30 编码）；OpenGL ES，3.0 图形

I/O：PCIe 总线，板载以太网，DSI×2 （树莓派 4B 仅使用了一个），CSI×2（树莓派 4B 仅使用了一个），最多 I²C×6，最多 UART×6（与 I²C 复用），最多 SPI×6（树莓派 4B 仅使用了五个），双 HDMI 视频输出，复合视频输出。

BCM2711 的数据表包含更多细节。

BCM2712

博通 BCM2712 是树莓派 5 核心的 16 纳米应用处理器。它是树莓派 4 中使用的 BCM2711 设备的后继产品，并具有 BCM27xx 系列中其他设备许多常见的架构特性，这些设备曾用于旧款树莓派产品。

以四核 Arm Cortex-A76 CPU 簇为核心，主频高达 2.4GHz，每个核心带有 512KB 的 L2 缓存和 2MB 的共享 L3 缓存，集成了优化的 12 核 VideoCore VII GPU；硬件视频缩放器和 HDMI 控制器可驱动双 4kp60 显示器；还集成了由树莓派开发的 HEVC 解码器和图像信号处理器。32 位 LPDDR4X 内存接口提供了高达 17GB/s 的内存带宽，而 ×1 和 ×4 PCI Express 接口支持高带宽外部外设；在树莓派 5 上，后者用于连接树莓派 RP1 南桥（提供了主板上大部分外部 I/O 功能）。4GB、8GB 款树莓派 5 使用 BCM2712C1 步进。

重要功能包括:

• 四核 Arm Cortex-A76 @ 2.4GHz

  • ARMv8-A ISA

  • 64K B I 和 D 缓存

  • 每个核心 512KB L2 缓存，2MB 共享 L3 缓存

• 新的树莓派开发的 ISP

  • 1 千兆像素/秒

• 改进的 HVS 和显示管线

  • 双 4Kp60 支持

• VideoCore V3D VII

  • ~2-2.5× 速度（更多硬件，树莓派 4 上的 1GHz 对比 600MHz）

  • OpenGL ES 3.1，Vulkan 1.3

• 4Kp60 HEVC 硬件解码

  • 其他 CODEC 在软件中运行

  • H264 1080p24 解码约占 CPU 的 10-20%

  • H264 1080p60 解码约占 CPU 的 50-60%

  • H264 1080p30 编码（来自 ISP）~30-40％的 CPU

总体而言，BCM2712 中的新功能为常见的 CPU 或 I/O 密集型用例显示了相比树莓派 4 有 2-3 倍的性能提升。

BCM2712D0

BCM2712D0 版本移除了 BCM2712C1 中未使用的功能。在功能上，C1 和 D0 版本间并无差异。这两种封装在物理上的规格尺寸也一致。

RP3A0

树莓派 RP3A0 是我们首次采用了系统级封装（SiP），它内置了博通 BCM2710A1——这是封装在博通 BCM2837 芯片内部的硅芯片，该芯片用于树莓派 3 和 512MB 的 DRAM。

它被树莓派 Zero 2 W 使用。

RP3A0 是一款四核 64 位 Arm Cortex A53 CPU，主频为 1 GHz，但是如果安装了散热片或使用了其他冷却解决方案，该芯片的潜在超频主频可达 1.2 GHz。

请参考 BCM2836 文档，了解 ARM 外围设备规格的详细信息，该规格同样适用于 BCM2837 和 RP3A0。

• BCM2836 ARM 原生外围设备

• Cortex-A53 MPCore 处理器技术参考手册

注意

旧款树莓派 Zero 使用堆叠封装（PoP）DRAM，其中 DRAM 直接焊接在 BCM2835 芯片顶层。

什么是 MicroPython？

MicroPython 是编程语言 Python 3 的完整实现，直接运行在嵌入式硬件（如树莓派 Pico）上。你可以用 USB 串口获得交互提示（REPL），立即执行命令，并且内置了文件系统。Pico 版的 MicroPython 包含了用于访问底层芯片特定硬件的模块。

拖放安装 MicroPython

你可以通过将 Pico 通过 USB 连接到计算机，然后将文件拖放到其上来编程，因此我们提供了可下载的 UF2 文件，以便更轻松地安装 MicroPython。

下载适合你板子的正确 MicroPython UF2 文件：

• 带有 Wi-Fi 和蓝牙 LE 功能的

要在树莓派 Pico W 上使用 Wi-Fi 和蓝牙，可以使用 C/C++ 或 MicroPython，参见 。有关支持的蓝牙协议和配置文件的详细信息，请查看 Blue Kitchen 的 GitHub 仓库。

注意

其他基于 RP2040 的板子的 MicroPython 发行版可在 上找到。

要编程你的设备，请按照以下步骤操作：

1. 在连接 Pico 到计算机的 USB 电缆时，按住 BOOTSEL 按钮。当你的 Pico 显示成 RPI-RP2 的大容量存储设备时，请释放 BOOTSEL 按钮。

2. 将 MicroPython UF2 文件拖放到 RPI-RP2 卷上。你的 Pico 将重启。MicroPython 将自动运行。

3. 通过 USB 串口访问 REPL。

书籍提供了逐步连接你的 Pico 并使用命令行和 IDE 编程 MicroPython 的说明。

我可以在哪里找到文档？

你可以在以下位置找到有关 MicroPython 到 RP2040 的端口的信息：

- 用于 RP2040 微控制器的 MicroPython 环境

- 使用 C/C++ 或 MicroPython 将树莓派 Pico W 连接到互联网

- 关于 MicroPython RP2040 端口的官方文档

- 关于 MicroPython 中 rp2 模块的官方文档

进一步阅读

查看 了解如何使用 MicroPython 编程语言让你的 Pico 与周围的世界互动。本书已完全更新，适用于 树莓派 Pico W 和最新版本的 MicroPython，它向你展示如何：

• 设置并开始使用你的 Pico、Pico W

• 使用 MicroPython 编写程序

• 控制和感知电子组件

• 发现如何使用 Pico 独特的可编程 IO

• 将树莓派 Pico W 转换为物联网的网络连接节点

• 将你的 Pico W 与智能手机、平板电脑或另一个 Pico W 通过蓝牙低功耗（BLE）连接起来

我正在用的硬件是哪个？

在 MicroPython 中，没有直接的方法可以通过查看硬件来判断是在树莓派 Pico 还是 Pico W 上运行的软件。然而，你可以间接地通过查看你的特定 MicroPython 固件中是否包含网络功能来判断：

另外，你可以使用sys模块检查 MicroPython 固件的版本，以确定它是否为树莓派 Pico 或 Pico W 编译而成：

如果sys.implementation._machine中包含字符串 'Pico W'，那么你的固件是为 Pico W 编译的。

关于电视扩展板（TV HAT）

树莓派电视扩展板（TV HAT）

树莓派电视扩展板可使你在树莓派上使用内置的 DVB-T 及 DVB-T2 调谐器接收数字地面电视广播系统。通过该扩展板，你可以在树莓派上接收和观看电视，或创建电视服务器，使你能够通过网络将接收到的电视流式传输到其他设备。电视扩展板可与一切 40 针树莓派板一起用作网络上其他设备的服务器。这在树莓派上本身接收和观看电视时的性能可能有所不同，如果你出于此使用目的，我们建议树莓派 2 或更新的树莓派。

主要特点：

• 索尼 CXD2880 电视调谐器

• 支持的电视标准：DVB-T2，DVB-T

• 接收频率：VHF III，UHF IV，UHF V

• 频道带宽：

  • DVB-T2：1.7MHz，5MHz，6MHz，7MHz，8MHz

  • DVB-T：5MHz，6MHz，7MHz，8MHz

关于 DVB-T

警告

电视扩展板不兼容北美所使用的数字电视标准——ATSC。

数字视频广播 - 地面（DVB-T）是 DVB 欧洲联盟的广播数字地面电视传输标准。世界其他地方使用其他的数字电视标准，例如在北美使用的 ATSC。但是这个电视扩展板仅支持 DVB-T 和 DVB-T2 标准。

已实施或采取的 DTT 系统（来源：DVB/EBU/BNE DTT 部署数据库，2023 年 3 月）

设置说明

遵循我们的入门文档，并使用最新版本的树莓派系统设置树莓派。

将天线转接器连接到电视扩展板，将转接器指向远离 USB 接口的方向，轻轻按下扩展板，覆盖在树莓派的 GPIO 引脚上，并在扩展板的两到三个角落放置间隔柱，通过安装孔将螺丝拧紧以固定它们。然后将电视扩展板的天线转接器连接到你的电视天线的线缆上。

我们推荐用于解码流（称为复用或简称为 muxes）并查看内容的软件称为 TVHeadend。电视扩展板一次只能解码一个复用，每个复用可以包含多个可供选择的频道。可以在连接了电视扩展板的树莓派上查看其内容，也可以发送到同一网络上的其他设备。

启动你的树莓派，然后打开终端，运行以下两个命令来安装 tvheadend 软件：

在 tvheadend 的安装过程中，你将被要求设置管理员账户名称和密码。稍后你会需要这些信息，所以确保设置了一个你能记住的内容。

在你网络中的另一台计算机上，打开一个网络浏览器，然后在地址栏中输入以下内容： http://raspberrypi.local:9981/extjs.html

这应该连接到运行在树莓派上的 tvheadend。在通过浏览器连接到 tvheadend 后，你将被提示使用你在安装 tvheadend 时选择的账户名和密码进行登录。

应该出现设置向导。

首先，你需要设置你希望 tvheadend 使用的语言，然后设置网络、用户和管理员访问权限。如果你没有特定偏好，请将允许网络留空，并在用户名和密码字段中输入星号（*）。这将能让连接到你的本地网络的人访问 tvheadend。

你应该看到一个名为网络设置的窗口。在网络 2 下，你应该看到 Tuner: Sony CDX2880 #0 : DVB-T #0。对于网络类型，请选择 DVB-T Network。下一个窗口是为网络分配预定义的复用器；在这里，你选择要接收和解码的电视流。在网络 1 下，对于预定义的复用器，请选择你的本地电视发射器。

注意

你可以使用 Freeview 网站找到你的本地发射器。输入你的邮政编码以查看哪个发射器应该给你一个良好的信号。

当你单击保存并继续时，软件将开始扫描所选的复用器，并显示进度条。大约两分钟后，你应该看到类似以下内容：

在下一个窗口中，名为服务映射，请勾选所有三个框：映射所有服务，创建提供者标签和创建网络标签。你应该看到一个可以观看的电视频道列表，以及它们当前正在播放的节目。

要在浏览器中观看电视频道，请单击频道列表左侧的小电视图标，就在 i 图标的右侧。这将在浏览器中打开一个媒体播放器。根据你的浏览器内置的解码功能和正在播放的流类型，你可能会发现播放会有些卡顿。在这些情况下，我们建议使用本地媒体播放器作为播放应用程序。

要在本地媒体播放器（例如 VLC）中观看电视频道，你需要将其下载为流。单击频道列表左侧的 i 图标，以打开该频道的信息面板。在这里，你可以看到一个可以下载的流文件。

注意

许多应用程序都支持 tvheadend，例如 iOS 上的 TvhClient，可播放树莓派上的电视。

机械图纸

关于

树莓派 M.2 HAT+

树莓派 M.2 HAT+ M 键（key）能让你把 M.2 外部设备（如 NVMe 存储设备和其他 PCIe 配件）转接到树莓派 5 的 PCIe 接口。

M.2 HAT+ 扩展板可把树莓派 5 上的 PCIe 接口同单个 M.2 M 键接口的设备进行转接。你可以连接使用 2230/2242 尺寸的设备。M.2 HAT+ 可提供高达 3A 的功率。

M.2 HAT+ 遵守树莓派 HAT+ 规范，树莓派系统可自动检测 HAT+ 及其连接的设备。

附带的螺纹间隔柱提供了充足的空间，可在 M.2 HAT+ 下方安装树莓派主动散热器。

M.2 HAT+ 仅兼容树莓派 5 的树莓派外壳（需要你移除盖子和附带的风扇）。

特点

• 单通道 PCIe 2.0 接口（500 MB/s 峰值传输速率）

• 支持使用 M.2 M 键接口的设备

• 支持 2230/2242 尺寸的设备

• 为接入的 M.2 设备提供高达 3A 的电流

• 电源和状态指示灯

• 符合树莓派 HAT+ 规范

• 包含:

  • 连接线

  • 16 mm GPIO 堆叠排针

  • 4 个螺纹间隔柱

  • 8 颗螺丝

  • 1 个带有花纹的双凸缘固态硬盘配件螺丝（用于固定和支撑 M.2 外围设备）

安装

要使用树莓派 M.2 HAT+，你需要：

• 树莓派 5

每份 M.2 HAT+ 都配备了排线、GPIO 堆叠排针和要安装的硬件。请按照以下说明来完成 M.2 HAT+ 的安装：

1. 首先，请确保你的树莓派运行的是最新软件。运行以下命令，进行更新：

   复制

   $ sudo apt update && sudo apt full-upgrade

2. 接下来，请确保你的树莓派固件也是最新的。运行以下命令查看你正在运行的固件版本：

   复制

   $ sudo rpi-eeprom-update

   如果你看到的日期是 2023 年 12 月 6 日及更晚，请继续下一步。如果你看到的日期早于 2023 年 12 月 6 日，请运行以下命令打开树莓派配置 CLI：

   复制

   $ sudo raspi-config

   在 Advanced Options 下 > Bootloader Version，选择 Latest。然后，点击 Finish 或 Esc 键 退出 raspi-config。

   运行以下命令以将固件更新到最新版本：

   复制

   $ sudo rpi-eeprom-update -a

   然后，使用 sudo reboot 重启。

3. 在开始安装之前，请断开树莓派的电源。

4. M.2 HAT+ 兼容于树莓派 5 主动散热器。如果你有主动散热器，请在安装 M.2 HAT+ 之前先安装散热器。

5. 使用提供的四颗螺丝安装间隔柱。将 GPIO 堆叠排针牢固地压在树莓派的 GPIO 引脚上；只要所有引脚都能正确插入即可，方向并不重要。将扁平带状线缆从 M.2 HAT+ 上拔下，并将另一端插入树莓派的 PCIe 接口。从两侧抬起扁平带状线缆固定器，然后将带有铜触点朝向内部、即朝向 USB 的线缆插入。确保扁平带状线缆完全且均匀地插入 PCIe 接口，然后从两侧向下按紧线缆固定器，将扁平带状线缆牢固地固定在位。

6. 把 M.2 HAT+ 放在螺柱上面，然后使用剩下的四颗螺丝将其固定在位。

7. 把排线插入 M.2 HAT+ 上的插槽。从两侧抬起排线固定器，然后插入铜触点朝上的电缆。将排线完全均匀地插入端口，从两侧向下推动电缆固定器，将排线牢固地固定在位。

8. 通过逆时针旋转螺丝来取下驱动附件螺丝。将你的 M.2 固态硬盘插入 M.2 键接口，将固态硬盘以轻微向上的角度滑入插槽。不要强行将固态硬盘插入插槽：而应轻轻地滑入。

9. 将固态硬盘附件螺丝上的凹口推入 M.2 固态硬盘尾部的插槽中。将固态硬盘平放在 M.2 HAT+ 上，并顺时针旋转螺丝，直到固态硬盘固定。不要太过紧拧螺丝。

10. 恭喜，你已成功的安装了 M.2 HAT+。现在把你的树莓派接入电源；树莓派系统能自动检测到 M.2 HAT+。如果你使用桌面版树莓派系统，你应该能在桌面上看到代表硬盘的图标。如果你不使用桌面版，你可以在 /dev/nvme0n1 找到硬盘。要使硬盘自动可用于文件访问，请考虑配置自动挂载。

警告

在连接/断开 M.2 插槽上的设备之前，务必将树莓派断开电源。

从 NVMe 启动

要从连接到 M.2 HAT+ 的 NVMe 存储设备启动，请完成以下步骤：

1. 使用树莓派启动盘制作工具格式化你的 NVMe 存储设备。如果你已经有带有树莓派系统镜像的存储卡，可以在你的树莓派上执行此操作。

2. 使用存储卡或 USB 存储设备将树莓派启动到树莓派系统，以持久性更改板载 EEPROM 配置中的引导顺序。

3. 在树莓派终端上运行 sudo raspi-config 以打开树莓派配置 CLI。

4. 在 Advanced Options > Boot Order 下，选择 NVMe/USB boot。然后，点击 Finish 或按 Esc 键 退出 raspi-config。

5. 使用 sudo reboot 重启你的树莓派。

要获取更多信息，请参阅 NVMe 启动。

启用 PCIe Gen 3

警告

树莓派 5 未获 Gen 3.0 速度认证。PCIe Gen 3.0 连接可能不稳定。

要启用 PCIe Gen 3 速度，请按照在启用 PCIe Gen 3.0 中的说明操作。

框图

PDF 格式的原理图。

产品简介

更多有关 M.2 HAT+ 的信息，如机械规格和操作环境限制，请参阅产品简介。

传感器扩展板（Sense HAT）简介

树莓派传感器扩展板（Sense HAT）可为你的树莓派提供一系列传感功能。板载传感器可让你监测压力、湿度、温度、颜色、方向和运动。明亮的 8×8 RGB LED 矩阵可使传感器数据可视化，五个按钮的摇杆能让用户与你的项目进行交互。

Sense HAT 最初是为在国际空间站上使用而开发的，是树莓派基金会与欧洲航天局合作开展的 Astro Pi 教育计划的一部分。它可以帮助完成一切需要位置、运动、方向或环境传感的项目。

由官方支持的 Python 库提供了对所有板载传感器、LED 矩阵和操纵杆的控制。传感器扩展板兼容带有 40 针 GPIO 引脚排针型号的树莓派计算机。

安装

为了正确工作，传感器扩展板需要最新的内核，启用 I²C，并准备一些库来继续。

确保你的 APT 软件源是最新的：

$ sudo apt update && sudo apt full-upgrade

接下来，安装传感器扩展板软件包，这将确保内核是最新的，启用 I²C，并安装必要的库和程序：

$ sudo apt install sense-hat

最后，如果 I²C 被禁用或在安装之前内核是旧的，则可能需要重启：

$ sudo reboot

入门指南

安装后，可在 /usr/src/sense-hat/examples 下找到示例代码。

进一步阅读

你可以在由树莓派出版的《Experiment with the Sense HAT》一书中找到有关如何使用传感器扩展板的更多信息。由 Raspberry Pi 基金会的教育团队编写，这本书是由 Raspberry Pi Press 出版的 MagPi Essentials 系列的一部分。该书涵盖了 Astro Pi 项目的背景，并指导你如何使用 Python 库利用所有传感器扩展板的功能。

你可以以 PDF 格式免费下载这本书，它已根据知识共享署名-非商业性使用-相同方式共享 3.0 未本地化（CC BY NC-SA）许可发布。

使用 Python 与传感器扩展板

sense-hat 是传感器扩展板的官方支持库；它提供对所有板载传感器和 LED 矩阵的访问。

可在 sense-hat.readthedocs.io 找到该库的完整文档。

使用 C++ 与传感器扩展板

RTIMULib 是一个 C++ 和 Python 库，可使嵌入式 Linux 系统与 9 自由度和 10 自由度 IMU 的使用变得更加容易。/etc/RTIMULib.ini 中提供了一个预校准的设置文件，也被 sense-hat 复制并使用。包含的示例在当前工作目录中查找 RTIMULib.ini，因此你可能希望将文件复制到那里以获得更准确的数据。

RTIMULibDrive11 示例已经被预编译，以确保一切按预期工作。可以通过运行 RTIMULibDrive11 启动，并通过按 Ctrl C 停止。

注意

可以通过在适当的目录中运行 make 来编译 C/C++ 示例。

传感器扩展板硬件

传感器扩展板配备有 8×8 RGB LED 点阵和五向按钮摇杆，并包含以下传感器：

• 陀螺仪

• 加速度计

• 磁力计

• 温度

• 气压

• 湿度

• 颜色和亮度

Sense HAT 和 Sense HAT V2 的原理图和机械图可供下载。

• Sense HAT V1 原理图。

• Sense HAT V2 原理图。

• 传感器扩展板机械图纸。

LED 点阵

LED 点阵是一个带有 id“RPi-Sense FB”的 RGB565 帧缓冲区。适当的设备节点可以被写入为标准文件或进行 mmap 映射。包含的“snake”示例展示了如何访问帧缓冲区。

操纵杆

操纵杆显示为名为“Raspberry Pi Sense HAT Joystick”的输入事件设备，映射到方向键和回车键。它应该受到任意能够处理输入的库的支持，或直接通过 evdev 接口。适用的库包括 SDL、pygame 和 python-evdev。包含的“snake”示例显示了如何直接访问操纵杆。

硬件校准

安装必要的软件并按照以下步骤运行校准程序：

$ sudo apt update
$ sudo apt install octave -y
$ cd
$ cp /usr/share/librtimulib-utils/RTEllipsoidFit ./ -a
$ cd RTEllipsoidFit
$ RTIMULibCal

然后你将看到此菜单：

Options are:

  m - calibrate magnetometer with min/max
  e - calibrate magnetometer with ellipsoid (do min/max first)
  a - calibrate accelerometers
  x - exit

Enter option:

按小写的 m。然后将显示以下消息。按任意键开始。

    Magnetometer min/max calibration
    --------------------------------
    Waggle the IMU chip around, ensuring that all six axes
    (+x, -x, +y, -y and +z, -z) go through their extrema.
    When all extrema have been achieved, enter 's' to save, 'r' to reset
    or 'x' to abort and discard the data.

    Press any key to start...

启动后，你将看到屏幕上滚动的类似内容：

 Min x:  51.60  min y:  69.39  min z:  65.91
 Max x:  53.15  max y:  70.97  max z:  67.97

关注屏幕底部的两行，因为这些是程序中最近发布的测量结果。

现在，拿起树莓派和传感器扩展板，以尽可能多的方式移动它。最好拔掉所有非必要的电缆，以避免混乱。

尝试在俯仰、横滚和偏航轴上各获得一个完整的圆圈。在执行此操作时，请注意不要意外弹出存储卡。花几分钟移动传感器扩展板，当你发现数字不再变化时停止。

现在按小写 s 然后小写 x 退出程序。如果现在运行 ls 命令，你会看到已创建一个新的 RTIMULib.ini 文件。

除了这些步骤，你还可以通过执行上述步骤，但按 m 键而不是 e 键来执行椭球拟合。

当你完成后，将生成的 RTIMULib.ini 复制到 /etc/ 并删除 ~/.config/sense_hat/ 中的本地副本：

$ rm ~/.config/sense_hat/RTIMULib.ini
$ sudo cp RTIMULib.ini /etc

读取和写入 EEPROM 数据

通过向 /boot/firmware/config.txt 文件添加以下行来启用 I2C0 和 I2C1：

 dtparam=i2c_vc=on
 dtparam=i2c_arm=on

输入以下命令以重启：

 sudo systemctl reboot

下载并构建闪存工具：

$ git clone https://github.com/raspberrypi/hats.git
$ cd hats/eepromutils
$ make

注意

这些步骤可能不适用于树莓派 2B Rev 1.0 和树莓派 3B。固件将控制 I2C0，致使 ID 引脚被配置为输入。

阅读

可以使用以下命令读取 EEPROM 数据：

$ sudo ./eepflash.sh -f=sense_read.eep -t=24c32 -r

写入

下载 EEPROM 设置并构建 .eep 二进制文件：

$ wget https://github.com/raspberrypi/rpi-sense/raw/master/eeprom/eeprom_settings.txt -O sense_eeprom.txt
 ./eepmake sense_eeprom.txt sense.eep /boot/firmware/overlays/rpi-sense-overlay.dtb

禁用写保护：

$ i2cset -y -f 1 0x46 0xf3 1

写入 EEPROM 数据：

$ sudo ./eepflash.sh -f=sense.eep -t=24c32 -w

重新启用写保护:

 i2cset -y -f 1 0x46 0xf3 0

警告

此操作不会损坏你的树莓派或传感器扩展板，但如果发生错误，扩展板可能不能被自动检测到。上述步骤仅供调试目的。

设置 SDK

要全面了解如何使用 C/C++ SDK，请阅读我们的文档。然而，如果你打算在 上开发 Pico，可以通过命令行快速设置 C/C++ 工具链，只需运行我们的。

注意

在运行设置脚本之前，请确保你的树莓派操作系统已经。

树莓派 Pico C/C++ SDK

我们的官方 C SDK 可以从命令行使用，也可以与 Visual Studio Code、Eclipse 和 CLion 等流行的集成开发环境一起使用。要开始，请下载我们的 C/C++ SDK 和示例，并查看我们的'。或者，可以查看下一节进行快速设置。

• SDK

• 示例

你可以在以下位置找到有关 C/C++ SDK 的文档：

与基于 RP2040 的微控制器板的 C/C++ 开发

使用 C/C++ 或 MicroPython 将 Raspberry Pi Pico W 连接到互联网

用于 RP2040 微控制器的库和工具的 C/C++ 开发

Raspberry Pi Pico C/C++ SDK 的文档

注意

如果你正在使用 C/C++ SDK 构建应用程序，并且目标板不仅限于 Raspberry Pi Pico，你需要在 CMake 中传递 -DPICO_BOARD=boardname。这里的 boardname 是你的开发板名称，例如，对于 Adafruit Feather RP2040，你应该传递 -DPICO_BOARD=adafruit_feather_rp2040。更多信息请参考 Raspberry Pi Pico SDK 中的 目录和。

注意

关于在 Raspberry Pi Pico W 上使用 C/C++ SDK 构建应用程序并连接到网络，你需要在 CMake 中传递 -DPICO_BOARD=pico_w -DWIFI_SSID="你的网络" -DWIFI_PASSWORD="你的密码"。如果只需启用蓝牙支持，则无需传递 SSID 和密码，但仍需传递 -DPICO_BOARD=pico_w 字符串至 CMake。

第一个二进制程序

闪烁 LED

当使用新的微控制器时，第一个程序通常是控制板上的 LED 闪烁。树莓派 Pico 板上有一个单独的 LED，连接到板上的 GP25（用于 Raspberry Pi RP2040 for Pico），以及 WL_GPIO0（用于 Pico W 上的 Infineon 43439 无线芯片）。

你可以按照以下步骤进行 LED 的闪烁：

1. 下载适用于 或 的 Blink UF2。

2. 按住 BOOTSEL 按钮，将 Pico 插入树莓派或其他计算机的 USB 端口。

3. 它将作为名为 RPI-RP2 的大容量存储设备挂载。

4. 将 Blink UF2 二进制文件拖放到 RPI-RP2 卷上。Pico 将重新启动。

你应该看到板上的 LED 闪烁。

你可以在 Github 上查看 和 版本的代码。

打印 "Hello World"

下一个程序是通过 USB 串行连接打印 'Hello World'。

1. 下载 。

2. 按住 BOOTSEL 按钮，将 Pico 插入树莓派或其他计算机的 USB 端口。

3. 它将作为名为 RPI-RP2 的大容量存储设备挂载。

4. 将 'Hello World' UF2 二进制文件拖放到 RPI-RP2 卷上。Pico 将重新启动。

5. 打开终端窗口并键入：

你应该在终端看到 'Hello, world!' 的输出。

你可以在 Github 上查看。

快速启动你的项目

注意

以下说明简洁，并且仅适用于基于 Linux 的系统。有关详细步骤、其他平台的说明以及一般建议，请参阅 和 书籍。

安装 CMake（版本不低于 3.13）和 GCC 交叉编译器

设置项目以使用树莓派 Pico SDK，通过将 SDK 克隆到本地：

从 SDK 中将 external/pico_sdk_import.cmake 复制到你的项目目录中

在你的环境中设置 PICO_SDK_PATH 为 SDK 的路径，或者稍后通过 -DPICO_SDK_PATH= 选项传递给 cmake。

设置一个 CMakeLists.txt 如下：

接着编写你的代码，参见 或 书籍获取更多信息。

最简单的例子可以是一个单一源文件（例如 hello_world.c）：

并将以下内容添加到你的 CMakeLists.txt 中：

注意

此示例使用默认的 UART 作为 stdout；如果要使用默认的 USB，请参见 hello-usb 示例。

设置一个 CMake 构建目录。例如，如果不使用 IDE：

当为树莓派 Pico 以外的板子构建时，你应该将 -DPICO_BOARD=board_name 传递给上述 cmake 命令，例如 cmake -DPICO_BOARD=pico_w ..，以相应地配置 SDK 和构建选项。

这样做会设置各种编译器定义（例如 UART 和其他硬件的默认引脚号），在某些情况下还会启用其他库的使用（例如在构建 PICO_BOARD=pico_w 时启用无线支持），这些库在没有提供所需功能的板子上无法构建。

有关 SDK 自身定义的板子列表，请查看中每个命名板子的头文件。

从你创建的构建目录中制作你的目标。

现在你有了 hello_world.elf，可以通过调试器加载，或者有了 hello_world.uf2，可以通过拖放安装并在树莓派 Pico 上运行。

树莓派触摸显示屏

树莓派触摸显示屏是一款可通过 DSI 连接器连接到树莓派的液晶显示屏。你可以同时使用触摸显示屏和 HDMI 显示输出。

树莓派 7 吋触摸显示屏

除了树莓派 Zero 和 Zero 2 W 以外，触摸显示屏兼容所有型号的树莓派（这两款型号没有 DSI 接口）。最早的树莓派型号没有适当的安装孔，需要额外的硬件来安装显示屏 PCB 上的支架。

该显示屏核心参数如下：

• 800×480 RGB LCD 显示屏

• 24 位色彩

• 工业品质：水平 140 度视角，垂直 120 度视角

• 10 点多点触摸触摸屏

• 通过 I²C 接口进行 PWM 背光控制和电源控制

• 金属框架背面带有安装孔，可用于树莓派显示转换板和树莓派

• 背光寿命：20000 小时

• 工作温度：-20 至 +70 °C

• 存储温度：-30 至 +80 °C

• 对比度：500

• 平均亮度：250 cd/m²

• 视角（度）：

  • 顶部—50

  • 底部—70

  • 左侧—70

  • 右侧—70

• 功率要求：在最大亮度下，典型值为 5V 200mA。

• 外部尺寸：192.96 × 110.76 mm

• 可视区域：154.08 × 85.92 mm

安装触摸显示屏

你可以使用支架将树莓派安装在触摸显示屏背面，然后接入适当的线缆。如果有可用的外壳，你也可以将触摸显示屏安装在单独的外壳中。连接方式保持不变，但根据外壳的不同，你可能需要更长的线缆。

连接到触摸显示屏的树莓派

将扁平柔性电缆（FFC）的一端连接到触摸显示 PCB 上的 RPI-DISPLAY 接口。银色/金色接触点应远离显示屏。然后将另一端的 FFC 连接到树莓派上的 DISPLAY 接口。此接口的接触点应朝向树莓派。

如果 FFC 未完全插入或位置不正确，你将在显示屏上碰壁。在故障排除时，尤其是如果你在显示屏上看不到任何内容或显示屏只显示单一颜色时，你应始终仔细检查连接状况。

注意

触摸显示屏的机械图可供下载。

为触摸显示屏供电

我们建议使用树莓派的 GPIO 为触摸显示屏供电。或者你可以直接使用单独的 Mirco USB 电源适配器为显示屏供电。

用树莓派供电

要使用树莓派为触摸显示屏供电，你需要在树莓派的 GPIO 上的 5V 和 GND 引脚及显示屏上的 5V 和 GND 引脚间连接两根跳线。如下图所示。

显示屏的 5V 和 GND 引脚的位置

在开始之前，请确保树莓派已关机且未连接到电源。将黑色跳线的一端连接到树莓派上的引脚 6 ( GND )，将红色跳线的一端连接到引脚四 (5V)。如果引脚 6 不可用，你可以使用其他未使用的 GND 引脚来连接黑线。如果引脚 4 不可用，你可以使用其他的 5V 引脚来连接红线，例如引脚 2。

树莓派引脚的位置

接下来，将黑线的另一端连接到显示器上的 GND 引脚，将红线的另一端连接到显示器上的 5V 引脚。在完成所有连接后，下次打开树莓派时，你应该会看到触摸显示屏被点亮。

使用触摸显示屏上的另外三个引脚将显示器连接到早期树莓派 1B 和 B。有关更多信息，请参考我们关于旧版支持的文档。

注意

要判别早期的树莓派，请检查 GPIO 针脚连接器。仅早期型号有 26 针引脚的 GPIO 连接器；后续型号都有 40 针引脚。

用 Mirco USB 电源适配器供电

如果你不想用树莓派为触摸显示屏供电，可用 Mirco USB 电源适配器。我们建议使用树莓派 12.5W 电源适配器，可确保显示屏正常运行。

如果选择使用 Mirco USB 供电，请不要把树莓派的 GPIO 引脚连接到显示器上。两个板之间唯一的连接应为扁平柔性电缆。

警告

若使用 micro USB 线为显示器供电，并将其安装在外壳内，在使用时会无法触及显示器的 PCB 板。

使用屏幕键盘

在树莓派系统 Bookworm 及更高版本中，你可以将屏幕键盘 wvkbd 用作输入设备。要安装 wvkbd，请运行以下命令：

$ sudo apt install wvkbd

技巧

在旧版树莓派系统发行版中，请你使用 matchbox-keyboard 来代替。

更改屏幕方向

如果你想要在物理上调整显示屏方向，或者将其安装在特定位置，你可以使用软件调整屏幕的方向，以更好地满足你的设置。

使用桌面调整屏幕方向

要从桌面环境调整屏幕方向，请从“首选项”菜单中选择“屏幕配置”。在布局编辑器中右键单击矩形的 DSI-1 显示器，选择“方向”，然后选择最适合你需求的参数。你还可以通过“触摸屏”参数确保触摸叠加层分配给正确的显示屏。

在没有桌面的情况下调整屏幕方向

要在缺少桌面环境的设备上设置屏幕方向，请编辑 /boot/firmware/cmdline.txt 配置文件，向系统传递一个方向。将以下行添加到 cmdline.txt：

video=DSI-1:800x480@60,rotate=<旋转值>

用以下值替换占位符 <旋转值>，这些值对应于相对于显示器默认值的旋转度数：

• 0

• 90

• 180

• 270

例如，旋转值为 90 会将屏幕显示向右旋转 90 度。180 会把屏幕显示旋转 180 度，即倒置。

注意

使用 cmdline.txt 无法单独旋转 DSI 显示器，即无法 HDMI 显示器分离。当同时使用 DSI 和 HDMI 时，它们将应用相同的旋转参数。

旋转触摸屏输入

警告

在设备树旋转触摸输入可能会与你的输入库发生冲突。请尽可能在你的输入库/桌面中配置触摸事件旋转。

触摸输入的旋转与显示本身的方向无关。要更改此设置，你需要在 /boot/firmware/config.txt 中手动添加 dtoverlay 指令。在 config.txt 中添加以下行：

dtoverlay=vc4-kms-dsi-7inch,invx,invy

然后，在 config.txt 中删除以下行（如有）来禁用自动显示检测：

display_auto_detect=1

触摸显示设备树参数参考

叠加层 vc4-kms-dsi-7inch 支持以下选项：

要指定这些参数，请将它们用逗号分隔添加到你的 dtoverlay 行中的 /boot/firmware/config.txt。当存在时，布尔值默认为 true，但你可以使用后缀“=0”将其设置为 false。整数值需要一个值，例如 sizey=240。例如，要将 X 分辨率设置为 400 像素并反转 X 和 Y 坐标，请使用以下行：

dtoverlay=vc4-kms-dsi-7inch,sizex=400,invx,invy

旧版支持

警告

这些说明仅适用于最老的树莓派 A、B 款的开发板。要识别最老的树莓派，请检查 GPIO 连接器。只有原始型号带 26 引脚的 GPIO 连接器；后续型号有 40 针引脚。

树莓派 1B 和 B 款上的 DSI 连接器没有与触摸屏控制器和 DSI 控制器通信所需的 I²C 连接。为了解决这个问题，请使用显示套件附带的额外一组跳线。将 GPIO 头上的 SCL/SDA 连接到显示板上标有 SCL/SDA 的水平引脚。使用跳线电缆通过 GPIO 引脚为 B/B 供电。

这些主板上默认禁用了 DSI 显示自动检测。要启用检测，请在 /boot/firmware/config.txt 文件中添加以下行：

ignore_lcd=0

请用 Mirco USB 电源适配器连接到显示屏上的 PWR IN 来供电。不要通过树莓派的 Mirco USB 为设备供电。这将超过流过保险丝的最大电流额定值，因为显示屏的消耗大约为 400mA。

关于

树莓派 AI 套件

树莓派 AI 套件将树莓派 M.2 HAT+ 与 Hailo AI 加速模块捆绑在一起，用于树莓派 5。该套件包含以下物品：

• Hailo AI 模块，含神经处理单元（NPU）

• 树莓派 M.2 HAT+，用于将 AI 模块接入你的树莓派 5

• Ai 模块和 M.2 HAT+ 间预装了导热触点

• 安装螺丝套件

• 16 mm 堆叠 GPIO 引脚

AI 模块功能

• 每秒 13 万亿次（TOPS）神经网络推理加速器，基于 Hailo-8L 芯片设计。

• M.2 2242 外形尺寸

安装

要使用 Ai 套件，你需要：

• 树莓派 5

每份 Ai 套件都配备了预安装的 Ai 模块、排线电缆、GPIO 堆叠排针和安装硬件。请按照以下说明完成安装你的 Ai 套件：

1. 首先，请确保你的树莓派运行的软件是最新的。运行以下命令进行更新：

2. 接下来，请确保你的树莓派固件是最新的。运行以下命令可查看你正在运行的固件版本：

   如果你看到的日期是 2023 年 12 月 6 日及更晚，请继续下一步。如果你看到的日期早于 2023 年 12 月 6 日，请运行以下命令打开树莓派配置 CLI：

   在 Advanced Options > Bootloader Version 下，选择 Latest。然后，单击 Finish，或按 Esc 键 可退出 raspi-config。

   运行以下命令，可以将固件更新到最新版本：

   然后，使用 sudo reboot 重启。

3. 在开始安装前，请断开树莓派的电源。

4. 为了获得最佳性能，我们建议将 Ai 套件与树莓派主动散热器搭配使用。如果你有主动散热器，请在安装 Ai 套件之前安装它。

1. 使用附带的四颗螺丝安装间隔柱。牢固地将 GPIO 堆叠排针压在树莓派的 GPIO 引脚顶部；只要所有引脚都能正确插入即可，方向无所谓。从 Ai 套件上断开排线电缆，将另一端插入树莓派的 PCIe 接口。从两侧抬起排线电缆固定器，然后将带有铜触点朝向内部、即朝向 USB 接口的线缆插入。确保排线电缆完全且均匀地插入 PCIe 接口，然后从两侧按下电缆固定器，将排线电缆牢固地固定在位。

1. 将 AI 套件放在间隔物顶部，并使用剩下的四颗螺丝将其固定在位。

1. 将排线插入 AI 套件上的插槽。从两侧抬起排线固定器，然后插入铜接点朝上的电缆。将排线完全均匀地插入接口，从两侧按下电缆固定器，牢固地固定排线电缆。

1. 恭喜，现在你已成功的安装 AI 套件了。将你的树莓派接入电源；树莓派系统可自动检测 AI 套件。

警告

在连接/断开 M.2 插槽上的设备之前，务必先将你的树莓派断开电源。

入门指南

本指南将帮助你设置树莓派 5 与树莓派 AI 套件配合使用。这将使你能够使用 Hailo AI 神经网络加速器运行 rpicam-apps 摄像头演示。

准备工作

对于本指南，你将需要以下物品：

• 树莓派 5

• 树莓派 Ai 套件，其中包括：

  • M.2 HAT+

  • 预装的 Hailo-8L Ai 模块

• 64 位树莓派系统 Bookworm 系统

• 官方树莓派摄像头（例如摄像头模块 3 或高质量（HQ）摄像头）

硬件设置

1. 将摄像头连接到你的树莓派 5 主板，按照在安装树莓派摄像头中的说明进行操作。你可以跳过电源连接，因为你需要在下一步中断开树莓派的电源。

2. 按照安装说明将你的 AI 套件硬件连接到你的树莓派 5。

3. 按照说明启用 PCIe Gen 3.0。这一步骤是可选的，但为了使你的 AI 套件获得最佳性能，强烈建议启用它。

4. 安装使用 Ai 套件所需的依赖包。在终端运行以下命令：

   这将安装以下依赖项：

   • Hailo 内核设备驱动程序和固件

   • HailoRT 中间件软件

   • Hailo Tappas 核心后处理库

   • rpicam-apps Hailo 后处理软件演示阶段

5. 最后，使用 sudo reboot 重启你的树莓派，以使这些设置生效。

6. 为确保一切正常运行，请运行以下命令：

   如果你看到类似如下信息的输出，则已成功安装了 Ai 套件及其软件依赖包：

   另外，你可以运行 dmesg | grep -i hailo 来查看内核日志，应该会产生类似以下的输出：

7. 为了确保摄像头正常运行，请运行以下命令：

   这将启动摄像头并显示一个十秒钟的预览窗口。如果你已经验证一切安装正确，就可运行一些演示了。

演示

rpicam-apps 摄像头应用套件实现了一个后处理框架。本节包含一些演示后处理阶段，突出了 Ai 套件的一些功能。

以下演示使用 rpicam-hello，默认情况下显示一个预览窗口。但是，你也可以使用其他 rpicam-apps，包括 rpicam-vid 和 rpicam-still。你可能需要添加或修改一些命令行选项，以使演示命令与替代应用程序兼容。

要开始，请下载演示所需的后处理 JSON 文件。这些文件确定要运行的后处理阶段，并配置每个阶段的行为。例如，你可以在对象检测演示中启用、禁用、加强/减弱时间滤波的强度。或者你可以在分割演示中启用或禁用输出蒙版绘制。

要下载完整的后处理 JSON 文件集合，请克隆 rpicam-apps 存储库。运行以下命令仅拉取存储库中最新的提交，以节省空间：

技巧

后续部分提供的命令使用此存储库中的 JSON 文件。为了便于引用这些文件，此命令在你的主文件夹中创建了克隆的 rpicam-apps 目录。如果你修改了此目录的位置，则还必须修改下面的演示命令，以引用 JSON 文件的新位置。

目标检测

此演示显示神经网络检测到的物体周围的边界框。要禁用取景器，请使用参数 -n。要返回纯文本输出，说明检测到的物体，请添加参数 -v 2。运行以下命令在你的树莓派上尝试演示：

或者，你可以尝试另一款性能和效率上不同权衡的模型。

使用 Yolov8 模型运行演示，请运行以下命令：

使用 YoloX 模型运行演示，请运行以下命令：

使用 Yolov5 人脸模型运行演示，请运行以下命令：

图像分割

此演示执行对象检测，并通过在取景器图像上绘制颜色掩模来对对象进行分割。运行以下命令在你的树莓派上尝试演示：

姿势估计

此演示执行 17 点人体姿势估计，绘制连接检测点的线条。运行以下命令在你的树莓派上尝试演示：

进一步资源

Hailo 还创建了一组演示，你可以在树莓派 5 上运行，可在GitHub 存储库 hailo-ai/hailo-rpi5-examples 中找到。

你可以在GitHub 存储库 hailo-ai/hailo_model_zoo 中找到 Hailo 广泛的模型库，其中包含大量神经网络。

查看 Hailo 社区论坛和开发者区，进一步讨论有关 Hailo 硬件和工具的内容。

产品简介

有关 Ai 套件的更多信息，包括机械规格和操作环境限制，请参阅产品简介。

调试套件简介

树莓派调试套件是一款提供了 UART 串口和标准 Arm 串行线调试（SWD）接口的 USB 设备。该调试器设计用于简单、无需焊接的即插即用调试。它具有以下功能：

• USB ARM 串行线调试（SWD）接口

• USB 串口桥接器

• 兼容 CMSIS-DAP 标准

• 与兼容 CMSIS-DAP 的 OpenOCD 和其他工具搭配使用

• 易升级的开源固件

注意

有关树莓派三针调试连接器的更多信息，请参阅规格书。

这使得在 Windows、macOS 和 Linux 等没有 GPIO 引脚来直连 Pico 串口或 SWD 接口的设备也可轻松使用树莓派 Pico。

调试器

调试器在 3.3V 容忍 I/O 电压下运行。

调试器附带一根 USB 线和三根调试线：

• 三针 JST-SH 连接器到 3 针 JST-SH 连接器电缆

• 三针 JST-SH 连接器到 0.1 英寸排针（母）

• 三针 JST-SH 连接器到 0.1 英寸排针（公）

两根 0.1 英寸排针电缆 — 用于面包板（公头）或直接连接到带排针的板上（母头） — 颜色如下：

橙色 TX/SC（调试器输出）

黑色 GND

YellowRX/SD（输入到调试器或 I/O）

带有三针 JST-SH 连接器的电缆旨在与较新的树莓派主板用于 SWD 调试端口和 UART 连接器的标准三针连接器一起使用。

调试器有五个 LED 灯：一个是红色 LED 电源指示灯，另外四个是状态指示灯。

注意

当目标连接时，OpenOCD 会同时打开 DAP 的两个 LED，并在调用 DAP_DISCONNECT 时将它们关闭。

入门指南

根据你的设置，有不同的方法可以将调试器连接到树莓派 Pico。在下面的示例中，我们将调试器连接到具有更新的三针 JST-SH 连接器用于 SWD 的树莓派 Pico H。

连接以下内容：

• 将调试器“D”接口连接到 Pico H SWD JST-SH 连接器

• 将调试器“U”接口，带有三针 JST-SH 连接器连接到 0.1 英寸排针（公头）:

  • 调试器 RX 连接到 Pico H TX 引脚

  • 调试器 TX 连接到 Pico H RX 引脚

  • 调试器 GND 连接到 Pico H GND 引脚

注意

如果你有非 H Pico 或 Pico W（没有 JST-SH 连接器），你仍然可以将其连接到调试器。在板上的 SWCLK，GND 和 SWDIO 引脚上焊接一个公连接器。使用随调试器附带的备用 3 引脚 JST-SH 连接器到 0.1 英寸排针（母）电缆，连接到调试器的“D”端口。分别将 Pico 或 Pico W 上的 SWCLK，GND 和 SWDIO 连接到调试器上的 SC，GND 和 SD 引脚。

安装工具

要使用调试器，需安装以下工具。

安装 OpenOCD

你需要安装 OpenOCD。

要安装 OpenOCD，请在终端中运行以下命令：

$ sudo apt install openocd

在终端中使用 openocd 命令来运行 OpenOCD。

在 macOS 上安装 OpenOCD

首先，安装包管理器 Homebrew：

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

在 macOS 上安装 OpenOCD，请运行以下命令：

$ brew install openocd

要运行 OpenOCD，请在终端中使用 openocd 命令。

安装 GDB

我们还需要安装 GNU 调试器 (GDB)。

Linux

安装 gdb-multiarch ：

$ sudo apt install gdb-multiarch

macOS

运行以下命令安装 gdb ：

$ brew install gdb

你可以安全地忽略安装过程中关于“特殊权限”请求的消息。

重要

GDB 不支持 gdb Arm-based Macs。因此，要么从源代码编译 gdb，要么使用 lldb 来代替 gdb。开发者没有为在 Arm-based Macs 上运行 GDB 提供官方支持。可以在 Sourceware.org 的 GDB 邮件列表中找到有关 GDB 的支持。lldb 可作为 Xcode 命令行工具的一部分进行安装。

MS Windows

GDB 包含在我们的 Pico Windows 安装程序中。它也包含在 Arm GNU Toolchain Downloads 中。

或者，你可以在我们的《树莓派 Pico 入门指南》第 9 章和附录 A 中找到有关手动安装的信息。

注意

不建议在 Windows 上手动安装 GDB。

串行线调试（SWD）

串行线调试（Serial Wire Debug，SWD）是一种两引脚接口（SWDIO 和 SWCLK），可替代 JTAG 四或五引脚调试接口标准。

将新程序上传到你的 Pico

Pico 调试器可使你通过 SWD 接口和 OpenOCD 来加载二进制文件：从而无需在每次将新二进制文件推送到 Pico 后拔下，然后按住 BOOTSEL 按钮这些操作。使用调试器上传新的二进制文件是完全自动化的。

假如你构建了一个二进制文件：

$ sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" -c "program blink.elf verify reset exit"

注意

当你使用调试器上传二进制文件时，使用的是文件的 ELF 版本，而不是你在拖放时使用的 UF2 文件。

使用 SWD 进行调试

它还将让你在服务器模式下使用 openocd，并连接 GDB，这将为你提供断点和“正确”的调试。

$ cd ~/pico/pico-examples/
$ rm -rf build
$ mkdir build
$ cd build
$ export PICO_SDK_PATH=../../pico-sdk
$ cmake -DCMAKE_BUILD_TYPE=Debug ..
$ cd blink
$ make -j4

在调试构建中，当你在调试器下运行时，你将获得更多信息，因为编译器会使用信息构建你的程序，以告诉 GDB 你的程序正在做什么。

有关更多信息，请参阅《树莓派 Pico 入门指南》第 6 章。

要启动 OpenOCD 服务器，请运行以下命令：

$ sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000"

然后打开第二个终端窗口，切换到包含你构建的二进制文件的目录，并启动调试器以将其附加到 OpenOCD 服务器：

$ gdb blink.elf
> target remote localhost:3333
> monitor reset init
> continue

GDB 不适用于所有平台。根据你的操作系统和设备，请使用以下替代方案取代 gdb ：

• 在非树莓派设备上使用 gdb-multiarch。

• 在基于 Arm 的 macOS 设备上使用 lldb。

串行连接

确保调试器连接到了你树莓派 Pico 的 UART 引脚。

树莓派 Pico UART0 的默认引脚如下：

在连接后，树莓派 Pico 的 UART 上的流量将通过调试器中继到你的计算机，并显示为 CDC UART。在树莓派上，显示为 /dev/ttyACM0；在其他平台上，此串口将以不同方式显示（例如，在 macOS 上，显示为 /dev/cu.usbmodemXXXX ）。

如果你尚未安装 minicom，请执行以下操作：

$ sudo apt install minicom

并打开串口：

$ minicom -b 115200 -o -D /dev/ttyACM0

技巧

要退出 minicom，请按 CTRL-A，然后按 X 键。

要测试串行通信，你可以构建并上传“Hello World”示例应用程序。

进入 pico-examples 树中的 hello_world 目录，并运行 make。之后，你可以使用 openocd 将其上传到你的树莓派 Pico。要了解构建 hello_serial 示例程序的完整步骤，请参阅《开始使用树莓派 Pico》第 4 章。

$ cd pico-examples
$ mkdir build
$ cd build
$ export PICO_SDK_PATH=../../pico-sdk
$ cmake ..
$ cd hello_world/serial
$ make -j4
$ sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" -c "program hello_serial.elf verify reset exit"
$ minicom -b 115200 -o -D /dev/ttyACM0

打开 minicom 后，应该在控制台上看到打印出了"Hello, world!"。

对于支持的终端程序，USB 串行 UART 的描述会在 USB 设备描述中进行广告。

此描述中的唯一序列号意味着在 Windows 上，你的 COM 端口编号是"粘性"的每个设备，并且将允许你编写 udev 规则以将命名设备节点与特定的调试器绑定起来。

更新调试器固件

调试器固件以 UF2 文件的形式由树莓派分发。

调试器固件的最新版本是版本 2。如果你正在运行旧版，或者如果你意外地覆盖了调试器的固件，你可以在 debugprobe GitHub 存储库中找到最新版本的固件。

从最新版本下载 debugprobe.uf2。

捏住调试器外壳顶部以拆除。

在将调试器插入计算机时按住 BOOTSEL 按钮，以挂载名为“RPI-RP2”的卷。

将 debugprobe.uf2 复制到 "RPI-RP2" 卷。文件复制到设备后，将自动卸载设备。

你的调试器将重启，现在运行更新版本的调试器固件。现在已准备好进行调试了。

框图

调试器的原理图和机械图纸可用：

• 原理图（PDF）

• 机械图（PDF）

原理图上显示的测试点（TP）位于下图所示位置。

Pico 设备根据产品代次划分系列。

第一代树莓派 Pico 系列被称为 Pico（或 Pico 1），包含四个型号：

• 树莓派 Pico

• 树莓派 Pico H

• 树莓派 Pico W

• 树莓派 Pico WH

第二代树莓派 Pico 系列被称为 Pico 2，包含两个型号：

• 树莓派 Pico 2

  • 带有插针的树莓派 Pico 2

Pico 2 系列

树莓派 Pico 2 系列包含两款开发板：树莓派 Pico 2 和带有插针的树莓派 Pico 2。

树莓派 Pico 2

树莓派 Pico 2 是一款低成本、高性能的微控制器开发板，具有灵活的数字接口。主要特点包括：

• 由 Raspberry Pi 在英国设计的 RP2350 微控制器芯片

• 双核 Cortex-M33、或双核 Hazard3 处理器，最高可达 150MHz

• 520KB 的 SRAM 和 4MB 的板载闪存

• 带设备模式和主机模式支持的 USB 1.1

• 低功耗睡眠和休眠模式

• 通过 USB 大容量存储拖放编程

• 多功能 GPIO 引脚 ×26，其中 3 个可用于 ADC

• SPI ×2，I²C ×2，UART ×2，12 位 500ksps 模拟到数字转换器 (ADC) ×3，可控 PWM 通道 ×24

• 定时器 ×2，带 4 个报警，AON 定时器 ×1

• 温度传感器

• 3× 可编程 IO (PIO) 模块，总共 12 个状态机，支持自定义外围设备

  • 灵活、用户可编程的高速 IO

  • 可以模拟接口，如存储卡和 VGA

树莓派 Pico 2 采用镀边模块设计，便于直接焊接到载板上，而带有插针的 Pico 2 预装有插针。

注意

两款开发板均配备三针串行线调试 (SWD) 插针。然而，带有插针的 Pico 2 使用的是小型、带定位的 3 针连接器，而 Pico 2 则是板边相邻的三个镀边通孔插针。

引脚分布图和设计文件

• 下载 引脚分布图 (PDF)

• 下载 STEP 文件

• 下载树莓派 Pico 的 Fritzing 部件

注意

关于 Fritzing 的更多信息，请访问网站 fritzing.org 。

Pico 1 系列

树莓派 Pico 1 系列包含四款开发板：树莓派 Pico（最左侧），Pico H（左中），Pico W（右中），Pico WH（最右侧）。

树莓派 Pico 和 Pico H

树莓派 Pico 是一款低成本、高性能的微控制器开发板，具有灵活的数字接口。主要特点包括：

• 由 Raspberry Pi 在英国设计的 RP2040 微控制器芯片

• 双核 Arm Cortex M0+ 处理器，灵活的时钟频率最高可达 133 MHz

• SRAM 为 264KB，板载闪存 2MB

• 带设备模式和主机模式支持的 USB 1.1

• 低功耗睡眠和休眠模式

• 通过 USB 大容量存储拖放编程

• 多功能 GPIO 引脚 ×26

• SPI ×2，I²C ×2，串口 ×2，3× 12 位 ADC，可控 PWM 通道 ×2

• 精确的片上时钟和定时器

• 温度传感器

• 片上加速浮点库

• 可编程 IO (PIO) 状态机 ×8，支持自定义外围设备

树莓派 Pico 采用镀边模块设计，便于直接焊接到载板上，而 Pico H 则预装有插针。

注意

两款开发板均配备三针串行线调试 (SWD) 插针。然而，Pico H 使用的是小型、带定位的 3 针连接器，而 Pico 则是板边相邻的三个镀边通孔插针。

引脚分布图和设计文件

• 下载 引脚分布图 (PDF)

• 下载 设计文件 (Cadence Allegro)

• 下载 STEP 文件

• 下载树莓派 Pico 的 Fritzing 部件

• 下载树莓派 Pico H 的 Fritzing 部件

注意

关于 Fritzing 的更多信息，请访问网站 fritzing.org 。

树莓派 Pico W 和 Pico WH

树莓派 Pico W 在保持 Pico 外形尺寸的同时，增加了板载单频 2.4GHz 无线接口（802.11n），该接口采用 Infineon CYW43439 芯片。板载的 2.4GHz 无线接口具有以下特性：

• 无线（802.11n），单频（2.4 GHz）

• WPA3 安全协议

• 支持最多四个客户端的软接入点

• 蓝牙 5.2

  • 支持蓝牙低功耗（LE）中央和外围角色

  • 支持经典蓝牙

天线为板载天线，由 ABRACON（前身为 ProAnt）授权。无线接口通过 SPI 连接到 RP2040 微控制器。

由于引脚限制，部分无线接口的引脚是共享的。时钟信号（CLK）与 VSYS 监视器共享，因此只有在没有 SPI 事务进行时，才能通过 ADC 读取 VSYS。Infineon CYW43439 的 DIN/DOUT 和 IRQ 引脚都与 RP2040 上的一个引脚共享。仅在没有 SPI 事务进行时，才适合检查 IRQ。该接口通常以 33MHz 运行。

为了获得最佳的无线性能，天线应处于空旷空间。例如，在天线下方或附近放置金属会降低其增益和带宽性能。将接地金属添加到天线两侧可以改善天线的带宽。

注意

CYW43439 无线芯片通过 SPI 连接到 RP2040。CYW43439 支持通过此接口进行 802.11 无线和蓝牙通信。

重要

一般情况下，libcyw43 仅授权用于非商业用途，但 Pico W 用户以及其他所有围绕 RP2040 和 CYW43439 构建其产品的用户都可以享受免费的商业使用许可证。

重要

除了 BTstack 标准许可条款外，还提供了一个 补充许可，涵盖了树莓派 Pico W 或树莓派 Pico WH 商业使用 BTstack 的情况。

引脚图和设计文件

• 下载 引脚图 (PDF)

• 下载 设计文件 (Cadence Allegro)

• 下载 STEP 文件

• 下载适用于树莓派 Pico W 的 Fritzing 部件

文档

Pico 系列及其他基于 Raspberry Pi 微控制器的板卡文档。

RP2350

RP2350 数据手册

Raspberry Pi 的微控制器

使用 RP2350 进行硬件设计

使用 RP2350 微控制器构建板卡和产品

RP2040

RP2040 数据手册

Raspberry Pi 的微控制器

使用 RP2040 进行硬件设计

使用 RP2040 微控制器构建板卡和产品

树莓派 Pico 2

树莓派 Pico 2 数据手册

基于 RP2350 的微控制器板

入门指南：使用树莓派 Pico 系列微控制器

使用树莓派 Pico 系列设备及其他基于 Raspberry Pi 微控制器的板卡进行 C/C++ 开发

树莓派 Pico

树莓派 Pico 数据手册

基于 RP2040 的微控制器板

入门指南：使用树莓派 Pico

使用树莓派 Pico 及其他基于 RP2040 的微控制器板进行 C/C++ 开发

树莓派 Pico W

树莓派 Pico W 数据手册

带无线功能的 RP2040 微控制器板

使用树莓派 Pico W 连接互联网

使用 C/C++ 或 MicroPython 让树莓派 Pico W 上网

注意

在 使用树莓派 Pico W 连接互联网一书中介绍了使用 C/C++ 或 MicroPython 进行 Wi-Fi 和蓝牙开发的文档。

软件开发

树莓派 Pico C/C++ SDK

用于在 RP2040 微控制器上进行 C/C++ 开发的库和工具

树莓派 Pico Python SDK

用于 RP2040 微控制器的 MicroPython 环境

树莓派 Pico C/C++ SDK 的 API 级 Doxygen 文档也可以通过 微型站点 获取。

注意

提供了一个适用于 Windows 10 和 Windows 11 的 Pico C/C++ SDK 一键安装程序。

软件工具

如何查看 Pico 系列设备上的内容？

如果您不确定树莓派 Pico 系列设备上编写了什么程序，并且该程序是使用 Pico C/C++ SDK 构建的，通常会在二进制文件中嵌入一个名称和其他有用信息。您可以使用 Picotool 命令行工具来查找这些详细信息。关于如何使用 Picotool 的完整说明可在我们的 '入门指南' 文档中找到。

• 前往 Picotool 的 GitHub 仓库。

使用另一台 Pico 系列设备进行调试

注意

debuprobe_on_pico 调试软件尚不支持 Pico 2。

您可以使用一台 Pico 系列设备来调试另一台 Pico 系列设备。这可以通过 debugprobe 实现，debugprobe 是一个允许 Pico 充当 USB → SWD 和 UART 转换器的应用程序。

您可以在 debugprobe GitHub 仓库 中找到最新版本的固件。

下载最新发布的 debugprobe_on_pico.uf2 文件。

按住 BOOTSEL 按钮并将调试设备插入计算机，以挂载名为“RPI-RP2”的卷。

将 debugprobe_on_pico.uf2 复制到该卷上。文件复制完成后，卷会自动卸载。

您的设备将重启，并运行更新版本的 debugprobe 固件。现在它已准备好进行调试。

注意

有关如何使用调试器的说明，请参见 Pico 系列微控制器入门指南。

重置 Flash 内存

Pico 的 BOOTSEL 模式存储在 RP2040 芯片的只读内存中，无法意外覆盖。无论如何，只要按住 BOOTSEL 按钮并插入 Pico，它都会显示为一个驱动器，您可以将新的 UF2 文件拖放到该驱动器上。通过软件无法将板卡刷砖。但是，在某些情况下，您可能希望确保 Flash 内存为空。您可以通过在 Pico 处于大容量存储模式时拖放一个特殊的 UF2 二进制文件来完成此操作。

• 下载 UF2 文件

• 查看 GitHub 上的代码

RP2350

RP2350 是由树莓派设计的一款微控制器。

无论你是拥有树莓派 Pico 2 还是其他 RP2350 衍生的微控制器板，你都可以在这里找到所需的所有入门资源。你将找到适用于树莓派 Pico 2 的 C/C++ 或 MicroPython 的入门支持，并可获得使用 RP2350 的其他开发板的相关资源链接。同时，还有关于树莓派 Pico 2 微控制器板和 RP2350 微控制器芯片的技术文档链接。

芯片为何命名为 RP2350？

RP2350 中的后缀数字源于以下因素：

1. 处理器核心数量（2）

2. 大致的处理器类型（M33）

3. floor(log2(内存 ÷ 16KB))

4. floor(log2(非易失性存储器 ÷ 128KB))，如果没有板载非易失性存储器，则为 0

技术规格

RP2350 是树莓派推出的高性能、安全、低成本且易于使用的微控制器。

它拥有大容量的片上存储器、对称的双核处理器系统、确定性的总线结构以及丰富的外设集合，辅以独特的可编程 I/O (PIO) 子系统，为专业用户提供无与伦比的性能和灵活性。详细的文档、精心打磨的 MicroPython 移植版本和 ROM 中的 UF2 引导加载程序，使其成为初学者和爱好者的最佳选择。

RP2350 是一个无状态设备，支持从外部 QSPI 存储器进行缓存执行。这一设计决策允许你为应用选择合适的非易失性存储器密度，并受益于商品闪存的低价格。

RP2350 使用现代 40nm 工艺节点制造，提供高性能、低动态功耗和低漏电率，并支持多种低功耗模式，以延长电池供电的操作时间。

主要特性包括：

• 双核 Cortex-M33 或 Hazard3 处理器，最高可达 150MHz

• 520KB 多片高性能 SRAM

• 通过专用 QSPI 总线支持最多 16MB 的片外 Flash 存储器

• DMA 控制器

• 全连接 AHB 交叉开关

• 片上可编程 LDO 生成核心电压

• 2 个片上 PLL 生成 USB 和核心时钟

• GPIO 引脚 x30，其中 4 个可用作模拟输入

• 外设

  • 串口 x2

  • SPI 控制器 x2

  • I²C 控制器 x2

  • PWM 通道 x24

  • USB 1.1 控制器和 PHY，支持主机和设备模式

  • 可编程 IO (PIO) 模块 x3，总共 12 个状态机

安全性

RP2350 拥有全方位安全架构，基于面向 Cortex-M 的 Arm TrustZone 构建，包括以下功能：

• 支持签名引导

• 8KB 片上反熔丝一次性可编程 (OTP) 存储器

• SHA-256 加速

• 硬件真随机数生成器 (TRNG)

架构切换

RP2350 包含一对开源硬件 Hazard3 RISC-V 内核，这些内核可在启动时替代 Cortex-M33 内核。我们的引导 ROM 甚至可以自动检测第二阶段二进制文件的构建架构，并将芯片重新引导到适当的模式中。除了少数安全功能和双精度浮点加速器之外，芯片的所有功能都在 RISC-V 模式中可用。

基于 RP2350 的开发板

树莓派设计了树莓派 Pico 2，作为开发板和参考设计，基于 RP2350。

许可你出于任何目的使用、复制、修改和/或分发此设计，无论是否收费。

该设计按“原样”提供，作者对该设计不作任何担保，包括所有适销性和适用性隐含担保。在任何情况下，作者均不对因使用或性能问题引起的任何特殊、直接、间接或后果性损害或任何损害负责，无论是合同、过失或其他侵权行为。

其他开发板

你可以在树莓派论坛上找到关于第三方 RP2350 开发板的讨论。

USB 产品 ID (PID)

许多基于 RP2350 的设备使用树莓派的 USB 供应商 ID 和产品 ID 组合。如果你构建了基于 RP2350 的第三方开发板，可能需要一个唯一的 USB 产品 ID (PID)。

如果需要为 Windows 用户提供自定义驱动程序，可能需要一个唯一的 USB PID。

USB-IF 授权树莓派为其供应商 ID (0x2E8A) 的常用硅组件分配 USB 产品 ID。

要预留与树莓派供应商 ID 相关联的 USB PID，请按照树莓派 USB PID Git 仓库中的说明操作。

注意

如果你使用标准的 RP2350 PID，可以使用 iManufacturer、iProduct 和 iSerial 字符串来唯一标识你的设备。

RP2040

RP2040 是由树莓派设计的一款微控制器。

无论你是拥有树莓派 Pico 1 还是其他基于 RP2040 的微控制器板，你都可以在此找到所需的一切。这里提供了有关在树莓派 Pico 上使用 C/C++ 或 MicroPython 的入门支持，以及使用 RP2040 的其他板的相关资源链接。此外，还提供了有关树莓派 Pico 微控制器板和我们的 RP2040 微控制器芯片的技术文档链接。

为什么芯片被称为 RP2040？

RP2040 后缀数字的含义如下：

1. 处理器核心数（2）

2. 松散定义的处理器类型（M0+）

3. floor(log2(内存 ÷ 16k))

4. floor(log2(非易失性存储 ÷ 16k))，如果没有板载非易失性存储则为 0

技术规格

RP2040 是树莓派推出的首款微控制器，延续了我们一贯的高性能、低成本和易用性。

凭借大容量的片上内存、对称的双核处理器、确定性总线结构和丰富的外设集，RP2040 为专业用户提供了无与伦比的性能和灵活性。借助详细的文档、成熟的 MicroPython 移植和 ROM 中的 UF2 引导加载程序，RP2040 为初学者和爱好者提供了最便捷的入门体验。

RP2040 是一个无状态设备，支持从外部 QSPI 存储器中执行缓存操作。这一设计决定允许你为应用选择适当的非易失性存储密度，并享受商品级闪存器件的低成本优势。

RP2040 使用现代 40nm 工艺制造，提供高性能、低动态功耗和低漏电，支持多种低功耗模式，以延长电池供电设备的使用时间。

关键特性包括：

• 双 ARM Cortex-M0+ @ 133MHz

• 264kB 片上 SRAM，分为六个独立的存储单元

• 支持通过专用 QSPI 总线连接的高达 16MB 的片外 Flash 存储器

• DMA 控制器

• 全连接的 AHB 交叉开关

• 插值器和整数除法外设

• 片上可编程 LDO，用于生成内核电压

• 2 个片上 PLL，用于生成 USB 和内核时钟

• 30 个 GPIO 引脚，其中 4 个可用作模拟输入

• 外设

  • 2 个串口

  • 2 个 SPI 控制器

  • 2 个 I²C 控制器

  • 16 个 PWM 通道

  • 带有主机和设备支持的 USB 1.1 控制器和 PHY

  • 8 个 PIO 状态机

低待机电流应用中的 RP2040 电源切换

即使在深度睡眠模式下，RP2040 的典型电流也为 ~180μA，睡眠电流高度依赖于 PVT：工艺（芯片间电流变化）、电压（电流随电压线性变化）和温度（电流随温度非线性变化）。

对于许多需要最小电流消耗的使用场景，最好的选择是完全关闭系统电源（或 RP2040 系统部分的电源）。本文档提供了一些实现这一目标的电路示例，设计人员可以根据自己的使用需求对这些电路进行调整。

设计文件

• 下载 Minimal Viable Board 设计文件（KiCad）

• 下载 VGA Carrier Board 设计文件（KiCad）

基于 RP2040 的板卡

树莓派设计了树莓派 Pico 1 作为开发板和参考设计，Pico 系列目前包括树莓派 Pico（最左），Pico H（左），Pico W（右）和 Pico WH（最右）。

树莓派 Pico 和 Pico W 的设计文件是公开提供的，没有任何限制。

• 下载 设计文件（Cadence Allegro）

• 下载 设计文件（Cadence Allegro）

许可允许为任何目的使用、复制、修改和/或分发此设计，无论是否收取费用。

设计按“原样”提供，作者不对与该设计有关的任何明示或暗示的适销性和适用性担保承担责任。在任何情况下，作者都不对因使用或性能问题导致的任何特殊、直接、间接或后果性损害或任何损害负责，无论是因合同、过失或其他侵权行为引起。

其他板卡

你可以在树莓派论坛 中找到关于第三方 RP2040 板卡的讨论。

USB PIDs

许多基于 RP2040 的设备使用树莓派的 USB 供应商 ID 和产品 ID 组合。如果你基于 RP2040 设计了第三方板卡，可能需要一个唯一的 USB 产品 ID（PID）。

如果需要为 Windows 用户提供自定义驱动程序，你可能需要唯一的 USB PID。

USB-IF 已授权树莓派使用其供应商 ID（0x2E8A）许可 USB 产品 ID，用于 RP2040 的常见硅组件。

要预留与树莓派供应商 ID 关联的 USB PID，请按照树莓派USB PID git 仓库中的说明进行操作。

注意

如果你使用标准的 RP2040 PID，可以使用 iManufacturer、iProduct 和 iSerial 字符串唯一标识你的设备。

内部温度传感器

RP2040 封装中的内部温度传感器为低分辨率传感器，需要用户校准后才具有精确度。

准确测量温度的一个关键部分是了解 ADC VREF 电压。转换公式意味着 ADC VREF 电压中的小误差会导致计算出的温度出现较大差异。RP2040 没有内部固定电压参考来确定 VREF 电压，因此 VREF 电压需要手动测量——需要注意的是，它可能会变化——或者需要提供外部固定电压参考。

注意

随着温度升高，RP2040 传感器电压会下降。

有关内部温度传感器的更多详细信息，请参见 RP2040 数据手册 第 4 章第 4.9.5 节。

RP1

RP1 是一款 12×12mm，引脚中心距为 0.65mm 的 BGA 南桥芯片，它为树莓派 5 提供了主要的 I/O（输入/输出）功能。

RP1 可提供：

• PCIe 2.0 x4

• 千兆以太网 MAC（GEM）控制器

• USB 3 主机控制器 x2

  • 每个都有 USB 3 x1 和 USB 2 x1 端口

  • USB 可用带宽是树莓派 4 的 2 倍

• SDIO 通道/eMMC x2（树莓派 5 未使用）

• MIPI 转换器 x2（4 通道，支持 DSI 和 CSI-2）

• 视频数模转换器（DAC）（3 通道，支持 PAL/NTSC 和 VGA）

  • 树莓派 5 仅使用单通道（复合视频）

• 低速外围设备（SPI、UART、I²C、PWM、GPIO、I²S）

• Delta-sigma（Σ-Δ）脉宽调制（PWM）音频输出

可在 RP1 外围设备文档中找到更多有关 RP1 的信息。

文档

关于 Pico 系列和其他基于树莓派微控制器的开发板的文档。

RP2350

RP2350 数据手册

树莓派设计的微控制器。

使用 RP2350 进行硬件设计

使用 RP2350 微控制器构建开发板和产品。

RP2040

RP2040 数据手册

树莓派设计的微控制器。

使用 RP2040 进行硬件设计

使用 RP2040 微控制器构建开发板和产品。

树莓派 Pico 2

树莓派 Pico 2 数据手册

基于 RP2350 的微控制器开发板。

从零开始使用树莓派 Pico 系列微控制器

在树莓派 Pico 系列设备和其他基于树莓派微控制器的开发板上进行 C/C++ 开发。

树莓派 Pico

树莓派 Pico 数据手册

基于 RP2040 的微控制器开发板。

从零开始使用树莓派 Pico

在树莓派 Pico 和其他基于 RP2040 的微控制器开发板上进行 C/C++ 开发。

树莓派 Pico W

树莓派 Pico W 数据手册

带有无线功能的基于 RP2040 的微控制器开发板。

将树莓派 Pico W 连接到互联网

使用 C/C++ 或 MicroPython 使树莓派 Pico W 上网。

注意

关于在树莓派 Pico W 上使用 C/C++ 或 MicroPython 进行 Wi-Fi 和蓝牙开发的文档，请参阅 将树莓派 Pico W 连接到互联网 一书。

软件开发

树莓派 Pico C/C++ SDK

用于在 RP2040 微控制器上进行 C/C++ 开发的库和工具。

树莓派 Pico Python SDK

用于 RP2040 微控制器的 MicroPython 环境。

树莓派 Pico C/C++ SDK 的 API 级别 Doxygen 文档也可 作为一个微型网站 提供。

注意

提供了适用于 Windows 10、Windows 11 的 Pico C/C++ SDK 一键安装程序。

简介

树莓派远程访问（Raspberry Pi Connect）可让你在世界上的任意地点，安全地访问你的树莓派。

要使用树莓派远程访问，请在你的树莓派上。然后打开 ，即可在浏览器窗口中访问，运行在你的树莓派上的桌面或 Shell。

Connect 使用安全的加密连接。在默认情况下，Connect 会直接在你的树莓派和浏览器之间进行通信。但是，当 Connect 无法在树莓派和浏览器间建立直接连接时，我们会使用中继服务器。在这种情况下，树莓派官方服务器也仅保留操作 Connect 所需的元数据。

Connect 目前处于 BETA 开发阶段。

注意

要使用 Connect，你的树莓派必须运行着 及更新版本。

安装

要开始安装，请打开终端。运行以下命令，更新你的系统和软件包：

在你的树莓派上，运行以下命令安装 Connect：

安装完成后，请重启你的树莓派或 以使用 Connect：

在下次登录树莓派时，Connect 就会自动启动。

精简版 Connect（Connect Lite）

我们提供了 Connect 的替代 精简（Lite） 版本，仅支持远程 Shell 访问，无法进行屏幕共享。

在你的树莓派上，运行以下命令，来安装精简版 Connect：

重启你的树莓派或 来使用 Connect。

考虑，即使你的用户账户未登录，也可访问你的设备。

技巧

精简版命令与完整版 Connect 相同，都叫 rpi-connect。rpi-connect-lite只是一个软件包名称而已。

手动启动 Connect

要用命令行手动启动服务，请运行以下命令：

将树莓派绑定到树莓派 ID

现在你已在树莓派上安装了 Connect，你必须把你的树莓派绑定你的树莓派 ID，才能使用 Connect。

如果你没有树莓派 ID，。

要把你的树莓派绑定树莓派 ID，需要使用 Connect 生成一个验证网址。访问该链接并登录你的树莓派 ID，将你的树莓派添加到你的账户中。

你可以使用树莓派桌面上的 Connect 图标或命令 rpi-connect生成验证网址。

使用树莓派桌面

rpi-connect 服务开始运行后，在系统托盘中将出现Connect 的图标。

单击 Connect 图标，从下拉菜单中选择“Sign in”。

这将打开一个验证网址，你可以用它把你的树莓派绑定到你的树莓派 ID 上。

通过命令行

使用以下命令生成一个链接，将你的树莓派绑定到你的树莓派 ID上：

该命令应输出类似以下内容：

在任意设备上访问生成的验证网址，并使用你的树莓派 ID 登录，将你的树莓派绑定到树莓派 ID。

完成树莓派连接

访问上一步生成的验证 URL。

使用你的 登录 Connect。

认证后，为你的树莓派起个名。请选择一个能帮助你辨识设备的名字。点击“创建设备并登录”按钮可继续。

现在你就可以远程连接到你的树莓派了。Connect 系统托盘图标会变成蓝色，代表你的树莓派已经连接至 Connect 服务。你将会收到一封电子邮件，通知你有新设备登录 Connect。

点击 Connect 系统托盘图标，打开 Connect 菜单。该菜单会显示你的当前登录状态、登出选项，以及启用或禁用远程访问方法的选项。

访问你的树莓派

现在你的树莓派会出现在 Connect 仪表板上，你可以通过浏览器在所有地方访问你的树莓派。Connect 提供了多种远程交互方式。

屏幕共享

Connect 能在浏览器中共享你树莓派的屏幕。使用以下说明来共享你树莓派的屏幕。

在任意计算机上访问。

Connect 会将你重定向至树莓派 ID 服务进行登录。登录后，Connect 会显示已连接设备的列表。支持屏幕共享的设备在设备名称下方显示灰色的 屏幕共享 徽章。

点击你想访问的设备右侧的 通过 Connect 按钮。从菜单中选择 屏幕共享 选项。这将打开一个浏览器窗口，显示你树莓派的桌面。

现在你可以像本地使用你的树莓派一样使用它。要了解更多连接信息，请将鼠标悬停在 断开连接 按钮右侧的挂锁图标上。

连接后，Connect 仪表板中 屏幕共享 徽章旁边会出现绿色圆点，表示有活动的屏幕共享会话。悬停以查看当前的屏幕共享会话数。

当屏幕共享会话进行中时，系统托盘中的 Connect 图标会变成紫色并显示一个闭合的圆圈。

停止屏幕共享

要关闭屏幕共享会话，请点击桌面上方的 断开连接 按钮。

禁用屏幕共享

要关闭屏幕共享，请点击 Connect 系统托盘图标并取消选择 允许屏幕共享。你的树莓派仍然登录到 Connect，但你将无法从 Connect 仪表板创建屏幕共享会话。

或者，你可以使用以下命令禁用屏幕共享：

在 Connect 仪表板上，屏幕共享 徽章和 通过 Connect 菜单中的 屏幕共享 选项将显示为删除线。

要重新启用屏幕共享，请执行以下操作之一：

• 点击 Connect 系统托盘图标并选择 允许屏幕共享

• 运行以下命令：

远程 shell

Connect 包含从浏览器访问在 Raspberry Pi 上运行的 shell 的功能。按照以下说明访问远程 shell。

在其他计算机上访问 。

Connect 会重定向到 Raspberry Pi ID 服务以进行登录。登录后，Connect 显示已链接设备的列表。可远程访问 shell 的设备在设备名称下方显示灰色的 Remote shell 标记。

点击你想访问的设备右侧的 Connect via 按钮。从菜单中选择 Remote shell 选项。这将在你的 Raspberry Pi 上打开一个 shell 会话。

现在你可以像本地一样使用你的 Raspberry Pi。

连接后，Connect 仪表板上的 Remote shell 标记旁边会出现绿色圆点，表示活动的远程 shell 会话。悬停显示当前的远程 shell 会话数量。

当远程 shell 会话进行时，系统托盘中的 Connect 图标会变为紫色，并显示一个闭合的圆圈。

结束远程 shell 会话

要关闭远程 shell 会话，请运行 exit 命令或关闭窗口。

禁用远程 shell 访问

要关闭远程 shell 访问，请点击 Connect 系统托盘图标并取消选择 Allow remote shell。你的 Raspberry Pi 仍然登录到 Connect，但你将无法从 Connect 仪表板创建远程 shell 会话。

或者，你可以使用以下命令禁用远程 shell 访问：

在 Connect 仪表板上，Remote shell 标记和 Connect via 菜单中的 Remote shell 选项将显示为被划掉。

要重新启用 shell 共享，请执行以下操作之一：

• 点击 Connect 系统托盘图标并选择 Allow remote shell

• 运行以下命令：

随时启用远程 shell

Connect 作为用户级服务运行，而不是作为 root。因此，只有当你的用户帐户当前在 Raspberry Pi 上登录时，Connect 才能正常工作。如果禁用自动登录并重新启动，这可能导致你的 Raspberry Pi 不可访问。为了即使在你没有登录设备时也能继续运行 Connect，请启用 user-lingering。从你的用户帐户运行以下命令以启用 user-lingering：

管理设备

Connect 仪表板列出了与你的 Raspberry Pi ID 链接的所有 Raspberry Pi 设备，并显示可以访问它们的各种方法。

点击设备名称以打开设备详细信息页面。该屏幕提供有关设备的低级信息。你还可以编辑设备名称或从 Connect 中删除设备。

从 Connect 中删除设备会自动登出设备上的 Connect。Connect 系统托盘图标变为灰色，并且菜单只提供 Sign in 选项。

更新

要更新到最新版本的 Connect，请运行以下命令：

重新启动设备以使更新生效：

Here's the translation of the provided text:

断开连接设备

在树莓派上运行以下命令来注销你的树莓派 ID，这将在连接屏幕上禁用你的设备：

卸载

运行以下命令从树莓派上移除连接软件：

卸载后，树莓派的序列号仍与你的树莓派 ID 关联。设备仍然显示在连接仪表板上，但无法用于远程访问。如果你再次安装 Connect，即使使用不同的存储卡，在同一台树莓派上，它将重复使用连接仪表板中现有的设备名称。

要解除树莓派与树莓派 ID 之间的关联，请从连接仪表板的设备列表中移除树莓派。

故障排除

已知问题

• 屏幕共享仅支持共享树莓派的单个主显示器。当树莓派连接多个 HDMI 屏幕时，Connect 有时会共享次要屏幕的内容。你可以通过右键单击桌面并在桌面首选项中更改任务栏位置来解决此问题。

• Connect 不支持屏幕键盘。为了完整功能，请使用物理键盘。

• Connect 需要支持（ES11）的浏览器，因为它使用了旧版本浏览器中不可用的。

• 浏览器截获某些键和键组合。因此，你无法将这些键输入到你的 Connect 窗口中。屏幕共享包括一个工具栏，模拟一些最受欢迎的被截获键。

查看 Connect 状态

要查看 Connect 服务的当前状态，请运行以下命令：

此命令的输出显示你当前是否已登录到 Connect，以及在你的树莓派上启用的远程服务。

启用增强日志记录

你可以为rpi-connect及其专用的 WayVNC 服务器启用调试日志，详细记录树莓派上的本地操作。

在rpi-connect中启用增强日志记录

用以下命令打开rpi-connect配置文件进行编辑：

在注释之间输入以下配置行：

最后，使用以下命令重启服务：

在专用的wayvnc服务器中启用增强日志记录

打开与 Connect 关联的专用 WayVNC 服务器的配置文件：

在注释之间输入以下配置行：

最后，使用以下命令重启服务：

查看 Connect 日志

要查看 Connect 服务及其专用 WayVNC 服务器的日志，请运行以下命令：

开始你的树莓派之旅

要开始你的树莓派之旅，请先准备以下配件：

• 电源适配器

• 启动介质（如大容量高速存储卡）

你可以把树莓派配置成带桌面的交互式计算机，也可以将其配置为仅通过网络访问的无头设备（headless）。无需其他外部设备，你就能无头设置树莓派：你可以在安装操作系统时预先配置主机名、用户账户、网络连接和 SSH。但如果你要直接使用树莓派，还需以下若干配件：

• 显示器

• 用于把树莓派接入显示器的线缆

• 键盘

• 鼠标

电源适配器

下表列出了用于各种款式的树莓派供电所需的 USB-PD 电源适配器。你可以使用其他能提供符合供电功率要求的高品质电源适配器来代替。

请把电源适配器接入树莓派（接口标有“POWER IN”、“PWR IN”或“PWR”）。某些型号的树莓派（如 Zero 系列），其 USB 输出接口的规格与电源接口相同。请确保你在树莓派上使用的那个接口是正确的！

启动介质

树莓派未搭载内置存储，因此需要你来提供启动介质。你可以用安装在受支持的介质上的操作系统，来启动你的树莓派：一般用存储卡，亦可用 USB 存储设备、网络存储设备和通过 PCIe 扩展板转接的存储设备。但是，仅有最新款的树莓派才能支持上述全部类型。

自树莓派 1A+ 以降，所有消费者型号的树莓派都搭载了存储卡槽。把存储卡插入卡槽后，你的树莓派就能自动从存储卡启动。

推荐的存储卡

我们建议，用于安装树莓派系统（Raspberry Pi OS）的存储卡，存储容量至少为 32GB［对于精简版树莓派系统（Raspberry Pi OS Lite），建议至少为 16GB］。你可以使用任意容量不大于 2TB 的存储卡。由于 MBR 的限制，目前不支持容量大于 2TB 的存储卡。同所有其他启动介质一样，读写速度更快的存储卡性能也更佳。

受硬件限制，以下设备仅可从 256GB（及更小）的启动分区上启动：

• 树莓派 Zero

• 树莓派 1

• 基于 BCM2836 SoC 的早期树莓派 2

其他操作系统需求可能各异。请查阅你使用的操作系统文档来了解容量需求。

键盘

你可以使用树莓派上的任一 USB 接口来连接有线键盘和 USB 蓝牙接收器。

鼠标

你可以使用树莓派上的任一 USB 接口来连接有线鼠标和 USB 蓝牙接收器。

显示器

树莓派支持以下显示输出功能：

注意

所有型号的树莓派均不支持 Type-C 视频传输（DisplayPort alt mode）。

如果你的树莓派有多个 HDMI 端口，请把主显示器插入到标有 HDMI0 的那个口。

常见的显示器都不支持 micro HDMI，亦不支持 mini HDMI。但是，你可以用 micro-HDMI-to-HDMI 转换线 和 mini-HDMI-to-HDMI 转换线来把树莓派上的这些接口转接至 HDMI 显示器。如果显示器不支持 HDMI，请考虑用转换器把 HDMI 输出转为该设备所支持的类型。

音频

所有型号的树莓派都能通过 HDMI、micro HDMI 或 mini HDMI 进行音频输出，且都支持通过 USB 进行音频输出。所有搭载了蓝牙的树莓派都支持蓝牙音频。所有基于树莓派 1、2、3 和 4 的型号都有一个 3.5 mm 的 TRRS AUX 耳机插孔，但可能需要用放大器才能得到足够大的音量输出。

网络

如下型号的树莓派配备了 WiFi 和蓝牙连接功能：

• 树莓派 5

• 树莓派 4

• 树莓派 3B+

• 树莓派 3

• 树莓派 Zero W

• 树莓派 Zero 2 W

后缀“B”代表带以太网接口的款式，“A”代表不带以太网接口。如果你的树莓派没有以太网接口，你还可以用 USB 转以太网转换器来连接有线互联网。

安装操作系统

如果你要使用树莓派，还需要操作系统。在默认情况下，树莓派会在卡槽里的存储卡中查找操作系统。

视你的树莓派型号而定，也许你还能用别的存储设备来启动操作系统，比如 USB 设备、网络存储和同扩展板接入的存储设备。

要让存储设备提供树莓派操作系统，你需要：

• 能把镜像写入到该存储设备的计算机

• 把你的存储设备接入该计算机的方法

大多数树莓派用户会选择使用存储卡作为他们的启动设备。

我们建议用树莓派启动盘制作工具来安装操作系统。

树莓派启动盘制作工具是一款能帮助你在 macOS、Windows 和 Linux 上下载和写入镜像的软件。启动盘制作工具包含了许多常见的树莓派操作系统镜像。它还能直接加载已下载的镜像，比如树莓派和第三方供应商（如 Ubuntu）。你可以用它预配置树莓派的凭据，设定远程访问。

启动盘制作工具亦兼容打包成 .img 格式的镜像，以及像 .zip 这样的压缩文件。

如果你没有能把镜像写入到存储设备的计算机，你可以通过互联网直接在你的树莓派上安装操作系统。

树莓派启动盘制作工具的使用方法

你可以通过如下方式安装树莓派启动盘制作工具：

• 在树莓派官网 raspberrypi.com/software 上下载运行最新版本的安装程序。

• 在终端里用包管理器安装，如 sudo apt install rpi-imager。

在树莓派启动盘制作工具安装完成后，单击启动盘制作工具的图标（或执行 rpi-imager）即可启动应用程序。

单击“选择设备（Choose device）”，然后从列表中选定你的树莓派型号。

接下来，单击“选择操作系统（Choose OS）”，然后选定要安装的操作系统。树莓派启动盘制作工具将始终在列表顶部显示树莓派系统（Raspberry Pi OS），且是适用于你树莓派型号的推荐版本。

将所选存储设备接入计算机。若使用外部/内置存储卡读卡器，请先插入存储卡。然后，单击“选择存储设备（Choose storage）”，选择你的存储设备。

警告

如果你的计算机接入了多款存储设备，请务必选择正确的那款设备！ 通常可以用大小来识别存储设备。如不确定，请断开其他设备，直到能确定要写入镜像的存储设备。

接下来，点击“下一步（Next）。

在弹出窗口中，树莓派启动盘制作工具会要求你应用操作系统设置。我们强烈建议使用自定义系统配置来设定你的树莓派。单击“编辑设置（Edit Settings）”按钮可打开自定义系统配置（ OS customisation）。

如果你没有用自定义系统配置这个功能来设定你的树莓派，在首次启动时，树莓派系统会在配置向导中，要求你再次提供相同内容。你可以单击选项“否（No）”来跳过自定义系统配置。

操作系统定制

操作系统定制菜单能让你在首次开机之前，设定你的树莓派。你可以预先配置：

• 用户名和密码

• WiFi 凭据

• 设备主机名

• 时区

• 键盘布局

• 远程连接

在你首次打开菜单自定义系统配置时，你也许会看到一个提示，询问你是否允许从计算机加载 WiFi 凭据。如果你回答“确认”，启动盘制作工具将从你当前连接的网络预填 Wi-Fi 凭据。如果你回答“否”，你可手动输入 WiFi 凭据。

选项 主机名（hostname） 设定了你的树莓派在网络上广播的主机名（使用 mDNS）。当你把树莓派接入网络后，网络上的其他设备就可以使用 <你的主机名>.local 或 <你的主机名>.lan 与你的树莓派进行通信。

选项 用户名（username）和密码（password） 设定了树莓派上管理员用户账户的用户名和密码。

选项 无线局域网（wireless LAN） 能让你输入无线网络的 SSID（网络名称）和密码。如果你的网络未公开广播 SSID，则应启用“隐藏 SSID”设置。在默认情况下，制作工具会使用你当前所在的地区作为“无线局域网地区”。该设置控制着树莓派使用的 WiFi 广播频率。如果你打算运行无头树莓派，请为无线局域网这个参数输入凭据。

选项 本地化设置（ locale settings） 能为你的树莓派设定时区和默认键盘布局。

菜单 服务（Services） 涉及了帮助你远程连接到树莓派的配置。

如果你打算用网络远程使用你的树莓派，请勾选“启用 SSH（Enable SSH）”旁边的方框。或者说，如果你想要不靠显示器直接运行树莓派，请启用该功能。

• 选择选项 密码验证（password authentication） ，可使用你在自定义系统配置的通用选项卡中提供的用户名和密码通过网络 SSH 连接到你的树莓派。

• 选择 仅允许公钥验证（Allow public-key authentication only ），可为你的树莓派预配置无密码，仅公钥的 SSH 验证，默认会使用你当前计算机上的私钥。如果你的 SSH 配置中已经有 RSA 密钥，制作工具将使用该公钥。如果没有，你可单击“运行 SSH-keygen（Run SSH-keygen）”来生成公私钥对。制作工具会使用新生成的公钥。

自定义系统配置还有“可选配置（Options）”这个菜单，能让你在写入过程中配置制作工具的操作。这些参数能让你在制作工具完成镜像校验时播放声音、在校验后自动卸载存储介质和禁用遥测。

写入

当你完成自定义系统配置的设定后，可单击“保存（Save）”来保存你的定制选项。

然后，在将镜像写入存储设备时，可单击“确认（Yes）”应用自定义系统配置。

最后，点击弹出窗口“你确定要继续吗？（Are you sure you want to continue?）”中的“确认（Yes）”，开始向存储设备写入数据。

如果看到要求管理员权限以读取和写入存储介质的提示，要继续，请授予制作工具权限。

这可能需要几分钟。去喝杯咖啡，散散步吧。

如果你想要找刺激，可以点击 取消校验（cancel verify） 来跳过校验这个过程。

当你看到弹出窗口“写入成功”时，表示镜像已完全写入和验证。现在你可以从存储设备启动树莓派了！

接下来，继续进行首次启动配置说明，让你的树莓派跑起来。

网络安装

网络安装能让树莓派使用制作工具通过网络下载的镜像（存储在设备上）进行操作系统的安装。使用网络安装，你可以在树莓派上安装操作系统，而无需存储卡读卡器，也不需要除树莓派之外的计算机。你可以在所有受支持的存储设备上运行网络安装——如存储卡和 USB 存储设备。

网络安装仅适用于树莓派 4、400、5。如果你的树莓派的引导加载程序比较旧，你可能需要更新引导加载程序才能使用网络安装。

网络安装须满足以下条件：

• 树莓派型号受支持且固件支持网络安装

• 显示器

• 键盘

• 有线网络连接

要启动网络安装，请在以下配置的基础上，按住 SHIFT 键，同时接通你的树莓派电源：

• 存储设备未写入镜像

• 已接入键盘

• 已接入兼容的存储设备，如存储卡、USB 存储设备

如果你尚未将树莓派连接到互联网，请使用网线进行连接。

连接到互联网后，你的树莓派会下载树莓派的安装程序。若下载失败，你可以重复该过程，再试一次。

在树莓派启动盘制作工具下载完成后，你的树莓派会自动运行启动盘制作工具。有关运行启动盘制作工具的更多信息，请参阅安装操作系统。

有关网络安装配置的更多信息，请参阅 HTTP 引导。

设置你的树莓派

在操作系统镜像写入完成后，把存储设备接入你的树莓派。

首先，拔掉树莓派的电源适配器插头，确保在连接外部设备时，树莓派已关机。如果你在存储卡上安装了操作系统，现在就可以把存储卡插入树莓派的卡槽。如果你在其他存储设备上安装了操作系统，现在就可以将它接入树莓派了。

然后，插入所需的其他外部设备，如鼠标、键盘和显示器。

最后，把电源接入你的树莓派。当你的树莓派开机时，你将看到 LED 状态灯亮起。如果你的树莓派接入了显示器，你在几分钟后就能看到启动屏幕。

首次启动配置

如果你在启动盘制作工具中使用了系统自定义来预配置你的树莓派，恭喜你！ 你的设备已经准备就绪。可继续下一步，了解如何充分发挥你的树莓派。

若你的树莓派在 5 分钟后仍无法启动，请检查 LED 状态灯。如果 LED 灯闪烁，请查看 LED 警告指示灯以获取更多信息。如果你的树莓派无法启动，可尝试以下解决方案：

• 如果你的启动设备不是存储卡，请先试试用存储卡启动

• 为你的存储卡重新写入镜像; 确保在启动盘制作工具中完成了完整的校验步骤

• 更新你树莓派上的引导加载程序，然后再次为你的存储卡再次镜像

如果你在启动盘制作工具中选择跳过了系统定制，则你的树莓派会在首次启动时运行配置向导。你需要显示器和键盘（没有鼠标也能完成）来设置向导。

蓝牙

如果你正在使用蓝牙键盘、蓝牙鼠标，此步骤将指引你完成设备配对。你的树莓派将扫描可配对的设备，然后连接至第一个扫描到的设备。

此过程适用于内置/外置 USB 蓝牙适配器。如果你使用 USB 适配器，请在启动树莓派前插入。

语言环境

此页面可帮助你配置区域、语言、时区和键盘布局。

用户

此页面可帮助你配置默认用户账户的用户名和密码。

在默认情况下，旧版树莓派系统会把用户名设置成“pi”。如果你使用的用户名是“pi”，请不要使用旧系统中的默认密码——“raspberry”，来确保你树莓派的安全性。

无线网络

该页面能帮助你连接到 WiFi 网络。从列表中选择你需要的网络。

如果你的网络需要密码验证，你可以在这里输入。

浏览器

此页面能让你选择：把默认的互联网浏览器设定为 Firefox（火狐浏览器）或者 Chromium（开源的 Chrome）。对于那个你未设置成默认的浏览器，你可以选择卸载。

软件更新

当你的树莓派接入互联网后，此页面能帮你把操作系统和软件更新到最新版本。在软件更新过程中，向导会删除非默认浏览器（如果你在默认浏览器这一步选择卸载它）。可能需要几分钟时间才能完成更新。

当你看到弹出窗口指示系统已经更新，请点击“确定（OK）”继续下一步。

完成

在配置向导结束后，点击“重启（Restart）”来重启你的树莓派。你的树莓派将应用个性化并启动至桌面。

下一步

树莓派已经设定且准备就绪，接下来做什么？

软件推荐

树莓派操作系统预装了许多基本应用程序，因此可开箱即用。如果你想使用那些我们认为有用的软件，请单击屏幕左上角的树莓派图标。选择 首选项（Preferences） > 推荐软件（Recommended Software），你将找到软件包管理器。你可以在那免费安装各种推荐软件。

具体来说，如果你打算把树莓派当家用电脑用，你可能会需要 LibreOffice，它对于撰写和编辑文档和电子表格极有用。你还可以使用诸如屏幕放大器和 Orca 屏幕阅读器之类的工具，来让树莓派更易于使用，这些应用程序在通用访问里。

教程

我们的教程向你介绍了各种有关你新树莓派使用的方法。你可以跟随那些让你感兴趣的教程，来学习编程、控制外部设备，创建令人激动的新项目。

支持

对于树莓派官方产品的支持，与其他树莓派用户交流，请访问树莓派论坛。

进一步阅读

你可以在由 Gareth Halfacree 撰写的最新版《树莓派官方初学者指南》中找到有关树莓派入门使用的更多信息。

可学习如何：

• 配置你的树莓派，为其安装操作系统，并开始使用这台功能齐全的计算机。

• 使用编程语言 Scratch 3、Python 和 MicroPython，通过逐步指南开始编程项目。

• 尝试连接电子元件，乐在其中，创造令人惊叹的项目。

第五版的新增内容：

• 针对最新的树莓派计算机进行更新：树莓派 5 和树莓派 Zero 2 W。

• 涉及最新的树莓派系统。

• 涉及树莓派 Pico 的新章节！

你可以在树莓派出版社的网站上购买这本书。

关于摄像头模块

现有若干款树莓派官方摄像头模块。最早的 500 万像素型号发布于 2013 年，随后于 2016 年发布了 800 万像素的摄像头模块 2。最新款的摄像头是发布于 2023 年的 1200 万像素的摄像头模块 3。最早的 500 万像素摄像头树莓派现已停产。

上述所有摄像头都有可见光和红外夜视版本。除此之外，摄像头模块 3 还带有标准、广角类型，总计四种不同的版本。

摄像头模块 3（左）和摄像头模块 3 广角（右）

摄像头模块 3 红外夜视（左）和摄像头模块 3 红外夜视广角（右）

此外，于 2020 年推出了可与外置镜头搭配使用的 1200 万像素的高质量摄像头，配有 CS 卡口——于 2023 年推出了 M12 卡口。高质量（HQ）摄像头没有红外夜视版本，但可根据需要拆除红外滤镜。

高质量（HQ）摄像头，M12 卡口（左）和 C/CS 卡口（右）

最后，有全局快门相机（发布于 2023 年）。GS 相机没有红外版本（但如有需要，也可拆除红外滤镜）。

全局快门相机

注意

树莓派摄像头模块同所有搭载了 CSI 接口的树莓派计算机均兼容——即仅与树莓派 400 和旧版 Zero 不兼容。

卷帘快门还是全局快门？

大多数数码相机，包括我们的摄像头模块，都使用 卷帘快门：它们会对正在捕捉的图像逐行扫描，然后输出结果。你可能已经注意到，在某些情况下，这可能会造成失真效果；如果你曾经拍摄过旋转的螺旋桨叶片，你可能已经注意到了，场景在晃动，看起来不像一个正在旋转的物体。螺旋桨叶片有足够的时间在相机扫过和观察场景的瞬间内变更位置。

全局快门 不会这样做，就像我们的全局快门摄像头模块上的那个。它能一次性捕捉场景中每个像素的光线，因此你拍摄的螺旋桨叶片照片不会遇到相同的失真问题。

这有什么用呢？高速移动的物体，比如那些螺旋桨叶片，现在很容易捕捉到；我们还可以同步多台摄像头在同一时刻拍摄照片。这有很多好处，比如在捕捉立体图像时最小化失真。（如果左眼出现的运动尚未出现在右眼中，人类大脑会感到困惑。）树莓派全局快门摄像头还可以在较短的曝光时间内运行——在足够的光线下可达到 30 微秒。而卷帘快门相机则无法做到，这使全局快门在高速摄影中非常有用。

注意

全局快门摄像头的图像传感器带有 6.3 毫米对角线活动感应区域，与树莓派的高质量（HQ）摄像头大小类似。但像素更大，可以收集更多光线。大像素尺寸和低像素计数在机器视觉应用中非常有好处；传感器产生的像素越多，实时处理图像就越困难。为了解决这个问题，许多应用程序会缩小和裁剪图像。使用全局快门摄像头和适当的镜头放大倍率，是无必要的，因为较低的分辨率和较大的像素尺寸意味着可以原生捕捉图像。

安装树莓派摄像头

警告

摄像头对静电极为敏感。在处理 PCB 之前请先将自己接地。如果没有接地带，水龙头和类似物品大概也行。

连接摄像头

将柔性电缆插入到树莓派上标有摄像头的接口中，该接口位于以太网口和 HDMI 口间。电缆必须以银色接触面朝向 HDMI 口插入。要打开接口，请将接口顶部的标签向上拉，然后朝向以太网口。柔性电缆应牢固插入接口中，注意不要使电缆以太锐角度弯曲。要关闭接口，请将接口顶部部分向 HDMI 口推下，同时保持线缆位置固定。

我们制作了一个视频来演示连接摄像头的过程。虽然视频中显示的是旧的树莓派 1 上的旧款摄像头，但对于所有摄像头模块，原理都是相通的。

根据型号而定，摄像头可能会附带一小片半透明蓝色塑料薄膜覆盖镜头。这只是为了在邮寄给你时保护镜头，使用时需将它轻轻剥下来。

注意

高质量（HQ）摄像头上推荐的 6mm、16mm 镜头有其他的文档说明。

准备软件

在继续之前，我们建议，确保你的内核、GPU 固件和应用程序都是最新版本。请参照保持操作系统最新的说明。

然后，请按照 rpicam-apps 的相关设置说明以及 Picamera2 Python 库。

硬件规格

注意

有证据表明，摄像头模块 3 可能会以 CSI 时钟速率的谐波发射射频干扰。这种射频干扰的范围可能会干扰 GPS L1 频率（1575 MHz）。请参阅 Github 上的主题以获取详细信息和提出的解决方法。

机械图纸

可用的机械图纸;

• 摄像头模块 2 PDF

• 摄像头模块 3 PDF

• 摄像头模块 3 宽幅 PDF

• 摄像头模块 3 STEP 文件

• HQ 摄像头模块（CS 卡口版本）PDF

  • CS 接口 PDF

• HQ 摄像头模块（M12 卡口版本）PDF

• GS 摄像头模块 PDF

注意

摄像头模块 3 的主板尺寸和安装孔位置与摄像头模块 2 相同。但是，由于传感器模块尺寸和位置的变化，它与树莓派 Zero Case 的摄像头外壳不具备机械兼容性。

框图

树莓派 CSI 摄像头连接器的原理图。

其他可用的原理图;

• 摄像头模块 2 PDF

• 摄像头模块 3 PDF

• HQ 摄像头模块 PDF

摄像头滤镜

摄像头模块 3 和 HQ 和 GS 摄像头的一些传输特性可用。

注意

这些图表可用作 PDF 文件。

摄像头模块 3

摄像头模块 3 是基于 IMX708 开发的，具有以下光谱灵敏度特性。

HQ 摄像头

树莓派 HQ 摄像头没有红外切除滤镜。

GS 摄像头

树莓派 GS 摄像头，无红外切换滤镜。

HQ 和 GS 摄像头

HQ 和 GS 相机使用 Hoya CM500 红外滤光片。其透射特性如下图所示。

拆卸滤光片

注意

该程序适用于 HQ 和 GS 相机。

警告

该步骤无法逆转：连接滤镜的粘合剂在被揭起并更换后将无法维持，而红外滤镜厚约 1.1 mm，在被移除时可能会破裂。移除它将失去保修。然而，对一些用户来说，移除滤镜是可取的。

高质量摄像头和全局快门摄像头都包含一个红外滤镜，用于降低摄像头对红外光的敏感性。它使得户外照片看起来更自然。然而，可以通过移除此滤镜来增强一些自然摄影；天空、植物和水的颜色可能会受到其移除的影响。在受红外光照明的地方，摄像头也可以在没有滤镜的情况下用于夜视。

警告

在继续之前，请阅读所有步骤并决定是否愿意使保修失效。除非你确定愿意放弃保修，否则不要继续。

要摘掉滤镜：

• 请在干净无尘的环境中工作，因为传感器将暴露在空气中。

• 在主电路板底部的两个 1.5 mm 六角锁定键上拧下。小心不要让触点圈滚开。在外壳和 PCB 之间有一层略带粘性的触点片，需要用一点力气才能分开。

• 将板子抬起并放在特别干净的表面上。确保传感器不会触及表面。

• 你可以尝试一些方法来溶解粘合剂，例如少量异丙醇、加热（~20-30 °C）。

• 将镜头底座转过来，使其朝上，并放在桌子上。

• 使用钢笔盖或类似软塑料物品，仅在玻璃与铝相连接的边缘处施加压力，以最大程度降低破坏滤镜的风险。胶水会断裂，滤镜会从镜头座上脱落。

• 鉴于更换镜头会暴露传感器，此时你可以固定一个透明滤镜（例如 OHP 塑料）以最小化灰尘进入传感器腔的机会。

• 将主机壳体放回电路板上。务必将壳体与仍留在电路板上的触点圈重新对齐。

• 尼龙触点圈可防止电路板受损；先放置这个触点圈。接着，放置钢触点圈，可防止尼龙触点圈受损。

• 将两个六角锁紧键拧紧。只要触点圈按正确顺序安装，就不需要拧得太紧。

注意

可能很难或压根没法通过将滤镜粘回原位来使设备恢复正常光学相机的功能。

推荐镜头

以下镜头建议与我们的 HQ 和 GS 摄像头一起使用。

注意

虽然 HQ 摄像头有 C/CS 和 M12 卡口版本，但 GS 摄像头仅有 C/CS 安装版本。

C/CS 镜头

我们推荐两款镜头，一款 6mm 广角镜头和一款 16mm 远摄镜头。这些镜头应该可以在你最近的授权经销商处购买到。

M12 卡口

我们推荐由高嘉光电制造的三款镜头。这些镜头应该可以从你最近的授权经销商那里购买。

同步捕获

HQ 摄像头和全局快门摄像头都支持同步捕获。利用 XVS 引脚（垂直同步）使一台摄像头在启动帧捕获时脉冲。另一台摄像头可以监听此同步脉冲，并在另一台摄像头同时捕获帧。

使用 HQ 摄像头

为了正确运行，两个摄像头都需要在 XVS 线上提供 1.65V 的上拉电压，这是通过树莓派上的 3.3V 和 GND 引脚通过电位分压器创建的。

从两个 10kΩ 电阻器到 3.3V 和地（通过有效源阻抗为 5kΩ 制造 1.65V）创建一个电位分压器。这可以连接到任一款树莓派。

将每个 HQ 摄像头板的 GND 和 XVS 测试点焊接在一起。