1. 从树莓派到BTT Pi：为什么我们需要新的上位机选择

最近在折腾我的Voron 2.4，想给它换个“大脑”。之前一直用的是树莓派4B，稳定是稳定，但这两年价格和供货问题，懂的都懂。正好看到BigTreeTech（BTT）出了个叫BTT Pi的上位机，核心是他们的CB1计算模块，价格亲民，而且官方说对Klipper支持很好。这让我动了心思：是继续守着老旧的树莓派，还是试试这个新玩意儿？

所谓“上位机”，在3D打印的语境里，就是运行Klipper固件主机软件（Klipper Host）的那台小型计算机。它负责解析G代码、进行运动规划、与主板（下位机）通信，并提供一个Web界面（如Mainsail、Fluidd）供我们操作。树莓派之所以成为过去几年的“黄金标准”，是因为其社区支持强大、教程遍地、性能对于Klipper来说绰绰有余。但随着供应链变化和更多国产硬件的崛起，像BTT Pi（CB1）、Orange Pi、Radxa Zero这类替代品开始进入玩家的视野。

BTT Pi，或者说其核心的CB1模块，本质上是一个对标树莓派CM4的、基于全志H616芯片的计算模块。它最大的吸引力在于其“开箱即用”的Klipper生态整合。BTT作为知名的3D打印配件厂商，直接提供了预装Klipper相关系统的镜像，并且其GPIO引脚定义与树莓派高度兼容，这意味着很多为树莓派设计的扩展板（包括BTT自家的主板）可能无需修改就能用。这对于想快速搭建或升级一套Klipper系统，又不想在系统配置上耗费太多精力的用户来说，是个非常诱人的选择。

那么，玩BTT Pi到底是在玩什么？我认为核心是三点：一是体验一种更具性价比和可获得性的硬件方案；二是验证其在Klipper实际应用中的稳定性和性能表现；三是学习在非树莓派架构上部署和调试Klipper的通用技能，这能让你在未来面对任何ARM开发板时都更有底气。接下来，我就结合自己把玩BTT Pi的过程，从开箱到稳定运行，把其中的关键步骤、踩过的坑以及一些心得分享给大家。

2. BTT Pi开箱与硬件初体验：对比树莓派的得与失

拿到BTT Pi套件，通常包含CB1计算模块、一个承载CB1的底板（类似于树莓派的IO板），以及散热片、外壳等配件。第一印象是做工不错，接口布局清晰。底板通常会提供标准的40针GPIO排针（与树莓派兼容）、千兆网口、HDMI、USB接口等。核心的CB1模块通过板对板连接器扣在底板上，这种模块化设计和树莓派CM4如出一辙，有利于产品迭代和成本控制。

从硬件参数上看，全志H616是一颗四核Cortex-A53处理器，主频最高1.5GHz或1.8GHz（取决于具体版本），集成Mali-G31 MP2 GPU。对比树莓派4B的博通BCM2711（四核Cortex-A72），单核性能上A72架构更老但性能更强，而A53则更偏向能效。但对于运行Klipper主机服务、OctoPrint或Mainsail这类应用来说，两者的性能都是过剩的。更关键的指标其实是I/O性能、稳定性和软件生态。

硬件接口的异同与注意事项：

1. GPIO兼容性：这是最大的利好。BTT Pi底板的40针引脚排列在物理尺寸和顺序上与树莓派基本一致。这意味着绝大多数为树莓派设计的3D打印主板（如BTT的Manta系列、Octopus，甚至一些简单的继电器控制板）可以直接插上使用。但是，必须核对引脚功能定义！虽然物理位置一样，但某些引脚的复用功能（如硬件PWM、特定的串口）可能在不同芯片上由不同的引脚实现。BTT通常会提供详细的引脚映射图，在配置Klipper的[mcu]部分时，务必以官方文档为准，而不是想当然地套用树莓派的引脚号（BCM编号）。
2. USB与网络：BTT Pi底板通常提供2-4个USB 2.0接口和一个千兆网口。对于3D打印来说，USB 2.0连接主板（如使用USB串口）完全足够。千兆网口提供了比树莓派4B更稳定的有线连接选项（树莓派4B也是千兆）。无线Wi-Fi通常由板载的AP6212模块提供，支持2.4G/5G双频，实测连接稳定性尚可，但对于追求极致稳定和低延迟的打印控制，我仍然强烈推荐使用网线。
3. 电源输入：底板通常采用Type-C接口供电，要求5V/3A以上。这里有一个重要细节：有些底板的Type-C口仅用于供电，不支持数据传输。如果你习惯用USB线连接电脑进行SSH或烧录系统，可能需要确认你的底板是否有额外的Micro-USB或USB-B口用于OTG功能，或者需要通过网络来配置。我使用的版本就是纯供电Type-C，初始设置必须依靠网线或预先在镜像中配置好Wi-Fi。
4. 散热与功耗：H616的发热和功耗控制得不错，标配的散热片在运行Klipper和Web界面时基本能应付，机身微温。相比树莓派4B在负载下的“热情”，BTT Pi的发热表现反而更好一些。整体功耗也略低于树莓派4B，对长期开机更友好。

注意：在购买或使用前，一定要找到你所持有的具体型号的CB1底板原理图或用户手册。不同批次或不同供应商的底板，其USB电路、音频编码芯片、按钮等可能有细微差别，这些差别可能会影响系统镜像的兼容性。

3. 系统镜像选择与烧录：避开第一个大坑

给BTT Pi安装系统，第一步是选择正确的镜像。这里和树莓派用Raspberry Pi OS（原Raspbian）不同，BTT为CB1提供了专门优化的系统镜像。通常有两个主流选择：

1. BTT官方预装Klipper的镜像：这是最省事的入门方式。BigTreeTech会在其GitHub仓库或下载站提供基于Armbian或Debian定制、并预装了Klipper、Moonraker、Mainsail/Fluidd的完整镜像。下载后解压得到一个.img文件。对于新手，我强烈推荐从这个开始，它能帮你跳过最繁琐的底层系统配置和Klipper编译环境搭建。
2. 纯净的Armbian/Debian镜像：如果你喜欢从零开始，享受完全掌控的乐趣，或者官方镜像的版本较旧，你可以选择安装由Armbian社区或BTT提供的纯净Linux镜像。然后像在树莓派上一样，通过KIAUH（Klipper Installation And Update Helper）脚本或手动方式安装Klipper全家桶。这给了你最大的灵活性，但也需要更多的Linux操作知识。

烧录工具与关键步骤：烧录工具推荐使用Raspberry Pi Imager（它支持多种板卡）或BalenaEtcher。步骤和烧录树莓派镜像几乎一样：

• 将MicroSD卡插入读卡器。
• 打开烧录软件，选择下载好的.img文件。
• 选择目标SD卡，点击“烧录”。

这里有一个至关重要的坑点：DTB（设备树覆盖）的正确选择。对于树莓派，烧录软件或镜像内部会自动配置好硬件。但对于BTT Pi这类板卡，系统启动时需要加载一个正确的DTB文件来告诉内核这块底板的具体硬件信息（如GPIO分配、USB控制器、网卡等）。如果DTB不对，可能会导致无法启动、网卡不识别、USB失灵等问题。

BTT官方预装镜像通常已经内置了正确的配置。但如果你使用通用Armbian镜像，则需要在烧录后，编辑SD卡boot分区下的extlinux/extlinux.conf或uEnv.txt文件，指定正确的DTB文件路径。例如，你可能需要将一行类似FDT /dtb/allwinner/sun50i-h616-btt-cb1.dtb的配置取消注释或修改为对应的文件名。这个正确的DTB文件名需要你去查阅该Armbian版本对BTT CB1的支持说明。

我的建议是，首次尝试务必使用BTT官方预装镜像。成功启动并确认所有硬件（网络、USB）工作正常后，再考虑尝试其他自定义方案。烧录完成后，将SD卡插入BTT Pi底板，接通电源，看到指示灯有规律地闪烁，就说明系统开始启动了。

4. 网络配置与首次登录：没有屏幕如何操作

和树莓派一样，我们大多数时候通过SSH远程操作BTT Pi。如果你使用了官方预装Klipper的镜像，它通常已经开启了SSH服务，并可能预设了主机名（如bttpi或cb1）。你需要知道它的IP地址才能连接。

方法一：有线网络（推荐）这是最可靠的方法。用网线将BTT Pi连接到你的路由器。然后登录到路由器的管理界面（通常地址是192.168.1.1或192.168.0.1），在“已连接设备”或“DHCP客户端列表”里，查找主机名包含bttpi、cb1或orangepi（因为底层可能是Armbian）的设备，记下其IP地址。

方法二：无线网络（需预先配置）如果镜像支持，并且你在烧录后、启动前有机会修改SD卡中的配置文件，可以预先配置Wi-Fi。对于基于Armbian的系统，通常可以在boot分区下找到一个叫armbian-firstrun.txt或wpa_supplicant.conf的文件（具体因镜像而异）。你可以参照树莓派的方法，在boot分区创建一个wpa_supplicant.conf文件，填入你的Wi-Fi SSID和密码。但并非所有镜像都支持这种方式，最稳妥的还是先通过网线连接。

方法三：使用mDNS（如果支持）如果系统安装了Avahi服务（树莓派OS默认就有），你可以直接使用主机名加.local后缀进行访问。例如，在终端里尝试ssh pi@bttpi.local（用户可能是pi，也可能是root或btt，具体看镜像说明）。但BTT的镜像不一定默认开启这个服务。

获取到IP地址后（假设是192.168.1.100），打开你的SSH客户端（如Windows下的PuTTY，或Mac/Linux下的终端），输入：ssh btt@192.168.1.100默认密码通常是btt或者1234，首次登录会强制要求修改密码，请按照提示操作。

登录成功后，你就进入了BTT Pi的命令行世界。首先可以运行sudo armbian-config命令（如果镜像基于Armbian），这是一个非常方便的系统配置工具，可以在这里直观地设置网络、时区、语言、安装软件等。对于Klipper预装镜像，可能已经集成了类似的配置脚本，或者你可以直接开始配置Klipper本身。

5. Klipper服务配置与主板连接：让机器动起来

登录系统后，如果是官方预装镜像，Klipper（klipper）、Moonraker（moonraker）和Web界面（如Mainsail，服务名可能是mainsail）应该已经作为系统服务安装并默认启动了。你可以使用以下命令检查状态：sudo systemctl status klippersudo systemctl status moonrakersudo systemctl status mainsail(或fluidd)

如果状态是active (running)，那么核心服务都在运行。接下来是最关键的一步：配置Klipper与你的3D打印机主板通信。

步骤1：确定主板连接方式与串口路径BTT Pi连接打印机主板主要有两种方式：

• USB连接：最通用。用USB线连接BTT Pi的USB口和主板的USB口。
• 直接UART连接：性能更优，延迟更低。利用BTT Pi底板的GPIO引脚中的UART引脚（通常是TX、RX、GND），直接连接到主板上的对应UART引脚。这需要你的主板支持（例如很多32位主板都有专门的UART接口），并且需要正确配置。

首先确定你的连接方式。如果是USB连接，需要找到对应的串口设备文件。在BTT Pi上执行：ls /dev/serial/by-id/*如果连接正常，你会看到一个类似/dev/serial/by-id/usb-Klipper_stm32f103xe_38FFDA505243555943461157-if00的路径。这个路径是固定的，与USB端口物理位置无关，强烈建议在配置中使用这个by-id路径，而不是/dev/ttyUSB0，因为后者可能在重启后发生变化。

如果是GPIO UART连接，设备名通常是/dev/ttyS1或/dev/ttyAMA0，具体取决于芯片和DTB配置。你需要查阅BTT Pi的引脚图，确认哪个GPIO被映射为UART，并在后续编译固件时指定正确的引脚。

步骤2：配置Klipper的printer.cfg文件Klipper的主配置文件是~/printer_data/config/printer.cfg（这是较新Klipper的路径，旧版可能在~/klipper_config）。你需要编辑这个文件。nano ~/printer_data/config/printer.cfg

首先，在[mcu]部分指定你的主板：

[mcu] # 如果是USB连接，使用 by-id 路径 serial: /dev/serial/by-id/usb-Klipper_stm32f103xe_38FFDA505243555943461157-if00 # 如果是GPIO UART连接，可能是 # serial: /dev/ttyS1 # 设置正确的波特率，通常Klipper固件默认是250000 baud: 250000

然后，你需要根据你的打印机结构（CoreXY、i3、三角洲等）、使用的步进电机驱动、热床、热端型号，来配置其余的[stepper_x],[stepper_y],[extruder],[heater_bed],[thermistor]等章节。这部分配置与使用树莓派时完全一样，因为Klipper固件运行在主板上，上位机只是发送指令。

一个BTT Pi相关的特殊配置：GPIO控制如果你想用BTT Pi的GPIO来控制一个继电器（比如控制打印机总电源）、一个LED灯，或者读取一个按钮，你需要在printer.cfg中配置[output_pin]或[gcode_button]等。这时，引脚名称不能使用树莓派的BCM编号（如GPIO17），而必须使用BTT Pi（全志H616）的引脚名。例如，物理引脚第11号（对应树莓派GPIO17）在BTT Pi上可能被命名为PC7。 你需要查阅BTT提供的引脚映射表。配置示例如下：

[output_pin my_led] pin: PC7 pwm: True value: 0.5 shutdown_value: 0

配置完成后，保存文件（Ctrl+X，然后按Y，再按Enter）。

步骤3：重启Klipper服务并验证运行sudo systemctl restart klipper重启Klipper服务。然后通过Web界面（在浏览器输入BTT Pi的IP地址）或使用命令~/klippy-env/bin/python ~/klipper/scripts/whconsole.py -m来查看Klipper的串口通信状态。如果看到mcu显示为已连接或ready，恭喜你，上位机与下位机的通信链路已经建立。

6. Web界面安装与优化：Mainsail/Fluidd的部署

如果你使用的是官方预装镜像，Web界面很可能已经装好了。如果没有，或者你想自己安装/更换，过程也非常简单。目前最流行的两个Klipper Web界面是Mainsail和Fluidd，它们轻量、快速、功能强大。

通过KIAUH脚本安装（最推荐）KIAUH是一个自动化安装和更新Klipper生态组件的脚本，极大简化了流程。

1. 登录BTT Pi SSH。
2. 依次执行以下命令：

   cd ~ git clone https://github.com/th33xitus/kiauh.git ./kiauh/kiauh.sh

3. 这会启动一个文本图形界面。使用方向键和回车键操作。
4. 在主菜单，选择安装[4] Mainsail或[5] Fluidd。
5. 脚本会自动下载、安装并配置Nginx作为反向代理。安装完成后，它会告诉你访问地址，通常是http://<你的BTT Pi IP>。

手动安装（了解原理）手动安装能让你更清楚每个组件的作用：

1. 安装Nginx：sudo apt install nginx
2. 下载Web界面文件：以Mainsail为例，你可以下载其最新发行版，解压到Nginx的网页目录，例如/var/www/html/mainsail。
3. 配置Nginx：编辑Nginx站点配置文件（如/etc/nginx/sites-available/mainsail），设置根目录为刚才解压的路径，并配置反向代理，将/websocket等路径转发给Moonraker服务（默认监听7125端口）。
4. 启用配置并重启Nginx：sudo ln -s /etc/nginx/sites-available/mainsail /etc/nginx/sites-enabled/，然后sudo systemctl restart nginx。

无论哪种方式，安装完成后，在浏览器输入BTT Pi的IP地址，你应该就能看到熟悉的Klipper Web操作界面了。通过这个界面，你可以上传G代码、控制打印机、查看摄像头、调整配置等。

性能优化小贴士：

• 使用有线网络：无线网络可能受干扰，导致Web界面操作延迟或视频流卡顿。对于打印控制，有线网络是必须的。
• 摄像头优化：如果你连接了USB摄像头，高分辨率高帧率会占用大量CPU和带宽。在printer.cfg的[camera]部分，可以适当降低resolution和framerate。例如设置为1280x720和15fps，能在画质和流畅度间取得很好平衡。
• 日志管理：Klipper和Moonraker的日志默认会不断增长。可以配置日志轮转（logrotate）或定期清理，避免占满存储空间。可以编辑/etc/logrotate.d/下的相关配置文件。

7. 常见问题排查与性能调优指南

即使按照步骤操作，也可能会遇到一些问题。这里汇总一些我在使用BTT Pi过程中遇到或可能遇到的典型问题及解决方法。

问题1：系统无法启动，指示灯异常。

• 可能原因：镜像烧录不正确；SD卡损坏或不兼容；电源不足（要求5V/3A）；DTB配置错误。
• 排查：
  1. 重新使用Raspberry Pi Imager（选择“验证写入”选项）或BalenaEtcher烧录镜像，确保过程无报错。
  2. 尝试更换一张品牌可靠、速度Class10以上的MicroSD卡。
  3. 使用万用表测量Type-C电源口的电压，确保在5V左右，且电源能提供3A电流。劣质电源或过长的USB线可能导致电压跌落。
  4. 如果是自选Armbian镜像，确认extlinux.conf中FDT指向的DTB文件确实存在于/boot/dtb/目录下，且型号匹配。

问题2：SSH无法连接，Ping不通IP。

• 可能原因：网络连接问题；IP地址不对；SSH服务未启动；防火墙阻止。
• 排查：
  1. 确认网线已插好，路由器对应端口指示灯亮。
  2. 在路由器后台仔细查找设备，主机名可能不是bttpi。
  3. 如果有显示器，可以接上HDMI查看系统启动后的IP地址信息。
  4. 登录路由器，查看是否给BTT Pi分配了IP。尝试设置静态IP（DHCP保留）以避免IP变化。
  5. 对于预装镜像，SSH通常是默认开启的。如果手动安装的系统，可能需要用sudo systemctl enable ssh --now来启用。

问题3：Klipper无法连接MCU（主板）。

• 可能原因：串口路径错误；主板未刷写Klipper固件或固件不匹配；波特率错误；USB线或UART线有问题。
• 排查：
  1. 执行ls /dev/serial/by-id/*，确认设备存在。如果列表为空，检查USB线是否可靠，主板是否上电。
  2. 确认主板已正确刷入为它编译的Klipper固件。使用lsusb命令可以查看连接的USB设备，如果能识别到主板（如STMicroelectronics STM32 Virtual ComPort），说明USB通信底层是通的。
  3. 检查printer.cfg中[mcu]下的serial:路径和baud:速率是否与主板固件设置一致（默认250000）。
  4. 查看Klipper日志获取更详细错误信息：sudo journalctl -u klipper -f。

问题4：Web界面（Mainsail/Fluidd）可以打开，但显示“Klipper未连接”或“Moonraker未连接”。

• 可能原因：Moonraker服务未运行；Moonraker配置错误；防火墙/权限问题。
• 排查：
  1. 检查Moonraker服务状态：sudo systemctl status moonraker。确保它是active (running)。
  2. 检查Moonraker配置文件~/printer_data/config/moonraker.conf，确保[server]部分的host设置为0.0.0.0（允许所有IP访问），并且没有不正确的IP过滤规则。
  3. 查看Moonraker日志：sudo journalctl -u moonraker -f，看是否有错误提示。
  4. 确保BTT Pi的防火墙（如果启用）放行了80（HTTP）、443（HTTPS，如果启用）和7125（Moonraker API）端口。

性能调优建议：

• 关闭不必要的服务：如果只是作为打印服务器，可以关闭图形界面（如果安装了）、蓝牙等不需要的服务。使用sudo systemctl disable <服务名>来禁用它们开机自启。
• 监控资源使用：使用htop命令可以实时查看CPU、内存使用情况。在打印复杂模型或同时进行视频流时，观察系统负载。
• SD卡性能：系统的读写性能受限于SD卡。如果条件允许，可以考虑使用USB SSD硬盘启动（如果底板和系统支持），这将极大提升系统响应速度和日志写入性能。不过对于Klipper应用，一张好的SD卡已经足够。

8. 进阶玩法：从CB1到更广阔的ARM世界

成功让BTT Pi驱动起你的打印机后，它的潜力远不止于此。这台小设备本质上是一台完整的ARM Linux计算机，我们可以用它做很多有趣的事情。

1. 作为家庭轻量级服务器：

• 打印服务器+：除了Klipper，你还可以安装OctoPrint作为另一个打印管理前端（虽然Klipper+Mainsail组合更现代）。或者安装Obico（原Spaghetti Detective）实现AI打印失败检测和远程监控。
• 网络存储（NAS）：通过USB连接一个移动硬盘，安装Samba服务，就能变成一个简单的家庭文件共享中心，存放你的3D模型库。
• Home Assistant节点：如果你玩智能家居，可以将其作为Home Assistant的一个从节点，用来控制连接到GPIO上的传感器或继电器，实现打印室灯光、排气扇的自动化控制。

2. GPIO的创造性应用：BTT Pi的40针GPIO是它的宝藏。通过Python脚本（使用RPi.GPIO库的兼容层，或libgpiod）或Klipper的[gcode_shell_command]功能，你可以：

• 连接环境传感器：如DHT11/DHT22温湿度传感器，监控打印环境，并在湿度过高时通过Web界面报警。
• 控制照明：连接一个RGB LED灯带，编写G代码脚本，让打印机在开始打印时自动开灯，完成后关灯。
• 安全监控：连接一个门磁开关或PIR运动传感器，当有人打开打印机外壳或靠近时，自动暂停打印并发送通知。

3. 编译自己的软件和内核：如果你对Linux有更深兴趣，可以在BTT Pi上搭建交叉编译环境，或者直接在上面编译软件。例如，你可以尝试为它编译最新版本的内核，启用更多的驱动模块或优化性能。也可以从源码编译OpenCV，结合USB摄像头实现更复杂的图像处理应用（虽然对于H616的算力来说比较吃力）。

4. 探索其他ARM开发板：玩转BTT Pi的经验是通用的。无论是Orange Pi、Radxa Rock，还是其他任何一款流行的ARM开发板，部署Klipper的流程都大同小异：找到合适的系统镜像、配置网络、安装Klipper全家桶、根据具体板子的引脚定义调整配置。掌握了在BTT Pi上排错的方法（如查看日志、检查服务状态、理解硬件配置），你就能轻松地将Klipper移植到任何类似的设备上。

回过头看，从树莓派切换到BTT Pi的过程，更像是一次技能的迁移和验证。它没有想象中那么难，核心的Klipper知识是完全通用的。差异点主要集中在前期的硬件适配和系统准备阶段。对于大多数用户，选择官方预装镜像能避开90%的坑。而成功运行后，其稳定性和性能在日常打印中与树莓派并无感知差异，但成本却低了不少。