Klipper Macros: What They Are and How to Build Your Own Macro

Introduction

Klipper is a powerful open-source firmware for 3D printers. It offers plenty of options that enable users to fine-tune their printing experience. One of those tools is the macro system.

Macros allow you to automate complex sequences of commands in a direct way, streamlining your workflow and unlocking new functions.

In this guide, we will cover all aspects of Klipper macros: what they can do, the benefits of using them, how they should be written, and how to create your own macro and add it to your Klipper.

G-code vs. Macros: Understanding the Difference

Before we get into details about macros, let’s clarify some basics since when people talk about macros, there is often confusion with G-code. So, what exactly sets them apart?

What is G-Code?

G-Code is the language that 3D printers can understand. It's a set of instructions (commands and parameters) that tell the printer how to move, when to extrude filament, and how to control various aspects of the printing process.

What are macros?

On the other hand, macros are like custom shortcuts made with these G-code commands, but in the Jinja2 template language, which allows more complex things than just repeating simple G-codes one after another. They let you combine several G-code commands, along with logical statements, variables, and even other macros, into one named command. By using this simple command, you can execute complex actions.

How do macros work?

Macros can be executed by Klipper in response to specific triggers; below are examples of common triggers:

Direct Call

Think of this as calling the macro by name. You can simply use the macro name to call it so that it excites a series of pre-build commands.

This direct approach is useful when you want to integrate macros into your existing G-code scripts or send them manually through the console or by using the Klipper web interface.

Events

Klipper can automatically trigger macros in response to specific events during your print. For instance, you can have a macro that runs itself when:

• A print is finished successfully.
• The filament sensor detects a runout.
• A bed leveling procedure is completed.
• Reach a specific heat temperature.
• And many more!

This is based on how you pre-configured and programmed your macro.

Custom Triggers

If you're an experienced user, you can use Klipper's scripting to set up your own triggers. This gives you precise control and more customized options, allowing you to create advanced functions with high flexibility.

Benefits of using macros

Macros in the Klipper firmware can completely change how you approach 3D printing tasks. One significant benefit is the ability to automate repetitive tasks.

For example, consider the filament change process. If you frequently need to switch filaments during a print, writing a macro can streamline this task.

Instead of manually pausing the print, retracting the filament, loading the new filament, and resuming the print, a macro can perform all these actions with a single command.

Using macros means that all you have to do is click one button or write the macro name in your G-code, and all those actions will occur without any additional manual input from your side, saving a lot of time and effort.

Another advantage of using macros is that they allow you to define start and end G-code directly in the firmware, eliminating the need to manually add these commands to your slicing software every time.

This can be particularly useful if you decide to upgrade a component of your printer, like installing a BLTouch sensor for auto bed leveling. With the traditional method, the start G-code for ABL must be added in the slicer, meaning old sliced files won't work with the new setup because they lack the necessary G-code for auto bed leveling.

However, by adding a START_PRINT macro in the slicer's start print section, this macro will be executed by the firmware at the beginning of each print. This way, you only need to update the configuration for the macro to include the new G-code commands, such as those for the BLTouch sensor, without having to re-slice or edit all your old files.

This shifts the start-code functionality to the firmware itself and separates it from the sliced files, making it easier to update start commands in the future without modifying each generated G-code file.

Macros could also be helpful if you've sliced files for a different printer firmware and some commands are not recognized by Klipper. You can create a macro to translate these commands into ones that Klipper understands.

Macros allow you to pass filament metadata from the slicer to the printer. This information, such as filament type and layer height, can be displayed on the printer's interface. This makes it easier to manage your prints and keep track of filament usage.

Another benefit of macros is that they enable you to achieve functionalities not supported by Klipper out-of-the-box. For instance, you can create a macro that adjusts the mesh bed leveling area based on the size of your model, reducing print preparation time. There is already a pre-build macro that allows you to achieve that easily called Klipper bed mesh on print area only macro.

Being able to use logical conditions, variables, and even other macros in your macros in parallel with G-code commands makes you able to be creative and perform tasks that could not be performed before without relying on pure programming commands.

Now that we have understood what macros are, how they work, and what their benefits are, let’s move on to understand their structure and syntax. This will help you if you need to build your own macro.

Exploring the Syntax of macros

Klipper macros follow a simple syntax, making them easy to understand:

Let's break down these elements:

[gcode_macro <macro_name>]:

This line defines the start of the macro definition. Replace <macro_name> with your chosen name for the macro.

gcode::

This keyword indicates that the following lines are G-Code commands for the macro to execute.

<gcode_command_1> through <gcode_command_n>:

These lines represent the individual G-Code commands that make up the macro.

Example: A Simple Macro for Homing All Axes

If you call this macro “HOME_ALL,” it will home all axes of your printer.

Adding Dynamic Behavior to Macros with Variables

While static G-Code sequences are useful, true power lies in making your macros dynamic. Klipper achieves this by using variables with these macros:

Klipper offers a variety of predefined variables, such as printer.toolhead.position.x, printer.extruder.target, and others. These variables let you access the printer's status and parameters within your macros.

By using these variables, one can create advanced dynamic macros that can interact with the printer’s state.

Expanding the Functionality of Macros

The Jinja2 template language with Klipper offers a wide range of functionality that can be used to improve your macros beyond standard G-Code commands. Here's how it can be helpful:

Conditional Statements

With Klipper macros, you can use conditional statements like {% if %} and {% else %} to steer the flow of your macros based on certain conditions. This means that you can make decisions inside your macros.

For example, you can check if the extruder temperature is above a certain level and perform different actions accordingly. This allows your macros to be smarter and more responsive to the printer's state.

Looping

Klipper macros also support loops with {% for %}. This is useful for performing repetitive actions efficiently.

For instance, if you need to repeat a certain action several times, you can use a loop to do it automatically.

This can simplify your macros and reduce the amount of code you need to write.

Mathematical Operations

Basic arithmetic calculations may be performed directly within a macro using standard mathematical operators such as addition (+), subtraction (-), multiplication (*), or division (/). This allows values to change dynamically based on current conditions. 

For example, you can calculate the required fan speed or adjust the temperature settings on the fly.

Functions

Klipper has many built-in functions that make complex operations easier when creating a macro script.

These functions cover various areas, including string manipulation and temperature control, among others.

You can format strings so as to display messages on the printer screen or convert readings from one unit into another by applying these features to your codes.

Creating Your Own Macros

Now that you have a basic understanding of Klipper macros without getting overly technical, let's create a simple example to show you how to build your own macro. We'll make a macro that homes the X and Y axes and then moves the Z axis to a specific position.

Here's how you can do it:

 In this example, we named our macro HOME_XYZ. The macro first homes the X and Y axes using G28 X Y, then moves the Z axis to 30 mm above the bed using G0 Z30.

Here's how you can add this macro to your Klipper using the Fluidd interface:

• 1.Create a new file called macros.cfg in your Klipper configuration folder.

• 2.Open macros.cfg and copy/paste your macro code inside it.

Then click save and restart.

• 3.In your printer configuration file (e.g., printer.cfg), include the created macro library by adding the following line:

Then click save and restart.

Now, you can use these macros in your prints by simply calling their names in your G-code. Additionally, you can access and run these macros through the Klipper web interface; they will appear in the Macros section of your interface, whether you are using Fluidd or Mainsail. You can also execute them directly from the console.

Best Practices for Writing Macros in Klipper

To create a good macro in Klipper, you need to be clear and well-organized. First, define your macro. Give it a name that is representative of its function so that you can easily identify what it does when looking at your configuration later on.

Commenting your code is also important; it helps whoever is reading the code (including yourself after some time) understand what each part of the macro does. This becomes especially useful when dealing with complex macros or revisiting them later.

Keep it simple. Try to make your macros as clean and straightforward as possible. If one gets too long or complicated, try breaking it down into smaller parts instead; this not only makes things easier for others but simplifies troubleshooting and maintenance down the line too.

Before putting your macro into action on a live printer, test it thoroughly first to ensure everything works as expected. Doing so may help you catch mistakes or unanticipated behavior early, which could save you hours later.

Lastly, consider adding a description to your macro. Descriptions provide more context about what they do, which can be helpful for both yourself and others who may come across them in future configurations.

These tips will enable anyone using Klipper firmware to create clean and effective macros for their 3D printer!

Delving Deeper into Macros

If you're interested in learning more about Klipper macros, check out the Command Templates page in the Klipper documentation. It provides a detailed guide on how to use macros effectively, helping you enhance your printer's functionality. You can find the page here.

FAQs

Q: Can I use one macro inside another?

A: Yes, you can use a macro inside another macro in Klipper. This allows you to create more complex sequences of commands by nesting macros within each other. However, it's important to keep track of the execution order and ensure that the nested macros are called correctly to avoid unexpected behavior.

Q: Can macros control external devices connected to my 3D printer (e.g., lights or fans)?

A: Yes, macros can be used to send commands to external devices. This allows you to control additional hardware based on specific conditions or events in your print.

Q: Is there a limit on how many macros I can have?

A: There is no hard limit to the number of macros you can create in Klipper. However, it's advisable to keep your macros organized and avoid creating too many unnecessary macros to maintain a clear and manageable configuration.

Q: Can others use my macros?

A: Yes! Share your macro configuration file with other users, and they can include it in the firmware.

Q: What can I do if my macros are not working?

A: When macros malfunction, it is advisable to examine their code with regard to syntax and logic. Ensure that variables and conditions are rightly defined. Besides, Klipper documentation can be of help or else seek assistance from the Klipper community.

Q: Do safety measures need to be taken into account when using macros?

A: Safety precautions should be considered when using macros, especially those controlling hardware or making significant changes to printer settings. Make sure that your macro is well tested and does not pose any danger to the printer or workspace.

Conclusion

Klipper Macros represent one of the most powerful ways through which you can improve your 3D printing experience. By automating complex sequences of commands, they make work easier, save time as well as unlocking new functionalities. Whether you create them yourself or use already made ones, understanding how they operate will greatly improve your printing process.