klipper-nerdygriffin-macros

Hardware-agnostic Klipper macros for Voron printers with automatic AFC detection and per-printer customization.

Features

• 🎯 Filament Management - Smart load/unload/purge with AFC auto-detection
• 🎨 Status & LED Control - Dict-based LED system adapts to any hardware configuration
• 🔧 Maintenance Helpers - PID tuning, belt settling, nozzle changes
• 🌡️ Chamber Control - Auto-detecting heat soak with LED animations
• 📊 Safety Features - Safe shutdown, config saving, fan preflight checks
• 🔄 Client Integration - Pause/resume/cancel hooks for Mainsail/Fluidd

Included Macros

• auto_pid.cfg - Automated PID tuning
• beeper.cfg - M300 beeper/tone support
• belt_tension.cfg - Belt tension calibration and frequency measurement
• client.cfg - Mainsail/Fluidd integration with AFC support
• filament_management.cfg - Load/unload/purge operations with encoder sensor management
• gcode_features.cfg - Enables advanced G-code features (force_move, pause/resume, arcs, etc.)
• heat_soak.cfg - Chamber preheating with sensor auto-detection
• homing.cfg - Sensorless and conditional homing helpers
• maintenance_macros.cfg - Nozzle cleaning, nozzle changes, and developer diagnostics
• nozzle_wiper.cfg - Servo-actuated nozzle purge bucket and brush system
• positioning_macros.cfg - Toolhead positioning helpers (CENTER, and future FRONT/REAR/TOP)
• print_macros.cfg - PRINT_START/PRINT_END with AFC, Beacon, and bed mesh support
• rename_existing.cfg - Enhanced G-code overrides (M109, M190, M117)
• save_config.cfg - Safe SAVE_CONFIG with print-state detection
• shaketune.cfg - Shake&Tune wrapper macros
• shutdown.cfg - Safe shutdown with conditional cooling
• squiggly_purge.cfg - Squiggly/serpentine line purge pattern
• status_macros.cfg - Hardware-agnostic LED status patterns
• tacho_macros.cfg - Part cooling fan preflight checks

Installation

Automated Installation (Recommended)

cd ~
git clone https://github.com/NerdyGriffin/klipper-nerdygriffin-macros.git
cd klipper-nerdygriffin-macros
./install.sh

The install script will:

• Create symlink in your config directory
• Optionally configure Moonraker's update_manager
• Provide include statements for your printer.cfg

Manual Installation

1. Clone and create symlink:

   cd ~
   git clone https://github.com/NerdyGriffin/klipper-nerdygriffin-macros.git
   ln -sf ~/klipper-nerdygriffin-macros/macros ~/printer_data/config/nerdygriffin-macros

2. Add to moonraker.conf:

   [update_manager klipper-nerdygriffin-macros]
   type: git_repo
   path: ~/klipper-nerdygriffin-macros
   origin: https://github.com/NerdyGriffin/klipper-nerdygriffin-macros.git
   primary_branch: main
   is_system_service: False
   managed_services: klipper

3. Include in printer.cfg:

   [include nerdygriffin-macros/auto_pid.cfg]
   [include nerdygriffin-macros/beeper.cfg]              # Optional: Requires pin configuration
   [include nerdygriffin-macros/belt_tension.cfg]
   [include nerdygriffin-macros/client.cfg]
   [include nerdygriffin-macros/filament_management.cfg]
   [include nerdygriffin-macros/heat_soak.cfg]
   [include nerdygriffin-macros/maintenance_macros.cfg]
   [include nerdygriffin-macros/nozzle_wiper.cfg]        # Optional: Requires servo hardware
   [include nerdygriffin-macros/positioning_macros.cfg]
   [include nerdygriffin-macros/print_macros.cfg]        # Optional: PRINT_START/PRINT_END
   [include nerdygriffin-macros/rename_existing.cfg]
   [include nerdygriffin-macros/save_config.cfg]
   [include nerdygriffin-macros/shaketune.cfg]           # Optional: Requires Shake&Tune
   [include nerdygriffin-macros/shutdown.cfg]
   [include nerdygriffin-macros/status_macros.cfg]
   [include nerdygriffin-macros/tacho_macros.cfg]

4. Restart Klipper:

   sudo systemctl restart klipper

Configuration

Most macros work out-of-the-box with sensible defaults. Per-printer customization is done via variable overrides in printer.cfg.

Quick Start - Minimal Configuration:

# Client macro integration (required for pause/resume)
[gcode_macro _CLIENT_VARIABLE]
variable_user_pause_macro : "_AFTER_PAUSE"
variable_user_resume_macro: "_BEFORE_RESUME"
variable_user_cancel_macro: "_BEFORE_CANCEL"
gcode:

# LED configuration (required for status_macros.cfg)
[gcode_macro _LED_VARS]
variable_leds: {
    'logo': {'toolhead': 1},
    'nozzle': {'toolhead': '2-3'},
    'chamber': {}
}
gcode:

Hardware Compatibility

AFC (Armored Filament Changer)

Automatically detects and uses AFC macros when available:

• AFC_PARK, AFC_BRUSH, AFC_CUT

Voron V0, V2, Trident, etc

All macros calculate positions dynamically based on configured bed size and axis limits.

LED Hardware

Dict-based _LED_VARS system supports any combination of neopixels across toolhead, logo, chamber, and bed zones.

Dependencies

Provided by this plugin:

• STATUS_* macros, RESET_STATUS — LED status indicators (status_macros.cfg)
• _CG28 — Conditional homing (homing.cfg)
• _AFTER_PAUSE, _BEFORE_RESUME, _BEFORE_CANCEL — Client hooks (client.cfg)

Required:

• SET_DISPLAY_TEXT — LCD display messages; provided by Klipper natively or Mainsail config

Optional — used if present:

• _CLIENT_VARIABLE — Parking coordinates and speeds; provided by Mainsail config
• encoder_sensor — Filament motion sensor (hardware config entry)
• Shake&Tune — Required for shaketune.cfg
• KAMP — Used by print_macros.cfg if available

Minimum Klipper version: v0.13.0+

See docs/DEPENDENCIES.md for the full cross-file dependency graph and the required-vs-optional breakdown of which macro files depend on each other.

Documentation

Macro File	Description
auto_pid.cfg	Extruder and bed heater PID tuning
beeper.cfg	Hardware-specific pin setup for audio feedback
belt_tension.cfg	Belt tension calibration and frequency measurement
client.cfg	Mainsail/Fluidd pause/resume/cancel integration
filament_management.cfg	Load, unload, and purge with AFC auto-detect
gcode_features.cfg	Enables advanced G-code features (force_move, pause/resume, arcs, etc.)
heat_soak.cfg	Chamber preheating with LED animations
homing.cfg	Sensorless and conditional homing helpers
idle_timeout.cfg	Idle cooldown, parking, and paused-print handling
maintenance_macros.cfg	Nozzle cleaning, nozzle changes, and developer diagnostics
nozzle_wiper.cfg	Servo-based nozzle cleaning with calibration guide
print_macros.cfg	PRINT_START/PRINT_END with hardware detection
rename_existing.cfg	Safe G-code command overrides
save_config.cfg	Configuration persistence and delayed saves
shaketune.cfg	Input shaper analysis wrappers
shutdown.cfg	Safe shutdown and host reboot operations
status_macros.cfg	LED system setup and customization
tacho_macros.cfg	Fan tachometer monitoring and pre-flight checks
positioning_macros.cfg	Toolhead positioning helpers

Development

Document	Description
dev/MARKDOWN_STYLE_GUIDE.md	Documentation (Markdown) formatting standards
dev/MACRO_STYLE_GUIDE.md	Klipper macro .cfg file structure standards
dev/GIT_HOOKS.md	Markdown lint pre-commit hook setup
dev/TODO.md	Development task tracking

Contributing

Contributions are welcome! Please submit a Pull Request.

License

GNU General Public License v3.0 - See LICENSE

Credits

Created by NerdyGriffin

Inspired by:

• AFC-Klipper-Add-On
• Voron Design
• Mainsail

Adapted from:

• Chirpy's Nozzle Wiper v2 — nozzle_wiper.cfg
• mjonuschat's Squiggly Purge — squiggly_purge.cfg

Support

For issues or questions, join the Voron Discord.