Time is provided by Adafruit IO, and astronomical data from the Norwegian Meteorological Institute. These two sources were chosen as they are free and do not require a paid account for access.

The orientation of the clock at startup determines how information is displayed — in a vertical “portrait” format, or horizontal “landscape” format. There’s different artwork for all four directions!

Clock Operation Basics

A downward-pointing arrow (as shown above) indicates the next lunar event will be a moonset — that the Moon is currently above the horizon (in the sky) as seen from your position, regardless of phase.

An upward-pointing arrow indicates a moonrise is next — the Moon is currently below the horizon, not currently visible from your position, regardless of phase.

The time shown next to the arrow is when this next lunar rise or set event will occur. It can alternately be configured as a countdown, explained shortly.

The color of the time and arrow indicates whether this next event occurs in the a.m. hours (green) or p.m. (amber).

The rise and set times are for an “idealized” horizon. Hills or other local obstructions could have it rising a short time later or setting earlier.

The percentage shown is the amount of the lunar “disc” that’s currently illuminated, not the “age” of the current lunar month. So this will go from 0% (new Moon) to 100%* (full Moon) and back down to 0% (next new Moon) over the course of the lunar month. The lunar terminator — the line between light and dark — always moves right to left, like turning the pages of a book (that’s why it doesn’t bother reporting if the phase is waxing or waning — it’s easy to visualize).

* It’s normal some months that you’ll see this only go to 99.8 or 99.9 percent…the Moon’s never quite perfectly full from our position.

If the clock starts up in the wrong orientation…just tap the reset button and let it try again. Occasionally the accelerometer gets confused when grappling the clock to plug it in, or the “snap” of a USB cable being inserted.

Customizing the Clock Display

Some aspects of the clock display can be changed by editing the file code.py in your text editor of choice. Starting around line 35, look for this section of code:

# CONFIGURABLE SETTINGS -------------------------------------

TWELVE_HOUR = True # If set, use 12-hour time vs 24-hour
COUNTDOWN = False  # If set, show time to next rise/set event

# CONFIGURABLE SETTINGS -------------------------------------

TWELVE_HOUR = True # If set, use 12-hour time vs 24-hour
COUNTDOWN = False  # If set, show time to next rise/set event

Change the value of TWELVE_HOUR to False (capitalized — Python is case sensitive) to have the clock display times in 24-hour military time.

Changing COUNTDOWN to True makes the clock show the time to the next rise/set event (hours and minutes), rather than the time of the event. Both modes are shown in the same HH:MM format, so COUNTDOWN mode may be confusing if you’re not familiar with the clock’s operation.

The startup splash screen images are inside the moon folder, named splash-0.bmp, splash-90.bmp, splash-180.bmp and splash-270.bmp — one image is selected on startup based on the Matrix Portal orientation. If you’ve settled on a position for installing your Moon clock but want the opposite splash image, you can just rename these files, e.g. swap the filenames on splash-0.bmp and splash-180.bmp (or 90 and 270). Or you can delete the splash images (they might be frightening to children) or substitute your own BMP files.

Matrix brightness is not currently adjustable. It’s just more than the microcontroller can handle.

Timekeeping

The clock will periodically contact a time server to keep itself in sync. But if you observe the time drifting by more than a minute or two, you can have it sync more often.

Look for these lines in code.py (in the “MAIN LOOP” section):

# Sync with time server every ~3 hours
if NOW_LOCAL_SECONDS - LAST_SYNC_LOCAL_SECONDS > 3 * 60 * 60:

# Sync with time server every ~3 hours
if NOW_LOCAL_SECONDS - LAST_SYNC_LOCAL_SECONDS > 3 * 60 * 60:

Change the 3 to a smaller value…perhaps 2, or 1 if the time drift is really pronounced. This is the period (in hours) between clock updates. To avoid over-taxing the server, provided as a free service, don’t set this too low.

Interestingly, the clock will keep better time if powered from a computer’s USB port (which provides a steady 1.000 KHz reference pulse) than from a passive USB “wall wart.” Not always practical, of course…but if you have a free USB port on a NAS or other nearby system that runs 24/7, it’s something to consider.