Lessons and the learning game

Build a moon phase lamp

A lamp on an Uno that shows tonight's Moon on 64 LEDs, works the phase out from the date, and glows only when the room is dark.

What you build

One circuit carries the whole course. Every lesson opens on the same wiring and changes only the sketch:

  • The Moon: an 8x8 WS2812B panel, 64 LEDs on one data wire from pin 6, through 330 ohms.
  • The date: a DS3231 real-time clock on I2C (A4 and A5). It keeps the date on its own coin cell and stays within about a minute a year.
  • The dark: a light cell from 5 V into A0, with 10 k from A0 to ground.
  • The brain: an Arduino Uno.

How it works

The phase from a date. The Moon goes from new moon to new moon in 29.530589 days on average, the synodic month. That is 42524 minutes. Pick one new moon you know exactly (the lamp uses January 6, 2000 at 18:14 UTC), count the minutes from it to now, and divide by 42524. The whole months do not matter; the remainder is the Moon's age.

Age Phase Lit
0 days New moon 0%
7.4 days First quarter 50%
14.8 days Full moon 100%
22.1 days Last quarter 50%

The lit fraction is (1 - cos(angle)) / 2, with the angle a full turn per month. The lamp names the four big moments when the age is within a day of them, and calls everything between a crescent or a gibbous moon.

This is the mean Moon. The real Moon's orbit is an ellipse, pulled on by the Sun, so a real new or full moon can come up to about half a day before or after the lamp's. That is plenty to name the phase on any night, and not enough to time an eclipse.

Counting days. Months have different lengths and leap years come and go, so the sketch uses a well known trick: it starts the year on March 1, which puts the leap day last, and counts 400-year eras of exactly 146097 days. The same trick run backwards turns "full moon in 3.8 days" into a date.

Drawing it. The disc is every LED within 4 of the panel's center, which keeps 52 of the 64. On each row the shadow's edge sits at halfWidth x cos(angle). A waxing Moon is lit to the right of the edge, a waning one to the left, and in the southern hemisphere the two swap.

The clock. The DS3231 stores the time in binary coded decimal: 21 hours is the byte 0x21. Its oscillator stop flag goes up whenever it has stopped, so a careful sketch knows when the time cannot be trusted.

The dark. Night starts when A0 falls below 250 (about 3 lux) and day comes back only above 350 (about 7 lux), so the lamp never flickers at dusk. Either has to last a whole second, so headlights sweeping past the window are ignored.

The course

Build a moon phase lamp takes six lessons:

  1. The lunar cycle: a whole month in fifteen seconds, why phases happen, and the synodic month.
  2. Phase from a date: one known new moon, a remainder, and the Moon over Apollo 11.
  3. LEDs as a moon: the 52-LED disc, the shadow edge, and panels that zigzag.
  4. RTC time: the DS3231 register by register, setting the clock and a leap day.
  5. Glow at night: a light cell divider, hysteresis and a one-second wait.
  6. Project: tonight's moon: the whole lamp, the next full moon, a month-long time-lapse and a southern sky.

Every step but the last is checked against the running circuit.