ITADN
Arksine/katapult
代码 动态 Issues81 合并请求15 版本
Arksine/katapult · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

Katapult (formerly known as CanBoot)

ARM Cortex-M MCU 引导加载程序

该引导加载程序最初是为与 Klipper 配合使用的 CAN 节点设计的。 引导加载程序 本身使用了 Klipper 的硬件抽象层，并进行了精简 以保持最小的占用空间。 除了 CAN 之外，Katapult 现在 还支持 USB 和 UART 接口。

目前支持 lpc176x、stm32 和 rp2040 MCU。 CAN 支持目前 仅限于 stm32 F 系列和 rp2040 设备。

Katapult 采用 GNU GPL v3 许可证。

注意：对 CanBoot 的引用既存在于本仓库的源代码中， 也存在于 Klipper 等相关项目中。 其中一些引用必须 永久保留以维持兼容性。 不会破坏兼容性的文档和源代码引用 将随时间推移逐步更新。

构建

Katapult 也使用 Klipper 的构建系统。 构建通过 menuconfig 进行配置。 获取和构建的步骤如下：

git clone https://github.com/Arksine/katapult
cd katapult
make menuconfig
make

menuconfig 将显示以下选项：

  • Microcontroller Architecture: 在 lpc176x、stm32 和 rp2040 之间进行选择
  • Processor model: 选项取决于所选的架构
  • Build Katapult deployment application: 参见下文 deployer 部分。
  • Disable SWD at startup: 这是针对 GigaDevice STM32F103 克隆芯片的选项。请注意，此选项未针对 bootloader 进行测试，GigaDevice 克隆芯片 可能无法按预期工作。
  • Clock Reference: 为您的板卡晶振选择适当的设置
  • Communication interface: 在 CAN、USB 和 UART 之间进行选择。请务必 为您的硬件选择具有适当引脚的接口。
  • 对于 CAN 接口：
    • CAN bus speed: 为您的 canbus 选择适当的速度。
  • 对于串行 (USART) 接口：
    • Baud rate for serial port: 为您的 串行设备选择适当的波特率。
  • 对于 USB 接口：
    • USB ids: 允许用户定义 USB Vendor ID、Product ID 和/或 Serial Number。
  • Support bootloader entry on rapid double click of reset button: 当 启用时，可以在 500ms 的时间窗口内按两次 reset 按钮进入 bootloader。
  • Enable bootloader entry on button (or gpio) state: 启用以使用 gpio 进入 bootloader。
    • Button GPIO Pin: 用作按钮的 GPIO 的 Pin Name。可以通过前缀 ^ 启用硬件 上拉，通过前缀 ~ 启用 下拉。
  • Enable Status Led: 启用选择状态 LED gpio 的选项。
    • Status LED GPIO Pin: 您的 LED 的 pin name。如果 LED 在引脚为低电平时点亮，则 Pin 可以反转 （例如，"blue pill" 的状态 LED Pin 为 !PC13）。

配置完成后，使用 ST-Link 等编程器进行烧录。 如果 没有可用的编程器，则可以通过 UART 烧录 STM32F103 设备，并通过 DFU 烧录 STM32F042/72 设备。 ST 的 STM32CubeProgrammer 软件可以支持所有这些方法，但还有其他 工具，例如 stm32flash (UART) 和 dfu-util (USB DFU)。

注意： 在烧录 Katapult 之前，建议执行完整的芯片擦除。 这样做可以让 Katapult 检测到没有应用程序存在并进入 引导加载程序。 如果您没有配置替代的进入方式， 这是进入引导加载程序所必需的。

注意 RP2040：要烧录 rp2040 目标，mcu 应重启至系统启动模式 （通常按住 BOOT 按钮）。之后可以使用 make flash 命令。 您也可以使用 rp2040 特定的大容量存储设备 拖放方法，从 out 文件夹烧录 katapult.uf2。烧录 Katapult 会擦除主应用程序（即 klipper），因此应使用 Katapult 重新上传。

上传 Klipper

  1. 确保 klipper 服务已停止。

  2. 构建带有 CAN 支持且引导程序偏移量与 Katapult 中“应用程序偏移量”相匹配的 Klipper。

  3. 进入引导程序。 如果 Katapult 检测到闪存的应用程序区域为空，它将自动进入引导程序。 当从当前已刷写的 Klipper 版本升级时，flashtool.py 脚本将命令 USB 和 CANBus 设备进入引导程序。 请注意，“USB 转 CAN 桥接设备”和“UART”设备无法自动检测。 如果设备未处于引导程序模式，则必须首先使用 -r 选项手动请求引导程序，然后在不使用 -r 的情况下重新运行脚本以执行上传。 运行除 Klipper 以外软件的设备需要使用其自身的方法请求引导程序。

  4. 运行刷写脚本： 对于 CAN 设备：

    cd ~/katapult/scripts
python3 flashtool.py -i can0 -f ~/klipper/out/klipper.bin -u <uuid>

    将 替换为您的 CAN 设备对应的 uuid。 如果该设备之前未使用 Klipper 进行过刷写， 可以查询引导程序以获取 UUID：

    flashtool.py -i can0 -q

注意：仅当网络上存在单个 can 节点时，才应执行查询操作。 尝试查询多个节点可能会导致传输错误，从而迫使节点进入“bus off”状态。 当节点进入“bus off”状态时，它将变得无响应。 必须重置节点才能恢复。

对于 USB/UART 设备： 在刷写之前，请确保已安装 pyserial。 安装所需的命令 取决于 linux 发行版。 基于 Debian 和 Ubuntu 的发行版可以运行以下命令：

sudo apt update
sudo apt install python3-serial

python3 flashtool.py -d <serial device> -b <baud_rate>

将 <serial_device> 替换为您希望 刷写的 USB/UART 设备的路径。 <baud_rate> 仅对 UART 设备是必需的，如果省略 则默认为 250000 波特率。

Flash Tool 用法

运行 scripts/flashtool.py -h 以显示帮助：

usage: flashtool.py [-h] [-d <serial device>] [-b <baud rate>] [-i <can interface>]
                    [-f <klipper.bin>] [-u <uuid>] [-q] [-v] [-r]

Katapult Flash Tool

options:
  -h, --help            show this help message and exit
  -d <serial device>, --device <serial device>
                        Serial Device
  -b <baud rate>, --baud <baud rate>
                        Serial baud rate
  -i <can interface>, --interface <can interface>
                        Can Interface
  -f <klipper.bin>, --firmware <klipper.bin>
                        Path to Klipper firmware file
  -u <uuid>, --uuid <uuid>
                        Can device uuid
  -q, --query           Query Bootloader Device IDs (CANBus only)
  -v, --verbose         Enable verbose responses
  -r, --request-bootloader
                        Requests the bootloader and exits
  -s, --status          Connect to bootloader and print status

通过 CAN 编程

如果省略，-i 选项默认为 can0。 编程时 uuid 选项为必需项。 -q 选项将查询 CAN 接口以获取未分配的节点，并返回它们的 UUID。

如果省略，-f 选项默认为 ~/klipper/out/klipper.bin。

串行编程（USB 或 UART）

-d 选项为必需项。 如果省略，-b 选项默认为 250000。

如果 flashtool 检测到设备通过 USB 连接，它将检查 USB ID 以确定其当前是否正在运行 Klipper。 如果是， flashtool 将尝试请求引导加载程序，直到检测到 Katapult 为止。

请求引导加载程序并退出

当提供 -r 选项时，flashtool 会请求 MCU 进入 引导加载程序。 然后 Flashtool 将立即退出，不会尝试通过 canbus 上传新的二进制文件。

这对于配置为“USB 到 CAN 桥接模式”的 Klipper 设备特别有用。这些设备使用 DFU 和/或 Katapult-USB 上传固件。此 选项允许用户在无需物理接触 电路板的情况下进入引导加载程序，然后使用适当的工具（dfu-util 或 flashtool.py -d） 上传新的二进制文件。

此外，-r 选项可用于通过 UART 连接连接到主机的设备，以请求 Klipper 的引导加载程序。

Katapult 部署器

警告：在上传部署器之前，请务必确保您的 Katapult 构建配置 正确。 使用配置错误的构建覆盖现有的 引导程序会导致设备变砖 并需要编程器来恢复。

Katapult 部署器允许用户用 Katapult 覆盖现有的引导程序， 从而允许在没有编程器的情况下进行修改和更新。 强烈 建议准备一种备用恢复（编程器、DFU 等） 方法，以防部署过程中出现问题。 如果来自原厂引导程序，也建议用户在继续之前 创建备份。

要构建部署器，请将 Build Katapult deployment application 选项 在 menuconfig 中设置为现有引导程序的偏移量。 额外的设置 适用于 Katapult 二进制文件，请像没有 部署器一样配置它们。 保存设置并使用 make 进行构建。

这将在 out 文件夹中生成一个额外的二进制文件，即 deployer.bin。 使用现有引导程序（SD 卡、HID、旧版 Katapult 等）刷写 deployer.bin。 完成后，部署器应重置 设备并进入 Katapult。 现在您可以使用 Katapult 来刷写 应用程序，例如 Klipper。

贡献

Katapult 实际上是 Klipper MCU 源代码的一个分支。 因此，保留 与 Klipper 类似的贡献指南是合适的。 提交应按以下格式 格式化：

filename: brief description of commit

More detailed explanation of the change if required.

Signed-off-by: Your Name <your email address>

所有提交都必须使用真实姓名和电子邮件地址进行签署，以表示 接受 开发者来源证明。

备注

  • 建议使用刷有 candlelight 的 USB-CAN 设备，例如 Canable。或者，支持 Klipper USB-CAN 桥接模式的设备也能良好工作。
  • BTT U2C v2.1 CAN 设备需要最新的固件。 二进制文件可以在 U2C 仓库 中找到， 源代码可以在 BTT 的 candlelight 分支 中找到。
  • 如果使用 MCP2515 CAN 设备（例如：Waveshare RS485 CAN HAT），在 验证过程中从节点读取闪存时，可能会丢失数据包。 话虽如此，我已成功测试了 12 MHz 晶振变体，并使用了 推荐设置。
  • 有关用于与引导加载程序通信的协议的详细信息， 可在 protocol.md 中找到。