USB 固件编译

开始编译

固件编译简明指南

注意事项

• 网络: 确保上位机(树莓派等)已联网
• 登录方式: 必须使用 SSH 通过网络登录，禁用串口
• 输入法: 保持键盘为英文半角模式

---

SSH登录与用户切换

使用 MobaXterm、PuTTY 等工具 SSH 登录上位机。

切换用户：

• 普通系统(树莓派官方系统等)
  禁止使用 root,需切换到普通用户：

  su <用户名>

• FLY上位机(FlyOS-FAST系统)
  仅支持 root 用户登录(密码： mellow)

---

固件编译操作指南

在 Klipper 固件配置界面中仅支持键盘操作,无法使用鼠标。

按键	功能
↑ / ↓	上下移动光标，选择菜单项
Enter / 空格	确认选择、勾选选项或进入子菜单
ESC	返回上一级菜单
Q	退出配置界面
Y	退出时，如有提示则按 Y 保存配置

开始固件编译

下面介绍如何编译固件：

1. 连接到 SSH，输入下面的命令并按 Enter：

   cd ~/klipper && rm -rf ~/klipper/.config && rm -rf ~/klipper/out && make menuconfig

   其中，rm -rf ~/klipper/.config && rm -rf ~/klipper/out 用于清除之前的编译配置与固件； make menuconfig 用于打开 Klipper 固件配置界面。

2. 按照下方顺序逐项设置，每完成一项再继续下一项。

   1启用 Enable extra low-level configuration options

   (Top)

   Klipper Firmware Configuration

   [*] Enable extra low-level configuration options

   [Space/Enter] Toggle/enter[?] Help[/] Search

   [Q] Quit (prompts for save)[Esc] Leave menu

   2Micro-controller Architecture 选择 Raspberry Pi RP2040/RP235x

   (Top)

   Klipper Firmware Configuration

   [*] Enable extra low-level configuration options

   Micro-controller Architecture (Raspberry Pi RP2040/RP235x) --->

   [Space/Enter] Toggle/enter[?] Help[/] Search

   [Q] Quit (prompts for save)[Esc] Leave menu

   3Processor model 选择 rp2040

   (Top)

   Klipper Firmware Configuration

   [*] Enable extra low-level configuration options

   Micro-controller Architecture (Raspberry Pi RP2040/RP235x) --->

   Processor model (rp2040) --->

   [Space/Enter] Toggle/enter[?] Help[/] Search

   [Q] Quit (prompts for save)[Esc] Leave menu

   4Bootloader offset 选择 16KiB bootloader

   (Top)

   Klipper Firmware Configuration

   [*] Enable extra low-level configuration options

   Micro-controller Architecture (Raspberry Pi RP2040/RP235x) --->

   Processor model (rp2040) --->

   Bootloader offset (16KiB bootloader) --->

   [Space/Enter] Toggle/enter[?] Help[/] Search

   [Q] Quit (prompts for save)[Esc] Leave menu

   5Communication Interface 选择 USBSERIAL

   (Top)

   Klipper Firmware Configuration

   [*] Enable extra low-level configuration options

   Micro-controller Architecture (Raspberry Pi RP2040/RP235x) --->

   Processor model (rp2040) --->

   Bootloader offset (16KiB bootloader) --->

   Communication Interface (USBSERIAL) --->

   [Space/Enter] Toggle/enter[?] Help[/] Search

   [Q] Quit (prompts for save)[Esc] Leave menu

   6启用 Optimize stepper code for 'step on both edges'

   (Top)

   Klipper Firmware Configuration

   [*] Enable extra low-level configuration options

   Micro-controller Architecture (Raspberry Pi RP2040/RP235x) --->

   Processor model (rp2040) --->

   Bootloader offset (16KiB bootloader) --->

   Communication Interface (USBSERIAL) --->

   USB ids --->

   [*] Optimize stepper code for 'step on both edges'

   [Space/Enter] Toggle/enter[?] Help[/] Search

   [Q] Quit (prompts for save)[Esc] Leave menu

   7按 Q 键退出配置界面

   (Top)

   Klipper Firmware Configuration

   [*] Enable extra low-level configuration options

   Micro-controller Architecture (Raspberry Pi RP2040/RP235x) --->

   Processor model (rp2040) --->

   Bootloader offset (16KiB bootloader) --->

   Communication Interface (USBSERIAL) --->

   USB ids --->

   [*] Optimize stepper code for 'step on both edges'

   () GPIO pins to set at micro-controller startup

   [Space/Enter] Toggle/enter[?] Help[/] Search

   [Q] Quit (prompts for save)[Esc] Leave menu

   GPIO 状态说明：GPIO state at micro-controller startup 是 FLYOS-Klipper 的扩展功能，本页面仅作说明。普通固件编译请保持 Not set，无需进入或修改；如需了解全部 GPIO 启动状态，请查看 GPIO 启动状态使用说明。

   8出现 Save configuration 时按 Y 保存配置

   Quit

   Save configuration?

   (Y)es(N)o(C)ancel

3. 完成上方最后两个步骤，按 Q 退出配置界面，再按 Y 保存配置。

4. 返回命令行后输入下面的命令并按 Enter 开始编译：

   make -j4

   root@flyos-11e5f8 ~/klipper # make -j4

   Compiling out/src/rp2040/bootrom.o

   Compiling out/src/rp2040/usbserial.o

   Compiling out/src/generic/usb_cdc.o

   Compiling out/src/rp2040/chipid.o

   Compiling out/src/rp2040/hard_pwm.o

   Compiling out/src/rp2040/spi.o

   Compiling out/src/rp2040/i2c.o

   Preprocessing out/src/rp2040/rpxxxx_link.ld

   Building out/compile_time_request.o

   Version: XXXX

   Linking out/klipper.elf

   Creating bin file out/klipper.bin

   终端末尾出现 Linking out/klipper.elf 和 Creating bin file out/klipper.bin，即表示编译成功。 实际编译时，部分 Compiling 行和 Version 会随 Klipper 与系统版本变化。

确认是否进入烧录模式

断电操作

开始前请完全关闭打印机并断开电源供应。不要在通电状态下插拔线束、整理线序或触碰端子。

• 使用Type-C数据线将主板连接至上位机后,双击reset按钮,此时主板上会有LED灯闪烁。

警告

• 如果没有LED灯闪烁,请重新烧录Katapult固件:烧录Katapult固件
• 如果没有LED灯闪烁,请在烧录完Katapult固件后,再执行下一步

烧录固件

适用范围

本流程用于通过 USB Katapult 烧录刚刚编译好的 Klipper 固件，只需要操作当前页面所选的固件类型。

1. 搜索 Katapult USB ID

非 FLY 官方上位机需要先安装 Katapult：

查看 Katapult 安装方法

执行以下命令：

ls /dev/serial/by-id/*

识别结果

搜索结果中应出现包含 usb-katapult_ 的完整路径，例如：

/dev/serial/by-id/usb-katapult_<芯片型号>_<设备ID>-if00

每块下位机的 ID 都不同，请复制自己设备显示的完整路径。

2. 烧录 Klipper 固件

替换设备 ID

请将命令中的 <Katapult USB ID> 替换为上一步搜索到的完整路径，不要保留尖括号。

• 普通 Linux 上位机
• FLYOS / FLY 上位机

~/klippy-env/bin/python ~/katapult/scripts/flashtool.py -d <Katapult USB ID>

python3 ~/katapult/scripts/flashtool.py -d <Katapult USB ID>

3. 确认烧录结果

命令执行完成且没有出现报错，即表示固件已经写入。烧录完成后，Katapult USB ID 会消失；请按照当前产品页面后续步骤重新上电并搜索对应的 Klipper ID。

Loading...

重刷固件

以后需要更新已经刷入的 Klipper 固件时，不需要重复烧录 Katapult。请先在当前页面重新编译目标固件，再根据设备当前状态选择一种方法。

方法一：使用命令自动进入 Katapult

如果当前能搜索到 usb-Klipper_ ID，可以让 Klipper 自动请求下位机进入 Katapult 并完成重刷：

cd ~/klipper && make flash FLASH_DEVICE=<usb-Klipper ID>

请将 <usb-Klipper ID> 替换为 ls /dev/serial/by-id/* 搜索到的完整路径。命令默认使用 ~/klipper/out/klipper.bin。

方法二：双击 RST 后手动烧录

如果当前没有 usb-Klipper_ ID，或方法一执行失败，请使用以下方法：

断电操作

开始前请完全关闭打印机并断开电源供应。不要在通电状态下插拔 USB 线或触碰端子。

1. 断电后重新连接 Type-C 数据线。

2. 快速双击下位机的 RST 按键，等待状态灯闪烁，表示已进入 Katapult。

3. 搜索 Katapult USB ID：

   ls /dev/serial/by-id/*

4. 使用搜索到的 usb-katapult_ ID 执行烧录：

   普通 Linux 上位机：

   ~/klippy-env/bin/python ~/katapult/scripts/flashtool.py -d <Katapult USB ID> -f ~/klipper/out/klipper.bin

   FLYOS / FLY 上位机：

   python3 ~/katapult/scripts/flashtool.py -d <Katapult USB ID> -f ~/klipper/out/klipper.bin

注意

重刷时必须使用与当前连接方式对应的固件。USB 桥接 CAN 固件虽然最终通过 CAN 工作，但 Katapult 重刷仍然使用 USB ID 和 USB 烧录命令。

烧录后搜索 USB ID

固件烧录完成并给主板重新上电后，请继续搜索 USB ID。

查看 USB ID 获取方法