feat(beacon): add Beacon probe discovery, registration, and flashing

[bassco]

Summary

• Adds full Beacon probe support: USB discovery, fleet registration, firmware flashing via beacon_klipper/update_firmware.py, version reporting via Moonraker update_manager, and batch exclusion
• Beacon devices use method: "beacon" with profile: null (no Klipper build artifact) and default to exclude_from_batch: true
• Includes fallback for Moonraker API omitting path field — parses moonraker.conf directly

Files changed: flash_manager.py (+93), main.py (+74/-12), ui/index.html (+99/-44), tests/test_beacon.py (+286 new)

---

Live Testing Evidence

Tested on two physical printers against a clean main baseline (be1d71e).

Test Machines

Printer	Host	Beacon Hardware	KF Data Dir
Voron 2.4	v24	RevH at ~/beacon_klipper (v2.0.0-26)	/home/pi/KlipperFleet
Voron 0.2	v02	None (negative test)	~/klipperfleet

---

Step 0 — Clean Baseline (main, be1d71e)

Both machines on main, fleet.json cleaned of any prior beacon entries, services restarted.

v24: git log --oneline -1 → be1d71e
v02: git log --oneline -1 → be1d71e

Step 1 — Before State (main, no beacon code)

v24 Discovery (main) — no "beacon" key, beacon USB shows as unmanaged serial device:

{
  "serial": [{"id": "/dev/serial/by-id/usb-Beacon_Beacon_RevH_698D6C3C...-if00", "managed": false}],
  "can": [{"id": "c20262880b1b", "name": "mcu", "managed": true}, {"id": "5f999a28d081", "name": "mcu ebb36", "managed": true}],
  "dfu": [],
  "linux": [{"id": "linux_process", "managed": true}]
}

v24 Fleet (main) — 3 devices, no beacon:

Main MCU (STM32F446) — can, spider-v3
EBB36 v1.2 Toolhead — can, ebb36
Linux Host MCU — linux

v02 Discovery (main) — no "beacon" key:

{
  "serial": [{"id": "...stm32g0b1xx...", "managed": true}, {"id": "...stm32f103xe...", "managed": true}],
  "can": [], "dfu": [],
  "linux": [{"id": "linux_process", "managed": true}]
}

Both printers: Klipper ready, KlipperFleet active (running), journals clean.

---

Step 2 — Deploy add-beacon-flashing

v24: Switched to branch 'add-beacon-flashing'
v02: Switched to branch 'add-beacon-flashing'
Both: klipperfleet.service active (running), Application startup complete

---

Step 3 — Discovery (PASS)

v24 — new "beacon" category appears with RevH device:

{
  "serial": [{"id": "...Beacon_RevH_698D6C3C...", "managed": false}],
  "can": [{"id": "c20262880b1b", "managed": true}, {"id": "5f999a28d081", "managed": true}],
  "dfu": [], "linux": [{"id": "linux_process", "managed": true}],
  "beacon": [{"id": "/dev/serial/by-id/usb-Beacon_Beacon_RevH_698D6C3C5154354D38202020FF0A1227-if00", "name": "Beacon RevH", "revision": "RevH", "serial": "698D6C3C5154354D38202020FF0A1227", "mode": "service", "managed": false}]
}

v02 — "beacon": [] (empty array, no hardware):

{"serial": [...], "can": [], "dfu": [], "linux": [...], "beacon": []}

---

Step 4 — Registration (PASS)

curl -X POST http://localhost:8321/fleet/device -d '{
  "name": "Beacon RevH",
  "id": "/dev/serial/by-id/usb-Beacon_Beacon_RevH_698D6C3C5154354D38202020FF0A1227-if00",
  "profile": null, "method": "beacon", "is_katapult": false, "exclude_from_batch": true
}'
→ {"message": "Device saved to fleet"}

After registration, discovery shows "managed": true for both serial and beacon categories.

Fleet entry:

{"name": "Beacon RevH", "id": "/dev/serial/by-id/usb-Beacon_Beacon_RevH_...", "profile": null, "method": "beacon", "exclude_from_batch": true, "status": "service"}

---

Step 5 — Versions (PASS)

{"/dev/serial/by-id/usb-Beacon_Beacon_RevH_...": {"live_version": "v2.0.0-26", "flashed_version": null}}

live_version pulled from Moonraker update_manager — confirmed v2.0.0-26.

---

Step 6 — Flash (PASS)

curl -X POST http://localhost:8321/flash -d '{"device_id": "/dev/serial/by-id/usb-Beacon_Beacon_RevH_...", "method": "beacon"}'

Output:

>>> Successfully Stopped: moonraker.service, klipper.service, klipper-mcu.service
>>> Beacon flash: using repo at /home/pi/beacon_klipper
>>> Running: python3 /home/pi/beacon_klipper/update_firmware.py update /dev/serial/by-id/usb-Beacon_Beacon_RevH_698D6C3C5154354D38202020FF0A1227-if00
Beacon '698D6C3C5154354D38202020FF0A1227' is already flashed with the current firmware version '2.1.0'. Skipping.
To force update, re-run `update_firmware.py` with the `--force` flag set.
>>> Flashing successful!
>>> Successfully Started: klipper-mcu.service, klipper.service, moonraker.service

Post-flash: Klipper ready, beacon serial device present.

Note: Initial attempt failed because Moonraker's API does not return a path field for git_repo entries. Fixed in 4f933eb by adding a fallback that parses moonraker.conf directly. Re-tested successfully.

---

Step 7 — Batch Exclusion (PASS)

>>> Excluding from batch: Beacon RevH

Batch summary:

BUILD RESULTS:
  - ebb36: SUCCESS
  - linux: SUCCESS
  - spider-v3: SUCCESS

FLASH RESULTS:
  - Beacon RevH: EXCLUDED
  - EBB36 v1.2 Toolhead: SUCCESS
  - Linux Host MCU: SUCCESS
  - Main MCU (STM32F446): SUCCESS

All 3 Klipper MCUs built and flashed, beacon correctly excluded.

---

Step 8 — After State (PASS)

Check	v24	v02
Klipper	ready	ready
KlipperFleet	active (running)	active (running)
Klippy log errors	None	N/A
Journal errors	None	None

---

Unit Tests

113 passed in 6.44s

14 new beacon-specific tests in tests/test_beacon.py covering discovery, registration, flash, version lookup, batch exclusion, and edge cases.

Test plan

• Clean baseline on main — no beacon in fleet or discovery
• Discovery: v24 shows beacon RevH, v02 shows empty array
• Registration: device saved with method: "beacon", exclude_from_batch: true
• Versions: live_version pulled from Moonraker update_manager
• Flash: services stopped, update_firmware.py executed, services restarted
• Moonraker API path fallback: parses moonraker.conf when API omits path
• Batch exclusion: beacon device marked EXCLUDED in batch summary
• Post-test health: both printers Klipper ready, no errors
• Unit tests: 113/113 pass
• Negative test: v02 (no beacon hardware) returns "beacon": []

[bassco]

beacon is only usb - this should possibly be reverted.

[bassco]

feels a bit weird doing this and maybe the intention is to default to excluded and let the user enable it?

[JohnBaumb]

Very nice! I didn't even consider this as an option. I always see my beacon probe in my discovered but never even thought of handling updating it through KF. Beacon's update process seems pretty robust already, but I like this, I'll test it out and let you know this week.

[bassco]

Beacon path discovery: switched from moonraker.conf parsing to /server/config API

Per feedback from Moonraker's maintainer (Arksine/moonraker#1060), the update_manager config (including path) is already available via GET /server/config — no upstream Moonraker change needed.

What changed

• get_beacon_klipper_path() now calls /server/config and looks for update_manager *beacon* sections
• Removed _read_beacon_path_from_moonraker_conf() (moonraker.conf parsing fallback)
• Paths with ~ are expanded via os.path.expanduser()

Live test on Voron 2.4 (stock Moonraker, no patches)

$ curl -s http://localhost:7125/server/config | python3 -c "
import json, sys
data = json.load(sys.stdin)
config = data['result']['config']
for k, v in config.items():
    if k.startswith('update_manager ') and 'beacon' in k.lower():
        print(f'{k}: path={v.get(\"path\")}')"

update_manager beacon: path=~/beacon_klipper

After os.path.expanduser() on the printer → /home/pi/beacon_klipper ✓

All 14 beacon tests pass.

[bassco]

Very nice! I didn't even consider this as an option. I always see my beacon probe in my discovered but never even thought of handling updating it through KF. Beacon's update process seems pretty robust already, but I like this, I'll test it out and let you know this week.

Yeah, I thought, why not. How hard can it be... Using a digital twin gets the ideas out of the mind and into reality.

I'm not too happy with the ui changes where I made comments. My frontend understanding is lacking there.

A "beacon" type could possibly be more generic as a future refactor.

Just a pity the beacon firmware is solid for flash testing 😉

Agree that having a card for it and not in the "unknown" list is a bonus.

[JohnBaumb]

I'm thinking if it shows up as beacon when discovering, it should also hide it from the discovered serial devices, what are your thoughts on this? This gives the user the ability to incorrectly add it to the managed devices rather than being autodetected as a beacon device.

Addtionally, the version delta logic in the UI compares each device's live_version against the system Klipper version to show green (match) or orange (mismatch). This works for Klipper MCUs since they all share the same firmware build, but Beacon devices have their own independent version stream from beacon_klipper (e.g. v2.0.0-28), which has no relation to the Klipper version (e.g. v0.13.0-572-g88a71c3c). So the comparison will always show orange even when the beacon is fully up to date.

The versionMatch, versionColor, and versionTitle functions should either skip the system comparison for non-Klipper device types like beacon, or compare against a relevant source like the beacon_klipper repo's remote version from Moonraker's update_manager status. The tooltip also pairs the two unrelated versions side by side which could be confusing.

[bassco]

@JohnBaumb - thanks for the feedback.

1. Serial discovery filtering — discover_serial_devices() now excludes Beacon_Beacon_Rev paths so beacon only appears via
   auto-detection.

2. Version comparison — /fleet/versions now includes method and remote_version. The UI compares beacon against its own
   remote_version from Moonraker's update_manager instead of system Klipper. Tooltip shows "Beacon: v2.0.0-30 | Latest:
   v2.0.0-30". Green when matching, no more false-orange.

Verified live on V2.4, all 14 tests pass.

Wait a minute - firmware is 2.1.0 and not the repo version - they are independent. Digging further.

[bassco]

That's better - 2.1.0 now showing.

The previous version was showing the beacon_klipper repo version (e.g. v2.0.0-30 from Moonraker's update_manager) instead
of the actual hardware firmware version. These are independent — the firmware (Beacon 2.1.0) is flashed onto the device,
the repo version tracks the Python integration code.

Fixed by sourcing versions from the right places:

• live_version: Now from Klipper's MCU query (/printer/objects/query?mcu+beacon → mcu_version: "Beacon 2.1.0")
• remote_version (available firmware): Extracted from the beacon_klipper repo's firmware/*.dfu git history, with a 3-step
  fallback: semver from commit message → closest git tag → short commit hash
• Comparison: Strips "Beacon " prefix from MCU version, compares against remote. Green when matched, orange when outdated,
  blue when only a commit hash is available (can't compare)
• Tooltip: "Beacon FW: 2.1.0 | Available: 2.1.0 | Klipper plugin: v2.0.0-30"
• versionMatch/versionColor/versionTitle skip the system Klipper comparison entirely for beacon devices

Verified live on V2.4 — MCU reports Beacon 2.1.0, repo firmware commit says 2.1.0, version shows green. 18 beacon tests
pass (4 new for the version fallback chain).

[bassco]

The "Flash Beacon" on the card should stay or be removed?

[JohnBaumb]

I think it can stay flash beacon, I'll try this out tonight.

[JohnBaumb]

What are your thoughts on this:

I have a pending update on beacon

Yet the UI says already on latest version, I think this is expected behavior, as we're not pulling the latest beacon version, we're just flashing what should already be on the beacon device when it is updated (which does seem sort of pointless when thinking about it). To make it truly useful, perhaps we should, only for beacon, pull the latest version and ensure it updates?

Just curious at your thoughts on this. Otherwise I'm not seeing a point in keeping it if it's just going to flash a version that should be on it already, persuade me. haha

[bassco]

The beacon software is a "monorepo" that has the firmware files that are released very rarely, and the python code (code_base) that causes the moonraker plugin to show "update", as it is changed more regularly. The beacon code change in the last commit, identifies the firmware_version state versus the code_base state. If the firmware_version matches the installed_firmware_version, the "Flash Beacon" button should be disabled/changed to show it is on the latest.

This is very similar to "klipper/kalico" where not every update to the repo requires devices to be flashed. There is no definitive, this file changes therefore the MCUs need to be flashed. The user has to kinda guess if they need to flash or not. Not entirely true; they are prompted to flash if there is a version mismatch, but that's a runtime warning. Perhaps we can identify this?

The "Flash Beacon" button should only be active if there is a firmware_version mismatch. Otherwise, button should be deactivated and the text changed to "On Latest Version". I'll fix this up and send a patch for you to review.

Fetch beacon code? I'm leaning towards let the user decide when to do updates via moonraker. Moonraker does a great job there already and is a known workflow.

[bassco]

Dashboard view with disabled flash button.

The Fleet Manager - removed Beacon from "Serial & Uart Devices". Was duplicated as it has its own section.

Before:

After: Also removed the "+" Add to Fleet button if any device is already managed.

[bassco]

Something else I've noticed - not sure if these changes caused this or if it is existing behaviour... But the firmware version being flashed is adding the -<count>-<short sha> to the end of the firmware version and the actual tag is being shown for the klipper version and therefore requesting me to flash. However, in this case I have already flashed the version in question. Kalico has started using monthly releases, following the CalVer semantic versioning notation.

My devices should be in "green".

# klippy/util.py
# 202:def get_git_version(from_file=True):
# method uses the following command to produce the version number
$ git describe --always --tags --long --dirty
v2026.03.00-0-g27902226c

# from klippy.log
$ grep -E "^Git|^Load|^Bran" ~/printer_data/logs/klippy.log|sort -u
Branch: (HEAD detached at v2026.03.00)
Git version: 'v2026.03.00-0-g27902226'
Loaded MCU 'beacon' 45 commands ( Beacon 2.1.0 / )
Loaded MCU 'ebb36' 133 commands (Kalico v2026.03.00-0-g27902226 / gcc: (15:12.2.rel1-1) 12.2.1 20221205 binutils: (2.40-2+18+b1) 2.40)
Loaded MCU 'mcu' 146 commands (Kalico v2026.03.00-0-g27902226 / gcc: (15:12.2.rel1-1) 12.2.1 20221205 binutils: (2.40-2+18+b1) 2.40)
Loaded MCU 'rpi' 134 commands (Kalico v2026.03.00-0-g27902226 / gcc: (Debian 12.2.0-14+deb12u1) 12.2.0 binutils: (GNU Binutils for Debian) 2.40)

Note to self: http://v24:8321/firmware/version is the "System: "

{"version":"v2026.03.00","commit":"27902226cab6","date":"2026-02-26 22:51:50 +0000"}

and uses

$ git describe --always --tags --dirty
v2026.03.00

The --long argument is missing from KlipperFleet in backend/build_manager.py

    async def get_klipper_version(self) -> Dict[str, str]:
        """Gets the current Klipper git version info."""
        version_info: Dict[str, str] = {"version": "unknown", "commit": "unknown", "date": "unknown"}
        try:
            # Get the short commit hash
            process: Process = await asyncio.create_subprocess_exec(
                "git", "describe", "--always", "--tags", "--dirty",
                cwd=self.klipper_dir,

[JohnBaumb]

_is_beacon_device() is defined but isn't called anywhere; use or remove.

The git fallback for beacon versions is quite complex, can this be simplified? maybe caching results?

Too many API calls per refresh. Cache the beacon path at startup and move git lookups to a background timer? Then it won't have to do it on every refresh.

[bassco]

Summary

Fixed device add/remove UX to provide instant feedback instead of waiting 10-20s for network round-trips. Optimized
discovery endpoint to show fleet names for managed devices.

Changes

Backend (main.py)

• Enrich /devices/discover response with fleet names for managed devices
• Instead of generic "Beacon RevH", users now see their custom name "Beacon 2" in the discovery list for managed devices

Frontend (ui/index.html)

• Optimistic add: When user clicks "+" to add device, button disappears instantly (before network call completes)
• Optimistic remove: When user clicks delete, card disappears instantly and "+" button reappears in discovery list without
  waiting for backend refresh
• Background refresh: Fleet and discovery lists update in background post-confirmation (non-blocking)
• Fixed Vue reactivity: Added missing beacon: [] to devices ref initialization
• Synchronized discovery state: Discovery list updates after add/remove operations

Result

Device add/remove operations now feel instant with optimistic UI updates. Network refreshes happen silently in the
background, eliminating the 10-20s perceived lag.

Before

• Click "+" → wait 10-20s → "+" disappears
• Click delete → card stays visible → wait 10-20s → card disappears

After

• Click "+" → instantly disappears, network call in background
• Click delete → card instantly removed, "+" reappears instantly

Testing

• Add beacon: "+" disappears instantly, card appears in fleet
• Remove beacon: card removed instantly, "+" reappears instantly
• Both beacons visible in discovery with fleet names
• Background refresh keeps UI in sync with server state

There is a spurious "Error: Failed to fetch" which just popped up. Digging into it too.

[bassco]

New commit fixes the double spinner fetching in parallel and resolves the Failed fetch.

[bassco]

Optimistic Fleet Card Addition

Added optimistic UI update when adding devices to the fleet. The fleet card now appears immediately after clicking the "+"
button, rather than waiting for the server response.

Implementation:

• Fleet card is added to fleet.value immediately before the POST request
• Device is marked as managed in the discovery list (existing behavior)
• Original fleet and device states are saved for rollback on error
• On success, a parallel refresh of both fleet and discovery ensures authoritative state
• On failure, both fleet and device states are fully restored

UX improvement: Instant visual feedback that the device was added, with graceful error recovery if the server request
fails.

[JohnBaumb]

@bassco sorry for the delay,

Post-flash status is wrong. generate_beacon() sets status to "ready" after a successful flash. But services get restarted right after, so the beacon goes back to running Klipper. Status should be "service" to match what check_device_status("beacon") returns.

Flash sentinels missing. flash_beacon() and generate_beacon() never emit ">>> Flashing successful!" or ">>> Flashing failed!". Beacon flashes will finish without any visual feedback.

stripGitSuffix works around the git describe --long format mismatch instead of fixing it in build_manager.py.
fixes my requested change, but the root bug still exists, should probably adjust it at the root instead.

some minor stuff, not really necessary but should probably be fixed in this pr:

httpx.AsyncClient created per beacon device in get_fleet_versions(). Could lift the client outside the loop.

addDeviceToFleet uses a per-category if/else for optimistic UI. removeDeviceFromFleet already uses the cleaner forEach pattern. Should match.

[bassco]

Thanks for the review @JohnBaumb - summary of the work that was done for you to review.

Changes Made:

1. Post-flash status → Set to "service" instead of "ready" since beacon runs Klipper after services restart
2. Flash sentinels → Added visual feedback:
   • "Flashing Beacon successful!" in flash_beacon()
   • "Flashing Beacon failed!" on error in generate_beacon()
3. git describe --long → Added --long flag to build_manager.py to match Klipper's runtime version format, eliminating the stripGitSuffix workaround
4. httpx.AsyncClient reuse → Lazy-create single client outside loop in get_fleet_versions(), close after use
5. UI consistency → addDeviceToFleet now uses forEach pattern matching removeDeviceFromFleet
6. Discovery consistency → Added interface and application fields to beacon/linux devices, UI now shows mode/interface badges consistently

[JohnBaumb]

Looks good! Good job @bassco! I'll merge it to dev