README.md

Fadecandy is a project that makes LED art easier, tastier, and more creative. We're all about creating tools that remove the technical drudgery from making LED art, freeing you to do more interesting, nuanced, and creative things. We think LEDs are more than just trendy display devices, we think of them as programmable light for interactive art.

Simple Example

Here's a simple project, a single LED strip controlled by a Processing sketch running on your laptop:

// Simple Processing sketch for controlling a 64-LED strip.
// A glowing color-blob appears on the strip under mouse control.

OPC opc;
PImage dot;

void setup()
{
  size(800, 200);

  // Load a sample image
  dot = loadImage("color-dot.png");

  // Connect to the local instance of fcserver
  opc = new OPC(this, "127.0.0.1", 7890);

  // Map one 64-LED strip to the center of the window
  opc.ledStrip(0, 64, width/2, height/2, width / 70.0, 0, false);
}

void draw()
{
  background(0);

  // Draw the image, centered at the mouse location
  float dotSize = width * 0.2;
  image(dot, mouseX - dotSize/2, mouseY - dotSize/2, dotSize, dotSize);
}

A More Complex Example

Fadecandy is also useful for larger projects with many thousands of LEDs, and it's useful for art that runs on embedded computers like the Raspberry Pi:

Project Scope

This project is a collection of reusable pieces you can take or leave. The overall goal of making LED art easier, tastier, and more creative is a broad one. To keep this project manageable to start with, there are some rough limitations on what's supported:

• LED strips, grids, and other modules based on the WS2811 or WS2812 chip.
  • Common and inexpensive, available from many suppliers for around $0.25 per pixel.
• Something with a USB host port that can run your art.
  • Laptops and Mac Minis work great
  • The Raspberry Pi is also a great platform for this, but it requires more technical skill
• Distances of no more than 60ft or so between your computer and your farthest LEDs
  • USB cables < 50ft
  • WS2811 data cables < 10ft
• No more than about 10000 LED pixels total
  • There's no hard limit, but it gets more difficult after this point.

These are fuzzy limitations based on current software capabilities and rough electrical limits, so you may be able to stretch them. But this gives you an idea about the kind of art we try to support. Projects are generally larger than wearables, but smaller than entire buildings.

For example, the first project to use Fadecandy was the Ardent Mobile Cloud Platform at Burning Man 2013. This project used one Raspberry Pi, five Fadecandy controller boards, and 2500 LEDs.

Fadecandy makes no assumptions about how you generate control patterns for the LEDs. You can generate a 2D video and sample pixels from the video, you can make a 3D model of your sculpture and sample a 3D shader for your pixel values, or you can create a unique system specifically for your art.

Fadecandy Controller

The centerpiece of the Fadecandy project is a controller board which can drive up to 512 LEDs (as 8 strings of 64) over USB. Many Fadecandy boards can be attached to the same computer using a USB hub or a chain of hubs.

Fadecandy makes it easy to drive these LEDs from anything with USB, and it includes unique algorithms which eliminate many of the common visual glitches you see when using these LEDs.

The LED drive engine is based on Stoffregen's excellent OctoWS2811 library, which pumps out serial data for these LED strips entirely using DMA. This firmware builds on Paul's work by adding:

• A high performance USB protocol
• Zero copy architecture with triple-buffering
• Interpolation between keyframes
• Gamma and color correction with per-channel lookup tables
• Temporal dithering
• A custom PCB with line drivers and a 5V boost converter
• A fully open source bootloader