On power-up, the clock will display a splash screen while it connects to the WiFi network and makes a couple of initial server requests for time and Moon data.
Time is provided by WorldTimeAPI, and astronomical data from the Norwegian Meteorological Institute. These two sources were chosen as they are free and do not require an account for access.
The orientation of the clock at startup determines how information is displayed — in a vertical “portrait” format, or horizontal “landscape” format.
With the clock set up horizontally (either hung or propped up with a stand or case), the current Moon phase (with percentage lit) is displayed on the left.
The current time and date are displayed on the right. Below this is an indication of the next moonrise or set…
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.
All the same data is displayed when the clock’s in a vertical orientation, but the visibility of the Moon from your location is made more apparent.
When the Moon is above the local horizon (in the sky) the phase is shown at the top of the matrix.
And if the Moon is currently below the local horizon, the phase scoots to the bottom.
The Moon might still appear above the horizon for someone to the west of you, but the phase will be nearly the same. That’s how this game of cosmic billiards works.
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.
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
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.
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 ~12 hours if NOW - LAST_SYNC > 12 * 60 * 60:
Change the 12 to a smaller value…perhaps 6, or 3 if the time drift is really pronounced. This is the period (in hours) between clock updates. To avoid over-taxing the server, which they’re providing 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.
