diff --git a/src/components/LightEffectPreview.astro b/src/components/LightEffectPreview.astro new file mode 100644 index 0000000000..c9cf9b7591 --- /dev/null +++ b/src/components/LightEffectPreview.astro @@ -0,0 +1,316 @@ +--- +/** + * LightEffectPreview Component + * Renders a small CSS-animated preview of an ESPHome light effect. + * + * Usage in MDX: + * + */ + +type EffectType = + | 'pulse' + | 'random' + | 'strobe' + | 'flicker' + | 'lambda' + | 'rainbow' + | 'color-wipe' + | 'scan' + | 'twinkle' + | 'random-twinkle' + | 'fireworks' + | 'addr-flicker' + | 'addr-lambda'; + +interface Props { + type: EffectType; + label: string; +} + +const { type, label } = Astro.props; + +const STRIP_TYPES: ReadonlySet = new Set([ + 'rainbow', + 'color-wipe', + 'scan', + 'twinkle', + 'random-twinkle', + 'fireworks', + 'addr-flicker', + 'addr-lambda', +]); + +const isStrip = STRIP_TYPES.has(type); +const PIXEL_COUNT = 20; +--- + + + {isStrip ? ( + + {Array.from({ length: PIXEL_COUNT }, () => )} + + ) : ( + + )} + + + diff --git a/src/content/docs/components/light/index.mdx b/src/content/docs/components/light/index.mdx index 3b4eab0878..6e5f70b0a6 100644 --- a/src/content/docs/components/light/index.mdx +++ b/src/content/docs/components/light/index.mdx @@ -8,6 +8,7 @@ sidebar: import APIClass from '@components/APIClass.astro'; import APIStruct from '@components/APIStruct.astro'; import APIRef from '@components/APIRef.astro'; +import LightEffectPreview from '@components/LightEffectPreview.astro'; In ESPHome, `light` components allow you to create lights usable from Home Assistant's frontend and have many features such as colors, transitions and even effects. @@ -498,6 +499,44 @@ light: > After setting a light effect, it is possible to reset the in-use effect back to a static light by setting the > `effect` to `none` when it is being called through Home Assistant or directly on the device. +### Basic Animations + +These effects work on any light platform. + +| Preview | Effect | Description | Parameters | +| --- | --- | --- | --- | +| | [Pulse](#pulse-effect) | Smooth brightness pulse | `name`, `transition_length`, `update_interval`, `min_brightness`, `max_brightness` | +| | [Random](#random-effect) | Random colors at fixed intervals | `name`, `transition_length`, `update_interval` | +| | [Strobe](#strobe-effect) | Cycle through a list of colors with set durations | `name`, `colors` | +| | [Flicker](#flicker-effect) | Candle-like brightness variation | `name`, `alpha`, `intensity` | +| | [Lambda](#lambda-effect) | Run custom C++ on each update | `name`, `update_interval`, `lambda` | + +### Strip Animations + +These effects require an addressable light (LED strip). + +| Preview | Effect | Description | Parameters | +| --- | --- | --- | --- | +| | [Addressable Rainbow](#addressable-rainbow-effect) | Hue sweeps the length of the strip | `name`, `speed`, `width` | +| | [Addressable Color Wipe](#addressable-color-wipe-effect) | New colors shift in at the start of the strip | `name`, `colors`, `add_led_interval`, `reverse` | +| | [Addressable Scan](#addressable-scan-effect) | Single dot slides back and forth across the strip | `name`, `move_interval`, `scan_width` | +| | [Addressable Twinkle](#addressable-twinkle-effect) | Random pixels brighten and fade | `name`, `twinkle_probability`, `progress_interval` | +| | [Addressable Random Twinkle](#addressable-random-twinkle-effect) | Twinkle, but each pixel gets a random color | `name`, `twinkle_probability`, `progress_interval` | +| | [Addressable Fireworks](#addressable-fireworks-effect) | Sparks burst from random pixels | `name`, `update_interval`, `spark_probability`, `use_random_color`, `fade_out_rate` | +| | [Addressable Flicker](#addressable-flicker-effect) | Per-pixel candle flicker | `name`, `update_interval`, `intensity` | +| | [Addressable Lambda](#addressable-lambda-effect) | Run custom C++ per LED | `name`, `update_interval`, `lambda` | + +### External Control + +These effects receive frames from an external source instead of generating animation locally. + +| Effect | Description | Parameters | +| --- | --- | --- | +| [Automation](#automation-light-effect) | Run ESPHome automation actions on a loop | `name`, `sequence` | +| [E1.31](#e131-effect) | Receive sACN / E1.31 frames over the network | `universe`, `channels` | +| [Adalight](#adalight-effect) | Receive Adalight protocol over UART | `uart_id` | +| [WLED](#wled-effect) | Receive WLED UDP sync protocol | `port`, `blank_on_start`, `sync_group_mask` | + ### Pulse Effect This effect makes a pulsating light. The period can be defined by `update_interval`, the transition length with