MedusaHC Python Controller

Experimental Python controller for the MedusaHC toolchanger.

Support the project

https://irbis3d.xyz/

If this project is useful to you, you can support its continued development through Patreon, make a one-time contribution at Buy Me a Coffee, or use YouTube Super Thanks on the Irbis3D channel. Support helps fund parts, testing hardware and the time needed to maintain the project.

It moves tool pickup, parking, feeder control, priming, cleaning, offsets and sensor verification out of chained Klipper Jinja macros and into a Klipper extra. Existing public G-code command names remain available through a small replacement MHC_macros.cfg.

Warning

This is beta software for testing on an already configured and working MedusaHC installation. Keep a known-good backup and stay near the printer while testing tool changes. Do not update during a print.

What changes

Only two installed files need to change:

• medusahc.py is added to Klipper's klippy/extras directory.
• the existing MHC_macros.cfg is replaced by the file from this repository.

Your existing MHC_config.cfg, MHC_variables.cfg, tool coordinates, offsets, sensor pins and slicer command names stay in place. The existing MedusaHC pin_watch.py remains required.

Install

Read MIGRATION.md before copying anything. The short procedure is:

1. Back up the complete printer configuration and the current pin_watch.py.
2. Copy klippy/extras/medusahc.py to the same path inside your Klipper checkout.
3. Replace ~/printer_data/config/MHC_macros.cfg with config/MHC_macros.cfg.
4. Restart Klipper and test with the printer idle and heaters cold.

For BTT/BIQU images the usual Klipper path is /home/biqu/klipper/klippy/extras/. Raspberry Pi installations commonly use /home/pi/klipper/klippy/extras/. Use the actual path on your printer.

Compatibility defaults

The controller works when these newer optional variables are absent:

Variable	Default
TOOL_CFG.servo_open_angle	90
TOOL_CFG.servo_close_angle	180
TOOL_STATE_n.first_prime_enabled	1
TOOL_STATE_n.first_prime_prime_retract	0.2 mm
TOOL_STATE_n.first_prime_clean_retract	0.1 mm

Add them to MHC_variables.cfg only when you want explicit or per-tool values.

Documentation

• Migration
• Rollback
• Changelog

Scope

This repository contains only the experimental MedusaHC tool-change controller. It does not contain or require a web control panel.

License

GNU General Public License v3.0. See LICENSE.