clocksync: expose transmit_extra as a tunable [danger_options] knob

[pdscomp]

Problem

When the host computer is under CPU or scheduling pressure, the MCU 'X' shutdown: Timer too close error can occur across multiple MCUs simultaneously. This happens because TRANSMIT_EXTRA in clocksync.py — the fixed 1 ms forward-scheduling headroom added to the MCU clock estimate passed to the serialqueue — is too small to absorb the host's scheduling jitter. The MCU then receives a command whose scheduled waketime has already passed, triggering the hard try_shutdown("Timer too close") guard in src/sched.c.

Because the error originates on the klippy/host side (not in MCU firmware), this is safely fixable without reflashing.

Changes

klippy/clocksync.py

• Increased the TRANSMIT_EXTRA module-level default from 0.001 s → 0.002 s.
• Added self.transmit_extra instance attribute (initialized from the module default) so each ClockSync / SecondarySync object can be overridden independently.
• Added set_transmit_extra(value) method so danger_options can push a user-supplied value in at connect time.
• _handle_clock() now uses self.transmit_extra instead of the bare TRANSMIT_EXTRA constant.
• dump_debug() now includes transmit_extra in its output to aid diagnostics.

klippy/extras/danger_options.py

• Added transmit_extra config option (minval=0.0, maxval=0.010, default sourced from clocksync.TRANSMIT_EXTRA).
• Registers a klippy:mcu_identify event handler that walks all MCU objects and calls set_transmit_extra() on each _clocksync, so a single config line applies to every MCU (primary + secondary/CAN).

Tuning Guide for End Users

Add to printer.cfg:

[danger_options]
transmit_extra: 0.002   # seconds; default

Scenario	Recommended value
Dedicated quiet host (CB1/CM4, nothing else running)	0.001
Default / lightly loaded host	0.002
Shared host with background services	0.003 – 0.004
CAN-bus multi-MCU setups with added bus latency	0.003 – 0.005
Severely overloaded or high-latency host	0.005 – 0.010

Values above 0.010 s are capped by maxval and are not recommended — they push commands so far ahead that scheduling latency for reactive events (endstops, probes) could be marginally affected, though step timing accuracy and print quality are not impacted at normal values.

Do not increase transmit_extra as a substitute for fixing the underlying host load issue. If you need values above 0.004 consistently, investigate CPU usage, swap, disk I/O, or thermal throttling on the host.

Safety

The MCU-side Timer too close guard in src/sched.c is not modified. It is a hard safety check that must remain intact. All changes are confined to the host-side Python layer.

[Copilot]

Pull request overview

Exposes the host-side clock sync forward-scheduling headroom (transmit_extra) as a configurable [danger_options] knob to reduce “Timer too close” MCU shutdowns under host scheduling jitter.

Changes:

• Increase klippy.clocksync.TRANSMIT_EXTRA default and make it instance-tunable via set_transmit_extra().
• Add [danger_options] transmit_extra config option with bounds and apply it to all MCU clocksync instances at klippy:mcu_identify.
• Include transmit_extra in clocksync debug output to aid diagnostics.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
klippy/clocksync.py	Makes transmit headroom configurable per ClockSync instance and uses it in clock estimation + debug output.
klippy/extras/danger_options.py	Adds config plumbing to set transmit_extra and propagates it to all MCU _clocksync objects during connect.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.