Skip to content

MACROS.md

Latest commit

 

History

History
545 lines (443 loc) · 22.3 KB

MACROS.md

File metadata and controls

545 lines (443 loc) · 22.3 KB

3D Printer Macros Documentation

Warning: This page was fully generated by an AI model/ While efforts have been made to ensure accuracy, please verify the information against the original configuration files (base.cfg, headless.cfg, stock.cfg) for critical applications.

This document provides a concise overview of the G-code macros defined in the base.cfg, headless.cfg, and stock.cfg configuration files for a 3D printer running Klipper based Forge-X firmware modification. These macros enhance printer functionality, including bed leveling, filament management, system control, user interface interactions, and stock screen integration. Each macro is described with its parameters and default values where applicable.

Macros Overview

Bed Leveling and Calibration

  • BED_LEVEL_SCREWS_TUNE

    • Description: Performs bed screw tilt adjustment with temperature control and nozzle cleaning prompts.
    • Parameters:
      • EXTRUDER_TEMP (float, default: 130): Target extruder temperature (°C).
      • BED_TEMP (float, default: 80): Target bed temperature (°C).
    • Defaults: Cleans nozzle and adjusts screws after heating.

  • _CHECK_BED_MESH

    • Description: Validates the bed mesh by probing multiple points and checking tolerances.
    • Parameters:
      • TOLERANCE (float, default: printer.mod_params.variables.bed_mesh_validation_tolerance): Maximum allowable deviation (mm).
      • RETRACT (int, default: 0): Whether to retract filament during probing (1 = yes, 0 = no).
    • Defaults: Probes corner points to avoid bed screw holes.

  • AUTO_FULL_BED_LEVEL

    • Description: Automates full bed leveling and stops heating afterward.
    • Parameters:
      • EXTRUDER_TEMP (float, default: 240): Target extruder temperature (°C).
      • BED_TEMP (float, default: 80): Target bed temperature (°C).
      • PROFILE (string, default: "auto"): Bed mesh profile name.
    • Defaults: Calls _FULL_BED_LEVEL and stops heaters.

  • ZSHAPER

    • Description: Runs input shaper calibration and provides instructions for analyzing results.
    • Parameters: None.
    • Defaults: Clears previous calibration data and generates CSV files for analysis.

  • KAMP

    • Description: Executes KAMP-specific bed mesh calibration with nozzle cleaning.
    • Parameters:
      • EXTRUDER_TEMP (float, default: 240): Target extruder temperature (°C).
      • BED_TEMP (float, default: 80): Target bed temperature (°C).
    • Defaults: Clears bed mesh and performs KAMP calibration.

Filament Management

  • LOAD_FILAMENT

    • Description: Loads filament with a specified distance and speed, followed by a beep.
    • Parameters:
      • SPEED (int, default: 450): Extrusion speed (mm/min).
    • Defaults: Uses load_distance variable (125 mm).

  • UNLOAD_FILAMENT

    • Description: Unloads filament with a specified distance and speed, followed by a beep.
    • Parameters:
      • SPEED (int, default: 450): Retraction speed (mm/min).
    • Defaults: Uses unload_distance variable (75 mm).

  • PURGE_FILAMENT

    • Description: Purges filament with a specified distance and speed, followed by a beep.
    • Parameters:
      • SPEED (int, default: 450): Extrusion speed (mm/min).
    • Defaults: Uses purge_distance variable (25 mm).

  • LOAD_MATERIAL

    • Description: Guides manual filament loading/changing with material selection prompts.
    • Parameters: None.
    • Defaults: Prompts for material selection (PLA, PETG, ABS) if extruder is not preheated.

  • M600

    • Description: Pauses printing for filament switching, offering load/unload/purge options.
    • Parameters:
      • X (float, optional): X-coordinate for parking.
      • Y (float, optional): Y-coordinate for parking.
      • Z (float, optional): Z-coordinate for parking.
    • Defaults: Uses current position if coordinates are not specified.

  • COLDPULL

    • Description: Performs a cold pull to clean the nozzle, supporting multiple material types.
    • Parameters: None (material selection via prompt).
    • Defaults: Offers PETG (250°C/100°C), ABS (260°C/105°C), NYLON (265°C/120°C) options.

Nozzle Cleaning

  • CLEAR_NOZZLE

    • Description: Cleans the nozzle with a sequence of movements and temperature control.
    • Parameters:
      • EXTRUDER_TEMP (float, default: 230): Target extruder temperature (°C).
      • BED_TEMP (float, default: 80): Target bed temperature (°C).
    • Defaults: Probes left and right positions for Z-offset correction.

  • _CLEAR1, _CLEAR2, _CLEAR3, _CLEAR4

    • Description: Different nozzle cleaning algorithms for priming lines.
    • Parameters: None.
    • Defaults: Each follows a specific movement pattern to clean the nozzle.

Homing and Movement

  • G28

    • Description: Smart axis homing, parking specified or all axes with safety checks.
    • Parameters:
      • X (optional): Home X-axis.
      • Y (optional): Home Y-axis.
      • Z (optional): Home Z-axis.
    • Defaults: Homes all axes if no parameters are provided.

  • MOVE_SAFE

    • Description: Executes safe movements with boundary checks for X, Y, Z, and E axes.
    • Parameters:
      • X (float, optional): X-coordinate.
      • Y (float, optional): Y-coordinate.
      • Z (float, optional): Z-coordinate.
      • E (float, optional): Extrusion distance.
      • F (float, optional): Feed rate (mm/min).
      • ABSOLUTE (int, default: 0): Use absolute coordinates (1 = yes).
      • ABSOLUTE_E (int, default: 0): Use absolute extrusion (1 = yes).
    • Defaults: Ensures movements stay within X:[-110, 110], Y:[-110, 110], Z:[0, 220].

Temperature Control

  • _WAIT_TEMPERATURE

    • Description: Waits for the extruder or bed to reach a target temperature within tolerances.
    • Parameters:
      • CMD (string, required): M104 (extruder) or M140 (bed).
      • VALUE (int, required): Target temperature (°C).
      • TIMEOUT (int, default: 300): Timeout duration (seconds).
      • DELAY (int, default: 1000): Polling interval (ms).
      • ABOVE (float, default: 1): Upper tolerance (°C).
      • BELOW (float, default: 1): Lower tolerance (°C).
    • Defaults: Cancels if timed out or interrupted.

  • PID_TUNE_BED

    • Description: Calibrates PID for the bed heater at a specified temperature.
    • Parameters:
      • TEMPERATURE (int, default: 80): Target bed temperature (°C).
    • Defaults: Homes printer before calibration.

  • PID_TUNE_EXTRUDER

    • Description: Calibrates PID for the extruder at a specified temperature.
    • Parameters:
      • TEMPERATURE (int, default: 245): Target extruder temperature (°C).
    • Defaults: Homes and positions nozzle before calibration.

Air Circulation

Note

Flashforge uses reversed fan naming conventions ('external' refers to internal fans and vice versa).
The mod maintains this original (reversed) naming to ensure compatibility with the stock interface - changing it would break stock screen functionality

  • AIR_CIRCULATION_INTERNAL

    • Description: Turns on internal air circulation with fan and servo control.
    • Parameters: None.
    • Defaults: Sets internal fan to full speed, external fan off, servo angle to 95°.

  • AIR_CIRCULATION_EXTERNAL

    • Description: Turns on external air circulation with fan and servo control.
    • Parameters: None.
    • Defaults: Sets internal fan to full speed, external fan to 80%, servo angle to 180°.

  • AIR_CIRCULATION_STOP

    • Description: Stops all air circulation by disabling fans and resetting servo.
    • Parameters: None.
    • Defaults: Sets both fans to 0 speed, servo angle to 95°.

Audio and Notifications

  • TONE

    • Description: Plays a tone if sound is enabled, wrapping the original _TONE command.
    • Parameters:
      • NOTES (string, required): Tone sequence (e.g., "1479.98:150").
    • Defaults: Only plays if printer.mod_params.variables.sound is true.

  • M300

    • Description: Plays a tone with specified frequency and duration.
    • Parameters:
      • S (int, default: 1000): Frequency (Hz).
      • P (float, default: 100): Duration (ms).
    • Defaults: Calls TONE with formatted parameters.

  • M356

    • Description: Plays "Für Elise" using a sequence of tones.
    • Parameters: None.
    • Defaults: Fixed tone sequence for the melody.

  • BEEP

    • Description: Plays a short beep sequence.
    • Parameters: None.
    • Defaults: Plays "1479.98:150 50 1975.53:200".

  • ALARM

    • Description: Plays an alarm tone sequence.
    • Parameters: None.
    • Defaults: Plays "100:300 200 100:300".

  • PLAY_MIDI

    • Description: Plays a MIDI file if sound is enabled.
    • Parameters:
      • FILE (string, default: "For_Elise.mid"): MIDI file name.
    • Defaults: Only plays if printer.mod_params.variables.sound is true.

System Control

  • SHUTDOWN

    • Description: Shuts down the printer after clearing the bed mesh and syncing.
    • Parameters: None.
    • Defaults: Resets power-off pin and runs poweroff command.

  • REBOOT

    • Description: Reboots the printer after clearing the bed mesh and syncing.
    • Parameters: None.
    • Defaults: Resets power-off pin and runs reboot command.

  • REMOVE_MOD

    • Description: Prompts to uninstall the mod, with an option for soft removal.
    • Parameters: None.
    • Defaults: Offers full or soft removal via dialog.

  • REMOVE_MOD_SOFT

    • Description: Uninstalls the mod while preserving root access and configurations.
    • Parameters: None.
    • Defaults: Preserves root, audio, and MD5 settings.

  • SKIP_MOD

    • Description: Reboots to stock firmware, skipping mod loading.
    • Parameters: None.
    • Defaults: Sets SKIP_MOD flag and reboots.

  • SKIP_MOD_SOFT

    • Description: Reboots to stock firmware with SSH service enabled.
    • Parameters: None.
    • Defaults: Sets SKIP_MOD_SOFT flag and reboots.

  • STOP_MOD

    • Description: Stops Fluidd/Mainsail and Moonraker services.
    • Parameters: None.
    • Defaults: Runs S99root stop command.

  • START_MOD

    • Description: Starts Fluidd/Mainsail and Moonraker services.
    • Parameters: None.
    • Defaults: Runs S99root start command.

  • NEW_SAVE_CONFIG

    • Description: Saves configuration, using an alternative method for stock screens.
    • Parameters: None.
    • Defaults: Uses restart_klipper command for stock screens.

  • _MAYBE_AUTO_REBOOT

    • Description: Schedules an automatic reboot after a delay if enabled.
    • Parameters: None.
    • Defaults: Reboots after 90 seconds if printer.mod_params.variables.auto_reboot is non-zero.

  • _CANCEL_AUTO_REBOOT

    • Description: Cancels a scheduled automatic reboot.
    • Parameters: None.
    • Defaults: Cancels if reboot is active.

  • NEW_RESTART

    • Description: Reloads Klipper configuration, using a shell command for stock screens.
    • Parameters: None.
    • Defaults: Runs restart_klipper for stock screens.

Configuration and Backup

  • CONFIG_BACKUP

    • Description: Initiates a configuration backup.
    • Parameters:
      • DRY (int, default: 0): Dry run (1 = yes, 0 = no).
      • VERBOSE (int, default: 0): Verbose output (1 = yes, 0 = no).
    • Defaults: Performs full backup unless dry run is specified.

  • CONFIG_RESTORE

    • Description: Restores configuration from a backup.
    • Parameters:
      • DRY (int, default: 0): Dry run (1 = yes, 0 = no).
      • VERBOSE (int, default: 0): Verbose output (1 = yes, 0 = no).
    • Defaults: Restores unless dry run is specified.

  • CONFIG_VERIFY

    • Description: Verifies configuration against a backup.
    • Parameters:
      • VERBOSE (int, default: 0): Verbose output (1 = yes, 0 = no).
    • Defaults: Verifies configuration integrity.

  • TAR_BACKUP

    • Description: Creates a tar archive of the mod configuration.
    • Parameters: None.
    • Defaults: Runs zbackup --tar-backup.

  • TAR_DEBUG

    • Description: Creates an archive with debug information.
    • Parameters: None.
    • Defaults: Runs zbackup --tar-debug.

Stock Screen Integration

  • START_PRINT (stock.cfg)

    • Description: Initiates printing from the stock screen, validating parameters and setting print variables.
    • Parameters:
      • EXTRUDER_TEMP (float, required): Target extruder temperature (°C).
      • BED_TEMP (float, required): Target bed temperature (°C).
      • FORCE_KAMP (int, default: 0): Force KAMP bed leveling (1 = yes).
      • FORCE_LEVELING (int, default: 0): Force bed leveling (1 = yes).
      • SKIP_LEVELING (int, default: 0): Skip bed mesh creation (1 = yes).
      • SKIP_ZOFFSET (int, default: 1): Skip Z-offset for stock screen (1 = yes).
      • Z_OFFSET (float, default: 0.0): Z offset (mm).
      • MESH (string, default: ""): Bed mesh profile name.
    • Defaults: Validates parameters and calls _START_PRINT.

  • END_PRINT (stock.cfg)

    • Description: Finalizes printing with filament retraction, parking, and optional MIDI playback.
    • Parameters: None.
    • Defaults: Retracts 3 mm, moves to X105 Y105, plays MIDI if configured.

  • PAUSE

    • Description: Pauses printing by sending an M25 command to the stock firmware.
    • Parameters: None.
    • Defaults: Sends M25 via zsend.

  • RESUME

    • Description: Resumes printing by sending an M24 command to the stock firmware.
    • Parameters: None.
    • Defaults: Sends M24 via zsend.

  • CANCEL_PRINT

    • Description: Cancels printing by sending an M26 command, with logic to avoid redundant sends.
    • Parameters: None.
    • Defaults: Sends M26 once, stops printer, and closes dialogs if configured.

  • LEVELING_PRINT_FILE

    • Description: Prints a file from the stock screen with bed leveling, optionally checking MD5.
    • Parameters:
      • FILENAME (string, required): File to print.
    • Defaults: Performs MD5 check if enabled, sends print command via zprint.

  • NOLEVELING_PRINT_FILE

    • Description: Prints a file from the stock screen without bed leveling, optionally checking MD5.
    • Parameters:
      • FILENAME (string, required): File to print.
    • Defaults: Performs MD5 check if enabled, sends M23 via zsend.

  • CLOSE_DIALOGS

    • Description: Closes dialog windows on the stock screen using GDB.
    • Parameters: None.
    • Defaults: Runs close_dialogs command.

  • FAST_CLOSE_DIALOGS

    • Description: Closes dialog windows on the stock screen using the API.
    • Parameters: None.
    • Defaults: Runs zprint CLOSE CLOSE.

  • _MAYBE_CLOSE_DIALOGS

    • Description: Conditionally schedules dialog closure based on configuration.
    • Parameters: None.
    • Defaults: Schedules CLOSE_DIALOGS or FAST_CLOSE_DIALOGS if printer.mod_params.variables.close_dialogs is 1 or 2.

Miscellaneous

  • WAIT

    • Description: Pauses execution for a specified time.
    • Parameters:
      • TIME (float, default: 1): Pause duration (ms).
    • Defaults: Waits 1 ms if no time is specified.

  • SHELL

    • Description: Runs a shell command via bash.
    • Parameters:
      • CMD (string, required): Command to execute.
    • Defaults: Executes command in bash.

  • M108

    • Description: Cancels a heating wait command specific to the mod.
    • Parameters: None.
    • Defaults: Calls original M108.1.

  • SET_GCODE_OFFSET

    • Description: Sets a G-code offset, updating the global Z offset if changed.
    • Parameters:
      • X (float, optional): X offset (mm).
      • Y (float, optional): Y offset (mm).
      • Z (float, optional): Z offset (mm).
      • Z_ADJUST (float, optional): Z offset adjustment (mm).
    • Defaults: Updates printer.mod_params.variables.z_offset if Z changes.

  • LOAD_GCODE_OFFSET

    • Description: Restores the global Z offset.
    • Parameters: None.
    • Defaults: Uses printer.mod_params.variables.z_offset.

  • SET_FAN_SPEED

    • Description: Controls fan speed, ignoring the PCB fan.
    • Parameters:
      • FAN (string, required): Fan name.
      • SPEED (float, required): Speed (0 to 1).
    • Defaults: Ignores pcb_fan.

  • SET_LED

    • Description: Controls LED brightness, respecting screen LED disable settings.
    • Parameters:
      • LED (string, required): LED name (e.g., "chamber_light").
      • WHITE (float, required): Brightness (0 to 1).
    • Defaults: Skips if disable_screen_led is true for chamber LED.

  • _PRINT_STATUS

    • Description: Logs the current printer state.
    • Parameters:
      • S (string, required): State message.
    • Defaults: Logs to console with "//" prefix.

  • _ENSURE_SERVICES_STARTED

    • Description: Ensures services like camera and SSH are running.
    • Parameters: None.
    • Defaults: Starts services on initialization, reloads periodically.

  • TEST_EMMC

    • Description: Tests internal storage speed.
    • Parameters:
      • SIZE (int, default: 100): Test file size (MB).
      • PATH (string, default: "/data"): Test directory.
    • Defaults: Runs test with 100 MB file in /data.

  • CLEAR_EMMC

    • Description: Cleans internal storage with logging options.
    • Parameters:
      • LOG (int, default: 1): Enable logging (1 = yes).
      • ANY (int, default: 0): Clear all files (1 = yes).
    • Defaults: Logs by default, clears selectively unless ANY=1.

  • ZSSH_RELOAD

    • Description: Reloads the SSH tunnel if enabled.
    • Parameters: None.
    • Defaults: Runs if printer.mod_params.variables.zssh is true.

  • WEB

    • Description: Switches the default WebUI between Fluidd and Mainsail.
    • Parameters: None.
    • Defaults: Runs zhttp switch.

  • DATE_GET

    • Description: Prints the current date and time.
    • Parameters:
      • DT (string, default: ""): Optional format (unused).
    • Defaults: Runs date command.

  • DATE_SET

    • Description: Sets the date and time.
    • Parameters:
      • DT (string, default: "2024.01.01-00:00:00"): Date-time in format YYYY.MM.DD-HH:MM:SS.
    • Defaults: Sets to default if no value provided.

  • SET_TIMEZONE

    • Description: Changes the system timezone.
    • Parameters:
      • ZONE (string, default: "Europe/Moscow"): Timezone (e.g., "Asia/Yekaterinburg").
    • Defaults: Sets to Europe/Moscow if unspecified.

  • CAMERA_RELOAD

    • Description: Reloads camera parameters.
    • Parameters:
      • SILENT (int, default: 0): Suppress output (1 = yes).
    • Defaults: Runs S98camera reload.

  • CAMERA_RESTART

    • Description: Restarts the camera service.
    • Parameters: None.
    • Defaults: Runs S98camera restart.

  • MEM

    • Description: Prints memory usage.
    • Parameters: None.
    • Defaults: Runs zmem command.

  • _G17, G18, G19

    • Description: Warns about unsupported spiral/automatic Z-hop settings.
    • Parameters: None.
    • Defaults: Provides OrcaSlicer configuration advice.

Feather / Headless Specific Macros

  • START_PRINT (headless.cfg)

    • Description: Initiates printing with parameter validation and filament sensor control.
    • Parameters:
      • EXTRUDER_TEMP (float, required): Target extruder temperature (°C).
      • BED_TEMP (float, required): Target bed temperature (°C).
      • FORCE_KAMP (int, default: 0): Force KAMP bed leveling (1 = yes).
      • FORCE_LEVELING (int, default: 0): Force bed leveling (1 = yes).
      • SKIP_LEVELING (int, default: 0): Skip bed mesh creation (1 = yes).
      • SKIP_ZOFFSET (int, default: 1): Skip Z-offset (1 = yes).
      • Z_OFFSET (float, default: 0.0): Z offset (mm).
      • MESH (string, default: ""): Bed mesh profile name.
    • Defaults: Enables filament sensor if configured.

  • END_PRINT (headless.cfg)

    • Description: Finalizes printing with filament retraction, parking, and optional MIDI playback.
    • Parameters: None.
    • Defaults: Retracts 5 mm, parks at custom coordinates, plays MIDI or tone sequence.

  • _CANCEL_PRINT_WITH_AUDIO_WARNING

    • Description: Cancels printing with an audio warning and common end-print logic.
    • Parameters:
      • REASON (string, optional): Cancellation reason.
    • Defaults: Plays cancellation tones and calls _COMMON_END_PRINT.

  • _PAUSE_WITH_STATUS

    • Description: Pauses printing with a status tone.
    • Parameters: None.
    • Defaults: Plays "2093:120 140 1047:140".

  • _RESUME_WITH_STATUS

    • Description: Resumes printing with a status tone.
    • Parameters: None.
    • Defaults: Plays "1319:70 140 2093:140".

  • _COMMON_END_PRINT

    • Description: Common logic for ending or canceling prints, including stopping motors and resetting the screen.
    • Parameters: None.
    • Defaults: Stops heaters, fans, and schedules motor stop if configured.

  • _BACKLIGHT

    • Description: Adjusts display backlight brightness.
    • Parameters:
      • S (int, default: printer.mod_params.variables.backlight): Brightness (0-100).
    • Defaults: Clamps to 0-100 range.

  • M24

    • Description: Resumes printing (alias for RESUME).
    • Parameters: None.
    • Defaults: Calls RESUME.

  • M25

    • Description: Pauses printing (alias for PAUSE).
    • Parameters: None.
    • Defaults: Calls PAUSE.

Notes

  • Many macros rely on variables stored in printer.mod_params.variables, allowing dynamic configuration.
  • The stock.cfg file integrates with the printer’s stock firmware, using shell commands (zsend, zprint) to communicate with the stock screen.
  • The headless.cfg file extends base.cfg with macros tailored for alternative display implementations, such as Mainsail/Fluidd.
  • Macros like _START_PRINT and _CHECK_BED_MESH include extensive logic for safety and validation, ensuring robust printer operation.
  • Audio feedback (tones, MIDI) enhances user interaction, configurable via sound settings.
  • System control macros (e.g., SHUTDOWN, REBOOT, NEW_RESTART) provide seamless integration with the printer’s operating system.
  • Stock screen-specific macros (LEVELING_PRINT_FILE, NOLEVELING_PRINT_FILE) enable printing directly from the stock interface with optional bed leveling.

For detailed implementation, refer to the base.cfg, headless.cfg, and stock.cfg files.