Configuring the effects

※Introduction

In the previous chapter, we discussed how to configure different types of LED strips. In this chapter, we will explain in detail how to set up lighting effects.

Let's assume we have a VORON 2.4 printer.

On the Stealthburner toolhead, we have installed an LED strip containing 3 SK6812 LEDs, and we have correctly specified the pin, number of LEDs, and color order in the led_effects.cfg file:

[neopixel hotend_light]
pin: EBBCan:gpio16      # Replace with the actual pin used for RGB LEDs
chain_count: 3          # Number of LEDs in the RGBW strip
color_order: GRBW       # Color order for RGBW LEDs

Additionally, we have installed two PCB strips on the frame, each containing 18 WS2812 LEDs. These strips are connected in parallel to the mainboard, with pin, LED count, and color order accurately configured in the led_effects.cfg file.

[neopixel frame_lights]
pin: PB0      # Replace with the actual pin used for RGB LEDs
chain_count: 18          # Number of LEDs in the RGBW strip
color_order: GRB       # Color order for RGBW LEDs

Please note that the above configuration is for reference only. When configuring in practice, be sure to use the actual pin names, the actual number of LEDs in the strip, and the correct color order.

-Parallel Connection

In a parallel connection, all LED strips display the same effect synchronously, and it is not possible to control a single LED independently.

-Series Connection

In a series connection, each LED can be precisely controlled, allowing for unique effects to be defined for each light.

※Experiment

Now we want all LED devices to light up with a breathing effect when the printer successfully starts and connects to Klipper. We have written a configuration and added it to the led_effects.cfg file, defining a custom lighting effect called light_start:

[led_effect light_start]
autostart: true
#recalculate:false
frame_rate: 24
leds:
    neopixel:hotend_light
    neopixel:frame_lights 
layers:
    breathing 10 1 top (.5, .5, 1)

After saving and restarting, you'll be pleasantly surprised to see that the configured LEDs all light up with a nearly white light, gradually increasing and decreasing in brightness, simulating the rhythm of breathing and creating a smooth brightness transition.

Next, we will break down the light_start effect configuration line by line, helping you understand the creation of lighting effects in detail.

---

• Line 1 [led_effect light_start] The led_effect field is fixed. After the space, enter the name you want to define, using _ to replace spaces in the name.

---

• Line 2 autostart: true

Entering true indicates that this light effect will automatically start when the printer powers on.

Entering false, which means the effect will not start automatically and will need to be activated manually.

---

Line 3 recalculate:false

Enable layer template recalculation on effect activation.

---

• Line 4 frame_rate: 24 This sets the frame rate of the effect (in frames per second).

---

• Line 5 leds: The leds label is fixed. Below this line, list the LED strips you want to use, prefixed with neopixel: followed by the LED name. For example, in the above configuration, we listed hotend_light and frame_light. You can choose to include one or more.Make sure there is no space between the colon and the LED strip name; otherwise, it may not be recognized.

 leds:
    neopixel:hotend_light
    neopixel:frame_lights

You can also specify which specific LEDs to display the effect by providing their indices after the strip name. The indices can be given as a list or a range. You can even invert the range to change the effect. If no indices are specified, the entire strip will be used.Additionally, if needed, the same strip can be included multiple times in an effect, allowing for different emitters to be specified.

Ensure there is a space between the LED strip name and the uppercase parentheses (), or copy directly from here: ().

Example:

leds: 
    neopixel:hotend_light (3-1)   # Uses LEDs 3 to 1 from hotend_light (inverted range)
    neopixel:frame_lights (1-9)    # Uses LEDs 1 to 9 from frame_light
    neopixel:frame_lights (18-10)  # Uses LEDs 18 to 10 from frame_light (inverted range)

---

• Line 8 layers: The layers label is fixed. Below this line, place the definitions for the lighting effect layers. Each line represents a layer, and you can define multiple layers and use special commands to blend them, a concept we can discuss in more detail later.

layers:
    breathing 10 1 top (.5, .5, 1)

---

※Effect Layer Analysis in Line 8

In the effect layer, we use a combination of words and numbers, which may seem complex at first glance. However, it can actually be broken down into five fundamental modules, each contributing to form a complete effect layer:

1. Layer Name Each layer has a unique name for identification and referencing. In the table below, there are 24 example layer names, such as breathing or linearfade. As the names suggest, the breathing layer achieves a breathing effect, while linearfade creates a linear fade-in and fade-out effect.

2. Effect Rate For most layers, this parameter controls the speed of the effect’s updates, typically measured in frames. For instance, setting it to 10 means the effect updates 10 times per second. However, in some specific effect layers, this parameter might have a different function.

3. Cutoff The cutoff parameter sets the starting or ending point of the effect, determining when the effect should begin or stop. Similar to the effect rate, cutoff may have varied meanings depending on the effect layer type.

4. Blending Mode Blending mode defines how the current layer combines with other layers. Common blending modes include add (overlay), subtract (subtraction), and others, which allow more complex effects. This is a more advanced feature, so if interested, you may explore additional details after this section.

5. Color Palette The length of the palette is unlimited, with colors defined as groups of red, green, blue, and (optional) white. The white channel is only used for RGBW LEDs and will be ignored on RGB LEDs. The range for each color is a decimal number from 0.0 to 1.0. For white, you can use (1.0, 1.0, 1.0) on RGB LEDs or (0.0, 0.0, 0.0, 1.0) on RGBW LEDs.

Depending on the type of layer, you can fill one or more color values in the palette. Each color must be enclosed in parentheses and separated by commas, with each color group also enclosed in parentheses.

Example 1 For instance, when using the linearfade layer, you can specify blue (0,0,1) and red (1,0,0). This will create a lighting effect that gradually transitions from blue to red over a 3-second period.

layers:  
       linearfade 3 0 top (0,0,1),(1,0,0)  

Example 2 When using the twinkle layer, you can fill the palette with colors like red: (1,0,0), orange: (1,0.647,0), yellow: (1,1,0), green: (0,1,0), cyan: (0,1,1), blue: (0,0,1), and purple: (0.5,0,0.5). This will create a lighting effect that randomly twinkles through seven colors, resembling a disco effect, right?

layers:  
       twinkle 50 .25 top (1,0,0),(1,0.647,0),(1,1,0),(0,1,0),(0,1,1),(0,0,1),(0.5,0,0.5)  

※ Layer typical example

1. Regular Effect Layers

Effect Name

static

Effect Rate

Not used，but must be provided

Cutoff

Not used，but must be provided

Palette Setting

Colors are blended evenly across the strip

Effect Explanation

A single color is displayed and it does not change. If a palette of multiple colors is provided, colors will be evenly blended along the LEDs based on difference in hue.

Effect Name

linearfade

Effect Rate

3 Duration of a complete cycle

Cutoff

0 Not used but must be provided

Palette Setting

Colors are cycled in order

Effect Explanation

LEDs fade through the colors. If a palette of multiple colors is provided, it will cycle through those colors in the order they are specified in the palette. The effect rate parameter controls how long it takes to go through all colors.

Effect Name

breathing

Effect Rate

3 Duration of a complete cycle

Cutoff

0 Not used but must be provided

Palette Setting

Colors are cycled in order

Effect Explanation

Colors fade in and out. If a palette of multiple colors is provided, it will cycle through those colors in the order they are specified in the palette. The effect rate parameter controls how long it takes to "breathe" one time.

Effect Name

blink

Effect Rate

1Duration of a complete cycle

Cutoff

0.5 Ratio of the time the LEDs are on (between 0 and 1)

Palette Setting

Colors are cycled in order

Effect Explanation

LEDs are turned fully on and fully off based on the effect speed. If a palette of multiple colors is provided, it will cycle through those colors in order.

Effect Name

strobe

Effect Rate

1Number of times per second to strobe

Cutoff

1.5Determines decay rate. A higher number yields quicker decay

Palette Setting

Colors are cycled in order.

Effect Explanation

LEDs are turned fully on and then faded out over time with a decay. If a palette of multiple colors is provided, it will cycle through those colors in order. The effect rate controls how many times per second the lights will strobe. The cutoff parameter controls the decay rate. A good decay rate is 1.5.

Effect Name

twinkle

Effect Rate

1 Increases the probability that an LED will illuminate. (0 = never, 254 = always)

Cutoff

.25Determines decay rate. A higher number yields quicker decaye

Palette Setting

Random color chosenith decay.

Effect Explanation

Random flashes of light with decay along a strip. If a palette is specified, a random color is chosen from the palette.

Effect Name

gradient

Effect Rate

1 How fast to cycle through the gradient, negative values change direction.

Cutoff

1Number of gradients on chain

Palette Setting

Linear gradient with even spacing.

Effect Explanation

Colors from the palette are blended into a linear gradient across the length of the strip. The effect rate parameter controls the speed at which the colors are cycled through. A negative value for the effect rate changes the direction the gradient cycles (right to left vs left to right). The Cutoff determines the length of the gradient in relation to the chain length. The bigger the value, the shorter the gradient (e.g. the value 2 means 2 gradients on the length of the chain)

Effect Name

pattern

Effect Rate

1Time between pattern shifts

Cutoff

1 How far the pattern gets shifted

Palette Setting

The pattern to be shifted

Effect Explanation

The palette is applied as a recurring pattern on the chain and shifted along the chain. The effect rate determines the time between the shifts in seconds, the cutoff determines the amount of LED positions the pattern gets shifted.

Effect Name

comet

Effect Rate

1 How fast the comet moves, negative values change direction

Cutoff

1 Length of tail (somewhat arbitrary)

Palette Setting

Color of "head" and gradient of "tail"

Effect Explanation

A light moves through the LEDs with a decay trail. Direction can be controlled by using a negative effect rate value. The palette colors determine the color of the comet and the tail. The first color of the palette defines the color of the "head" of the comet and the remaining colors are blended into the "tail"

Effect Name

chase

Effect Rate

1 How fast the comet moves, negative values change direction

Cutoff

1 Length of tail (somewhat arbitrary)

Palette Setting

Same as Comet Color of "head" and gradient of "tail"

Effect Explanation

Identical settings as Comet, but with multiple lights chasing each other.

Effect Name

fire

Effect Rate

45 Probability of "sparking"

Cutoff

40 Rate of "cooling"

Palette Setting

Color values to blend from "Cold" to "Hot"

Effect Explanation

The FastLED library for Arduino has a sample sketch called Fire2012WithPalette included with it. This effect is a port of that sketch. It simulates a flame by "sparking" an LED. The "heat" from that LED travels down the length of the LEDs where it gradually cools. A higher rate of sparking causes a greater amount of heat to accumulate at the base of the strip resulting a more intense flame. Changing the rate of cooling results in longer or shorter overall flames.

2. Heater Control Effect Layers

Specifies which heater to use for a heater effect. #Use extruder for the extruder heater and heater_bed for the bed heater. Example:

[led_effect light_start]
autostart: true
#recalculate:false
frame_rate: 24
leds:
    neopixel:hotend_light 
layers:
    temperature 10 200 top (0,0,1),(1,0,0)
heater: extruder 
#heater:heater_bed 
#heater:"temperature_fan myfan" 

For temperature fans or sensors, include the type in quotes.

Effect Name

heater

Effect Rate

1 Minimum temperature to activate effect

Cutoff

0 Disable effect once temp is reached

Palette Setting

Color values to blend from Cold to Hot

Effect Explanation

This effect activates when the heater is on or the temperature exceeds the minimum threshold. As the heater approaches its target temperature, LEDs cycle through gradient colors, holding the final color once the target is reached. If cutoff is specified, the effect disables at the target temperature. When the heater turns off, the colors reverse until the temperature falls below the minimum, signaling it’s safe to touch.

Effect Name

temperature

Effect Rate

20 Cold Temperature

Cutoff

80 Hot Temperature

Palette Setting

Color values to blend from "Cold" to "Hot"

Effect Explanation

The temperature of the configured heater determines the color in a gradient over the palette. When only one color is defined in the palette, the brightness of that color is defined by the temperature.

Effect Name

heaterhauge

Effect Rate

50 Number of trailing LEDs

Cutoff

0 Number of leading LEDs

Palette Setting

Color values to blend from "Cold" to "Hot"Color values to blend from "Cold" to "Hot"

Effect Explanation

The temperature of the heater relative from 0 to its target is represented by the first color in the palette. The remaining colors in the gradient are blended and mirrored on either side. As the heater heats up to it's target temperature, the lights move up the strip. A negative value in effect rate will fill the entire strip leading up to the temperature position, a negative value in cutoff will fill the entire strip after the temperature position.

Effect Name

temperaturegauge

Effect Rate

20 Cold Temperature

Cutoff

80 Hot Temperature

Palette Setting

Color values to blend

Effect Explanation

The temperature of the heater or temperature sensor relative from the cold temperature to the hot temperature its target is represented by the first color in the palette. The remaining colors form a gradient on the lower side of the strip.

Effect Name

heaterfire

Effect Rate

1Minimum temperature to activate effect

Cutoff

0 Disable effect once temp is reached

Palette Setting

Color values to blend from "Cold" to "Hot"

Effect Explanation

The fire effect but responsive to the temperature of the specified heater. The flame starts as a small ember and increases in intensity as the heater's target temperature is reached. If the cutoff parameter is set to 1, the effect will be disabled once the target temperature is reached, otherwise it will stay active until the heater is disabled.

3. Stepper Control Effect Layer

Specifies the axis to be used for the stepper effect. Possible values are x, y, and z.

[led_effect light_start]
autostart: true
#recalculate:false
frame_rate: 24
leds:
    neopixel:frame_lights 
layers:
    stepper 4 4 top (.5, .5, 1)
stepper:x

Effect Name

stepper

Effect Rate

4Number of trailing LEDs

Cutoff

4 Number of leading LEDs

Palette Setting

Color values to blend

Effect Explanation

The first color in the palette represents the position of the specified stepper motor, with the remaining gradient colors mirrored on either side. As the stepper moves along the axis, the lights shift up and down the strip. The effect updates the position every half second based on the stepper's reported position, similar to the GET_POSITION gcode command, but is not real-time. A negative effect rate fills the strip up to the stepper’s position, while a negative cutoff fills it after the position.

Effect Name

steppercolor

Effect Rate

1 Scaling of position

Cutoff

0 Offset of position

Palette Setting

DColor values to blend

Effect Explanation

The color of the LEDs are determined by the position of the stepper motor. The position is determined between 0 and 100 and is multiplied with the effect rate and the cutoff is added as offset. This then determines the value in the palette, that is calculated as a gradient over the specified color values.

Effect Name

progress

Effect Rate

4 Number of trailing LEDs

Cutoff

4 Number of leading LEDs

Palette Setting

Color values to blend

Effect Explanation

Exact same configuration as Stepper but instead of reporting stepper position, this layer reports print progress.

4. Limit Switch Trigger Effect Layer

Lists the endstops that the homing effect will trigger. You can specify multiple endstops as a comma-separated list. Possible values are x, y, z, and probe. #Example: endstops: x, y

[led_effect light_start]
autostart: true
#recalculate:false
frame_rate: 24
leds:
    neopixel:frame_lights 
layers:
    homing 1 0 top (.5, .5, 1)
endstops: x, y

Effect Name

homing

Effect Rate

1 Determines decay rate. A higher number yields slower decay

Cutoff

0 Not used, but must be provided

Palette Setting

Colors are cycled in order

Effect Explanation

Needs an endstop defined. LEDs turn on during homing when the endstop is triggered and fade out again. The effect rate determines the time for the fade out. If a palette of multiple colors is provided, it will cycle through those colors in order.

5. Button Trigger Effect Layer

Lists the pins that trigger the button effect. You can specify multiple pins as a comma-separated list, and the effect will trigger when any button is pressed. You can also use already assigned pins (like endstop pins) by employing duplicate_pin_override (refer to the Klipper documentation for more details). Example: button_pins: PC1, PC2.

[led_effect light_start]
autostart: true
#recalculate:false
frame_rate: 24
leds:
    neopixel:frame_lights 
layers:
    SwitchButton 1 1 top (.5, .5, 1)
button_pins: PC1, PC2

Effect Name

switchbutton

Effect Rate

1 Fade in time. Time until LEDs are on after button press

Cutoff

1Fade out time. Time until LEDs are off after button release

Palette Setting

Colors are cycled in order

Effect Explanation

Needs a button_pin defined. LEDs turn on when the button is pressed and turn off when the button is released again. Each press cycles through the colors of the palette.

Effect Name

togglebutton

Effect Rate

1 Fade in time. Time to fade in next color

Cutoff

1 Fade out time. Time to fade out previous color

Palette Setting

Colors are cycled in order

Effect Explanation

Needs a button_pin defined. Cycles through the colors with each button press. The transition times can be configured with the effect rate and cutoff parameters. Hint: Define (0,0,0) as a color if you want to toggle between on and off.

Effect Name

flashbutton

Effect Rate

00.1 Fade in time. Time to fade in.

Cutoff

1 Fade out time. Time to fade out.

Palette Setting

LEDs fade on with Colors are cycled in order

Effect Explanation

Needs a button_pin defined. When the button is pressed the LEDs fade on in the defined time and fade off immediately afterwards. If a palette of multiple colors is provided, it will cycle through those colors in order with each button press.

6.AnalogPin Effect Layers

Indicates the pin used for effects that rely on an analog signal.

[led_effect light_start]
autostart: true
#recalculate:false
frame_rate: 24
leds:
    neopixel:frame_lights 
layers:
    analogpin 10 40 top (.5, .5, 1)
analog_pin:PA1

Effect Name

analogpin

Effect Rate

10 M10 Multiplier for input signal

Cutoff

40 Minimum threshold to trigger effect

Palette Setting

Color values to blend

Effect Explanation

This effect uses the value read from an analog pin to determine the color. If multiple colors are specified in the palette, it chooses one based on the value of the pin. If only one color is specified, the brightness is proportional to the pin value. An example usage would be attaching an analog potentiometer that controls the brightness of an LED strip. Internally, input voltage is measured as a percentage of voltage vs aref. Another use could be to attach the RPM wire from a fan if the fan has a tachometer. It must be used with care as too much current or too high a voltage can damage a pin or destroy a controller board.

※Controlling the effects

Active vs. Inactive Effects

• Active effects generate color data, while inactive effects do not.

Activating and Deactivating Effects

• To activate an effect, use SET_LED_EFFECT EFFECT=light_start

• To replace all currently active effects with a new one, use SET_LED_EFFECT EFFECT=light_start REPLACE=1

• To stop a specific effect, use SET_LED_EFFECT EFFECT=light_start STOP=1

• To stop all effects, use STOP_LED_EFFECTS

• To stop effects on specific LEDs, specify the LEDs with STOP_LED_EFFECTS LEDS="neopixel:panel_ring", or indicate LED indices, e.g., STOP_LED_EFFECTS LEDS="neopixel:panel_ring (1-7)". Note: only one LED parameter can be specified per command.

Fading Effects

• To fade an effect in or out, specify FADETIME:

  • Fade in: SET_LED_EFFECT EFFECT=light_start FADETIME=1.0 (one second).

  • Fade out: SET_LED_EFFECT EFFECT=light_start STOP=1 FADETIME=1.0

  • To fade out all effects, use STOP_LED_EFFECTS FADETIME=1.0

• Crossfade between effects by combining REPLACE and FADETIME: SET_LED_EFFECT EFFECT=light_start REPLACE=1 FADETIME=1.0

Restarting Effects

• To resume an effect from its last state, start it normally. To restart from the beginning, add RESTART=1: SET_LED_EFFECT EFFECT=light_start RESTART=1.

Template Processing

Effect Layers as Templates

• Effects use templates similar to Klipper macros, though this can increase processing load.

• Layers are processed on effect creation. To re-evaluate layers each time an effect is activated, set recalculate to true.

Using Parameters

• With recalculate: true, effects can accept parameters. For example:

[led_effect param_effect]
autostart: false
recalculate: true
leds:
    neopixel:leds
layers:
    blink {params.DURATION|default(1)|float} {params.CYCLE|default(0.5)|float} top (1.0, 0.0, 0.0)

• To activate param_effect with custom parameters, use: SET_LED_EFFECT EFFECT=param_effect DURATION=3 CYCLE=0.2.

Setting Default Values

• Each parameter in the layers should have a default value, as effects are initially processed without GCode context.