Skip to content

Releases: PrintStructor/klipper-toolchanger-extended

v1.0.1 – tool loss & error recovery bugfixes

26 Nov 21:12
@PrintStructor PrintStructor
v1.0.1
dc6877c

Choose a tag to compare

View all tags
v1.0.1 – tool loss & error recovery bugfixes Latest
Latest

v1.0.1 – tool loss & error recovery bugfixes

Summary

This release introduces several critical bug fixes to the toolchanger error
recovery flow and tool loss detection, and prepares the 1.0.1 patch release.

The changes make error recovery more reliable when pickup errors and tool loss
occur in the same print, fix incorrect Z-offset calculations, and prevent
false tool loss alarms after a print has finished.

Bug Fixes

1. Pause/Resume state corruption after pickup error (toolchanger.py)

  • Issue: After pickup error recovery, subsequent tool loss detection would
    no longer pause the print, causing the printer to continue moves without an
    attached tool.
  • Root cause: Only the is_paused flag was cleared, while sd_paused and
    pause_command_sent remained True, blocking further PAUSE commands.
  • Fix: Use pause_resume.send_resume_command() to properly clear all
    pause-related flags in a Klipper-compatible way.
  • Impact: Tool loss detection now correctly pauses the print again even
    after a prior pickup error recovery.

2. Z-offset double-setting during recovery (toolchanger.py)

  • Issue: During recovery, the Z-offset was effectively applied twice with
    different values, causing an incorrect final Z-offset for the active tool.

  • Root cause: extra_z_offset calculation did not account for the global
    Z offset and treated it like an additional "baby stepping" offset.

  • Fix: Corrected the calculation to:

    extra_z_offset = current_z_offset - (tool_z_offset + global_z_offset)

  • Impact: The Z-offset is now applied exactly once with the expected value,
    restoring correct Z positioning after recovery.

3. Tool loss false alarms after print end (tool.py + toolchanger_macros.cfg)

  • Issue: Manual tool changes after CANCEL_PRINT or after a completed print
    incorrectly triggered the tool loss alarm logic.
  • Root cause: The detection logic only checked that the toolchanger state
    was READY, without verifying whether a print was actually active.
  • Fix: Added checks for virtual_sdcard.is_active() and
    pause_resume.is_paused in tool.py before calling _handle_tool_loss(), and
    adjusted the macros accordingly.
  • Impact: Manual tool changes after print completion or cancellation now
    work silently without generating false tool loss alarms.

Example Configs

  • Added or updated a complete working configuration for a VORON 2.4
    6-tool ATOM setup in the examples directory, which serves as the
    reference configuration for this project.

Testing

  • Tested on a VORON 2.4 (350 mm) with a 6-tool ATOM toolchanger.
  • Verified the following scenarios:
    • ✅ Pickup error recovery (temperature, position, resume behaviour)
    • ✅ Tool loss detection (pause and resume) during active prints
    • ✅ Pickup error → subsequent tool loss in the same print (no state corruption)
    • ✅ Manual tool changes after CANCEL_PRINT (no tool loss alarm)
    • ✅ Manual tool changes after a successfully finished print (no tool loss alarm)

Breaking Changes

None. All changes are backwards compatible and focus solely on improving
robustness and correctness of existing behaviour.

Assets 2
Loading

v1.0.0 - Initial Release

20 Nov 18:20
@PrintStructor PrintStructor
v1.0.0
f162294

Choose a tag to compare

View all tags
v1.0.0 - Initial Release

🎉 klipper-toolchanger-extended v1.0.0

First official release of the extended toolchanger framework!

✨ Features

Safety Enhancements

  • Two-stage tool pickup with verification
  • Continuous tool presence monitoring during prints
  • Automatic heater shutoff on tool loss
  • Pause-based error recovery

Complete Configuration

  • 6-tool VORON 2.4 setup with ATOM toolheads
  • All macros and safety checks pre-configured
  • LED status integration
  • CPAP shuttle cooling support

Calibration Workflows

  • NUDGE probe for XY offset measurement
  • Beacon contact probe for Z offset calibration
  • Automated calibration workflows
  • SAVE_CONFIG integration

Flexibility

  • Any tool can be initial reference (not limited to T0)
  • Per-tool input shaper profiles
  • Optional KNOMI display support

📦 What's Included

  • Python Modules - Klipper extensions with safety features
  • Complete Config - Working 6-tool ATOM TC example
  • Documentation - Comprehensive guides for all user levels
  • Installation Script - Automated setup with Moonraker integration

🔧 Requirements

  • Klipper v0.11.0 or newer
  • Multi-tool printer with docks and sensors
  • Python 3.7+ (included with Klipper)

External Dependencies

Required:

Recommended:

📚 Documentation

🙏 Credits

Based on:

Hardware:

  • ATOM toolhead by Alex (APDMachine) - Creator of Reaper Toolhead
  • Shuttle system inspired by ClickChanger/Stealthchanger
  • Dock design influenced by Modular Docks concepts

⚠️ Important Notes

This is production-ready software, but:

  • Always start with slow speeds during testing
  • Keep emergency stop accessible
  • Monitor initial tool changes closely
  • Verify mechanical alignment regularly

📄 License

GPL-3.0 - See LICENSE file

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md

Full Changelog: Initial release

Loading