224 lines
9.6 KiB
Markdown
224 lines
9.6 KiB
Markdown
# 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](#overview-and-quick-start)
|
||
- [How to Run Examples](#how-to-run-examples)
|
||
- [Arduino IDE (classic workflow)](#arduino-ide-classic-workflow)
|
||
- [PlatformIO (boards and native host)](#platformio-boards-and-native-host)
|
||
- [Teensy/OctoWS2811](#teensyoctows2811)
|
||
- [ESP32 / I2S (parallel output)](#esp32--i2s-parallel-output)
|
||
- [WASM (browser demos + JSON UI)](#wasm-browser-demos--json-ui)
|
||
- [Directory Map (by theme)](#directory-map-by-theme)
|
||
- [Basics and core idioms](#basics-and-core-idioms)
|
||
- [Color, palettes, and HSV](#color-palettes-and-hsv)
|
||
- [Classic 1D effects](#classic-1d-effects)
|
||
- [2D, matrices, mapping](#2d-matrices-mapping)
|
||
- [FX engine and higher-level utilities](#fx-engine-and-higher-level-utilities)
|
||
- [Audio and reactive demos](#audio-and-reactive-demos)
|
||
- [Storage, SD card, and data](#storage-sd-card-and-data)
|
||
- [Multiple strips, parallel, and high-density](#multiple-strips-parallel-and-high-density)
|
||
- [ESP/Teensy/SmartMatrix specifics](#espteensysmartmatrix-specifics)
|
||
- [WASM and UI](#wasm-and-ui)
|
||
- [Larger projects and showcases](#larger-projects-and-showcases)
|
||
- [Quick Usage Notes](#quick-usage-notes)
|
||
- [Choosing an Example](#choosing-an-example)
|
||
- [Troubleshooting](#troubleshooting)
|
||
- [Guidance for New Users](#guidance-for-new-users)
|
||
- [Guidance for C++ Developers](#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, 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/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 / I2S (parallel output)
|
||
|
||
- See `examples/EspI2SDemo/` and `examples/Esp32S3I2SDemo/`
|
||
- These demonstrate high-throughput I2S-driven 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
|
||
- `TeensyMassiveParallel/` — larger multi-output wiring
|
||
- `OctoWS2811/`, `OctoWS2811Demo/` — OctoWS2811 multi-channel output
|
||
|
||
### ESP/Teensy/SmartMatrix specifics
|
||
|
||
- `EspI2SDemo/`, `Esp32S3I2SDemo/` — ESP32 parallel/I2S output
|
||
- `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`.
|