Device ID becomes stale after flash if USB descriptor changes

[bassco]

Summary

After flashing a non-Katapult RP2040 device (method: serial, is_katapult: false), the USB serial-by-id path can change if the firmware alters the USB manufacturer descriptor. KlipperFleet doesn't rescan /dev/serial/by-id/ after flashing, so the device_id in fleet.json becomes stale. Subsequent flash attempts silently fail — the device enters USB bootloader but the firmware write never executes, leaving it bricked in RP2 Boot mode.

Steps to reproduce

1. Register an RP2040 device (e.g. BTT Eddy USB) with is_katapult: false, method serial
2. Flash firmware that changes the USB manufacturer string (e.g. custom Klipper fork with a different vendor name)
3. First flash succeeds — device now enumerates with a new /dev/serial/by-id/ path
4. Attempt a second flash via KlipperFleet

Expected behavior

• KlipperFleet rescans serial devices after a successful flash and updates fleet.json if the path changed (matching by chip serial suffix)
• If make flash fails or the device doesn't re-enumerate after flashing, the error is reported to the user

Actual behavior

• POST /flash returns 200 OK
• Services are stopped, but no rp2040_flash command executes (confirmed via journalctl -u klipperfleet)
• Device is left stuck in RP2 Boot mode (lsusb shows 2e8a:0003 Raspberry Pi RP2 Boot)
• Services are restarted, Klipper enters error state (mcu 'eddy': Unable to connect)
• No error is surfaced to the user

Environment

• KlipperFleet v1.2.0-alpha (be1d71e)
• Kalico v2026.03.00 (27902226cab6)
• Hardware: BTT Eddy USB (RP2040), is_katapult: false, method: serial
• Raspberry Pi 4

Suggested fix

1. After a successful make flash, rescan /dev/serial/by-id/ and match devices by their unique chip serial (the suffix portion of the path, e.g. rp2040_50443403106DC01C). If the full path changed, update fleet.json automatically.
2. If make flash exits non-zero or the device doesn't re-enumerate within a timeout, report the failure rather than returning success.

[JohnBaumb]

I appreciate the well documented issue, I have a fysetc PIS v1 (rp2040 based) to test here, but am not using kalico to test that specific path. Confirmed main issue, and I believe it's fixed, also found a second issue of potential silent failures.

Stale device ID after flash: No post-flash rescan of /dev/serial/by-id/. If the USB descriptor changes, the old path goes stale in fleet.json. Now rescans after successful serial flashes and auto-updates the fleet entry by matching the chip serial suffix (e.g. rp2040_50443403106DC01C). Falls back to diff-based detection if the suffix isn't unique.

Silent flash failures: All flash methods (make flash, flashtool.py, dfu-util) reported failures as text in the log stream but the endpoint always marked the device as "ready" and recorded version metadata regardless. Now the endpoint checks for actual success before updating device status - failed flashes are marked as FAILED.

Also renamed the misleading "AVR/avrdude" labels on the non-Katapult serial path -- make flash handles RP2040, AVR, and other architectures through Klipper's own tooling, so the labels now reflect that. And .uf2 artifacts are now saved alongside .bin/.elf after builds.

Please test and give feedback if it resolves your issue, if it does it will be included in the next release (probably next week sometime):

cd ~/KlipperFleet
git fetch origin
git checkout dev
bash install.sh

[bassco]

Thanks for looking into this John. This project is destined for success and makes updating Klipper/Kalico so much easier. Was a breeze to migrate to as I was already storing my devices as KCONFIG_CONFIG references.

I've passed that printer where my digital twin did the diagnostics to a friend yesterday.

I have some time the day after tomorrow to test the changes on my other printers which need updates. I'll change device strings to test the patches.

Still getting used to mainsail, having used fluidd since my intro to Klipper.

Will comment in a few days.

All the best.

[bassco]

Here is the summary form this afternoon's testing and findings from direct API requests from the digital twin. Will find a machine that has USB devices next.

Tested on: Voron 2.4 — RPi 5, KlipperFleet dev branch (0d801d4), Kalico v2026.03.00

Fleet: 3 devices

• Main MCU (STM32F446) — CAN (c20262880b1b), profile spider-v3, Katapult bootloader
• EBB36 v1.2 — CAN (5f999a28d081), profile ebb36, Katapult bootloader
• Linux Host MCU — profile linux

What I tested:

• Changed CONFIG_USB_MANUFACTURER from "Klipper" to "Kalico" on ebb36 and linux profiles (spider-v3 was already "Kalico")
• Updated Kalico from v2026.02.00 → v2026.03.00
• Ran /batch/build_flash-all — all 3 devices built and flashed successfully, services restarted cleanly, Klipper came back ready with all MCUs on matching versions

Findings:

1. Post-flash rescan works — services stopped/started cleanly, all CAN devices re-discovered after flash, Klipper reconnected without issues.

2. Serial-by-id edge case not reproducible on CAN-only fleet — the Device ID becomes stale after flash if USB descriptor changes #17 scenario (USB vendor name change breaking device IDs) requires a device tracked by /dev/serial/by-id/ path. CAN devices use UUIDs and the gs_usb driver matches by interface name (can0), so the USB manufacturer rename has no effect. To fully validate the serial rescan fix, test on a fleet with USB serial devices (e.g. LPC1768 via USB, or RP2040 serial).

3. flashed_version / flashed_commit / last_flashed not populated — after a successful batch flash-all, all three fields remain null in the fleet. The /fleet/versions endpoint shows correct live_version (v2026.03.00) but flashed_version is never written. Looks like the batch flash path doesn't call the version tracking update after a successful flash.

4. /batch/build_flash silently skips all devices — using build_flash (without -all or -ready suffix) enters the flash phase but the should_flash gate requires "flash-all" or "flash-ready" in the action string, so every device is skipped with no warning. This is confusing — either reject unknown action variants or treat build_flash as build_flash-all.

[bassco]

Another test - although, I didn't change the kalico branch, only the USB_MANUFACTURER

Tested On: Voron 0.2, RPi 4B, Kalico v2026.03.00, KlipperFleet dev branch (0d801d4)

Test scenario

Changed CONFIG_USB_MANUFACTURER from "Kalico" → "Kalico17" in both USB device profiles (skr-mini-e3-v2, ebb-gen2) to trigger a /dev/serial/by-id/ path change, then ran batch/build_flash-all.

Before state

# /dev/serial/by-id/
usb-Kalico_stm32f103xe_30FFDA05344E393729680957-if00
usb-Kalico_stm32g0b1xx_350015001750304158373620-if00

# fleet.json device IDs
skr-mini-e3-v2:         /dev/serial/by-id/usb-Kalico_stm32f103xe_30FFDA05344E393729680957-if00
ebb-gen2:               /dev/serial/by-id/usb-Kalico_stm32g0b1xx_350015001750304158373620-if00
Linux Process (Host MCU): linux_process

# fleet.json timestamps
skr-mini-e3-v2:  last_flashed: 2026-03-03 00:11:23, flashed_version: v2026.03.00
ebb-gen2:        last_flashed: 2026-03-03 00:10:29, flashed_version: v2026.03.00
rpi:             last_flashed: 2026-03-03 00:08:38, flashed_version: v2026.03.00

After state (batch/build_flash-all on dev branch)

# /dev/serial/by-id/ — paths changed as expected
usb-Kalico17_stm32f103xe_30FFDA05344E393729680957-if00
usb-Kalico17_stm32g0b1xx_350015001750304158373620-if00

# fleet.json device IDs — NOT updated (stale)
skr-mini-e3-v2:         /dev/serial/by-id/usb-Kalico_stm32f103xe_30FFDA05344E393729680957-if00  ← STALE
ebb-gen2:               /dev/serial/by-id/usb-Kalico_stm32g0b1xx_350015001750304158373620-if00  ← STALE
Linux Process (Host MCU): linux_process  ← OK (unaffected)

# fleet.json timestamps — NOT updated
skr-mini-e3-v2:  last_flashed: 2026-03-03 00:11:23  ← STALE (should be 2026-03-17)
ebb-gen2:        last_flashed: 2026-03-03 00:10:29  ← STALE
rpi:             last_flashed: 2026-03-03 00:08:38  ← STALE

Observations

1. Device IDs not updated — The dev branch fix (0d801d4) did not update fleet.json device IDs after flashing. The batch log did detect the path change during the Katapult reboot phase (Device skr-mini-e3-v2 serial ID changed: ...katapult_stm32f103xe_...) but this was the temporary Katapult bootloader path, not the final post-flash application path.

2. last_flashed / flashed_version / flashed_commit not updated — All three metadata fields remain at their pre-flash values despite successful build+flash. This is the existing known issue where batch flash doesn't persist version metadata.

3. Klipper broken after flash — Klipper couldn't connect to MCUs because printer.cfg / ebb-gen2.cfg still referenced the old usb-Kalico_... serial paths. Manual config update + RESTART was required to restore the printer.

Impact

After a CONFIG_USB_MANUFACTURER change + batch flash, three things need manual intervention:

• fleet.json device IDs (stale, future flashes will fail to find devices)
• Klipper config serial paths (printer.cfg, MCU config files)
• Fleet metadata (last_flashed, flashed_version, flashed_commit)

Suggestions

1. Klippy.log notification: Send a gcode RESPOND MSG="..." or M118 via Moonraker (POST /printer/gcode/script) to log the device path change to klippy.log for audit trail.

2. Persist flash metadata: Update last_flashed, flashed_version, and flashed_commit in fleet.json after each successful device flash in the batch path.

I'm testing a patch for the batch flash endpoint and will create a new comment.

[bassco]

Issue #17 — Batch flash: post-flash serial rescan + version tracking

Environment: Voron 0.2, RPi 4B, Kalico v2026.03.00, KlipperFleet dev branch (0d801d4)

Problem

The dev branch fix (0d801d4) added _post_flash_rescan() and update_device_id() to handle USB descriptor changes after flashing. However, these are only wired into the single-device /flash endpoint — the batch flash path (/batch/build_flash-all) has neither the serial rescan nor version metadata tracking.

Additionally, the batch flash path has a device ID mutation bug: during the Katapult reboot phase, dev['id'] in the devices list is mutated from the fleet.json ID (e.g. usb-Kalico_...) to the temporary Katapult path (e.g. usb-katapult_...). Subsequent calls to update_device_version() and _post_flash_rescan() then fail to find the device in fleet.json because they're searching for the Katapult path.

Test procedure

Changed CONFIG_USB_MANUFACTURER from "Kalico" → "Kalico17" in both USB device profiles (skr-mini-e3-v2, ebb-gen2) to trigger a /dev/serial/by-id/ path change, then ran batch/build_flash-all. KlipperFleet handled all service stop/start — no manual Klipper management required.

Test 1 — Unpatched dev branch

BEFORE:
  Serial:  usb-Kalico_stm32f103xe_..., usb-Kalico_stm32g0b1xx_...
  Fleet:   usb-Kalico_stm32f103xe_..., usb-Kalico_stm32g0b1xx_...
  Timestamps: last_flashed: 2026-03-03

AFTER:
  Serial:  usb-Kalico17_stm32f103xe_..., usb-Kalico17_stm32g0b1xx_...  ← changed
  Fleet:   usb-Kalico_stm32f103xe_..., usb-Kalico_stm32g0b1xx_...      ← STALE
  Timestamps: last_flashed: 2026-03-03                                   ← STALE

Result: Fleet IDs stale, version metadata stale, Klipper broken (config still references old paths)

Root causes found

1. _post_flash_rescan not called in batch path — only wired into /flash endpoint
2. update_device_version not called in batch path — last_flashed, flashed_version, flashed_commit never updated
3. Device ID mutation bug — the Katapult reboot phase (line ~933) mutates dev['id'] to the temporary Katapult path via d['id'] = new_id. When the flash loop later references dev['id'] for version tracking or rescan, it holds the Katapult path (e.g. usb-katapult_stm32f103xe_...) instead of the original fleet.json ID. fleet_mgr.update_device_version() and fleet_mgr.update_device_id() both fail silently because no fleet entry matches the Katapult path.

Fix applied (3 changes to backend/main.py)

1. Preserve fleet.json ID — save dev["fleet_id"] = dev["id"] before the reboot phase mutates it
2. Add version tracking to batch — call fleet_mgr.update_device_version(fleet_id, build_info) after each successful flash
3. Add serial rescan to batch — call _post_flash_rescan(fleet_id, initial_serials) after each successful USB device flash

Test 2 — Patched batch path

BEFORE:
  Serial:  usb-Kalico_stm32f103xe_..., usb-Kalico_stm32g0b1xx_...
  Fleet:   usb-Kalico_stm32f103xe_..., usb-Kalico_stm32g0b1xx_...
  Timestamps: last_flashed: 2026-03-03

AFTER:
  Serial:  usb-Kalico17_stm32f103xe_..., usb-Kalico17_stm32g0b1xx_...  ← changed
  Fleet:   usb-Kalico17_stm32f103xe_..., usb-Kalico17_stm32g0b1xx_...  ← UPDATED ✓
  Timestamps: last_flashed: 2026-03-17 15:47:46                         ← UPDATED ✓

Batch log:
  >>> Version recorded: v2026.03.00 (27902226cab6)
  >>> Rescanning serial devices after flash...
  >>> Device path changed: usb-Kalico_stm32f103xe_... -> usb-Kalico17_stm32f103xe_...
  >>> Fleet updated automatically (matched by serial: 30FFDA05344E393729680957).

KlipperFleet correctly stopped services before flash and restarted them after — no manual service management needed.

Remaining gap

Klipper config files (printer.cfg, MCU configs) still reference old serial paths after a USB descriptor change. This requires manual intervention. A future enhancement could use Moonraker's file API (POST /server/files/upload with root=config) to update the serial paths automatically, then trigger POST /printer/restart.

[bassco]

A PR will be submitted to patch the above findings.

[JohnBaumb]

keep in mind some devices may reappear with a blank serial, I'll take a deeper look at this later.