Build it step by step
0 of 8 doneWire the clock and display
Both on A4 and A5 with 5V and GND.
Wire the button
D2 to GND.
Install the libraries
RTClib, Adafruit SSD1306 and Adafruit GFX.
Upload the sketch
The clock sets from the computer on first run.
Look at the moon view
Disc, age, lit percentage and days to full.
Press the button
The date and time view.
Compare with a calendar
Check against a moon phase table.
Change the hemisphere
Swap the lit side for the southern hemisphere.
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
| From | To | Why |
|---|---|---|
| DS3231 SDA and OLED SDA | Nano A4 | Shared I2C data |
| DS3231 SCL and OLED SCL | Nano A5 | Shared I2C clock |
| DS3231 VCC and OLED VCC | Nano 5V | Power (check your OLED accepts 5 V) |
| DS3231 GND and OLED GND | Nano GND | Common ground |
| Button leg 1 | Nano D2 | Switch between moon and date views |
| Button leg 2 | Nano GND | Pressed 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.
| Check | Expected |
|---|---|
| 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 |
| At full moon | Full disc lit, about 100 percent |
| Button press | Date 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 →
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.
