Skip to content

Latest commit

 

History

History
227 lines (165 loc) · 9.89 KB

README.md

File metadata and controls

227 lines (165 loc) · 9.89 KB

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.

Table of Contents

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, 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)

How to Run Examples

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/

The repository includes ci/native/ and ci/kitchensink/ PlatformIO configs you can reference for host builds and integration tests.

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 all ESP32 special drivers:
    • I2S/ - I2S-based parallel output for ESP32 and ESP32-S3
    • LCD_I80/ - LCD I80 peripheral for ESP32-S2/S3
    • LCD_RGB/ - LCD RGB peripheral for ESP32-P4
    • Parlio/ - Parallel IO driver for ESP32-P4
  • 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/wasm and src/fl/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 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

Color, palettes, and HSV

  • ColorPalette/ — palette usage and transitions
  • ColorTemperature/ — white point and temperature helpers
  • HSVTest/ — HSV types and conversions
  • ColorBoost/ — saturation/luminance shaping for high visual impact

Classic 1D effects

  • 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

2D, matrices, mapping

  • 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 and reactive demos

  • Audio/ — audio input + analysis (simple and advanced variants)
  • 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/ for ESP32 parallel drivers (LCD, I2S, Parlio)
  • See SpecialDrivers/Teensy/ for Teensy parallel drivers (OctoWS2811, ObjectFLED)
  • SmartMatrix/ — run on SmartMatrix hardware

WASM and UI

  • 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

Quick Usage Notes

  • 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

Choosing an Example

  • 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

Troubleshooting

  • 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

Guidance for New Users

  • 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.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.