📚 课程目录第1章 Klipper固件开发环境搭建

1. Klipper固件开发环境搭建

任务说明

本案例目标是在Ubuntu系统上完成Klipper固件开发环境搭建：安装编译依赖、克隆Klipper源码、配置目标微控制器（以常见的STM32F103为例），并编译生成可烧录的bin固件文件。完成后你将获得一个可直接用于烧录的klipper.bin。

环境准备与依赖安装

以下操作在Ubuntu 20.04/22.04 LTS（x86_64）上验证通过。首先更新软件源并安装编译Klipper所需的依赖包：

sudo apt update
sudo apt install -y git make gcc-arm-none-eabi binutils-arm-none-eabi \
    libnewlib-arm-none-eabi python3 python3-pip python3-venv \
    libusb-1.0-0-dev build-essential

验证ARM交叉编译工具链是否安装成功：

arm-none-eabi-gcc --version

应输出类似 arm-none-eabi-gcc (15:10.3-2021.07-4) 10.3.1 20210621 的版本信息，说明工具链可用。

克隆Klipper源码

使用git克隆Klipper官方仓库，并进入源码目录：

git clone https://github.com/Klipper3d/klipper.git
cd klipper

配置并编译固件

Klipper使用menuconfig进行图形化配置。在源码根目录执行：

make menuconfig

在菜单中按以下参数设置（对应常见的STM32F103蓝色板）：

Micro-controller Architecture：选择 STMicroelectronics STM32
Processor model：选择 STM32F103
Bootloader offset：选择 28KiB bootloader（若使用其他引导程序请按实际选择）
Clock Reference：选择 8 MHz crystal
Communication interface：选择 USB (on PA11/PA12)
USB IDs：可使用默认值

保存并退出menuconfig后，执行编译：

make

编译过程需要1～3分钟。编译完成后，在源码根目录下会生成固件文件：

ls -l out/klipper.bin

预期输出示例：

-rw-rw-r-- 1 user user 50176 Jul 20 10:30 out/klipper.bin

该out/klipper.bin即为可烧录的固件文件。

验证方法

验证分为两个层面：

编译产物验证：确认out/klipper.bin文件存在且大小非零（通常约50KB左右）。若文件缺失或大小为0，说明编译失败，需检查menuconfig配置或依赖安装。
固件烧录验证（可选）：将bin文件通过ST-Link或串口ISP烧录至STM32F103芯片。烧录后连接USB至主机，执行lsusb应能看到Klipper USB设备（默认VID:PID为1d50:614e），或通过dmesg | tail查看内核识别到的USB串口设备（通常为/dev/ttyACM0）。

判定标准：编译步骤成功生成out/klipper.bin即视为本案例目标达成；烧录验证为可选进阶步骤，用于确认固件在硬件上可正常启动。

常见问题排查

make menuconfig无法打开：需要先安装libncurses-dev，执行sudo apt install -y libncurses-dev后重试。
编译报错找不到arm-none-eabi-gcc：说明交叉编译工具链未正确安装，重新执行依赖安装命令。
编译过程中出现Python相关错误：Klipper编译需要Python3环境，确保python3 --version输出为3.6或更高版本。

关键文件说明

编译完成后，以下文件/目录是核心产物：

out/klipper.bin：最终固件二进制文件，用于烧录。
out/klipper.elf：带调试信息的ELF文件，可用于gdb调试。
.config：menuconfig生成的配置文件，记录当前固件配置参数。

至此，Klipper固件开发环境搭建完成，已生成可烧录的klipper.bin文件，可进入后续开发调试环节。