树莓派_开发指南

1 · 文档导读与阅读路径

树莓派不是一块「MCU 开发板」，它是一台完整的 Linux 计算机，外加一条 40 针的排针。这句话决定了本文所有章节的编排方式。

1.1 这份文档覆盖什么

本文覆盖树莓派官方产品线的开发全流程：从挑型号、选启动介质、烧录 Raspberry Pi OS，到 GPIO / I2C / SPI / UART 编程、设备树 Overlay、摄像头与显示、存储与备份、网络服务、功耗散热、Linux 内核编译，再到 RP2040 / RP2350 的 Pico SDK 开发，最后落到与 XTX 存储芯片协同的方案设计。

• 硬件层：五大产品系列、处理器 SoC、40-pin 排针、供电与散热。
• 系统层：启动链路、config.txt、raspi-config、包管理、systemd。
• 外设层：GPIO 三条软件栈、三条串行总线的使能与使用、Overlay 机制。
• 进阶层：libcamera、内核交叉编译、Pico SDK、容器化。
• 收尾层：与存储芯片协同、故障速查、五个附录。

1.2 不覆盖什么

树莓派生态太大，本文明确不写：Python 语法教学、Linux Shell 基础、通用 Qt / GTK 桌面开发、Kubernetes 集群，以及第三方发行版（Ubuntu Core、OpenWrt、LibreELEC）的专属配置。这些内容要么与树莓派无关，要么官方文档已经写得足够好。

1.3 事实来源与版本标注约定

树莓派官方文档迭代很快，本文以 raspberrypi.com/documentation 2026 年在线版本为准。凡是涉及具体数字（引脚号、频率、文件路径、命令参数）的地方，都在附录 A 标注了出处。三点提醒：

1.4 命令与代码的书写约定

• # 开头表示一行命令的解释说明，不是 root 提示符；命令行输入一律以 $ 开头表示普通用户、sudo 显式标注提权。
• 路径统一使用 Linux 正斜杠。<hostname>、<username> 这类尖括号是占位符，替换时不保留尖括号。
• 代码块里的行尾反斜杠续行符是可执行的，不是排版装饰。

1.5 MCU 工程师转树莓派最容易卡住的四件事

2 · 树莓派家族全景与选型

树莓派不是一个产品，而是五个形状完全不同、开发方式也完全不同的产品系列。第一步选错系列，后面怎么做都是徒劳。

2.1 五大系列怎么分

官方把产品划成五条线，分界线不是性能，而是形态与开发方式：旗舰单板（SBC）跑完整 Linux；键盘机把 SBC 塞进键盘壳；Zero 在最小体积里塞 Linux；Compute Module（CM）把 SBC 拆成 DDR2 SODIMM 或 100 pin 高密度连接器，交给客户画载板；Pico 则是完全另一条路 —— 它不跑 Linux。

来源：Raspberry Pi Documentation — Raspberry Pi computer hardware

2.2 旗舰单板系列：从 BCM2835 到 BCM2712

Model B 表示带以太网口，Model A 表示低成本缩小版 —— 没有网口、内存更小、USB 更少。这条命名规则从 Model B 一直沿用到 Pi 4。

2.3 键盘机 X00 系列

型号标识符形如 <X00>，其中 X 对应同代旗舰 SBC：Pi 400 就是 Pi 4 的键盘版。500+ 是这一代最特殊的 —— 板载 256 GB M.2 SSD，出厂预装系统，不再是 microSD。

2.4 Zero 系列：最小体积里的完整 Linux

Zero 全系 512 MB 内存、mini HDMI、2×micro-USB（一个供电一个接外设）、microSD，从 Zero v1.3 起都带 mini 22-pin 0.5 mm CSI 摄像头座。命名后缀这里最容易读错：

Zero 2 W 换用 RP3A0（四核 Cortex-A53 @ 1 GHz），性能比单核 1 GHz 的老 Zero 提升极大，价格几乎不变 —— 这是当前 Zero 系列唯一推荐的型号。

2.5 Compute Module 系列：量产产品的正确入口

CM 把 SBC 的核心部分拆出来，做成不带任何外设连接器的模块，由客户自己画载板来提供项目实际需要的接口。它支持工业温度范围、同一型号保证多年供货，是做量产产品的正确入口。

2.6 Pico 微控制器系列

Pico 跑不了 Linux，程序直接烧进片内 Flash，上电即运行。它是硬实时任务的答案：PIO（可编程 I/O）可以在不占用 CPU 的情况下精确模拟时序，这是 RP2040 / RP2350 最有辨识度的能力。

2.7 选型决策树

• 要接显示器、跑浏览器、NAS、AI 推理 → Pi 5（或键盘形态的 500）。
• 成本敏感、功能简单的数据采集网关 → Zero 2 W。
• 做产品的、要长期供货、要自画载板 → CM5（新设计首选）/ CM4（已量产项目）。
• 硬实时控制、电机驱动、自定义时序 → Pico 2（RP2350），必要时与 Pi 5 组成异构双芯片方案。
• 只是想体验桌面 Linux → Pi 400 / 500，键盘壳省掉一堆外设接线的麻烦。

2.8 EOL 与长期供货

2.9 和 STM32 / ESP32 怎么选

3 · 启动链路、启动介质与处理器

树莓派没有 BIOS。它靠 GPU 在 Arm CPU 之前读取一个纯文本文件 —— config.txt —— 来决定「怎么启动」。理解这条链路，是排查「黑屏、点不亮、卡彩虹屏」的前提。

3.1 七个阶段：从上电到 systemd

来源：Raspberry Pi Documentation — config.txt / Bootloader configuration

3.2 每个阶段具体在做什么

3.3 启动介质怎么选：microSD / USB / NVMe / 网络

树莓派必须有非易失存储介质作为 boot media。绝大多数机型从 microSD 启动，较新型号额外支持 USB 大容量存储、网络启动（PXE）、以及通过 PCIe 的 NVMe。

3.4 处理器血缘：从 BCM2835 到 RP2350

树莓派的处理器分成两条完全独立的血缘：BCM27xx 系列（跑 Linux，Broadcom 应用处理器）与 RP 系列（自研微控制器，RP2040 / RP2350），外加一颗为 Zero 2 W 定制的 RP3A0（BCM2837 家族的重新封装）。

3.5 BCM2712：Pi 5 的心脏

$ lscpu | grep Vulnerability | grep -v "Not affected"
Vulnerability Spec store bypass:      Mitigation; Speculative Store Bypass disabled via prctl
Vulnerability Spectre v1:             Mitigation; __user pointer sanitization
Vulnerability Spectre v2:             Mitigation; CSV2, BHB

来源：Raspberry Pi Documentation — Processors / IO controllers

3.6 RP1：为什么 Pi 5 的 GPIO 变了天

RP1 是树莓派自研的南桥芯片，通过 PCIe 挂在 BCM2712 下面，承担了 Pi 5 绝大部分对外 I/O：USB、以太网 MAC、SDIO（microSD 与 Wi-Fi）、GPIO 排针、CSI/DSI，以及那个 PCIe ×1 的 FFC 连接器。

4 · 40-pin GPIO 与硬件接口

树莓派最有用的东西，是沿着板子顶边那一排排针。它同时也是最容易把板子烧掉的地方 —— GPIO 是 3.3 V 电平，且不是 5 V 容忍。

4.1 排针的物理布局

从 Raspberry Pi 1 Model B+ 起的所有当前在售机型都用同一个 40 pin 排针，引脚间距 0.1 in（2.54 mm）。Zero / Zero W / Zero 2 W 上是空焊盘，没有针，需自己焊或用第三方针套件。

来源：Raspberry Pi Documentation — GPIO and the 40-pin header

4.2 三套编号：别再混淆 BCM 和 Board

$ pinout

4.3 电压与电流：三条不能碰的红线

• 电平是 3.3 V，且不是 5 V 容忍。输出高为 3.3 V，输入也只能承受 3.3 V。把 5 V 传感器的输出脚直接接到 GPIO 上会烧毁 SoC（Pi 4）或 RP1（Pi 5）。需要 5 V 通信时用电平转换器或分压。
• 3.3 V 和 5 V 电源脚的输出能力有限。排针上只有 2 个 5 V、2 个 3.3 V、8 个 GND 是固定功能，不能重新配置。
• 不要直接驱动感性/大电流负载。LED 必须串电阻；电机、继电器一定要走 H 桥或电机驱动板，不能直连 GPIO。

4.4 复用功能速查

4.5 供电规格：买错电源是最常见的「不稳定」来源

官方强调：推荐值要在插头侧测量，而不是在电源适配器侧；如果线材可拆卸，还要考虑线上的压降。

4.6 权限：新用户第一个要补的组

# 使用 GPIO 的前提：用户在 gpio 组里。默认用户默认具备，新建用户要手动加
$ sudo usermod -a -G gpio <username>

# 常用到的组还有这些
$ sudo usermod -a -G i2c,spi,dialout <username>

# 重新登录后才生效，验证一下
$ groups

5 · Raspberry Pi OS 与首次上电配置

把系统写进卡这件事官方只推荐一种方式：Raspberry Pi Imager。它不只是个写盘工具 —— 在离线阶段把主机名、用户、Wi-Fi、SSH 一次性配好，才是它的价值所在。

5.1 Imager 的五步流程

来源：Raspberry Pi Documentation — Getting started

5.2 Imager 的 App Options 与自定义源

Imager 左下角的齿轮（App Options）里藏着几个实用开关：

5.3 三个 OS 版本怎么选

5.4 无头配置：三个文件搞定

没有显示器、键盘、鼠标时，需要在已写好 OS 的启动分区（bootfs）里放两个文件：

# 1) 创建名为 ssh 的空文件（没有扩展名），开启 SSH
$ touch ssh

# 2) 创建 userconf.txt，内容只有一行：用户名:加密密码
#    加密串用下面的命令生成（不是明文的密码）
$ openssl passwd -6

# 3) 把两个文件放进 bootfs 分区根目录，安全弹出，插到板上通电

5.5 首次上电的桌面配置向导

如果你在 Imager 里跳过了 Customisation，或者用了预装 OS 的套件，上电后会进入配置向导。它的七步是：

• Welcome and Bluetooth：同时扫描蓝牙外设。欢迎窗口上显示的 IP 地址只有在走以太网时才有。
• Country：国家 / 语言 / 时区；可勾选强制用英文界面、美式键盘。
• User：设置管理员用户名与密码（规则同上，最长 31 字符）。
• Wireless network：从列表里选 Wi-Fi 并输密码，也可跳过。
• Default browser：Chromium 或 Firefox；可选卸载未选中的那个以省空间。
• Software update：联网时更新系统，可能长达半小时。
• Finish：确认后 Launch；若出现 Restart 则重启。

键盘不带鼠标时可以用 Tab 键在界面里前进；如果用蓝牙键鼠，配对用的 USB 蓝牙适配器要在开机前插好。

5.6 分区结构：Bookworm 之后路径变了

# 启动分区的新家（Bookworm 起）
/boot/firmware/config.txt      # GPU 早期固件读取的配置文件
/boot/firmware/cmdline.txt     # 内核命令行
/boot/firmware/overlays/       # 全部 Device Tree overlay（overlay_prefix 默认值）

# 很多老教程还写着 /boot/config.txt —— 在新系统里那是错的，改了不生效

# 查看当前生效的配置
$ vcgencmd get_config arm_freq
$ vcgencmd get_config int      # 所有非零整数配置项
$ vcgencmd get_config str      # 所有非空字符串配置项

5.7 系统与固件更新

# 常规系统与软件包更新
$ sudo apt update
$ sudo apt full-upgrade -y

# Pi 4 / Pi 5 的 EEPROM bootloader 更新（这一步和 apt 升级是两回事）
$ sudo rpi-eeprom-update
$ sudo rpi-eeprom-update -a

# 清理不再需要的包
$ sudo apt autoremove -y