grant0013/k2-reverse-engineering

# k2 逆向工程 逆向工程 Creality K2（及相关 K1/K1C）固件的研究笔记、协议文档和工具。重点在于理解 **Creality 在原本开源的 Klipper 栈中做了哪些更改**，以及如何在不刷写自定义固件的情况下配合或绕过这些更改。 本仓库是 [`k2-adaptive-bedmesh`](https://github.com/grant0013/k2-adaptive-bedmesh) 的**上游研究**（这是一个利用这些笔记解锁真正的自适应热床调平的生产工具）。如果你是只想获得更好打印效果的 K2 用户，请从那里开始。如果你是想知道这一切是**如何**运作，或者**为什么** Creality 的栈会这样表现的开发者/黑客，那你来对地方了。 ## 仓库内容 ``` docs/ k2_architecture.md Communication paths, MCU layout, RS-485 motor protocol motor_params_map.md All 226 motor controller params with configurability flags rs485_protocol.md RS-485 frame format, device addresses, class API decoded_what.md Field guide to every Creality binary, daemon, and Klipper hijack tools/ k2ssh.py Shared SSH helper - reads K2_HOST/K2_PASS env vars ssh_enum.py Initial recon - OS, Klipper version, extras dir, daemon list backup_printer.py Snapshot Klipper + Moonraker + config trees on the printer download_files.py Pull Creality's modified .py shims and configs locally tail_klippy.py Live log streamer with smart filtering for macro/mesh events deploy_extras.py Generic deploy helper for custom Klipper extras modules README.md LICENSE GPL v3 (matches Klipper) .gitignore ``` ## 范围 **在范围内：** - 记录 Creality 对上游 Klipper 栈的修改——他们添加了什么，替换了什么，删除了什么 - 逆向工程专有守护进程（`master-server`、`app-server`）以了解打印流程 - 映射闭环伺服电机控制器协议（226 个参数，RS-485 + 透传 UART 传输） - 让你能够 SSH 进入原厂 K2、进行备份、拉取文件和查看日志的工具，无需 root 或重新刷机 - 记录哪些 gcode 命令被哪个 `.so` 封装器拦截 **不在范围内：** - 托管 Creality 的二进制文件（`.so` 封装器、master-server、app-server）——版权问题 - 任何形式的反编译 `.so` 产物 - 任何需要刷写自定义固件的操作 - 托管 Klipper 本身（请克隆上游——参见 [klipper3d.org](https://www.klipper3d.org/)） - 云端 / Creality 账户集成 ## 我们发现了什么（重点） **最重要的一点** —— Creality 的 `prtouch_v3_wrapper.cpython-39.so` 劫持了 `BED_MESH_CALIBRATE`，使用了一个非自适应的实现，当你传入 `MESH_MIN`/`MESH_MAX`/`PROBE_COUNT` 时会崩溃（第 1922 行出现 `IndexError`）。上游的 `bed_mesh.BedMeshCalibrate.cmd_BED_MESH_CALIBRATE` 仍然存活在内存中的 `printer.lookup_object('bed_mesh').bmc.cmd_BED_MESH_CALIBRATE` —— 你可以在 `klippy:connect` 时从自定义 extras 模块重新注册它，自适应调平即可正常工作。完整实现请参见 [`k2-adaptive-bedmesh`](https://github.com/grant0013/k2-adaptive-bedmesh)。 **Master-server 会独立触发完整调平。** 即使你的切片器 + 宏完美无缺，`/usr/bin/master-server` 仍会在打印准备期间从 `Control/AppModeSdPrint.c:1992` 和 `Control/PrintfManager.c:604` 触发 `G29 BED_TEMP=NN` 和 `BED_MESH_CALIBRATE GCODE_FILE='...'`，它并不在乎你使用的是哪种切片器或上传路径。将 Klipper 端的 `G29` 宏劫持为空操作（同时发出伪造的 `[G29_TIME]` 响应握手）是绕过方法。 **闭环伺服电机是可调的。** K2 上的 X/Y/E 电机不是标准步进电机——它们是自带 MCU 的闭环伺服电机，运行级联的位置/速度/电流 PID 环，以及 LESO 观测器和“zazen”空闲电流降低。226 个控制器参数中约有 50 个可以在运行时通过 Klipper 配置进行配置；其余则是出厂锁定的。完整映射请参见 [`docs/motor_params_map.md`](docs/motor_params_map.md)。 **通过 `prtouch_v3` 进行应变片探测。** K2 的“探针”是整个打印头——它向下按压热床并测量龙门架的应变以检测接触。传统意义上没有 Z 限位；PA15 上的光耦限位仅用于 Z-max 安全保护。这就是为什么封装器集成得如此之深：探测涉及喷嘴 MCU 的应变 ADC 和主 MCU 的步进引擎，是一场多 MCU 的协作。 **Section 名称陷阱。** Klipper 的 `bed_mesh.ProfileManager` 会对每个匹配项执行 `config.get_prefix_sections('bed_mesh')` 和 `name.split(' ', 1)[1]`。一个名为 `[bed_mesh_override]` 的自定义配置段会导致 Klipper 在启动时崩溃，报错 `IndexError: list index out of range`。请使用不以 `bed_mesh` 开头的名称。 更多内容请参见 [`docs/decoded_what.md`](docs/decoded_what.md)。 ## 使用工具 所有脚本都从环境变量读取连接详情，因此凭据绝不会出现在仓库中： ``` export K2_HOST=192.168.x.x export K2_PASS=your_root_password # 可选： export K2_USER=root # default export K2_KEY=~/.ssh/k2_key # use SSH key instead of password ``` 然后： ``` # 对新访问的 K2 进行 Recon python tools/ssh_enum.py # 在任何补丁之前进行完整备份 python tools/backup_printer.py # 将 Creality 修改的 extras 和 configs 拉取到本地目录进行检查 python tools/download_files.py --out ./k2_dump # 实时监控日志，过滤 macro/mesh 事件 python tools/tail_klippy.py # 监控原始日志 python tools/tail_klippy.py --raw # 将自定义 Klipper extras 模块放入打印机 python tools/deploy_extras.py path/to/my_module.py --restart ``` ## 道德声明 **本仓库是研究，而非盗版。** 此处的所有内容均通过阅读打印机上可自由阅读的 Python 源码、观察实时的 gcode/log 流量、对我们拥有合法访问权限（即在我们拥有的硬件上）的二进制文件运行 `strings` 和 `grep`，以及与上游 Klipper 进行交叉比对而习得。我们不托管任何 Creality 的编译二进制文件、反编译产物或受版权保护的源码。 如果你来自 Creality 并且想聊聊：请考虑像项目的其余部分一样，在 GPL 下开源你们的 Klipper 修改。本仓库存在的原因是我们目前还无法做到——你们的封闭封装器积极阻止 K2 用户使用自 2022 年以来在上游 Klipper 中免费提供的 bed mesh 功能。 ## 相关项目 - [k2-adaptive-bedmesh](https://github.com/grant0013/k2-adaptive-bedmesh) —— K2 的即插即用自适应热床调平（本研究的产出） - [Klipper](https://www.klipper3d.org/) —— 上游项目 - [pellcorp/creality](https://github.com/pellcorp/creality) —— 早期的 K1 逆向工程工作，映射了大量 Creality 目录结构 ## 许可证 GPL v3，与 Klipper 保持一致。参见 [`LICENSE`](LICENSE)。

标签：3D 打印, Adaptive Bedmesh, Creality K2, Firmware Modding, Klipper, MCU 通信, Moonraker, Python 工具, RS-485 协议, SSH 自动化, 二进制分析, 云安全运维, 云资产清单, 内存分配, 协议文档, 固件分析, 嵌入式系统, 开源硬件, 电机控制, 系统架构, 逆向工具, 逆向工程