Happy Hare / ERCF sous Klipper : le guide config 2026

Happy Hare est le pilote logiciel qui permet à Klipper de piloter un changeur de filament multicouleur (MMU) : un ERCF v2, un Box Turtle, un Tradrack ou une variante compatible. Concrètement, il ajoute à Klipper les macros et la logique nécessaires pour charger, décharger et changer de filament gate par gate. La configuration se fait en quatre temps : installer Happy Hare via son script, renseigner trois fichiers .cfg, calibrer l'encodeur puis chaque gate, et vérifier le comportement avant la première impression multicouleur.

Ce guide est une synthèse de la documentation officielle du projet (dépôt moggieuk/Happy-Hare et son wiki), des retours de la communauté Voron et des discussions du forum LesImprimantes3D. Il ne suppose aucun test physique : c'est un état de l'art curatorial pour vous éviter les erreurs de configuration les plus courantes.

Happy Hare, l'écosystème Klipper pour piloter un MMU

Un MMU (Multi Material Unit), ou changeur de filament, est un mécanisme qui sélectionne un filament parmi plusieurs et le pousse vers l'extrudeur. Happy Hare est la couche logicielle qui fait dialoguer ce mécanisme avec Klipper. Il ne remplace pas Klipper : il s'y greffe, comme une extension.

Sa force est d'être agnostique du matériel. Le même pilote gère plusieurs designs de MMU open source, chacun avec sa carte de contrôle MMU et son nombre de gates. Voici les principaux systèmes pris en charge.

Système MMU	Type de sélection	Gates typiques	Remarque
ERCF v2 (Enraged Rabbit Carrot Feeder)	Sélecteur mobile à servo	4, 8 ou 12	Le plus répandu, écosystème Voron mature
Box Turtle	Une motorisation par gate	4 (extensible)	Design AFC, pas de sélecteur mécanique
Tradrack	Sélecteur mobile	Variable	Alternative à l'ERCF, conception distincte
Night Owl	Une motorisation par gate	Variable	Design communautaire récent
3MS / 3D Chameleon	Variable selon build	4+	Systèmes modulaires alternatifs
BTT ViViD	Une motorisation par gate	Variable	Solution commerciale BigTreeTech

Deux grandes familles se dégagent. Les systèmes à sélecteur, comme l'ERCF, déplacent un chariot piloté par un servo pour présenter tour à tour chaque filament à un unique jeu de galets d'entraînement. Les systèmes AFC (Automated Filament Changer), comme le Box Turtle, suppriment ce sélecteur mécanique : chaque gate possède son propre moteur d'entraînement. Cette distinction change le câblage et la calibration, mais pas la logique pilotée par Happy Hare.

Cette compatibilité large explique pourquoi Happy Hare est devenu la référence du multicouleur DIY sous Klipper. Que vous montiez un ERCF v2 sur une Voron ou un Box Turtle sur une machine CoreXY, le pilote et sa logique restent identiques. Seule la configuration matérielle change.

Prérequis : Klipper, Moonraker et un MMU assemblé

Avant d'installer Happy Hare, trois éléments doivent déjà fonctionner. Un montage précipité est la première cause d'échec.

• Klipper opérationnel sur votre imprimante, avec une impression classique déjà réussie. Si Klipper n'est pas encore en place, commencez par notre guide d'installation de Klipper sur Raspberry Pi avant d'aller plus loin.
• Moonraker installé et connecté à une interface web (Mainsail ou Fluidd). Happy Hare s'appuie sur Moonraker pour ses mises à jour via l'update-manager.
• Un MMU physiquement assemblé et câblé : moteurs, capteurs et encodeur branchés sur la carte de contrôle MMU, tubes bowden en place. Le firmware de la carte MMU doit être flashé avec Klipper au préalable.

Vérifiez aussi que vous connaissez l'ID série ou l'UUID de la carte MMU. Vous en aurez besoin pour la section matérielle de la configuration. Un ls /dev/serial/by-id/ depuis le Raspberry Pi liste les cartes détectées.

Installer Happy Hare sur Klipper

L'installation passe par un script interactif fourni par le projet. Il crée les liens symboliques (symlink) vers le dossier de configuration Klipper et enregistre le dépôt dans Moonraker pour les mises à jour futures.

1. Connectez-vous en SSH au Raspberry Pi qui héberge Klipper.
2. Clonez le dépôt : git clone https://github.com/moggieuk/Happy-Hare.git dans le répertoire home.
3. Lancez l'installateur interactif : cd Happy-Hare puis ./install.sh -i.
4. Répondez aux questions : type de MMU (ERCF, Box Turtle, Tradrack…), nombre de gates, présence d'un encodeur, options de capteurs. Le mode -i génère les fichiers de configuration à partir de vos réponses.
5. Ajoutez le bloc update-manager à moonraker.conf si le script ne l'a pas fait automatiquement, pour suivre les versions.
6. Redémarrez Klipper et Moonraker, puis vérifiez qu'aucune erreur n'apparaît dans la console.

Le drapeau -i (interactif) est important : sans lui, le script suppose une configuration par défaut qui correspond rarement à votre build. Prenez le temps de répondre précisément — chaque réponse conditionne le contenu des fichiers générés. En cas de doute sur une valeur, le wiki du projet documente chaque question de l'installateur.

À noter : ce mode interactif -i ne sert qu'à la première installation. Une fois Happy Hare en place, les mises à jour ne repassent pas par ce script — elles se font via l'update-manager de Moonraker (bouton « Update » dans Mainsail ou Fluidd), ce qui préserve vos fichiers de configuration existants.

Comprendre les 3 fichiers de configuration

Happy Hare répartit sa configuration en trois fichiers que vous éditez à la main. Happy Hare génère aussi des fichiers automatiques — comme mmu_vars.cfg, où il stocke les valeurs de calibration, et mmu_macro_vars.cfg — que vous ne touchez pas directement. Cette séparation déroute au début, mais elle a une logique : matériel, comportement, et macros ne se modifient pas au même rythme.

mmu_hardware.cfg

Ce fichier décrit le matériel : pins des moteurs, endstops, capteurs, encodeur, et paramètres électriques des drivers. C'est ici que vous reliez la configuration à votre carte de contrôle MMU réelle. Une erreur de pin ou d'UUID se manifeste immédiatement par un moteur qui ne bouge pas ou tourne à l'envers.

mmu_parameters.cfg

Ce fichier contient le comportement : vitesses de chargement, longueurs de bowden, seuils de détection, options d'EndlessSpool. Ce sont les valeurs que vous ajusterez le plus souvent pendant la mise au point. La plupart des paramètres de calibration atterrissent ici.

mmu.cfg

Ce fichier regroupe les définitions internes et les inclusions. En pratique, vous n'y touchez presque jamais : il est géré par l'installateur et par les mises à jour. Le modifier à la main est rarement nécessaire et souvent source de conflits lors d'un update.

Retenez la règle simple : le matériel dans mmu_hardware.cfg, le comportement dans mmu_parameters.cfg, et on laisse mmu.cfg tranquille.

Calibrer le MMU dans le bon ordre

La calibration est l'étape qui sépare un MMU fiable d'un MMU qui bourre une impression sur deux. Happy Hare impose un ordre logique : on calibre du plus général au plus spécifique. Ne sautez aucune étape.

1. Encodeur : la commande MMU_CALIBRATE_ENCODER mesure la résolution de l'encodeur, c'est-à-dire combien de millimètres de filament correspondent à un pas mesuré. Tout le reste dépend de cette valeur. Sur les systèmes sans encodeur (comme le Box Turtle), cette étape est remplacée par d'autres capteurs.
2. Rotation distance du sélecteur ou des gears : elle définit la distance de déplacement pour chaque gate. Sur un ERCF, la rotation distance se calibre gate par gate car de légères variations mécaniques existent d'un gate à l'autre.
3. Longueur de bowden : la distance entre le MMU et l'extrudeur, mesurée pour chaque trajet.
4. Détection de bourrage (clog) : le paramètre mmu_calibration_clog_length définit le headroom, la marge de mouvement tolérée avant que Happy Hare ne considère qu'il y a un bourrage.

Un point souvent mal compris : la clog detection a deux modes. En mode statique (valeur 1), le seuil est fixe. En mode automatique (valeur 2), Happy Hare ajuste le headroom en continu selon le comportement observé. Le mode automatique réduit les fausses alertes une fois le système rodé, mais il demande d'abord quelques impressions pour se calibrer.

La logique de calibration gate par gate rappelle celle des réglages fins de l'extrudeur principal. Si vous avez déjà réglé votre pressure advance sous Klipper, vous retrouverez la même exigence de rigueur : une mesure approximative donne un résultat approximatif.

Pièges et erreurs fréquents

Les problèmes rapportés par la communauté se concentrent sur quelques causes récurrentes. Les connaître à l'avance fait gagner des heures.

Les fausses erreurs de bourrage

C'est le grief numéro un. Un headroom trop serré déclenche des alertes de clog alors que rien n'est bloqué. Le filament bouge normalement, mais la marge tolérée est trop faible. La solution consiste à augmenter mmu_calibration_clog_length progressivement, ou à passer en détection automatique une fois l'encodeur bien calibré.

Le Selector Touch difficile à régler

Sur l'ERCF, l'option Selector Touch utilise la détection de charge du moteur (sensorless) pour trouver la position des gates sans endstop physique. Séduisant sur le papier, ce mode est capricieux : il dépend de la tension des drivers et de la mécanique. Beaucoup de builds fonctionnent plus sereinement avec un endstop classique, au moins au démarrage.

La calibration gate par gate négligée

Calibrer un seul gate et copier la valeur sur tous les autres est une erreur courante. Les tolérances mécaniques font que chaque gate a sa propre rotation distance. Une calibration mutualisée fonctionne « à peu près », ce qui signifie qu'elle échoue de temps en temps — le pire scénario pour une impression multicouleur de plusieurs heures.

Le montage mécanique bâclé

Un tube bowden mal coupé, un raccord qui fuit ou une tension d'idler mal réglée sabotent toute la configuration logicielle. Happy Hare ne compense pas un montage imparfait. Avant de blâmer le logiciel, vérifiez la mécanique.

La friction du trajet bowden est le facteur de fiabilité le plus sous-estimé sur un MMU. Sur un ERCF, le filament parcourt un long chemin tortueux entre le sélecteur et la tête : plus la paroi interne du tube freine, plus le moteur des galets force, plus les erreurs de load et d'unload se multiplient. Les retours de la communauté r/ender3 et du Discord Enraged Rabbit convergent sur un point : un tube PTFE à très faible friction en diamètre 1,75 mm réduit sensiblement les bourrages sur les runs longs. Le Capricorn XS, coupé bien perpendiculairement, est une valeur sûre pour ce trajet.

KlipperScreen et pilotage quotidien

Une fois configuré, Happy Hare se pilote depuis l'interface web (Mainsail, Fluidd) ou depuis un écran tactile. Le projet fournit une KlipperScreen Happy Hare Edition, une version enrichie de l'écran tactile avec des panneaux dédiés au MMU : sélection de gate, chargement, éjection, état de chaque filament.

Au quotidien, deux fonctions structurent l'usage. Le changement de couleur, déclenché automatiquement par le G-code du slicer via les tours de purge, gère la transition entre filaments. Et l'EndlessSpool, qui bascule automatiquement sur un gate de rechange contenant le même filament quand un runout est détecté — pratique pour les longues impressions monocolores sur plusieurs bobines.

Pour un premier essai, préparez un fichier simple à deux couleurs. Vérifiez la purge et le tour de purge dans le slicer : une purge insuffisante mélange les couleurs, une purge excessive gaspille du filament. C'est un compromis à ajuster selon les matériaux.

Ce qui arrive avec Happy Hare v4

Le projet prépare un rework majeur, la version 4, qui apporte une modularité inédite. Aujourd'hui, un profil Happy Hare décrit un MMU homogène. La v4 vise à gérer des configurations dissemblables sur une même machine.

• MMU dissimilaires combinés : faire cohabiter un ERCF et un Box Turtle sur la même imprimante, chacun avec sa logique.
• Support IDEX : les machines à double extrudeur indépendant, où chaque tête peut avoir son propre changeur.
• Architecture modulaire : une refonte interne qui facilite l'ajout de nouveaux designs de MMU sans réécrire le cœur du pilote.

Cette évolution ne change pas la démarche de configuration décrite ici pour un MMU simple. Elle élargit le champ des montages possibles pour les builds avancés. Si vous débutez avec un seul ERCF ou un seul Box Turtle, la version stable actuelle reste la bonne base. Surveillez le changelog du dépôt pour suivre l'arrivée de la v4.

Questions fréquentes

Qu'est-ce que Happy Hare et à quoi ça sert ?

Happy Hare est un pilote open source qui permet à Klipper de commander un changeur de filament multicouleur (MMU). Il ajoute les macros de chargement, déchargement et changement de gate, plus la détection de bourrage et l'EndlessSpool. Sans lui, Klipper ne sait pas piloter un ERCF ou un Box Turtle.

Quelle est la différence entre ERCF, Box Turtle et Tradrack ?

L'ERCF et le Tradrack utilisent un sélecteur mobile qui se déplace pour choisir un filament parmi plusieurs. Le Box Turtle motorise chaque gate indépendamment, sans sélecteur mécanique. Les trois sont des designs open source différents, tous pilotés par le même Happy Hare sous Klipper.

Combien de couleurs peut gérer un ERCF ?

Les kits ERCF standard proposent 4, 8 ou 12 canaux selon la taille du build, 12 étant la configuration haute la plus répandue. La conception reste extensible en ajoutant des blocs. Happy Hare ne limite pas le nombre de gates : c'est la mécanique du MMU qui fixe le plafond réel.

Comment installer Happy Hare sur Klipper ?

Clonez le dépôt moggieuk/Happy-Hare sur le Raspberry Pi, puis lancez le script ./install.sh -i en mode interactif. Répondez aux questions (type de MMU, nombre de gates, encodeur), ajoutez le bloc update-manager à Moonraker, puis redémarrez Klipper. Le script génère les fichiers de configuration automatiquement.

Quels fichiers de configuration faut-il modifier ?

Trois fichiers structurent la configuration. Le matériel (pins, capteurs, encodeur) va dans mmu_hardware.cfg. Le comportement (vitesses, longueurs, seuils) va dans mmu_parameters.cfg. Le fichier mmu.cfg, géré par l'installateur, ne doit presque jamais être modifié à la main.

Comment calibrer l'encodeur de l'ERCF ?

Lancez la commande MMU_CALIBRATE_ENCODER dans la console Klipper. Elle mesure la résolution de l'encodeur, soit la correspondance entre les pas mesurés et les millimètres de filament réels. Cette valeur conditionne toutes les autres calibrations : faites-la en premier, avant la rotation distance et le bowden.

Pourquoi j'ai des fausses erreurs de bourrage (clog) ?

Un headroom trop serré est la cause la plus fréquente. Le paramètre mmu_calibration_clog_length définit la marge tolérée avant l'alerte. Augmentez-le progressivement, ou passez la clog detection en mode automatique (valeur 2) une fois l'encodeur bien calibré, pour laisser Happy Hare ajuster le seuil.

Faut-il activer Selector Touch ?

Pas au démarrage. Le Selector Touch remplace l'endstop du sélecteur par une détection sensorless, plus élégante mais capricieuse à régler car sensible à la tension des drivers. Beaucoup de builds ERCF fonctionnent plus sereinement avec un endstop physique classique. Activez le Selector Touch plus tard, une fois le système stable.

Happy Hare fonctionne-t-il avec KlipperScreen ?

Oui. Le projet fournit une KlipperScreen Happy Hare Edition, une version enrichie de l'écran tactile avec des panneaux dédiés au MMU : sélection de gate, chargement, éjection et état des filaments. Le pilotage reste aussi possible depuis Mainsail ou Fluidd via l'interface web classique.

Conclusion

Configurer Happy Hare pour un ERCF, un Box Turtle ou un Tradrack tient en une méthode : installer proprement via install.sh -i, comprendre le rôle des trois fichiers .cfg, puis calibrer dans l'ordre — encodeur d'abord, rotation distance gate par gate, bowden, clog detection ensuite. La majorité des échecs viennent d'une calibration bâclée ou d'un montage mécanique imparfait, pas du logiciel lui-même.

C'est un mod exigeant, mais c'est aussi le seul écosystème qui apporte le multicouleur DIY sérieux sous Klipper, avec une modularité que la version 4 va encore élargir. Prenez le temps de la calibration : un MMU bien réglé se fait oublier, un MMU mal réglé ruine chaque impression longue.