Built-in project · Arduino Uno R3

Christmas light show on an Arduino Uno

A DFPlayer starts the song and three WS2812B strips, roofline, tree and arch, follow a cue list timed in beats from that moment until the song ends. The whole build, an Arduino Uno and 9 more parts, runs here in your browser on the firmware below; open it in the editor to change the wiring or the code and run it again.

Teaching? Assign it to your class in one click.

Advanced About 50 minutes to build and run. Runs in your browser. Free, and no account needed.

Build it as the Christmas Lights Kit: the parts in numbered bags and a booklet that checks every step. Retails for about $60, free on Mokxi.

The circuit runs here once the page has loaded.

What you'll learn

  • Syncing lights to music with a beat clock
  • A cue list that maps beats to looks
  • Driving WS2812B strips with Adafruit_NeoPixel
  • Using the DFPlayer BUSY pin to detect the end of a song
  • Animating without blocking by using timed frames
  • Difficulty: Advanced
  • Time: About 50 minutes
  • Board: Arduino Uno R3
  • Parts: 11

How it works

A DFPlayer Mini plays track 001 on its speaker. At the same moment, the sketch starts its own clock. The lights never listen to the music. They work out the current beat from the clock: the time since the song started divided by BEAT_MS, which is 500 ms, or 120 beats per minute.

A cue list says which look to show from which beat. The looks are intro, chase, pulse, wipe, rainbow, finale and dark. They run on three WS2812B strips: 16 LEDs on pin 5 for the roofline, 12 on pin 6 for the tree and 8 on pin 7 for the arch.

The BUSY pin on pin 3 goes high when the song ends. The strips go dark, and after DARK_MS (4 seconds) the show starts over. With no DFPlayer, it runs silent for 24 beats.

Wiring table

Every connection, pin by pin, read from the circuit itself. Each row joins the pin on the left to the pin on the right, by a jumper wire or a breadboard strip.

Part and pinConnects to
Resistor, 1k Ω pin 1Arduino Uno R3 pin 11
DFPlayer Mini MP3 module pin TXArduino Uno R3 pin 10
Resistor, 330 Ω (3) pin 1Arduino Uno R3 pin 7
Resistor, 330 Ω (2) pin 1Arduino Uno R3 pin 6
Resistor, 330 Ω (1) pin 1Arduino Uno R3 pin 5
DFPlayer Mini MP3 module pin BUSYArduino Uno R3 pin 3
DFPlayer Mini MP3 module pin VCCArduino Uno R3 pin 5V
Addressable RGB LEDs (1) pin VDDArduino Uno R3 pin 5V
Addressable RGB LEDs (2) pin VDDArduino Uno R3 pin 5V
Addressable RGB LEDs (3) pin VDDArduino Uno R3 pin 5V
DFPlayer Mini MP3 module pin GNDArduino Uno R3 pin GND
Addressable RGB LEDs (1) pin VSSArduino Uno R3 pin GND
Addressable RGB LEDs (2) pin VSSArduino Uno R3 pin GND
Addressable RGB LEDs (3) pin VSSArduino Uno R3 pin GND
Resistor, 1k Ω pin 2DFPlayer Mini MP3 module pin RX
Speaker, 8 ohm pin 1DFPlayer Mini MP3 module pin SPK_1
Speaker, 8 ohm pin 2DFPlayer Mini MP3 module pin SPK_2
Addressable RGB LEDs (1) pin DINResistor, 330 Ω (1) pin 2
Addressable RGB LEDs (2) pin DINResistor, 330 Ω (2) pin 2
Addressable RGB LEDs (3) pin DINResistor, 330 Ω (3) pin 2

The code

The firmware exactly as the editor opens it. Change a line there and press Run: it compiles in the browser.

sketch.ino · Arduino Uno R3
// Christmas light show: a song plays from a DFPlayer Mini and three LED
// strips, the roofline, the tree and the arch, change in time with it,
// following a cue list written in beats.
//
//   DFPlayer   VCC -> 5 V   GND -> GND   TX -> pin 10   RX <- 1 k <- pin 11
//              BUSY -> pin 3 (low while a track plays), speaker on SPK_1/SPK_2
//              track 001.mp3 is the song
//   roofline   16 WS2812B, DIN <- 330 ohms <- pin 5
//   tree       12 WS2812B, DIN <- 330 ohms <- pin 6
//   arch        8 WS2812B, DIN <- 330 ohms <- pin 7
//
// How the sync works. The lights do not listen to the music. The sketch
// starts the track and its own clock at the same moment, and from then on
// works out which beat of the song it is from the clock alone:
//
//   beat = (millis() - songStart) / BEAT_MS
//
// A cue list says what look the strips show from which beat on. That is the
// same idea big shows use, at a much smaller size. In xLights, a free
// sequencer for PCs, you lay effects out on a timeline against the song's
// waveform, export the result as frames, and a show player streams those
// frames to pixel controllers over the network while it plays the audio.
// Mokxi is not xLights and does not run its sequences: this sketch is the
// hand-written version, for a few strips on one Uno.
//
// The other way is beat detection: a microphone module and a sketch that
// flashes on every loud moment. It works with any song and needs no
// sequencing, but it reacts rather than performs, so nothing can happen just
// before the drop.
//
// Getting the timing right. Measure your song's tempo (many free tools tap or
// detect BPM) and set BEAT_MS = 60000 / BPM. The DFPlayer takes a moment to
// start a track, so START_DELAY_MS shifts the lights to match. BUSY tells the
// sketch when the song has really ended, and the show starts over after a
// short dark pause.
//
// The simulated DFPlayer plays silence. It shows the track and the seconds
// into it, so the beat count and the player's clock can be compared on the
// canvas; the song itself is for the speaker on the porch.
//
// On the porch: LED strips draw far more than the Uno can supply. Give them a
// 5 V supply sized for the LEDs you run, inject power at both ends of long
// strips, join every ground, and keep the supply's mains side in its case and
// out of the weather.
//
// Things to try. Add a cue. Change BEAT_MS for your song. Write a new look in
// render() and give it a beat.

#include <SoftwareSerial.h>
#include <DFRobotDFPlayerMini.h>
#include <Adafruit_NeoPixel.h>

const int BUSY_PIN = 3;
const unsigned long BEAT_MS = 500;          // 120 beats per minute
const unsigned long START_DELAY_MS = 150;   // the player's head start
const int SONG_BEATS = 24;                  // used only without a player
const unsigned long DARK_MS = 4000;         // pause between shows
const unsigned long FRAME_MS = 20;          // fifty frames a second is plenty

Adafruit_NeoPixel roof(16, 5, NEO_GRB + NEO_KHZ800);
Adafruit_NeoPixel tree(12, 6, NEO_GRB + NEO_KHZ800);
Adafruit_NeoPixel arch(8, 7, NEO_GRB + NEO_KHZ800);

SoftwareSerial link(10, 11);   // RX, TX
DFRobotDFPlayerMini player;
bool haveSound = false;

enum Look { INTRO, CHASE, PULSE, WIPE, RAINBOW, FINALE, DARK };
const char *const NAMES[] = {"intro", "chase", "pulse", "wipe", "rainbow", "finale", "dark"};

struct Cue {
  uint8_t beat;   // from this beat of the song...
  uint8_t look;   // ...show this look
};

// The sequence, in beats. Four beats is one bar.
const Cue CUES[] = {
  {0, INTRO}, {4, CHASE}, {8, PULSE}, {12, WIPE}, {16, RAINBOW}, {20, FINALE}, {24, DARK},
};
const int CUE_COUNT = sizeof(CUES) / sizeof(CUES[0]);

bool playing = false;
unsigned long songStart = 0;
unsigned long darkSince = 0;
unsigned long nextFrame = 0;
int lastCue = -1;

uint32_t rgb(uint8_t r, uint8_t g, uint8_t b) { return Adafruit_NeoPixel::Color(r, g, b); }

// Draw one frame of a look. `beat` is the whole beat, `phase` how far into
// it we are, 0 to 255, which is what makes a look move with the music.
void render(int look, int beat, int phase) {
  int fade = 255 - phase;   // bright on the beat, dimming until the next
  switch (look) {
    case INTRO:
      tree.fill(rgb(beat * 50 + phase / 6, beat * 40 + phase / 8, beat * 20));
      roof.clear();
      arch.clear();
      break;
    case CHASE:
      for (int i = 0; i < 16; i++) roof.setPixelColor(i, (i + beat) % 2 ? rgb(200, 0, 0) : rgb(0, 160, 0));
      tree.fill(rgb(0, 120, 0));
      arch.clear();
      break;
    case PULSE:
      roof.fill(rgb(fade, fade, fade));
      tree.fill(rgb(fade, fade * 3 / 4, fade / 3));
      arch.fill(rgb(fade, fade, fade));
      break;
    case WIPE:
      arch.clear();
      for (int i = 0; i <= phase * 8 / 256; i++) arch.setPixelColor(i, rgb(200, 0, 0));
      for (int i = 0; i < 16; i++) roof.setPixelColor(i, (i / 4 + beat) % 2 ? rgb(180, 180, 180) : rgb(180, 0, 0));
      tree.fill(rgb(0, 100, 0));
      tree.setPixelColor(random(0, 12), rgb(255, 255, 200));
      break;
    case RAINBOW: {
      uint16_t hue = (uint16_t)(beat * 16384 + phase * 64);
      roof.rainbow(hue);
      tree.rainbow(hue + 21845);
      arch.rainbow(hue + 43690);
      break;
    }
    case FINALE: {
      bool red = (phase < 128) != (beat % 2);
      uint32_t a = red ? rgb(255, 0, 0) : rgb(0, 200, 0);
      uint32_t b = red ? rgb(0, 200, 0) : rgb(255, 0, 0);
      roof.fill(a);
      tree.fill(b);
      arch.fill(a);
      break;
    }
    default:
      roof.clear();
      tree.clear();
      arch.clear();
      break;
  }
  roof.show();
  tree.show();
  arch.show();
}

void startShow() {
  if (haveSound) player.play(1);
  songStart = millis() + START_DELAY_MS;
  playing = true;
  lastCue = -1;
  Serial.println("Show starting");
}

void setup() {
  Serial.begin(9600);
  link.begin(9600);
  pinMode(BUSY_PIN, INPUT);
  roof.begin();
  tree.begin();
  arch.begin();
  roof.setBrightness(150);
  tree.setBrightness(150);
  arch.setBrightness(150);
  haveSound = player.begin(link);
  if (haveSound) {
    player.volume(25);
  } else {
    Serial.println("No DFPlayer answered: the show will run silent");
  }
  startShow();
}

void loop() {
  unsigned long now = millis();

  if (!playing) {
    if (now - darkSince >= DARK_MS) startShow();
    return;
  }
  if (now < songStart || now < nextFrame) return;
  nextFrame = now + FRAME_MS;

  unsigned long t = now - songStart;
  int beat = t / BEAT_MS;
  int phase = (t % BEAT_MS) * 256 / BEAT_MS;

  // The last cue whose beat has come.
  int cue = 0;
  while (cue + 1 < CUE_COUNT && beat >= CUES[cue + 1].beat) cue++;
  if (cue != lastCue) {
    lastCue = cue;
    Serial.print("Beat ");
    Serial.print(beat);
    Serial.print(": ");
    Serial.println(NAMES[CUES[cue].look]);
  }
  render(CUES[cue].look, beat, phase);

  // The song is over when the player says so (BUSY high), or, with no
  // player, when the beats run out.
  bool songOver = haveSound ? (t > 1000 && digitalRead(BUSY_PIN) == HIGH) : beat >= SONG_BEATS;
  if (songOver) {
    render(DARK, 0, 0);
    playing = false;
    darkSince = now;
    Serial.println("Show over");
  }
}

Code walkthrough

The key functions of the sketch, and what each one does.

startShow sketch.ino

Starts the DFPlayer on track 1 if one answered, then sets songStart to now plus START_DELAY_MS. That 150 ms head start covers the time the player takes to begin, so the lights line up with the sound. It also resets the cue and prints Show starting.

void startShow() {
  if (haveSound) player.play(1);
  songStart = millis() + START_DELAY_MS;
  playing = true;
  lastCue = -1;
  Serial.println("Show starting");
}

render sketch.ino

Draws one frame of a look on all three strips. It gets the whole beat and a phase from 0 to 255 showing how far into the beat we are. The pulse look uses the phase to fade after each beat. It ends by calling show on each strip.

// Draw one frame of a look. `beat` is the whole beat, `phase` how far into
// it we are, 0 to 255, which is what makes a look move with the music.
void render(int look, int beat, int phase) {
  int fade = 255 - phase;   // bright on the beat, dimming until the next
  switch (look) {
    case INTRO:
      tree.fill(rgb(beat * 50 + phase / 6, beat * 40 + phase / 8, beat * 20));
      roof.clear();
      arch.clear();
      break;
    case CHASE:
      for (int i = 0; i < 16; i++) roof.setPixelColor(i, (i + beat) % 2 ? rgb(200, 0, 0) : rgb(0, 160, 0));
      tree.fill(rgb(0, 120, 0));
      arch.clear();
      break;
    case PULSE:
      roof.fill(rgb(fade, fade, fade));
      tree.fill(rgb(fade, fade * 3 / 4, fade / 3));
      arch.fill(rgb(fade, fade, fade));
      break;
    case WIPE:
      arch.clear();
      for (int i = 0; i <= phase * 8 / 256; i++) arch.setPixelColor(i, rgb(200, 0, 0));
      for (int i = 0; i < 16; i++) roof.setPixelColor(i, (i / 4 + beat) % 2 ? rgb(180, 180, 180) : rgb(180, 0, 0));
      tree.fill(rgb(0, 100, 0));
      tree.setPixelColor(random(0, 12), rgb(255, 255, 200));
      break;
    case RAINBOW: {
  // ... 25 more lines in the editor

loop sketch.ino

Limits frames to one every FRAME_MS, then turns the time into a beat and a phase. It finds the last cue whose beat has come and renders that look. The song counts as over when BUSY reads HIGH, or when the beats run out if there is no player.

void loop() {
  unsigned long now = millis();

  if (!playing) {
    if (now - darkSince >= DARK_MS) startShow();
    return;
  }
  if (now < songStart || now < nextFrame) return;
  nextFrame = now + FRAME_MS;

  unsigned long t = now - songStart;
  int beat = t / BEAT_MS;
  int phase = (t % BEAT_MS) * 256 / BEAT_MS;

  // The last cue whose beat has come.
  int cue = 0;
  while (cue + 1 < CUE_COUNT && beat >= CUES[cue + 1].beat) cue++;
  if (cue != lastCue) {
    lastCue = cue;
    Serial.print("Beat ");
    Serial.print(beat);
    Serial.print(": ");
    Serial.println(NAMES[CUES[cue].look]);
  }
  render(CUES[cue].look, beat, phase);

  // The song is over when the player says so (BUSY high), or, with no
  // player, when the beats run out.
  // ... 8 more lines in the editor

Troubleshooting

The usual mistakes with this circuit, and the fix for each.

  • The lights drift away from the song. This project
    Measure your song's tempo and set BEAT_MS to 60000 divided by the BPM.
  • The lights start before or after the music. This project
    Adjust START_DELAY_MS until the first beat lines up.
  • The monitor says No DFPlayer answered. This project
    Check the DFPlayer power, its TX on pin 10 and its RX through the 1k resistor from pin 11. The lights still run without sound.
  • The module stays silent or does not respond to commands. DFPlayer Mini MP3 module
    Format the microSD card as FAT32 and name files 0001.mp3, 0002.mp3 and so on. Copy them in the order you want. Check the card is seated in the slot.
  • Commands are garbled or ignored on the serial link. DFPlayer Mini MP3 module
    The module uses 9600 baud and 3.3 V logic on RX. Put a 1 k resistor in series with the Arduino TX line to its RX. Cross the lines: Arduino TX to module RX.
  • The LED is dim, burns out, or the pin reads wrong because the resistor value is off. Resistor
    Read the color bands again. A 220 ohm to 330 ohm resistor suits a typical LED on 5 V. 10k is a common pull-up or pull-down value. Check with a multimeter if unsure.
  • A pull-up or pull-down resistor is missing, so the input floats and reads random values. Resistor
    Tie the input to 5 V or ground through about 10k. Or use INPUT_PULLUP and wire the switch to ground.
  • The first LED flickers, shows wrong colors, or the whole strip glitches. Addressable RGB LEDs
    Join the grounds of the strip and the controller. Add a 300 to 500 ohm resistor in series with the data line. Put a 1000 uF capacitor across the strip's 5 V and GND.

Change it and keep it

Open it in the editor, change the circuit or the code, and keep your version in a free account.