Built-in project · Arduino Uno R3

Christmas countdown on an Arduino Uno

A DS3231 keeps the date and an eight-digit MAX7219 display in the window counts the days, hours, minutes and seconds to Christmas, then flashes 25.12. The whole build, an Arduino Uno and 2 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.

Intermediate About 20 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.

Christmas countdown · Arduino Uno R3live0.000 s 0.00x
Click to open it in the editor
The circuit itself, running here on the simulator. Press what can be pressed; click anything else to open it in the editor.

What you'll learn

  • Why a real-time clock beats counting with millis
  • Date and time math with DateTime and TimeSpan
  • Driving a MAX7219 seven-segment display
  • Splitting a number into two display digits
  • Setting a clock once, then removing the line
  • Difficulty: Intermediate
  • Time: About 20 minutes
  • Board: Arduino Uno R3
  • Parts: 4

How it works

A DS3231 real-time clock keeps the date and time, even through a power cut. Each second, the sketch reads it and finds the next Christmas morning. It subtracts the current time from that to get the days, hours, minutes and seconds left.

The eight-digit display shows them as DD.HH.MM.SS, two digits for each, with a point after each pair. Pins 12, 11 and 10 carry the display data, clock and chip select. The clock uses the I2C pins.

On Christmas Day, the display flashes 25.12 and the year, on for one second and off for one. After the day ends, the target moves to next year.

Parts list

4 parts, plus the jumper wires. They retail for about $36; on Mokxi they're free.

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
Real-time clock, DS3231 pin SCLArduino Uno R3 pin SCL
Real-time clock, DS3231 pin SDAArduino Uno R3 pin SDA
Eight-digit display, MAX7219 pin DINArduino Uno R3 pin 12
Eight-digit display, MAX7219 pin CLKArduino Uno R3 pin 11
Eight-digit display, MAX7219 pin CSArduino Uno R3 pin 10
Eight-digit display, MAX7219 pin VCCArduino Uno R3 pin 5V
Real-time clock, DS3231 pin VCCArduino Uno R3 pin 5V
Eight-digit display, MAX7219 pin GNDArduino Uno R3 pin GND
Real-time clock, DS3231 pin GNDArduino Uno R3 pin GND

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 countdown: a display for the front window that counts down the
// days, hours, minutes and seconds to Christmas morning, then flashes the
// date all through Christmas Day.
//
//   DS3231    SCL -> SCL   SDA -> SDA   VCC -> 5 V   GND -> GND
//   MAX7219   8-digit seven-segment module: DIN -> pin 12, CLK -> pin 11,
//             CS -> pin 10, VCC -> 5 V, GND -> GND
//
// The display reads DD.HH.MM.SS: days on the left two digits, then hours,
// minutes and seconds, each pair split by a decimal point.
//
// Why a real-time clock: the Uno's own millis() forgets everything at every
// power cut and drifts over weeks. The DS3231 has a coin cell and a
// temperature-compensated crystal, so it keeps the date through a blown fuse
// on the porch and stays close to the right time all season. Set it once:
// uncomment the rtc.adjust() line, upload, then comment it out and upload
// again, or every reset will put the clock back to the moment you built it.
//
// The countdown is plain arithmetic on DateTime: Christmas minus now is a
// TimeSpan, and TimeSpan already knows how to split itself into days, hours,
// minutes and seconds.
//
// On the bench: turn INTENSITY down for a window at night; full brightness
// is a lot of light through glass.
//
// Things to try. Count to New Year's Eve instead by changing the month and
// day in christmasAfter(). Show only the days when there are more than
// thirty of them, so it changes once a day.

#include <Wire.h>
#include <RTClib.h>
#include <LedControl.h>

const int INTENSITY = 6;   // 0 to 15

RTC_DS3231 rtc;
LedControl display(12, 11, 10, 1);   // DIN, CLK, CS, one module

uint32_t lastShown = 0;

// The next Christmas morning that has not yet ended.
DateTime christmasAfter(const DateTime &now) {
  DateTime target(now.year(), 12, 25, 0, 0, 0);
  if (now.unixtime() >= target.unixtime() + 86400UL) {
    target = DateTime(now.year() + 1, 12, 25, 0, 0, 0);
  }
  return target;
}

// Two digits at positions `left` and `left - 1`, with an optional point.
void pair(int left, int value, bool point) {
  display.setDigit(0, left, value / 10, false);
  display.setDigit(0, left - 1, value % 10, point);
}

void showCountdown(const TimeSpan &left) {
  int days = left.days();
  if (days > 99) days = 99;
  pair(7, days, true);
  pair(5, left.hours(), true);
  pair(3, left.minutes(), true);
  pair(1, left.seconds(), false);
}

void showChristmas(const DateTime &now) {
  // 25.12.2026, on for a second and off for a second.
  if (now.second() % 2 == 0) {
    pair(7, 25, true);
    pair(5, 12, true);
    pair(3, now.year() / 100, false);
    pair(1, now.year() % 100, false);
  } else {
    display.clearDisplay(0);
  }
}

void setup() {
  Serial.begin(9600);
  display.shutdown(0, false);
  display.setIntensity(0, INTENSITY);
  display.clearDisplay(0);
  if (!rtc.begin()) {
    Serial.println("No DS3231 answered: check SDA and SCL");
    while (true) {
    }
  }
  // rtc.adjust(DateTime(F(__DATE__), F(__TIME__)));   // set once, see above
  if (rtc.lostPower()) Serial.println("The clock has lost power: set it once with rtc.adjust()");
  Serial.println("Christmas countdown");
}

void loop() {
  DateTime now = rtc.now();
  if (now.unixtime() == lastShown) return;   // once a second is enough
  lastShown = now.unixtime();

  DateTime christmas = christmasAfter(now);
  if (now.unixtime() >= christmas.unixtime()) {
    showChristmas(now);
    if (now.second() == 0) Serial.println("Merry Christmas!");
    return;
  }
  TimeSpan left = christmas - now;
  showCountdown(left);
  Serial.print(left.days());
  Serial.print(" days ");
  Serial.print(left.hours());
  Serial.print(" h ");
  Serial.print(left.minutes());
  Serial.print(" min ");
  Serial.print(left.seconds());
  Serial.println(" s to go");
}

Code walkthrough

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

christmasAfter sketch.ino

Builds a date for December 25 of this year at midnight. If that day has already completely passed, it uses next year's instead. So the countdown always points at a Christmas that is still to come, or happening now.

// The next Christmas morning that has not yet ended.
DateTime christmasAfter(const DateTime &now) {
  DateTime target(now.year(), 12, 25, 0, 0, 0);
  if (now.unixtime() >= target.unixtime() + 86400UL) {
    target = DateTime(now.year() + 1, 12, 25, 0, 0, 0);
  }
  return target;
}

pair sketch.ino

Puts a two-digit number on the display. The tens go in one digit position and the ones in the next, with an optional decimal point on the second. Every part of the display uses it.

// Two digits at positions `left` and `left - 1`, with an optional point.
void pair(int left, int value, bool point) {
  display.setDigit(0, left, value / 10, false);
  display.setDigit(0, left - 1, value % 10, point);
}

loop sketch.ino

Reads the clock and does nothing if the second has not changed. If it is Christmas Day, it calls showChristmas. If not, it works out the time left, shows it with showCountdown and prints it to the Serial Monitor.

void loop() {
  DateTime now = rtc.now();
  if (now.unixtime() == lastShown) return;   // once a second is enough
  lastShown = now.unixtime();

  DateTime christmas = christmasAfter(now);
  if (now.unixtime() >= christmas.unixtime()) {
    showChristmas(now);
    if (now.second() == 0) Serial.println("Merry Christmas!");
    return;
  }
  TimeSpan left = christmas - now;
  showCountdown(left);
  Serial.print(left.days());
  Serial.print(" days ");
  Serial.print(left.hours());
  Serial.print(" h ");
  Serial.print(left.minutes());
  Serial.print(" min ");
  Serial.print(left.seconds());
  Serial.println(" s to go");
}

Troubleshooting

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

  • The clock shows the wrong date This project
    The DS3231 has to be set once. Uncomment the rtc.adjust line, upload, then comment it out and upload again.
  • The sketch stops with No DS3231 answered This project
    Check that SDA and SCL are wired to the matching pins on the clock, and that it has power.
  • The display is blank This project
    Check DIN on pin 12, CLK on pin 11 and CS on pin 10. INTENSITY also sets the brightness.
  • The display is blank or shows garbage. The chip starts in shutdown, with scan limit and intensity not set. Eight-digit display
    In LedControl call shutdown(0, false), setIntensity(0, 8) and clearDisplay(0) at start. Also set the scan limit to 8 digits. Check that DIN, CLK and CS match the pins in the constructor.
  • The display dims, flickers, or resets. The segment current comes from one resistor, RSET, and the chip needs a clean 5 V. Eight-digit display
    Power it from 5 V with a 10 uF cap and a 0.1 uF cap near the chip. Keep ISET resistor values as the datasheet says, about 10k for a standard LED display.
  • The time shows odd numbers, such as 0x23 printed as 35, when you read it. Real-time clock
    All time registers are BCD, not plain binary. Convert each byte with (b >> 4) * 10 + (b & 0x0F) to read, and the reverse to write. A library such as RTClib does this for you.
  • The clock does not respond, or the I2C bus hangs. Real-time clock
    The DS3231 address is 0x68. Wire SDA and SCL to the right pins with pull-ups, about 4.7k, to the supply. Many breakout boards already have them. Join the grounds.
  • Upload fails or nothing runs after wiring pins 0 and 1 to a module. Arduino Uno R3
    Pins 0 and 1 are the USB serial port. Move the module to other pins, or unplug it while uploading. Also check the right board is selected.

Change it and keep it

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