# irbis3d/medusahc architecture

> Architecture diagram of the GitHub repository irbis3d/medusahc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/irbis3d/medusahc
- Repository: https://github.com/irbis3d/medusahc

## Overview

MedusaHC is a Klipper hotend toolchanger: the controller handles tool pickup/drop and preparation, while pin sensing can infer the mounted tool and optionally synchronize Klipper’s toolchanger and UI state. The repository also supplies printer configuration, printable mechanical assemblies, reference STEP models, and slicer profiles. Source excerpts show controller behavior and sensor dispatch; the configuration and hardware branches are documented in the README, but their internal links are not established by the sampled source.

Main entry points: [`klippy/extras/pin_watch.py`](https://github.com/irbis3d/medusahc/blob/main/klippy/extras/pin_watch.py) (Pin-state monitor), [`klippy/extras/medusahc.py`](https://github.com/irbis3d/medusahc/blob/main/klippy/extras/medusahc.py) (Tool-change controller), [`Slicer`](https://github.com/irbis3d/medusahc/tree/main/Slicer) (Slicer projects), [`config/MedusaHC`](https://github.com/irbis3d/medusahc/tree/main/config/MedusaHC) (MedusaHC configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Klipper Runtime"]
  node_controller["Tool-change controller<br/>[medusahc.py]"]
  node_pinwatch["Pin-state monitor<br/>[pin_watch.py]"]
  node_klipper["Klipper services"]
  node_toolchanger["Klipper toolchanger"]
  node_ui["Mainsail / Fluidd UI"]
end

subgraph group_config["Printer Setup"]
  node_cfg["MedusaHC configuration"]
  node_examples["Printer examples"]
end

subgraph group_hardware["Mechanical System"]
  node_base["Dock and base parts"]
  node_feeder["Feeder parts"]
  node_hotend["Hotend parts"]
  node_toolhead["Toolhead parts"]
  node_mounts["Layout mounts"]
  node_backmounts["V-Back mounts"]
  node_assembly["Reference assemblies"]
end

subgraph group_workflow["Print Workflow"]
  node_slicer["Slicer projects"]
  node_postprocess["G-code post-processors<br/>[SET_FINISH.py]"]
end

node_printer(("Printer operator"))
node_optionalcal["MedusaHC-Calibrate"]
node_controlpanel["MedusaHC Control"]

node_printer -->|"requests tool change"| node_controller
node_controller -->|"runs motion commands"| node_klipper
node_controller -->|"reads geometry settings"| node_cfg
node_pinwatch -->|"registers pin callbacks"| node_klipper
node_pinwatch -->|"dispatches sync commands"| node_toolchanger
node_pinwatch -->|"syncs tool indicators"| node_ui
node_printer -->|"sets up printer"| node_cfg
node_printer -->|"adapts example configs"| node_examples
node_printer -->|"reviews reference layout"| node_assembly
node_printer -->|"slices tool-change jobs"| node_slicer
node_slicer -.->|"runs G-code processing"| node_postprocess
node_printer -.->|"installs separately"| node_optionalcal
node_printer -.->|"installs separately"| node_controlpanel

click node_controller "https://github.com/irbis3d/medusahc/blob/main/klippy/extras/medusahc.py"
click node_pinwatch "https://github.com/irbis3d/medusahc/blob/main/klippy/extras/pin_watch.py"
click node_cfg "https://github.com/irbis3d/medusahc/tree/main/config/MedusaHC"
click node_examples "https://github.com/irbis3d/medusahc/tree/main/examples/printer-config"
click node_base "https://github.com/irbis3d/medusahc/tree/main/STLs/Base"
click node_feeder "https://github.com/irbis3d/medusahc/tree/main/STLs/Feeder"
click node_hotend "https://github.com/irbis3d/medusahc/tree/main/STLs/Hotend"
click node_toolhead "https://github.com/irbis3d/medusahc/tree/main/STLs/Toolhead"
click node_mounts "https://github.com/irbis3d/medusahc/tree/main/STLs/V-Front%20Mounts"
click node_backmounts "https://github.com/irbis3d/medusahc/tree/main/STLs/V-Back%20Mounts"
click node_assembly "https://github.com/irbis3d/medusahc/tree/main/STEP"
click node_slicer "https://github.com/irbis3d/medusahc/tree/main/Slicer"
click node_postprocess "https://github.com/irbis3d/medusahc/blob/main/Scripts/SET_FINISH.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_controller,node_pinwatch,node_klipper,node_toolchanger,node_ui toneBlue
class node_cfg,node_examples toneAmber
class node_base,node_feeder,node_hotend,node_toolhead,node_mounts,node_backmounts,node_assembly toneMint
class node_slicer,node_postprocess toneRose
class node_printer,node_optionalcal,node_controlpanel toneIndigo
```

## Components

### Klipper Runtime

- [Tool-change controller](https://github.com/irbis3d/medusahc/blob/main/klippy/extras/medusahc.py): `klippy/extras/medusahc.py`
- [Pin-state monitor](https://github.com/irbis3d/medusahc/blob/main/klippy/extras/pin_watch.py): `klippy/extras/pin_watch.py`
- **Klipper services**
- **Klipper toolchanger**
- **Mainsail / Fluidd UI**

### Printer Setup

- [MedusaHC configuration](https://github.com/irbis3d/medusahc/tree/main/config/MedusaHC): `config/MedusaHC`
- [Printer examples](https://github.com/irbis3d/medusahc/tree/main/examples/printer-config): `examples/printer-config`

### Mechanical System

- [Dock and base parts](https://github.com/irbis3d/medusahc/tree/main/STLs/Base): `STLs/Base`
- [Feeder parts](https://github.com/irbis3d/medusahc/tree/main/STLs/Feeder): `STLs/Feeder`
- [Hotend parts](https://github.com/irbis3d/medusahc/tree/main/STLs/Hotend): `STLs/Hotend`
- [Toolhead parts](https://github.com/irbis3d/medusahc/tree/main/STLs/Toolhead): `STLs/Toolhead`
- [Layout mounts](https://github.com/irbis3d/medusahc/tree/main/STLs/V-Front%20Mounts): `STLs/V-Front Mounts`
- [V-Back mounts](https://github.com/irbis3d/medusahc/tree/main/STLs/V-Back%20Mounts): `STLs/V-Back Mounts`
- [Reference assemblies](https://github.com/irbis3d/medusahc/tree/main/STEP): `STEP`

### Print Workflow

- [Slicer projects](https://github.com/irbis3d/medusahc/tree/main/Slicer): `Slicer`
- [G-code post-processors](https://github.com/irbis3d/medusahc/blob/main/Scripts/SET_FINISH.py): `Scripts/SET_FINISH.py`

### Other components

- **Printer operator**
- **MedusaHC-Calibrate**
- **MedusaHC Control**

## Connections

- Printer operator → Tool-change controller: requests tool change (evidence: `README.md`)
- Tool-change controller → Klipper services: runs motion commands (evidence: `klippy/extras/medusahc.py`)
- Tool-change controller → MedusaHC configuration: reads geometry settings (evidence: `klippy/extras/medusahc.py`)
- Pin-state monitor → Klipper services: registers pin callbacks (evidence: `klippy/extras/pin_watch.py`)
- Pin-state monitor → Klipper toolchanger: dispatches sync commands (evidence: `klippy/extras/pin_watch.py`)
- Pin-state monitor → Mainsail / Fluidd UI: syncs tool indicators (evidence: `klippy/extras/pin_watch.py`)
- Printer operator → MedusaHC configuration: sets up printer (evidence: `README.md`)
- Printer operator → Printer examples: adapts example configs (evidence: `README.md`)
- Printer operator → Reference assemblies: reviews reference layout (evidence: `README.md`)
- Printer operator → Slicer projects: slices tool-change jobs (evidence: `README.md`)
- Slicer projects → G-code post-processors: runs G-code processing
- Printer operator → MedusaHC-Calibrate: installs separately (evidence: `README.md`)
- Printer operator → MedusaHC Control: installs separately (evidence: `README.md`)
