# 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: ```ini [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. ```ini [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 ``` {% hint style="success" %} 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. {% endhint %}

## ※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.* ```plaintext 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. ```plaintext 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	Effect Rate	Cutoff	Palette Setting	Effect Explanation
`static`	Not used，but must be provided	Not used，but must be provided	Colors are blended evenly across the strip	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.	花瓣素材_彩虹背景。_129172061.jpg
`linearfade`	`3` Duration of a complete cycle	`0` Not used but must be provided	Colors are cycled in order	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.	349dbbb2-eacb-4926-a5f8-127eae3498b3.webp
`breathing`	`3` Duration of a complete cycle	`0` Not used but must be provided	Colors are cycled in order	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.	cd946664-6c4c-4fc9-905b-b66919af5136.webp
`blink`	`1`Duration of a complete cycle	`0.5` Ratio of the time the LEDs are on (between 0 and 1)	Colors are cycled in order	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.	7e5baf45-3b0d-4008-bda2-f357267f1cc7.webp
`strobe`	`1`Number of times per second to strobe	`1.5`Determines decay rate. A higher number yields quicker decay	Colors are cycled in order.	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.	e04c0486-d0d3-41b1-ac49-9db3b3563d1b.webp
`twinkle`	`1` Increases the probability that an LED will illuminate. (0 = never, 254 = always)	`.25`Determines decay rate. A higher number yields quicker decaye	Random color chosenith decay.	Random flashes of light with decay along a strip. If a palette is specified, a random color is chosen from the palette.	884b623d-ca45-4bfd-98ae-224966408e27.webp
`gradient`	`1` How fast to cycle through the gradient, negative values change direction.	`1`Number of gradients on chain	Linear gradient with even spacing.	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)	7e254abc-00a1-4109-959f-0e3f42c6e060.webp
`pattern`	`1`Time between pattern shifts	`1` How far the pattern gets shifted	The pattern to be shifted	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.	d0056404-f382-4545-b444-29f2c92e4925.webp
`comet`	`1` How fast the comet moves, negative values change direction	`1` Length of tail (somewhat arbitrary)	Color of "head" and gradient of "tail"	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"	7ca66e5d-d60d-4259-9006-e942c3dca164.webp
`chase`	`1` How fast the comet moves, negative values change direction	`1` Length of tail (somewhat arbitrary)	Same as Comet Color of "head" and gradient of "tail"	Identical settings as Comet, but with multiple lights chasing each other.	eabafb98-b9b8-4b40-b3c9-a584706b5aa0.webp
`fire`	`45` Probability of "sparking"	`40` Rate of "cooling"	Color values to blend from "Cold" to "Hot"	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.	d06b3499-6c71-4a00-8783-39ec85665518.webp

### 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: ```ini [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" ``` {% hint style="info" %} For temperature fans or sensors, include the type in quotes. {% endhint %}

Effect Name	Effect Rate	Cutoff	Palette Setting	Effect Explanation
`heater`	`1` Minimum temperature to activate effect	`0` Disable effect once temp is reached	Color values to blend from Cold to Hot	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.	d1c0c9c7-8ac0-4408-a7a9-6275f87bf6d2.webp.png
`temperature`	`20` Cold Temperature	`80` Hot Temperature	Color values to blend from "Cold" to "Hot"	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.	4a60afda-a90b-4965-9a4d-a4bb9fa101c8.webp
`heaterhauge`	`50` Number of trailing LEDs	`0` Number of leading LEDs	Color values to blend from "Cold" to "Hot"Color values to blend from "Cold" to "Hot"	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.	b8f4abc5-c108-4705-8297-f84d38edb6a9.webp
`temperaturegauge`	`20` Cold Temperature	`80` Hot Temperature	Color values to blend	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.	5e15c195-d8d0-446d-889d-729b7a32f988.webp
`heaterfire`	`1`Minimum temperature to activate effect	`0` Disable effect once temp is reached	Color values to blend from "Cold" to "Hot"	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.	140275bf-763f-4a21-9ee0-aa92d54bbdb6.webp

### 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	Effect Rate	Cutoff	Palette Setting	Effect Explanation
`stepper`	`4`Number of trailing LEDs	`4` Number of leading LEDs	Color values to blend	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.
`steppercolor`	`1` Scaling of position	`0` Offset of position	DColor values to blend	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.
`progress`	`4` Number of trailing LEDs	`4` Number of leading LEDs	Color values to blend	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	Effect Rate	Cutoff	Palette Setting	Effect Explanation
`homing`	`1` Determines decay rate. A higher number yields slower decay	`0` Not used, but must be provided	Colors are cycled in order	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	Effect Rate	Cutoff	Palette Setting	Effect Explanation
`switchbutton`	`1` Fade in time. Time until LEDs are on after button press	`1`Fade out time. Time until LEDs are off after button release	Colors are cycled in order	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.
`togglebutton`	`1` Fade in time. Time to fade in next color	`1` Fade out time. Time to fade out previous color	Colors are cycled in order	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.
`flashbutton`	`00.1` Fade in time. Time to fade in.	`1` Fade out time. Time to fade out.	LEDs fade on with Colors are cycled in order	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	Effect Rate	Cutoff	Palette Setting	Effect Explanation
`analogpin`	`10` M10 Multiplier for input signal	`40` Minimum threshold to trigger effect	Color values to blend	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: ```yaml [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.