Hardware

Updating JetFlight board firmware

Safe Ethernet updates, offline local packages, rollback, and USB recovery.

RuntimeUpdater runtime in JetFlight v1.4.10 and later
FirmwareOTA receiver implemented in unreleased source
HardwareJetFlight Adaptor V2 acceptance pending

JetFlight board firmware has its own identity and release history. It is separate from the JetFlight daemon, JetCad3, and the controller hardware revision. An update is offered only when the connected board reports a recognized exact target and a compatible stable package has been explicitly promoted.

JetFlight v1.4.10 and later include the host updater. The update UI and stable board packages have independent release schedules. On an isolated Adaptor V2 bench, USB bootstrap, Ethernet and UART updates, and automatic rollback after a host interruption passed. Wider hardware acceptance and stable board package availability are pending.

JetFlight v1.4.11 configures every assigned cutting output as a guarded output, including on existing single-torch profiles. A board whose firmware cannot accept guarded output configuration rejects the connection with a firmware update message. Guarded-output firmware is still in shop validation. Keep the matched runtime and firmware on an existing JetFlight development cutting setup until a compatible firmware package is available.

Update routes

  • Published stable package — JetCad3 can discover a compatible package through the private JetCad distribution service. Discovery never starts an update.
  • Local development package — a developer can select a signed local package and run the same inspection and update path entirely offline. It does not require CI, GitHub, cloud access, or a published tag.
  • Rollback — a failed or unconfirmed candidate returns to the prior accepted application. To return after acceptance, explicitly choose a compatible earlier signed package through the local-file update path; this performs a verified update and does not promise indefinite retention of an old flash slot.
  • USB recovery — the daemon can inspect and recover an exact supported board through its USB-UART connection when Ethernet firmware updating is unavailable.

FluidNC uses a different public rolling release and merged-image flasher. JetFlight packages must never be sent through the FluidNC full-flash or erase path.

Before an update

  1. Stop the program and put the machine in a safe idle state.
  2. Confirm the exact board identity and package compatibility shown by JetCad3.
  3. For a direct Ethernet cable, use a persistent manual host address and verify that the route stays on the wired interface beyond the normal DHCP timeout. A host reachable over Wi-Fi does not prove the board is reachable.
  4. For a shared LAN, use its normal DHCP or static-network profile. Switching between direct cable and shared LAN is a host network choice; the updater does not rewrite it.
  5. Keep the board's power arrangement stable. The current JetFlight Adaptor V2 mixed USB/carrier-power reset behavior remains a separate hardware investigation.

Opening the update view, checking for a release, or showing an outdated-board badge never flashes a controller. The operator must choose Start update after preflight succeeds.

What the update preserves

A normal Ethernet update writes only the inactive application slot. It does not erase configuration, network settings, licensing/provisioning data, filesystems, logs, or eFuses. Selection, boot, and acceptance are separate recorded steps.

After reboot, the machine is deliberately left disconnected from trusted motion state. JetCad3 does not restore outputs, resume a program, or assume the prior position. Reconnect, inspect the result, and home the machine before motion.

Interrupted transfer and recovery

Cached official packages work offline too: select JetCad official release key; locally signed development packages use This host’s development key. The selected verifier must match the package and enrolled board trust.

USB job evidence and its exact package survive a JetCad3 restart. If recovery evidence cannot be saved, the operation does not start. Retained evidence counts toward a storage limit; unresolved files are preserved for review. If the result is uncertain, reconnect remains blocked until verification or explicit recovery; the updater never automatically repeats the write.

An interrupted transfer is reported from a durable receipt. Checking status preserves the completed result; viewing an older interrupted job does not change the active update. Reconcile outcome checks the image the board is running. It can confirm the exact pending candidate. If a different image is running, JetCad3 reports the result and leaves that image in place. Installing the package again requires a new update start.

USB recovery first reads the chip, base MAC, flash size, partition layout, and security state. It recognizes the supported JetFlight Adaptor V2 factory layout and its original boot metadata. It refuses unknown layouts and unresolved boot selections. The initial installation of updater-capable firmware on an older JetFlight image may require a separately approved active-slot bootstrap. That operation is non-atomic and is never grouped with routine updating.

If older firmware cannot report its identity, the USB view starts with an explicit inspection of the isolated board. Installation uses that exact board identity. A completed write alone is not success: Verify running firmware checks the selected application after reset without writing again. Keep the machine disconnected until the result is verified.

Local development trust is established once over USB; later packages are signed automatically on that host. Recover lost trust is a separate physical USB operation for replacing unavailable update keys. Isolate machine outputs and other controller hosts, use USB-only power, and power-cycle before recovery. The previous public trust is retained and licensing/network configuration is preserved. This does not recover a lost private key or claim physical tamper protection.

Current acceptance boundary

Development verification covers packages, daemon and firmware behavior, JetCad3 and website distribution. The updater passes builds and automated updater tests on macOS universal, Windows x86_64, Linux x86_64 and Appliance static targets. Full acceptance still requires physical power interruption, populated provisioning preservation, shared-LAN testing and electrical measurements of isolated outputs. See connecting supported hardware for the current V2 commissioning status.

Reviewed 2026-11-17. Confirm the hardware catalog and current published release before connecting a machine.