Loading...
Searching...
No Matches
examples Directory Reference
Directory dependency graph for examples:Detailed Description
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.
Table of Contents
- Overview and Quick Start
- How to Run Examples
- Arduino IDE (classic workflow)
- PlatformIO (boards and native host)
- Teensy/OctoWS2811
- ESP32 / I2S (parallel output)
- WASM (browser demos + JSON UI)
- Directory Map (by theme)
- Basics and core idioms
- Color, palettes, and HSV
- Classic 1D effects
- 2D, matrices, mapping
- FX engine and higher-level utilities
- Audio and reactive demos
- Storage, SD card, and data
- Multiple strips, parallel, and high-density
- ESP/Teensy/SmartMatrix specifics
- WASM and UI
- Larger projects and showcases
- Quick Usage Notes
- Choosing an Example
- Troubleshooting
- Guidance for New Users
- Guidance for C++ Developers
Overview and Quick Start
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, andDATA_PINto 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)
How to Run Examples
Arduino IDE (classic workflow)
- Open an
.inofile 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(…)
- LED type:
- Select your board and COM/serial port, then Upload
Tips:
- For 2D examples, set
WIDTH/HEIGHTand 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.inithat targets your MCU and copy an example sketch into a projectsrc/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.buildand runuv run test.py --cpp)
Teensy/OctoWS2811
- 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)
examples/wasm/and related WASM-focused examples run in the browser- The JSON UI system enables sliders, buttons, and other controls (see
src/platforms/wasmandsrc/fl/ui/ui.h) - Typical flow: build to WebAssembly, serve the app, and interact via the browser UI
Directory Map (by theme)
This list highlights commonly used examples. It is not exhaustive—browse the folders for more.
Basics and core idioms
Blink/— minimal starting pointFirstLight/— walk a single bright pixel along the stripPinMode/— simple input pin usageRGBSetDemo/— basic pixel addressing and assignmentRGBCalibrate/— adjust color channel balance
Color, palettes, and HSV
ColorPalette/— palette usage and transitionsColorTemperature/— white point and temperature helpersHSVTest/— HSV types and conversionsColorBoost/— saturation/luminance shaping for high visual impact
Classic 1D effects
Cylon/,FxCylon/— scanning eye; FX variants use higher-level helpersFire2012/,Fire2012WithPalette/,FxFire2012/— classic fire effectTwinkleFox/,FxTwinkleFox/— twinkling star fieldsPride2015/,FxPride2015/— rainbow variantsDemoReel100/,FxDemoReel100/— rotating showcase of many patternsWave/— 1D wave toolkit
2D, matrices, mapping
XYMatrix/— matrix mapping helpers and layoutsWave2d/,FxWave2d/— 2D wavefieldsBlur2d/— separable blur across a matrixDownscale/— render high-res, resample to panel resolutionAnimartrix/— animated matrix patterns and helpersSmartMatrix/— SmartMatrix integration sketch
FX engine and higher-level utilities
FxEngine/— scaffolding for composing layers and framesFxGfx2Video/— utilities to pipe graphics into frame/video helpersfx/undersrc/provides the building blocks used by these examples
Audio and reactive demos
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 (seedata/subfolder)
Multiple strips, parallel, and high-density
Multiple/— organize multiple arrays/segmentsTeensyParallel/— 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 and UI
wasm/— browser-targeted demoWasmScreenCoords/— UI overlay and coordinate visualizationJson/— JSON-structured sketch exampleUITest/— showcase of JSON UI controls and groups
Larger projects and showcases
LuminescentGrand/— complex, multi-file installation pieceLuminova/— larger effect setChromancer/— 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.
Supported Filter Syntax
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
Filter Features
Operators:
is/is not- Exact match (supports wildcards with*)=/:- Shorthand forismatches- Regex/glob pattern match
Property shortcuts:
mem→memoryplat→platformtgt→targetbrd→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)
Quick Usage Notes
- Always set the LED chipset, pin, color order, and
NUM_LEDSto match your hardware:FastLED.addLeds<CHIPSET, DATA_PIN, COLOR_ORDER>(leds, NUM_LEDS);- Common CHIPSETs:
WS2812B,SK6812,APA102(APA102 also needsCLK_PIN)
- Adjust brightness and power:
FastLED.setBrightness(…)and consider power limits for dense strips - For matrices, define
WIDTH/HEIGHTand use serpentine or row-major helpers; verify orientation - Prefer using
fl::Leds+XYMapfor 2D logic when the example exposes those hooks - For high quality on low-res displays, render at higher resolution and
downscale
Choosing an Example
- New to FastLED: start with
Blink→FirstLight→DemoReel100 - Building a palette-based animation:
ColorPaletteandColorTemperature - Making a 1D animation:
Cylon,Fire2012,TwinkleFox - Driving a panel:
XYMatrix, then tryDownscaleorWave2d - Multi-output / high-density:
OctoWS2811Demo,TeensyParallel - Browser demo / UI:
wasm,UITest,Json - Advanced/experimental:
Corkscrew(insrc/fl),Fx*examples, andChromancer
Troubleshooting
- Nothing lights up:
- Re-check
DATA_PIN, chipset, andCOLOR_ORDER - Confirm
NUM_LEDSand power are correct; try a low brightness first
- Re-check
- Colors look wrong: try
GRBvs.RGBordering; some strips invert green/red - Matrix appears mirrored or wrapped: change serpentine/row-major mapping or flip
WIDTHandHEIGHT - 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
Guidance for New Users
- Include
FastLED.h, pick your chipset, setNUM_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_rainbowandCHSV - 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/andsrc/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.
