前言

原创文章，转载引用务必注明链接，水平有限，如有疏漏，欢迎指正交流。
文章如有更新请访问 DFRobot 社区及 cnblogs 博客园，前者内容较全，后者排版及阅读体验更佳。

思兼的学用Klipper系列文章合集

朋友使用MKS Pi (以下简称 Pi) 自带的无线网卡体验很差，准备升级成我的无线网卡，因为第三方编译的驱动性能更好，怕他不会操作，所以让他把 Pi 寄给我，顺便制作了新版系统，称为 KlipperBoxOS for MKSPi/SKIPR 特供版，仅实装了部分必要的特性。

测试环境：

• MKSPi with 8G eMMC、RTL8188 无线网卡

本文涉及的知识：

• KlipperBoxOS 特供版下载及使用
• 使用 iperf3 测试无线网卡传输速率以及稳定性，分析 iperf3 数据
• 如何热备份系统镜像 (shrink-backup)

一、MKS Pi 难用的现状

1.1 原厂无线网卡性能拉跨

官方套餐里搭配的是 RTL8188 无线网卡，性能、稳定性堪忧，甚至到了不堪用的程度。我们对比下参数规格：

可见自带的无线网卡基本处于不可用的状态，虽然标准差小，但是传输速率就那么低，想大都没法子。

由此带来的就是更好的信号强度，更好的无线网兼容性，小尺寸无线网卡除非本身发热小 (如 MT7601u)，否则更容易过热掉速。

1.2 原厂操作系统老旧

原厂系统基于 Debian 10 (Codename Buster)，发布于 2019 年，已于 2024 年结束支持，预装 Klipper 全家桶老旧，且系统一团糟，没有 linux-headers 包，无法自行编译驱动。当前最新版系统基于 Debian 12 (Bookworm)，全部组件更新到 2025 年 5 月。

二、使用 KlipperBoxOS 特供版

2.1 下载地址

通过网盘分享的文件：mkspi_2025_5_3.img.xz
链接: https://pan.baidu.com/s/12meo1X60tmPO6PRejiJ3Rg?pwd=sjmk 提取码: sjmk
--来自百度网盘超级会员v6的分享

2.2 系统介绍

• KlipperBoxOS MKS 特供版系统，基于最新的 社区版 Makerbase Armbian (Debian 12)系统 制作，实装了部分必要的特性，如果想体验完整版 KlipperBoxOS 操作系统，可以购买思兼的 KlipperBox 上位机，小黄鱼搜索 sjqlwy 即可。
• 提升 Klippy 进程优先级至最高，绑定 CPU 核心运行（modified from https://github.com/Dids/klipper-priority-fix/ ）
• 预装最新版 Klipper 全家桶：Klipper、Moonraker、Fluidd、KlipperScreen、Crowsnest 等
• 内置 RTL8821CU、RTL8812BU 双频高速网卡驱动，即插即用
• 预装 linux-headers 包，方便编译驱动
• 默认启用 APT、Github、Pypi 国内镜像源，升级、下载组件更快
• 预装 9527 网页助手（方便配网）

2.3 安装系统

2.3.1 使用 microSD 卡启动

下载镜像并使用 USBImager 或 Etcher 烧录到 SD 卡，无需解压 img.xz 文件，等待烧录完成插入上位机启动即可

2.3.2 使用 eMMC 启动

1. 使用上述 SD 卡启动后，登录终端，输入如下命令安装到 eMMC 存储

sudo nand-sata-install
# 选择 Boot from eMMC - system on eMMC
# 文件系统可以选择 btrfs 或者 f2fs，针对闪存有优化

2. 拔出 SD 卡重启启动即可

3. 由于默认的 eMMC 存储只有 8GB，建议初始化 SD 卡后使用自动扩容脚本。跟思兼学用Klipper(35) mergerfs 助力 Klipper 上位机热插拔自动扩容与脱机打印 - 思兼 - 博客园

2.4 快速上手

1. 提前插上 USB 无线网卡（如果出现 USB 接口遮挡，可以自行购买 USB2 延长线），通电开机后，稍等片刻手机或者电脑可以搜索到名为 KlipperBox 的无线网络，点击连接（无需密码）。
2. 使用浏览器打开 192.168.10.1:9527 可以添加无线网络，如果没有显示想要的网络，可以将设备移近路由器后点击 刷新网络列表 。优先连接 5G 网络，信号强度、连接速度更好，但是穿墙性能低于 2.4GHz，根据情况选择。注意所有标点符号为英文半角标点。
3. 联网后（当然你也可以略过以上步骤使用有线网进行连接）， KlipperBox 无线热点会关闭，电脑浏览器可以先尝试打开 http://kbox.local 访问 Fluidd 网页控制界面，如果网络环境或者操作系统不支持导致无法打开此网页，可以从路由器中查看设备 IP 地址进行访问。也可以使用下载的 PingTools 或者Fing 等软件扫描设备 IP 地址。
4. 不建议从上位机中设置静态 IP 地址，以免出现冲突以及更换网络后无法联网。推荐使用 kbox.local 访问，或者从路由器中绑定设备 MAC 地址分配固定 IP。如果仍然需要设置静态IP，可以使用 nmcli 命令。
5. 想要更改网络，可以在新环境开机等待自动创建热点。或者在浏览器输入 IP:9527访问配网助手，其中 IP 为当前上位机的 IP 地址。

B站演示视频：咕咕机（GuguBot）使用 KlipperBox 的简单介绍

2.5 注意

• 默认用户名 pi，密码 52mxpi，可以使用 passwd 命令进行修改，注意输入时不会回显。root 密码同上。
• 为了节省系统资源提升以及 Klipper 运行稳定性，默认 KlipperScreen 彩色触摸屏界面禁止开机启动，可以在终端使用 sudo systemctl enable --now KlipperScreen 启用。
• 想要使用第三方摄像头，输入 lv 命令获取摄像头设备地址，复制后修改 crowsnest.cfg 对应字段
• 想要访问上位机默认需要在同一局域网下！

三、操作细节

3.1 网络带宽测试方式

• 使用 iperf3 测试 180s，距离路由器距离相同。

• 每次仅连接单一无线网卡。

• Android 上可以使用 Magic iPerf 创建无线热点后作为服务端。

iperf3 -c 192.168.0.3 --logfile iperf_result.log -t 180 -f M

下面对生成的数据进行分析：

# analyze_iperf.py
import sys
import statistics

if len(sys.argv) < 2:
    print("请提供要分析的文件名作为参数，例如：python3 xx.py iperf_result.log")
    sys.exit(1)

filename = sys.argv[1]
speeds = []
retransmissions = []
try:
    with open(filename, 'r') as file:
        for line in file:
            if '------' in line:
                break
            if 'MBytes/sec' in line:
                parts = line.split()
                try:
                    speed = float(parts[6])
                    speeds.append(speed)
                    retr = int(parts[7])
                    retransmissions.append(retr)
                except (ValueError, IndexError):
                    continue

    print("Download speeds:", speeds)
    print("Retransmissions:", retransmissions)

    if speeds:
        max_speed = max(speeds)
        min_speed = min(speeds)
        avg_speed = statistics.mean(speeds)
        stdev_speed = statistics.stdev(speeds)
        total_retr = sum(retransmissions)

        print(f"Maximum speed: {max_speed:.2f} MB/s")
        print(f"Minimum speed: {min_speed:.2f} MB/s")
        print(f"Average speed: {avg_speed:.2f} MB/s")
        print(f"Standard deviation: {stdev_speed:.2f} MB/s")
        print(f"Total retransmissions: {total_retr}")
    else:
        print("No valid speed data found.")

except FileNotFoundError:
    print(f"文件 {filename} 不存在，请检查文件名是否正确。")

3.2 备份系统镜像并压缩

部署好操作系统后，需要对系统进行备份，常用的方法包括 dd、再生龙、armbian-ddbr、dietpi-imager 等。本文介绍 shrink-backup 这个工具，其优点很多，包括：

• 支持热备份，备份当前运行的系统
• 支持增量备份
• 支持排除列表
• 支持恢复到不同文件系统，如 ext4-f2fs
• 支持 shrink: 缩小分区中的空闲空间，并在启动后自动扩容。使最终生成的文件大大减小。

注意：

1. 关于 shrink 操作，我们默认备份的系统镜像大小和原磁盘大小一致，但是其中包含大量空闲空间。我们希望生成的镜像不包括这些空闲空间，例如系统运行在 32G 的磁盘上，实际占用 5G，默认镜像就是 32G。shrink操作后，可以获得一个 5G 左右的镜像，可以烧录到 8G 的存储上。
2. 原始img镜像还需要二次压缩成 img.xz 文件，如 7G 的镜像压缩后为不到 2G 大小

3.2.1 使用方法：

此处演示将系统镜像备份到 NAS 存储中。由于支持排除列表，也可以将其他存储设备插入后挂载到 /mnt 目录下。

# 安装
sudo apt install cifs-utils
git clone https://github.com/UnconnectedBedna/shrink-backup

# 在 NAS 上创建备份目录并挂载
sudo mkdir /mnt/backup
sudo mount -t cifs //192.168.0.3/Backup /mnt/backup -o username=[user],password=[password]

# 生成系统镜像
## 需要把 /boot 分区也挂载
sudo mount /dev/mmcblk0p1 /boot/efi
sudo ~/shrink-backup/shrink-backup -tal /mnt/backup/kboxpro-brix-2025_3_25.img
## 必要时修改排除列表
nano exclude.txt /var/log

# 固件烧录到 sd
## 使用 USBimager/etcher 等工具

# 以下略过，未在 MKS 设备上测试
# 固件烧录到 emmc
sudo dd if=/mnt/backup/kboxpro-brix-2025_3_25.img of=/dev/mmcblk0 bs=4M status=progress
## 从本地烧录
sudo dd if=/ddbr/kboxpro-brix-2025_3_25.img of=/dev/mmcblk0 bs=4M status=progress