1. 项目概述：为树莓派计算模块连接外部设备
如果你手头有一块树莓派计算模块，想把它塞进自己设计的电路板里，让它驱动摄像头、屏幕，或者连接各种传感器和控制器，那么“如何正确地把这些外部设备连上去”就是第一个要啃的硬骨头。这不仅仅是物理上把线焊对那么简单，更关键的是如何告诉系统：“嘿，我在这里接了个新玩意儿，你得用正确的方式跟它打招呼。”这个过程，我们称之为“外设接线与软件使能”。
计算模块和普通的树莓派单板电脑最大的不同在于，它去掉了所有现成的接口（比如USB、网口、HDMI），只把核心的处理器（SoC）和内存封装在一个类似内存条（DDR2 SODIMM）的模块上。这意味着你获得了极大的灵活性，可以把GPIO、摄像头接口（CSI）、显示接口（DSI）等引脚，按照你项目最需要的方式，引到你自己设计的主板上。但随之而来的责任是，你必须自己为模块供电（通常是3.3V和1.8V），并且亲自定义每一根引脚的用途。
这篇指南，就是基于我多年折腾嵌入式硬件和树莓派生态的经验，带你一步步走通从硬件连接到软件配置的全过程。我们会聚焦于最核心的两个环节：硬件上如何安全、正确地连接设备（以I2C和SPI设备为例），以及软件上如何通过“设备树”这个强大的配置工具，让Linux内核识别并驱动你的设备。无论你是正在设计产品的硬件工程师，还是热衷于定制化项目的开发者，理解这套流程都能让你摆脱对预封装板的依赖，真正释放计算模块的潜力。
2. 核心概念解析：启动流程与设备树
在动手接线之前，我们必须先理解树莓派（或者说其核心的博通BCM283x系列芯片）是如何启动的，以及“设备树”在其中扮演的关键角色。这是让软件识别硬件的基石，很多配置错误导致的“设备找不到”问题，根源都在于此。
2.1 BCM283x的三段式启动
树莓派的SoC内部包含一个VideoCore GPU和一个或多个Arm CPU核心。有趣的是，每次上电，最先醒来干活的是GPU内部的一个DSP核心，而不是我们通常认为的Arm CPU。这个设计决定了其独特的启动顺序：
第一阶段：GPU Boot ROM。芯片一上电，GPU的DSP核心就从内部一块很小的只读存储器中开始执行代码。这段代码的唯一任务就是去寻找一个“第二阶段引导程序”。它会检查SD卡（或计算模块上的eMMC）的启动分区，寻找一个名为
bootcode.bin的文件。如果找不到，它会进入USB启动模式，等待主机通过USB口给它发送引导程序。第二阶段：bootcode.bin。这个程序由树莓派基金会提供，它的职责非常关键：初始化系统内存。对于计算模块，就是配置好LPDDR2 SDRAM的接口。没有它，后续所有程序都无处安身。完成内存初始化后，它会加载并执行主GPU固件
start.elf。第三阶段：start.elf与Linux内核启动。
start.elf是真正的“大管家”。它首先会读取一个名为dt-blob.bin的特殊文件，这个文件专门用来告诉GPU如何设置那些由它管理的GPIO引脚初始状态（比如摄像头模块的I2C引脚）。接着，它解析config.txt这个我们熟悉的配置文件，根据其中的设置加载对应的Arm设备树文件，并合并任何指定的设备树“叠加层”。最后，它启动Arm子系统，并将组装好的完整设备树数据传递给即将启动的Linux内核。
实操心得：很多新手会忽略
dt-blob.bin的存在，因为对于标准树莓派板卡，它通常使用内置的默认配置。但在计算模块项目中，尤其是当你需要GPU早期就控制某些引脚（例如，在Linux驱动加载前，确保某个复位引脚处于高电平）时，定制dt-blob.bin是必须的。否则，引脚可能处于不确定的浮空状态，导致外设行为异常。
2.2 设备树：硬件的“地图”
Linux设备树是一种描述硬件配置的数据结构。你可以把它想象成一张交给Linux内核的“地图”，上面详细标注了：“在SOC的哪个位置（内存地址），有一个什么设备（比如I2C控制器1），这个设备的哪些引脚（比如GPIO44、45）被配置成了什么功能（I2C1_SDA, I2C1_SCL），以及这个总线上挂载了哪个具体芯片（地址为0x68的PCF8523 RTC）”。
对于树莓派，设备树文件主要分两类：
- 基础设备树：针对不同型号的树莓派预编译好的
.dtb文件。例如，计算模块3对应的是bcm2710-rpi-cm3.dtb。它描述了该型号板卡上“默认就有”的硬件，比如SD卡控制器。 - 设备树叠加层：这是我们自定义硬件时主要打交道的东西。它是一个“补丁”文件，作用是在基础设备树之上，添加或修改节点，来描述我们额外连接的硬件。叠加层文件通常以
.dtbo结尾。
为什么强烈推荐使用叠加层，而不是直接修改基础设备树？假设你为你的计算模块主板定制了一个完整的.dtb文件。那么每次树莓派官方更新内核，基础设备树可能有细微变动，你就必须手动合并这些变更，重新编译你的定制设备树，并制作一个包含它的特殊系统镜像。这个过程繁琐且容易出错。而使用叠加层，你只需要维护一个描述“我额外加了什么”的小文件。系统启动时，引导程序会自动将这个叠加层合并到标准的基础设备树上。只要叠加层编写规范，即使基础设备树升级，它通常也能无缝工作。这大大提升了项目的可维护性和与标准系统镜像的兼容性。
2.3 关键工具：设备树编译器
设备树源文件是文本格式的.dts文件，人类可读。但需要编译成二进制的.dtb或.dtbo文件，机器才能识别。这个编译工具就是dtc。
在树莓派系统上，安装它非常简单：
sudo apt update sudo apt install device-tree-compiler编译命令的基本格式是：
# 编译基础设备树 .dts 到 .dtb dtc -I dts -O dtb -o 输出文件.dtb 输入文件.dts # 编译叠加层（需要 -@ 参数处理外部引用） dtc -@ -I dts -O dtb -o 输出文件.dtbo 输入文件.dts3. 硬件接线与引脚管理
计算模块将BCM283x SoC的绝大多数引脚都引了出来，主要分为三组GPIO Bank：
- Bank 0: 28个引脚
- Bank 1: 18个引脚
- Bank 2: 8个引脚
总共54个GPIO引脚，但它们并非生而平等。Bank 0和Bank 1是我们可以安全使用的通用引脚，它们可以被软件配置为输入、输出，或者复用为各种外设功能，如I2C、SPI、PWM、UART等。而Bank 2是禁区，它专门用于控制计算模块的核心功能：eMMC闪存通信、HDMI热插拔检测以及ACT LED/USB启动控制。误用Bank 2的引脚会导致计算模块无法启动或存储功能失效。
3.1 引脚功能复用与电压
每个GPIO引脚除了基本的数字输入输出外，通常有多个“复用功能”。例如，GPIO18除了可以做普通的GPIO18，还可以被设置为PWM0输出、SPI1的CE1片选，或者用于PCM时钟。在设备树中配置一个设备时，本质上就是在声明“我将GPIOxx用于其ALTx功能”。
另一个关键点是引脚电压。计算模块的GPIO引脚工作电压通常是3.3V，并且不是5V耐受。连接任何外部设备时，务必确认其逻辑电平是3.3V兼容的。如果设备是5V电平，必须使用电平转换器，否则有损坏SoC的风险。
3.2 使用pinctrl工具验证配置
在软件配置好后，如何确认GPIO引脚的状态真的如我们所愿？系统提供了一个强大的命令行工具pinctrl。它可以列出所有GPIO的当前功能、电平、上下拉电阻状态。
# 查看所有GPIO状态 pinctrl # 查看特定GPIO，例如GPIO44 pinctrl get 44在调试设备树叠加层时，pinctrl是你的第一道防线。如果发现某个引脚的功能（ALT值）不是你期望的I2C或SPI，那么几乎可以断定是设备树配置没有生效。
4. 实战案例一：连接I2C实时时钟
让我们通过一个具体例子，把理论变成实践。我们将一个NXP PCF8523实时时钟模块连接到计算模块IO板的Bank 1引脚上。
4.1 硬件连接
你需要准备以下硬件：
- 树莓派计算模块（CM1/CM3/CM4）及对应的IO底板。
- PCF8523 RTC模块（通常是一个带电池的小板）。
- 杜邦线若干。
接线关系如下表所示：
| RTC模块引脚 | 计算模块IO板引脚 (Bank 1) | 功能说明 |
|---|---|---|
| VCC | 3.3V | 电源正极 |
| GND | GND | 电源地 |
| SDA | GPIO44 | I2C1数据线 |
| SCL | GPIO45 | I2C1时钟线 |
注意事项：确保IO板已为计算模块提供稳定的3.3V和1.8V电源。连接时最好在系统断电状态下进行。I2C总线通常需要上拉电阻，但很多RTC模块和树莓派SoC内部已经包含了上拉电阻。如果总线过长或挂载设备多，可能需要额外添加2.2kΩ - 10kΩ的外部上拉电阻到3.3V。
4.2 软件配置：定制 dt-blob.bin
如前所述，dt-blob.bin用于GPU早期配置引脚。虽然Linux驱动加载时会重新配置，但为了确保上电后I2C总线就处于正确状态（特别是使能内部上拉电阻，防止总线浮空），我们最好配置它。
获取并编辑模板。树莓派官方提供了一个最小化配置模板
minimal-cm-dt-blob.dts。你需要找到并下载它，或者直接在系统中创建。将其复制到/boot/firmware/目录下。sudo cp minimal-cm-dt-blob.dts /boot/firmware/ sudo nano /boot/firmware/minimal-cm-dt-blob.dts修改GPIO44和GPIO45的定义。在文件中找到对应
pin@p44和pin@p45的节点。默认它们可能被设置为输入且无上拉或下拉。我们需要将其修改为I2C1功能，并使能上拉电阻。// 找到并修改以下部分 pin@p44 { function = "i2c1"; termination = "pull_up"; }; // SDA1 pin@p45 { function = "i2c1"; termination = "pull_up"; }; // SCL1termination = "pull_up";这一行至关重要，它启用了SoC内部的物理上拉电阻，为I2C总线提供了稳定的高电平。编译生成 dt-blob.bin。
sudo dtc -I dts -O dtb -o /boot/firmware/dt-blob.bin /boot/firmware/minimal-cm-dt-blob.dts
4.3 软件配置：创建设备树叠加层
接下来，我们需要创建一个设备树叠加层，告诉Linux内核：“在I2C1总线上，地址0x68的地方，有一个兼容nxp,pcf8523的RTC设备。”
创建叠加层源文件。例如，创建
example1-overlay.dts。/dts-v1/; /plugin/; / { compatible = "brcm,bcm2835"; // 与基础设备树兼容 fragment@0 { target = <&i2c1>; // 目标：i2c1控制器节点 __overlay__ { #address-cells = <1>; #size-cells = <0>; status = "okay"; // 启用该控制器 pcf8523: rtc@68 { // 在地址0x68添加一个节点 compatible = "nxp,pcf8523"; reg = <0x68>; // I2C设备地址 status = "okay"; }; }; }; };编译叠加层。注意编译叠加层必须使用
-@参数。sudo dtc -@ -I dts -O dtb -o /boot/firmware/overlays/example1.dtbo /boot/firmware/example1-overlay.dts启用叠加层。编辑
/boot/firmware/config.txt文件，添加一行：dtoverlay=example1重启并验证。执行
sudo reboot。重启后，运行以下命令检查：# 查看I2C总线是否检测到设备 sudo i2cdetect -y 1 # 你应该能看到地址68处显示为“UU”，表示已被驱动占用。 # 查看RTC设备 ls /dev/rtc* # 应该会出现 /dev/rtc0 或 /dev/rtc1 # 使用硬件时钟工具读取时间 sudo hwclock -r如果
hwclock能正确读出时间，恭喜你，I2C RTC配置成功！
5. 实战案例二：连接SPI以太网控制器
现在我们来连接一个更复杂的设备：基于ENC28J60芯片的SPI接口以太网控制器。这个例子展示了如何使用树莓派OS中已有的预制叠加层，这在实际项目中非常常见。
5.1 硬件连接
ENC28J60模块通常需要连接以下引脚：
| ENC28J60模块引脚 | 计算模块IO板引脚 (Bank 0) | 功能说明 |
|---|---|---|
| VCC | 3.3V | 电源 |
| GND | GND | 地 |
| SI (MOSI) | GPIO10 (SPI0_MOSI) | SPI主设备输出，从设备输入 |
| SO (MISO) | GPIO9 (SPI0_MISO) | SPI主设备输入，从设备输出 |
| SCK | GPIO11 (SPI0_SCLK) | SPI时钟 |
| CS | GPIO8 (SPI0_CE0_N) | 片选0，低电平有效 |
| INT | GPIO25 | 中断引脚，低电平有效 |
5.2 软件配置：使用预制叠加层
树莓派OS已经内置了enc28j60的叠加层，这省去了我们手动编写.dts文件的步骤。我们只需要在config.txt中启用它，并确保引脚定义匹配我们的硬件连接。
检查叠加层文件。首先确认叠加层文件存在：
ls /boot/firmware/overlays/enc28j60.dtbo编辑 config.txt。在
/boot/firmware/config.txt中添加一行。这里有个关键点：预制叠加层默认可能使用不同的中断引脚。我们需要通过参数指定使用GPIO25。dtoverlay=enc28j60,int_pin=25有些版本的叠加层可能还需要指定SPI总线速率，可以加上
speed=20000000（20MHz）参数。无需修改 dt-blob.bin。对于SPI引脚，其默认状态通常就是输入，且Linux驱动加载时会正确配置为ALT0功能。因此，在这个例子中，我们可以不修改
dt-blob.bin。但如果你希望上电瞬间SPI引脚就处于确定状态，也可以像I2C例子一样去配置它们。重启并验证。
sudo reboot重启后，使用以下命令检查：
# 查看网络接口，应该能看到除了lo（本地环回）和可能的wlan0外，还有一个eth1（或eth0，取决于主以太网是否存在） ifconfig -a # 尝试ping一个外网地址，测试网络连通性 ping -c 4 8.8.8.8 # 使用pinctrl验证GPIO8-11的功能是否已变为ALT0 (SPI) pinctrl | grep -E "GPIO(8|9|10|11)"如果
ifconfig看到了新的以太网接口，并且ping命令成功，说明SPI以太网控制器已成功驱动。
6. 设备树调试技巧实录
配置过程很少一帆风顺。当设备没有按预期出现时，系统化的调试至关重要。
6.1 检查最终生效的设备树
Linux内核看到的设备树是基础设备树与所有叠加层合并后的结果。我们可以从/proc/device-tree这个虚拟文件系统中导出完整的树状结构来检查。
# 将当前运行的设备树导出为可读的.dts文件 sudo dtc -I fs -O dts -o /tmp/full.dts /proc/device-tree # 查看文件，搜索你的设备节点，比如“i2c1”或“spi0” nano /tmp/full.dts在这个文件里，你可以检查i2c1或spi0节点下的status是否是“okay”，下面是否挂载了你定义的子设备，reg（地址）属性是否正确。
6.2 查看内核启动日志
设备树信息会在内核启动时打印。使用dmesg命令并配合grep过滤是常用方法。
# 查看所有关于设备树的信息 dmesg | grep -i device-tree # 查看所有关于I2C的信息 dmesg | grep -i i2c # 查看所有关于SPI的信息 dmesg | grep -i spi # 查看特定驱动的探测信息，例如RTC dmesg | grep -i rtc如果驱动加载失败，这里通常会给出错误原因，比如“探测失败”、“未找到设备”或“地址无应答”。
6.3 启用更详细的GPU日志
如果问题出现在早期启动阶段（比如dt-blob.bin相关），可以查看GPU的日志。
sudo vclog --msg此外，在config.txt中添加dtdebug=1可以启用更详细的设备树调试信息。
6.4 常见问题排查表
| 现象 | 可能原因 | 排查步骤 |
|---|---|---|
i2cdetect看不到设备 | 1. 物理连接错误（线松、接反） 2. I2C总线未使能（status != “okay”） 3. 设备地址错误 4. 电源问题 | 1. 用万用表检查SDA/SCL电压（应有~3.3V，且上拉正常）。 2. 检查 /tmp/full.dts中i2c1节点状态。3. 确认设备树中 reg = <0x68>地址正确（PCF8523通常是0x68）。4. 测量设备VCC电压。 |
| SPI设备无响应 | 1. 片选（CS）引脚错误或未生效 2. SPI模式不匹配（CPOL, CPHA） 3. 时钟速率过高 | 1. 用pinctrl确认CS引脚（如GPIO8）功能为ALT0。2. 查阅ENC28J60数据手册，确认其SPI模式，检查叠加层参数。 3. 在叠加层参数中尝试降低 speed值。 |
| 叠加层未加载 | 1.config.txt中dtoverlay拼写错误2. .dtbo文件未放在正确路径3. 叠加层编译错误 | 1. 检查config.txt行尾无多余空格。2. 确认 .dtbo文件在/boot/firmware/overlays/下。3. 用 dtc反编译.dtbo检查内容：dtc -I dtb -O dts -o test.dts example1.dtbo。 |
| 系统无法启动 | 1.dt-blob.bin配置错误导致关键引脚（如eMMC）功能被篡改2. 叠加层与基础设备树冲突 | 1. 移除/boot/firmware/dt-blob.bin文件，使用默认配置启动。2. 逐一注释掉 config.txt中的dtoverlay行，排查是哪个叠加层导致问题。 |
7. 进阶：从零开始设计计算模块主板
当你掌握了单个外设的连接与配置后，可能会萌生设计一块属于自己的计算模块主板的想法。这不仅仅是简单的连线，更是一个系统工程。
7.1 电源设计：稳定性的基石
计算模块至少需要3.3V和1.8V两路电源。核心电压（如CM4的Core电压）通常由模块上的PMIC管理，但IO电压需要你提供。
- 3.3V电源：用于GPIO、SD卡电平、大部分外设。电流需求取决于你连接的外设，通常需要能提供2A-3A的电流能力，并需要有良好的滤波（π型滤波电路）以抑制噪声。
- 1.8V电源：用于DDR内存、某些SOC内部电路。虽然电流不大，但对噪声非常敏感。必须使用低噪声的LDO或高性能DC-DC，并配合紧靠引脚放置的MLCC电容进行退耦。
踩坑经验：我曾在一个早期设计中，使用了开关频率噪声较大的DC-DC为1.8V供电，导致系统随机性死机。后来更换为高性能LDO并优化了PCB布局（电源路径尽量短且宽，地平面完整），问题才彻底解决。电源纹波是嵌入式系统稳定性的头号杀手。
7.2 引脚分配与信号完整性
54个GPIO引脚是宝贵的资源，需要合理规划。
- 功能分组：将相同总线的引脚（如SPI0的四个引脚：CE0, MISO, MOSI, SCLK）尽量安排在相邻位置，并在PCB布线时保持等长，以减少时序问题。
- 高速信号：对于CSI（摄像头）、DSI（显示）这类高速差分信号，布线要求极高。需要做阻抗控制（通常为100欧姆差分阻抗），走线等长，并远离噪声源（如电源、晶振）。
- 未使用引脚的处理：不建议悬空。最好通过一个电阻（如10kΩ）上拉或下拉到固定的电平（3.3V或GND），防止因静电或噪声导致意外触发。
7.3 创建完整的自定义设备树
对于产品化的主板，最终你可能需要创建一个集成了所有外设定义的完整设备树文件，而不是依赖多个叠加层。这能提供最干净、最确定的配置。
- 获取基础dts：从树莓派Linux内核源码中找到对应计算模块的基础
.dts文件（如bcm2711-rpi-cm4.dts）。 - 整合叠加层：将你为各个外设编写的叠加层内容，手动合并到这个基础dts文件的相应节点下（如
&i2c1,&spi0）。 - 定义板级特有信息：在设备树根节点下，你可以定义自己的板卡型号（
model）和兼容性列表（compatible）。 - 编译与测试：使用
dtc编译这个完整的.dts为.dtb，并在config.txt中用device_tree=指定它。彻底测试所有功能。
这个过程更复杂，但能带来更好的启动性能和配置的一致性。记得将你的自定义设备树文件纳入版本控制系统进行管理。
从理解启动流程和设备树的概念，到动手连接I2C和SPI设备，再到最后的系统调试和进阶设计，这条路径是掌握树莓派计算模块硬件定制的核心。它要求你同时具备硬件连接的细心和软件配置的逻辑性。最大的成就感莫过于看到自己连接和定义的设备，在ls /dev列表中如期出现，并稳定工作。这标志着你的项目从“电路连接”真正迈入了“系统集成”的阶段。当你下次再面对一个陌生的传感器或驱动器时，这套“硬件接线-设备树描述-驱动验证”的方法论，将成为你最可靠的工具。
