FastLED Examples (examples/)
This document maps the example sketches, shows how to run them on different targets (Arduino/PlatformIO, Teensy, ESP32, WASM), and suggests learning paths. It mirrors the structure and tone of src/fl/README.md so you can quickly jump between concepts and runnable code.
The examples/ directory contains runnable sketches that cover:
- Getting started (blinking, first LED, pin modes)
- Color utilities, palettes, and HSV/CRGB conversions
- Classic 1D effects (Cylon, Fire, Twinkles, DemoReel100)
- 2D matrix helpers, XY mapping, and raster effects
- Advanced pipelines like downscale/upscale and path rendering
- Platform-specific demos (Teensy OctoWS2811, ESP I2S)
- Browser/WASM examples with JSON-driven UI controls
Typical first steps:
- Open an example in the Arduino IDE and change NUM_LEDS, chipset, and DATA_PIN to match hardware
- For matrices, define width/height and choose serpentine vs. row-major mapping
- For WASM or host exploration, use the WASM examples or the STUB platform (see below)
Arduino IDE (classic workflow)
- Open an .ino file directly (e.g., examples/Blink/Blink.ino)
- Edit the configuration near the top:
- LED type: FastLED.addLeds<WS2812B, DATA_PIN, GRB>(leds, NUM_LEDS)
- Strip length: NUM_LEDS
- Brightness: FastLED.setBrightness(…)
- Select your board and COM/serial port, then Upload
Tips:
- For 2D examples, set WIDTH/HEIGHT and confirm wiring (serpentine vs. linear)
- If the animation is mirrored or offset, adjust the mapping helper
PlatformIO (boards and native host)
- Board-based workflows: create a platformio.ini that targets your MCU and copy an example sketch into a project src/ folder
- Host/STUB workflows: use the STUB platform for local testing where appropriate (no hardware); advanced builds hook into src/platforms/stub/
- For native host compilation, FastLED uses Meson (see meson.build and run uv run test.py --cpp)
- Examples under examples/SpecialDrivers/Teensy/OctoWS2811/* and related Teensy demos show multi-output patterns
- Replace pin/channel configuration and buffer sizes to match your wiring; ensure you select the correct Teensy model in your IDE/toolchain
ESP32 Special Drivers (parallel output)
- See examples/SpecialDrivers/ESP/ for ESP32 special driver examples:
- DriverTest/ - Tests all available LED drivers for your ESP32 variant (RMT, SPI, I2S, PARLIO, UART, LCD_RGB)
- These demonstrate high-throughput hardware-accelerated output; choose a board definition matching your dev board and wiring
- On some environments, parallel output requires specific pin sets and PSRAM settings; consult the sketch notes
WASM (browser demos + JSON UI)
- Try FastLED without hardware in the FastLED Web Compiler
- The Wokwi FastLED playground runs the ColorPalette example in an Arduino simulator
- examples/wasm/ and related WASM-focused examples run in the browser
- The JSON UI system enables sliders, buttons, and other controls (see src/platforms/wasm and src/fl/ui/ui.h)
- Typical flow: build to WebAssembly, serve the app, and interact via the browser UI
This list highlights commonly used examples. It is not exhaustive—browse the folders for more.
- Blink/ — minimal starting point
- FirstLight/ — walk a single bright pixel along the strip
- PinMode/ — simple input pin usage
- RGBSetDemo/ — basic pixel addressing and assignment
- RGBCalibrate/ — adjust color channel balance
- ColorPalette/ — palette usage and transitions
- ColorTemperature/ — white point and temperature helpers
- HSVTest/ — HSV types and conversions
- ColorBoost/ — saturation/luminance shaping for high visual impact
- Cylon/, FxCylon/ — scanning eye; FX variants use higher-level helpers
- Fire2012/, Fire2012WithPalette/, FxFire2012/ — classic fire effect
- TwinkleFox/, FxTwinkleFox/ — twinkling star fields
- Pride2015/, FxPride2015/ — rainbow variants
- DemoReel100/, FxDemoReel100/ — rotating showcase of many patterns
- Wave/ — 1D wave toolkit
- XYMatrix/ — matrix mapping helpers and layouts
- Wave2d/, FxWave2d/ — 2D wavefields
- Blur2d/ — separable blur across a matrix
- Downscale/ — render high-res, resample to panel resolution
- Animartrix/ — animated matrix patterns and helpers
- SmartMatrix/ — SmartMatrix integration sketch
FX engine and higher-level utilities
- FxEngine/ — scaffolding for composing layers and frames
- FxGfx2Video/ — utilities to pipe graphics into frame/video helpers
- fx/ under src/ provides the building blocks used by these examples
- Audio/ — audio input + analysis (simple and advanced variants)
- AudioInput/ — I2S microphone input (ESP32 & Teensy, INMP441 compatible)
- Ports/PJRCSpectrumAnalyzer/ — Teensy-centric spectrum analyzer
Storage, SD card, and data
- FxSdCard/ — SD-backed media and assets (see data/ subfolder)
Multiple strips, parallel, and high-density
- Multiple/ — organize multiple arrays/segments
- TeensyParallel/ — multi-output example
- See SpecialDrivers/ for platform-specific high-performance drivers (ESP, Teensy, Adafruit)
ESP/Teensy/SmartMatrix specifics
- See SpecialDrivers/ESP/DriverTest/ for ESP32 driver testing (tests RMT, SPI, I2S, PARLIO, UART, LCD_RGB based on your variant)
- See SpecialDrivers/Teensy/ for Teensy parallel drivers (OctoWS2811, ObjectFLED)
- SmartMatrix/ — run on SmartMatrix hardware
- wasm/ — browser-targeted demo
- WasmScreenCoords/ — UI overlay and coordinate visualization
- Json/ — JSON-structured sketch example
- UITest/ — showcase of JSON UI controls and groups
Larger projects and showcases
- LuminescentGrand/ — complex, multi-file installation piece
- Luminova/ — larger effect set
- Chromancer/ — advanced example with assets and helpers
🎯 Platform-Specific Filtering with @filter
FastLED now supports flexible @filter directives in .ino sketch files for conditional compilation based on platform, memory, target, and board properties. This enables you to maintain platform-specific examples without duplicating code.
One-liner format (compact, flexible):
// @filter (memory is large) and (platform is esp32s3)
// @filter (memory is huge) and (platform is esp32)
// @filter (mem is large) and (plat is esp32*)
// @filter (mem: large) and (plat: esp32)
// @filter (mem=large) and (plat=esp32)
Multi-line YAML format (explicit):
// @filter
// - require:
// - platform: esp32s3
// - memory: large
// - exclude:
// - platform: avr
// @end-filter
Operators:
- is / is not - Exact match (supports wildcards with *)
- = / : - Shorthand for is
- matches - Regex/glob pattern match
Property shortcuts:
- mem → memory
- plat → platform
- tgt → target
- brd → board
Logical operators: and, or
Memory tiers (ordered: low < large < huge):
- (memory is large) — matches large AND huge boards
- (memory is huge) — matches only huge boards (ESP32, Teensy 4.x, RP2040, native)
- (memory is low) — matches all boards (every board is >= low)
Examples:
// @filter (platform is esp32*)
// @filter (memory is huge)
// @filter (memory is not low)
// @filter (target is -D__AVR__) or (board is uno)
- Always set the LED chipset, pin, color order, and NUM_LEDS to match your hardware:
- FastLED.addLeds<CHIPSET, DATA_PIN, COLOR_ORDER>(leds, NUM_LEDS);
- Common CHIPSETs: WS2812B, SK6812, APA102 (APA102 also needs CLK_PIN)
- Adjust brightness and power: FastLED.setBrightness(…) and consider power limits for dense strips
- For matrices, define WIDTH/HEIGHT and use serpentine or row-major helpers; verify orientation
- Prefer using fl::Leds + XYMap for 2D logic when the example exposes those hooks
- For high quality on low-res displays, render at higher resolution and downscale
- New to FastLED: start with Blink → FirstLight → DemoReel100
- Building a palette-based animation: ColorPalette and ColorTemperature
- Making a 1D animation: Cylon, Fire2012, TwinkleFox
- Driving a panel: XYMatrix, then try Downscale or Wave2d
- Multi-output / high-density: OctoWS2811Demo, TeensyParallel
- Browser demo / UI: wasm, UITest, Json
- Advanced/experimental: Corkscrew (in src/fl), Fx* examples, and Chromancer
- Nothing lights up:
- Re-check DATA_PIN, chipset, and COLOR_ORDER
- Confirm NUM_LEDS and power are correct; try a low brightness first
- Colors look wrong: try GRB vs. RGB ordering; some strips invert green/red
- Matrix appears mirrored or wrapped: change serpentine/row-major mapping or flip WIDTH and HEIGHT
- ESP32 I2S pinning: verify the chosen pins are valid for your board’s I2S peripheral
- Teensy multi-output: confirm channel count and buffer sizes match your wiring
- Include FastLED.h, pick your chipset, set NUM_LEDS, and get something simple running first
- For matrices, draw into width/height coordinates and let mapping/wiring helpers translate to indices
- Explore the palette and HSV examples for smooth color; try fill_rainbow and CHSV
- When moving to larger builds, consider splitting configuration and effect code into separate files for clarity
Guidance for C++ Developers
- Many examples are deliberately small; for more reusable building blocks, see src/fl/ and src/fx/
- Prefer fl:: containers, views (fl::span), and graphics helpers for portability and quality
- For UI/remote control on capable targets, use the JSON UI elements (see src/fl/ui/ui.h) and WASM bridge (src/platforms/wasm)
This README will evolve alongside the examples. Browse subfolders for sketch-specific notes and hardware details. For the core library map and deeper subsystems, see src/README.md and src/fl/README.md.