Projects / Moon phase clock

Moon phase clock

Beginner2.5 hGuided buildReviewed

Build it step by step

0 of 8 done
  1. NANO

    Wire the clock and display

    Both on A4 and A5 with 5V and GND.

  2. NANO

    Wire the button

    D2 to GND.

  3. NANODS323114:16SSD1306

    Install the libraries

    RTClib, Adafruit SSD1306 and Adafruit GFX.

  4. NANO

    Upload the sketch

    The clock sets from the computer on first run.

  5. NANO

    Look at the moon view

    Disc, age, lit percentage and days to full.

  6. NANO

    Press the button

    The date and time view.

  7. NANO

    Compare with a calendar

    Check against a moon phase table.

  8. NANO

    Change the hemisphere

    Swap the lit side for the southern hemisphere.

In short

How do you build a moon phase clock?

A clock and a small display work out today's moon phase from the date and draw it as a lit disc, with the age of the moon and the days to the next full moon. You need Arduino Nano, DS3231 RTC module, SSD1306 OLED Display, Tactile push button 6 mm, Jumper wires male to male (40 pcs, 20 cm) and Breadboard 830 Tie Points. It takes 8 steps and about 150 minutes.

Level
Beginner
Time
About 150 min
Parts
6

Parts list

Tick what you already own. It saves to My Garage, so “Build with what I have” knows.

Wiring

FromToWhy
DS3231 SDA and OLED SDANano A4Shared I2C data
DS3231 SCL and OLED SCLNano A5Shared I2C clock
DS3231 VCC and OLED VCCNano 5VPower (check your OLED accepts 5 V)
DS3231 GND and OLED GNDNano GNDCommon ground
Button leg 1Nano D2Switch between moon and date views
Button leg 2Nano GNDPressed pulls D2 low

Code

The moon goes through its phases in a regular cycle of about 29.53 days, called the synodic month. If you know the date of one new moon, you can work out the age of the moon on any other day by counting the days since then and keeping only the remainder after dividing by 29.53. The sketch uses the new moon of 6 January 2000 as its reference, takes the date from the DS3231 clock, and turns that age into a fraction of the cycle. The lit part of the moon follows a cosine curve: it is zero at new moon, half at the quarters and full at full moon. To draw it, the sketch goes row by row through the disc, works out the width of the disc on that row, and then finds where the dividing line between light and dark falls on that row, using the same cosine. On the waxing side the lit part is on the right, as seen from the northern hemisphere, and on the waning side it is on the left. The result is approximate, because the real month varies by several hours, so it may be off by a day near the quarters. A button flips between the moon view and the date and time. Set the clock once from the computer when the board first runs.

Runs on a virtual Arduino Nano in your browser, with sliders for the sensors. Happy with it? Verify and upload to your real board from the same page (Chrome or Edge on a computer).

#include <Wire.h>
#include <RTClib.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#include <math.h>

RTC_DS3231 rtc;
Adafruit_SSD1306 oled(128, 64, &Wire, -1);

const int BTN = 2;
const double SYNODIC = 29.530588853;          // days from new moon to new moon
const int CX = 32, CY = 32, R = 26;           // moon disc on the left of the screen

bool showDate = false, wasPressed = false;
unsigned long lastPress = 0, lastDraw = 0;

double moonAgeDays(const DateTime &now) {
  DateTime ref(2000, 1, 6, 18, 14, 0);                          // a known new moon
  double days = ((double)now.unixtime() - (double)ref.unixtime()) / 86400.0;
  double age = fmod(days, SYNODIC);
  if (age < 0) age += SYNODIC;
  return age;
}

void drawMoon(double frac) {
  double c = cos(2.0 * PI * frac);
  for (int dy = -R; dy <= R; dy++) {
    double w = sqrt((double)R * R - (double)dy * dy);
    int x0, x1;
    if (frac < 0.5) {                                           // waxing: lit side on the right
      x0 = CX + (int)(w * c);
      x1 = CX + (int)w;
    } else {                                                    // waning: lit side on the left
      x0 = CX - (int)w;
      x1 = CX - (int)(w * c);
    }
    if (x1 >= x0) oled.drawFastHLine(x0, CY + dy, x1 - x0 + 1, SSD1306_WHITE);
  }
  oled.drawCircle(CX, CY, R, SSD1306_WHITE);                    // outline of the dark part too
}

void setup() {
  pinMode(BTN, INPUT_PULLUP);
  Serial.begin(9600);
  if (!rtc.begin()) { Serial.println("RTC not found"); while (true) {} }
  if (rtc.lostPower()) rtc.adjust(DateTime(F(__DATE__), F(__TIME__)));
  if (!oled.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { while (true) {} }
}

void loop() {
  bool pressed = (digitalRead(BTN) == LOW);
  if (pressed && !wasPressed && millis() - lastPress > 40) {
    lastPress = millis();
    showDate = !showDate;
  }
  wasPressed = pressed;

  if (millis() - lastDraw >= 1000) {
    lastDraw = millis();
    DateTime now = rtc.now();
    double age = moonAgeDays(now);
    double frac = age / SYNODIC;
    int lit = (int)(100.0 * (1.0 - cos(2.0 * PI * frac)) / 2.0 + 0.5);
    double toFull = (age < SYNODIC / 2.0) ? (SYNODIC / 2.0 - age) : (SYNODIC * 1.5 - age);

    oled.clearDisplay();
    oled.setTextColor(SSD1306_WHITE);
    oled.setTextSize(1);
    if (!showDate) {
      drawMoon(frac);
      oled.setCursor(68, 6);  oled.print("Age "); oled.print(age, 1); oled.print(" d");
      oled.setCursor(68, 22); oled.print("Lit "); oled.print(lit); oled.print("%");
      oled.setCursor(68, 38); oled.print("Full in");
      oled.setCursor(68, 48); oled.print(toFull, 1); oled.print(" d");
    } else {
      char buf[24];
      snprintf(buf, sizeof(buf), "%04d-%02d-%02d", now.year(), now.month(), now.day());
      oled.setTextSize(2);
      oled.setCursor(4, 12); oled.print(buf);
      snprintf(buf, sizeof(buf), "%02d:%02d:%02d", now.hour(), now.minute(), now.second());
      oled.setCursor(16, 40); oled.print(buf);
    }
    oled.display();
  }
}

What the serial monitor should show

Open the serial monitor at the baud rate in the code. This is what our simulator prints for a virtual Arduino Nano with its sensors at their default values. Your numbers will follow your real readings, but the format should match.

RTC not found

Test checklist

What you should see at each check. If a reading is far off, stop and use the troubleshooting list.

CheckExpected
Power onMoon disc with the age in days
At new moonAlmost no lit part, about 0 percent
At first quarterRight half lit, about 50 percent
At full moonFull disc lit, about 100 percent
Button pressDate and time in large text

If it does not work

Blank screen

Check A4 and A5 and the OLED address.

Wrong date

Reflash once with the computer clock correct.

Phase is a day off

The mean month is approximate, this is normal near the quarters.

Lit side is on the wrong side

Swap the waxing and waning branches for your hemisphere.

Clock resets at power-off

Check the backup cell in the DS3231 module.

Still stuck? Find the fault step by step with your multimeter →

Ask Lark AI

Common questions

What parts do I need for the moon phase clock?

Arduino Nano, DS3231 RTC module, SSD1306 OLED Display, Tactile push button 6 mm, Jumper wires male to male (40 pcs, 20 cm) and Breadboard 830 Tie Points.

How long does the moon phase clock take to build?

About 150 minutes for a beginner maker, in 8 steps.

How do I know the moon phase clock works?

Power on: Moon disc with the age in days. At new moon: Almost no lit part, about 0 percent. At first quarter: Right half lit, about 50 percent.

Blank screen: what should I check?

Check A4 and A5 and the OLED address.

Wrong date: what should I check?

Reflash once with the computer clock correct.

Phase is a day off: what should I check?

The mean month is approximate, this is normal near the quarters.

Lit side is on the wrong side: what should I check?

Swap the waxing and waning branches for your hemisphere.