2.2 树莓派上位机环境纯净部署与 KlipperScreen 触摸屏配置

专栏导读：为了保证上位机系统的长期稳定、安全以及后续组件的平滑升级，强烈不建议使用旧版 FluiddPI / MainsailOS 镜像（官方已停止积极维护且版本容易死锁）。本教程采用树莓派官方纯净轻量版系统（Raspberry Pi OS Lite 64-bit），配合 Klipper 生态神器 KIAUH 进行纯净一键部署。 本文特别整理了实际搭建中极其容易踩坑的 存储卡硬件报错、tty 权限缺失、KlipperScreen 屏幕黑屏/显示异常 等经典问题的解决方案，适合存留并发布至个人技术网站作为保姆级手册。

🛠️ 准备工作

硬件需求

• 上位机：树莓派（Raspberry Pi 3B / 4B / 5 等）。
• MicroSD 卡（关键避坑）：强烈建议选择 高耐用度（High Endurance / 监控级）16GB 或 32GB 以上 MicroSD 卡（如闪迪白紫卡）。普通 TF 卡在 Klipper 频繁写入日志和升级时极易产生 Bad Sector 损坏，导致系统变为“只读”或抛出段错误。
• 显示设备：带有 DSI/HDMI/SPI 接口的实体触控屏幕（如 4.3 寸 / 5 寸 / 7 寸触控屏）。
• 辅助工具：电脑读卡器、网线或稳定的 Wi-Fi 环境。

软件工具

• 烧录软件：树莓派官方烧录工具 Raspberry Pi Imager。
• 📥 树莓派官方烧录工具官方下载地址：https://www.raspberrypi.com/software/
• 终端工具：PuTTY、Termius、MobaXterm 或 Windows 内置命令提示符。

第一步：烧录纯净系统与预配置网络（防坏卡与配置遗漏）

打开烧录软件，按照以下步骤完成系统选择与预配置：

1. 选择系统

1. 将 MicroSD 卡接入电脑，打开 Raspberry Pi Imager。
2. 在“设备（Device）”中选择你的树莓派型号。
3. 在“操作系统（Operating System）”中依次选择： Raspberry Pi OS (Other) ➡️ Raspberry Pi OS Lite (64-bit) (此系统无桌面 GUI，占用资源极低，响应速度最快)。

2. 预配置小齿轮（关键步骤）

在点击烧录前，软件右下角会弹出一个小齿轮（编辑设置）图标（或按快捷键 Ctrl + Shift + X）。点击进入并勾选以下参数：

• 设置主机名：自定义（如 voron 或 fluiddpi）。
• 开启 SSH 服务：勾选“启用 SSH”，并选择“使用密码认证”。
• 设置用户名和密码：建议用户名填 pi，并设置好你的登录密码。
• 配置无线局域网 (Wi-Fi)：勾选并准确输入你家里的 Wi-Fi 名称（SSID）和密码，国家/地区选择 CN。
• 语言和时区：时区选择 Asia/Shanghai。

⚠️ 避坑提醒 1：远离废弃镜像 切勿直接烧录几年前的 FluiddPI 整合包！因为其内部 Linux 内核和软件源过于陈旧，后续升级 Klipper 或安装 KlipperScreen 时会爆出大量的依赖冲突。

⚠️ 避坑提醒 2：闪存卡隐藏坏道避坑 如果旧卡在执行升级或编译时报出 -bash: ... Input/output error 或 Segmentation fault（段错误），说明 Linux 内核已检测到坏道并强行将卡挂载为 read-only（只读）。遇到此情况请直接换用高耐用度新卡重刷，不要在坏线上浪费时间。

3. 开始烧录

确认配置无误后点击“保存”并开始烧录。等待校验完成后拔出内存卡，插入树莓派并通电开机。

第二步：通过 SSH 远程连接树莓派

1. 等待树莓派首次开机（约 1~2 分钟，系统会自动完成分区扩展并连接 Wi-Fi）。
2. 在路由器后台查找树莓派的 IP 地址，或在电脑终端使用 ping voron.local 查找。
3. 打开 SSH 终端工具，执行连接命令：

ssh pi@<你的树莓派IP>

4. 输入预配置的小齿轮密码，成功登录黑框命令行界面。

第三步：部署并运行 KIAUH 脚本

KIAUH（Klipper Installation And Update Helper）是管理 Klipper 生态的瑞士军刀。在 SSH 终端中依次输入以下命令：

# 1. 更新系统软件源并安装 git 工具
sudo apt-get update && sudo apt-get install git -y

# 2. 克隆 KIAUH 官方源码仓库
git clone https://github.com/th33xitus/kiauh.git

# 3. 进入 kiauh 目录
cd kiauh

# 4. 运行 KIAUH 脚本
./kiauh.sh

运行后，终端会进入纯文本控制菜单界面。

第四步：使用 KIAUH 一键部署核心组件与 KlipperScreen

在 KIAUH 的 [ Installation Menu ] 中，我们需要依次安装 Klipper 核心三件套及屏幕驱动：

╔═══════════════════════════════════════════════════════╗
║ ~~~~~~~~~~~~~~~ [ Installation Menu ] ~~~~~~~~~~~~~~~ ║
╟───────────────────────────┬───────────────────────────╢
║ Firmware & API:           │ Touchscreen GUI:          ║
║  1) [Klipper]             │  7) [KlipperScreen]       ║
║  2) [Moonraker]           │                           ║
║ Webinterface:             │ Webcam Streamer:          ║
║  3) [Mainsail]            │  8) [Crowsnest]           ║
║  4) [Fluidd]              │                           ║
╚═══════════════════════════════════════════════════════╝

1. 安装 Klipper (核心固件)

• 输入 1 并回车。选择 Python 3.x 环境，安装实例数量保持默认 1。

• ⚠️ 核心避坑提醒（极其重要）： 在安装过程中，屏幕若弹出红框或提示： Add user 'pi' to group(s) tty now? (Y/n) 必须输入 Y 并回车！ 这会赋予用户串口通信与硬件设备的访问权限。如果误选了 n，后续主板刷写固件会提示无权限访问 /dev/ttyUSB* 或 /dev/ttyAMA0。

2. 安装 Moonraker (API 服务)

• 返回菜单后输入 2 并回车。
• 保持默认参数一路回车即可。

3. 安装 Fluidd (网页控制端)

• 输入 4 并回车选择安装 Fluidd。
• 当提示是否下载推荐的宏配置文件（Recommended macros）时，输入 Y 或按回车接受。这会自动生成标准的配置文件模板（包含 G28、PAUSE、RESUME 等通用宏）。

4. 安装 KlipperScreen (实体触控屏 GUI)

• 如果你的 Voron 打印机配备了实体触控屏，输入 7 并回车选择安装 KlipperScreen。
• KIAUH 会自动拉取 X11 图形环境、相关显卡驱动以及 KlipperScreen 依赖包。

第五步：实体屏幕 (KlipperScreen) 驱动硬件排坑与配置

安装完 KlipperScreen 后，不同类型的屏幕（DSI / HDMI / SPI）往往需要针对性地调整硬件驱动参数：

1. DSI 官方排线屏 / 常见 DSI 触控屏

• 物理连线：确保金手指方向正确插入树莓派的 DISPLAY 接口。
• 驱动设置：树莓派 OS Lite 默认开启了自动检测。如果开机显示屏无信号，编辑 /boot/firmware/config.txt（旧系统为 /boot/config.txt）：

sudo nano /boot/firmware/config.txt

确保包含以下配置或取消注释：

dtoverlay=vc4-kms-v3d

2. HDMI 触控屏（HDMI 显示 + USB 触控）

• 物理连线：需要连接 HDMI 视频线 + USB 触控信号线。
• 避坑要点： 如果画面超频或分辨率不对，需在 /boot/firmware/config.txt 尾部手动强制指定 HDMI 分辨率（如 800x480）：

hdmi_force_hotplug=1
hdmi_group=2
hdmi_mode=87
hdmi_cvt=800 480 60 6 0 0 0

3. SPI 小型屏（如 3.5 寸 GPIO 插拔屏）

• SPI 屏不走 X11 硬件加速，需先按照屏幕厂商提供的脚本安装 fbcp / fbtft 驱动，将 /dev/fb0 映射至 /dev/fb1，KIAUH 才会将 KlipperScreen 绘制到 SPI 屏上。

第六步：权限固化与开机服务验证

所有组件安装完毕后，必须完成以下闭环操作：

1. 退出 KIAUH 并重启系统

在 KIAUH 中输入 B 返回，输入 Q 退出。执行系统重启命令：

sudo reboot

⚠️ 为什么必须 reboot？ 在安装 Klipper 和 KlipperScreen 时，KIAUH 将用户 pi 加入了 tty、dialout、video 和 input 用户组。在 Linux 系统中，用户组权限修改必须在重启或重新登录后才能彻底生效。不重启直接操作会导致屏幕报 X11 permission denied 或主板无法通信。

2. 双端点亮验证

重启等待约 1~2 分钟：

1. 物理屏幕端：实体触控屏应当初始化完毕，显示 KlipperScreen 精美的图标交互界面。
2. 网页控制端：在电脑浏览器地址栏输入树莓派的 IP 地址，能够顺利点亮 Fluidd 控制面板。

💡 核心踩坑与故障排查速查表

为了方便将本教程整理收录，下表总结了搭建第一部分时最常见的报错与应对方案：

(第二部分：Voron 2.4 树莓派上位机环境纯净部署与 KlipperScreen 屏幕驱动避坑全指南完成。第三部分我们将进入下位机必趣八爪鱼主板的固件编译、刷写与双链路握手通信配置。)