# [HALO](/) Halo Clock design and code by Shae M Puckett 2025 ## The Clock Itself The clock is 20cm (8") in diameter and just 16mm (5/8") thick. From the front, it's a plain circle, with a small opening for an ambient light sensor. On the back are three buttons and a small text display. There's a hang hole near the top, and a USB-C port at the bottom. The halo LEDs are arranged in a circle under a reflector to reduce glare, and shine outward onto the wall where the clock is hung. ### Mount your Clock You can hang the clock from a picture hook / nail, or dangle it from the USB cable: see the Setup menu to set clock orientation. The display looks best when the clock is snug against the wall; if necessary for your situation, use a few pieces of poster adhesive (e.g. Blu-Tak) to gently secure it in place. Don't permanently tape/glue it down, though, you will interact with the clock's buttons and display occasionally, and if it's stuck to the wall you can't do that! ### Clock Buttons ❉ Set ◀ Prev ▶ Next Press `Set` to open the Main Menu, confirm menu choices, and save values Press `Prev` and `Next` to switch themes (in clock mode), change selections, and adjust values. Hold the button down to quickly change values. Hold down `Set` to return to clock mode from any other mode ### Touch Sensor The touch sensor is centred on the front of the clock face. Use your palm, or several fingers side by side, to activate the sensor reliably. From the factory, a brief tap with your hand will brighten the halo. A longer touch (about a second) will switch to the next theme. This is configurable in the Touch menu. ## Quick Start ### Method 1: Browser Setup (Recommended) 1. **Power the clock** Connect a USB-C cable. Note the **Clock ID #** on the back. 2. **Access the setup portal** Open [haloclock.ca](https://haloclock.ca) on any device with a web browser (phone/desktop). 3. **Configure basic settings** Under *HALO Tools*, click **Set Time**. Enter your three digit Clock ID where prompted. Follow on-screen instructions. Time, date and timezone will be set to match your computer. The setup portal does not use Bluetooth or WiFi, just short flashes of light. 4. **Advanced settings (optional)** Use **Set Location** to input latitude/longitude for astronomical theme accuracy. Use **WiFi Credentials** to connect your clock to WiFi for automatic time sync and firmware updates. *About internet connectivity*: the Halo Clock **does not maintain a constant WiFi connection**. It only connects occasionally to sync time with global servers (anonymous), or manually to check for theme updates. No other internet functions are used. ### Method 2: Manual Setup (No Internet) 1. **Power the clock** via USB-C. 2. **Set Timezone** Press `Set` 3 times: *(Menu → Time → Timezone)*. Use `Next`/`Prev` to select UTC offset → Press `Set`. Adjust minutes if needed → Press `Set`. Clock display shows *Ok* when settings are saved. 3. **Set Time** Press `Set` twice → `Next` → `Set` *(Menu → Time → Set Time)*. Adjust hours → `Set` → Adjust minutes → `Set` twice (skip seconds). 4. **Set Date** Press `Set` twice → `Next` twice → `Set` *(Menu → Time → Set Date)*. Adjust year/month/date → `Set`. 5. **Set Location (Optional)** Press `Set` → `Next` twice → `Set` → `Next` twice → `Set` *(Menu → Setup → Location)*. Adjust latitude/longitude with `Next`/`Prev` (hold for rapid changes) then `Set`. *Note*: WiFi **cannot** be configured manually—use the browser method. ### Starter Theme Descriptions 1. **Chronometer** - Hours: centre of wide dim white hand. Minutes: narrow bright white hand. Seconds: narrow orange hand. 2. **Fast Blend** - Hours: edge of green gradient. Minutes: edge of red gradient. Seconds: fast sweeping blue gradient. 3. **Dusk and Dawn** - Hours: edge of orange gradient. Minutes: edge of blue gradient. Seconds: narrow bright white hand. 4. **Pastel Blend** - Hours: edge of cyan gradient. Minutes: edge of magenta gradient. Seconds: edge of yellow gradient. 5. **Corona** - Hours: gap in warm white ring. Minutes and seconds are not shown. 6. **Bubblegum** - Hours: gap in magenta ring. Minutes: bright white narrow hand. Seconds just a faint blue. 7. **Metro** - Hours: gap in dim white ring. Minutes: bright white narrow hand. Seconds: narrow red hand. 8. **Gemstone** - Hours: edge of emerald green gradient. Minutes: edge of pink sapphire gradient. Seconds: bright white hand. ## Menu System Click the Set button in clock mode to show the Main Menu. When accessing the menu system, hold the clock with buttons facing you. When the menu is visible, the clock hands are flipped left-to-right so the time reads properly from the back. ### Menu Operation The top of the text display shows the name of the menu or setting you are viewing, alternating with extra information and button functions. The currently selected option or value is shown below in larger text. Click the `Prev` and `Next` buttons to switch among menu items. Click `Set` to confirm your choice. You can return to clock mode at any time by holding down the `Set` button. ## Main Menu Click the `Set` button in clock mode to show the Main Menu: **Ambient** - adjust how the clock responds to ambient light **Brightness** - adjust the overall halo brightness **Time** - set the time (this is the first menu option shown) **Theme** - modify the current clock theme **Setup** - additional clock settings **Touch** - choose what happens when you touch the clock face Click `Next` / `Prev` to switch among options. Click `Set` to choose. ## Ambient Menu **Constant** - halo brightness is always the same **Auto** - halo brightness adjusts to ambient room lighting **Off in Dark** - Auto, and halo shuts off when room is dark **Dark Level** - Set the ambient light level for dark mode When the clock has shut off in a dark room, a faint pip is still shown at the hour hand position so you can see the time without affecting your night vision. (Some themes may show a different dark mode pip.) ### Off in Dark Wake Time You can set the halo to turn back on at a certain time even if the room is still dark. The brightness increases slowly, starting 30 minutes before the time set. The halo will stay on four hours after the wake time, no matter how dark the room is. ## Brightness Menu Choose among: **Faint**, **Dim**, **Low**, **Medium**, **Moderate**, **Bright**, **Vivid**, **Maximum**. Each twice as bright as the previous. If the ambient light response setting allows automatic adjustment, brightness settings are not absolute: the halo tries to maintain a consistent visual impact as the room light level changes. The halo cannot get bright enough to be visible in direct sun, but it should be readable in most indoor lighting conditions. ## Time Menu **Timezone** - set the timezone / offset from UTC **Set Time** - set the current local time **Set Date** - set the year, month and day **Time Sync** - manage automatic time synchronization **Time Drift** - change the daily time adjustment (see below) ### Timezone Timezone is set as a single offset of hours and minutes (rounded to the nearest 15 minute interval). The current offset is shown as HH:MM with a + or -, followed by any time zone abbreviations associated with that offset (e.g. `-05:00 EST`). Halo Clock does not automatically change timezone offset as the year progresses. If your locality follows DST, you will need to reset the timezone twice a year. *Do not change the time directly,* just change the timezone offset. Note: Timezone, time and date will be set for you if you use haloclock.ca's time setting feature. ### Set Time / Synchronize Seconds Time is set in a sequence of three modes: hour, minute, and synch seconds. To synchronize seconds to another clock when prompted, wait until that clock shows :00 seconds and click `Prev` or `Next` to reset seconds to zero at the nearest minute. Otherwise just click `Set` to finish setting the time. As noted previously, don't change the time when Daylight Savings alterations are needed: change the Timezone instead. ### Time Sync **Off** - Do not automatically synchronize **Daily** - Synchronize as needed **Now** - Synchronize immediately Time Sync via NTP is a free service for synchronizing clocks to a global standard. To use this feature, you must have WiFi access set up on your clock, including an SSID and password to a local WiFi access point. The clock cannot update the halo LEDs while synchronizing, so the display will freeze in place and may show minor colour shifts. The display on the back of the clock will show the status of the synchronization attempt. Note that the WiFi antenna in the clock is small and may have trouble making a connection — including false reports of “bad passwd?” — if your access point is far away. ### Time Drift The clock has a built-in, battery backed quartz crystal chronometer that keeps accurate time within several seconds a day. The amount of error varies dependent on ambient temperature and crystal manufacturing tolerances. Drift is an algorithmic correction applied by the firmware to correct the chronometer beyond its physical capabilites. If you are using the Time Sync feature to synchronize the clock with the internet NTP service, drift will be automatically set over the course of a few days, and you should not need to manually set drift with this menu. If you are not using Time Sync, you will likely want to adjust the drift so your clock is more accurate. #### Drift adjustment v1.14 or later Setting the drift manually is a matter of matching up the time shown on the LED panel with realtime as shown by a web service, e.g. [time.is](http://time.is). Use the left and right buttons to sync up the seconds on the clock as close as you can to real time, then press SET. The clock will determine the drift adjustment from the correction applied here and the elapsed time since the last drift change. #### Older Versions The drift amount in older versions is the number of seconds per day to add / subtract from the quartz chronometer’s timekeeping. For example, if you discover the clock is running about 10 seconds fast per day, set drift to -10 sec/day. Drift is set cumulatively: make rough adjustments, then tweak over the course of several weeks. If drift seems to get out of hand and the clock becomes very unreliable, use the Reset Menu to reset Timekeeping. ## Theme Menu The clock ships with six theme types installed, and eight themes already setup. The factory themes all use the *Analogue* theme type; see the explanation of these themes at the beginning of the document. You switch among the themes shown on the clock face with the `Prev` / `Next` buttons while in clock mode. To edit the current theme, or create a new theme, you'll use the theme menu. To get to the theme menu, click `Set` from clock mode, then `Next`, then `Set` again. *(Menu -> Theme)* **Delete** - delete current theme (confirmation asked) **Edit** - edit current theme **Add** - add new theme, and begin editing (24 themes maximum) ### Editing Themes After you choose **Edit** (or **Add**) in the theme menu, you enter the theme editor. This is a *cyclical menu*, meaning that once you reach the end of the menus, they loop around back to the beginning. In this way you can easily tweak a theme's options repeatedly without having to reopen the editor. Exit the theme editor by holding the `Set` button. The first page in the theme editor is the theme type chooser. Changing this value will change all of the menu pages that follow according to the needs of the theme type. The halo display shows the changes you make right away. Press `Next` / `Prev` to change values in the theme editor, and press `Set` to advance to the next page. (Hold `Set` to exit the editor, returning to clock mode.) Some (not all) themes present a *Theme Code* menu which you can use to install the theme on another clock using the haloclock.ca Set Theme tool. A link that sets a theme from a code can be created as follows: `http://haloclock.ca/theme.html?code=####` ### Theme Types The clock as delivered has six theme types: **Analogue** - like a traditional dial clock, but the hands are beams of light **Flag** - displays colour stripes or a gradient, with light or dark analogue clock hands **Kaleido** - constantly changing colours, with light or dark clock hands **Sun & Moon** - shows the position of the sun and moon in the sky **Rise & Set** - shows the timing of dusk/dawn on a 24 hour clock, with the "sun" as time indicator **Ephemeris** - shows the equatorial positon of the sun, moon, major and dwarf planets Details about these theme types is available at [haloclock.ca](https://haloclock.ca). If you have installed additional theme types via online update, they will appear in the menu. ## Setup Menu These are infrequently used options to set your clock to specific needs. **12/24 Hour** - change dial scale from 12 hours to 24 (midnight at top, noon at bottom), applies to all themes unless otherwise noted **Colour Temp** - Overall warmth/coolness of Halo display **Orientation** - hanging from a hook (cord down), or dangling from the cord (cord up). **Location** - establish geographic coordinates of the clock (or use tools on haloclock.ca) **Fascia** - Brightness adjustment for clocks with fascia (covers) **Flashnet** - Flashnet settings (see below) **Update** - check for updated firmware (WiFi required) ### Flashnet and haloclock.ca Flashnet is a simple way to transmit small amounts of data to the clock from a web browser screen, without using WiFi or Bluetooth. To receive this data, Flashnet must be enabled on the clock. As shipped, the clock allows Flashnet data when the browser knows the clock ID (on the back of the clock). The Flashnet menu has these options: **Locked** - Flashnet is disabled (secure) **ID ###** - Flashnet is enabled only using the clock ID **Any ID** - Flashnet is enabled; the clock accepts any data sent Once enabled, use a web browser to open haloclock.ca — you can set accurate time, and provide WiFi credentials. #### Receiving Flashnet Data When Flashnet is enabled on your clock, hold the front of the clock (with the small ambient light sensor) near the bright circle on the page and click the Send button. The circle will flash for a few seconds while it transmits data. If the clock is close enough to receive it clearly, when the flashing is done the halo will blink green and the display will tell you what has been received. If the clock display shows “Try Again” or doesn’t respond at all, reposition the clock slightly closer or farther from the display, and try again. Be sure to hold the clock steady. If the clock display shows “Not For Me,” the clock ID in the widget does not match the clock’s own ID (shown in the menu, and when the clock powers on). Correct the ID or use the Flashnet menu to enable Any ID. “Bad Data” indicates data corruption or a malformed data packet from the server. ## Touch Menu **Clocks with firmware 1.16 and later.** Halo Clock has a touch sensor in the centre of the disc. There are two touch interactions you can perform: you can tap it briefly with the fingers of your hand ("tap"), or hold your hand there for a second ("hold") or so. (Note: use the flat of your hand or palm to touch, don't just poke with a finger. The sensor is small and reads touch better from a hand than a finger. The Touch Menu lets you select a function for each of the interactions, *Tap*, and *Hold*, as follows: **Do Nothing** - Take no action **Brighten** - Increases the brightness of the display to maximum for 15 minutes. Second touch returns to normal **Lamp** - Turns on all LEDs to bright white for 12 hours. Second touch returns to clock mode **Next Theme** - Advances to the next theme, like pressing the Next button on the back of the clock If the clock is asleep (dark), any touch will wake the display for 15 seconds as a nightlight. ## System Management ### Restoring the Clock to Factory State The clock’s settings can be restored to factory state through the reset menu. To access it, unplug the clock then hold down all three buttons: Set, Next and Prev. Plug the clock in while these buttons are down, and the Reset Menu will appear, with a red pattern on the halo. Release the buttons. #### Reset Menu **All** - restore entire clock to factory state **Firmware** - reset clock firmware, keeping all settings **Sensors** - reset light sensor (if you have changed the façade) **Settings** - reset themes and other user settings to original **Timekeeping** - reset crystal drift settings to zero **Network** - erase WiFi login credentials **Deep Sleep** - (see below) **Reboot Now** - returns to clock mode You must hold the `Set` button down for at least one second to activate any reset function. The halo will flash red once action has been taken. The Reset menu will time out after 30 seconds of inactivity, returning to clock mode. #### Deep Sleep If you’re not going to use the clock for a while, or are shipping it somewhere, you can stop timekeeping to conserve backup battery power. Select this option in the Reset Menu, then unplug the clock at once. The next time the clock is plugged in, time/date will need to be set. (All other settings are retained.) ### Troubleshooting #### Backup Battery If clock needs to be set each time it is plugged in, remove clock back as below, and replace the battery with a new lithium type CR2032, CR2025 or CR2016. To remove the back, unplug the clock, remove the two small screws from the back of the clock, then slide the back off the clips opposite the screws. Be careful: the display is attached to the back of the clock, and short cables lead to the circuit board on the clock body. Ideally, do not detach the cables when changing the battery. To remove the battery, use a flat-bladed screwdriver or other small instrument to pull the clip aside, then lift the battery out. Insert the new battery flat side up under the edge of the clip, and press the other side of the battery down into the holder until it clicks into place. To replace the back, ensure the display cables are routed loosely, align the hang hole with 12 o’clock and the cord hole with 6 o’clock (the USB cable position), slide the back into the clips, align the screw holes, and replace the screws. #### USB Cable Requirements The Halo Clock uses a USB C power cable. It can draw up to 5 Watts of power at its brightest, well within the specifications of properly made USB cables. If the clock behaves erratically, try changing cables or power ports, especially when using longer cables. (Some USB power banks may cut power unexpectedly, thinking nothing is attached. These are poorly designed.) #### Clock Brightness If the clock seems too bright or too dark despite adjustment in the Brightness menu, the ambient light sensor may need to be recalibrated. Using the Reset Menu, reset Sensors, then restart the clock. Now hold the light sensor on the front of the clock up to a lightbulb or a bright window for 10-15 seconds, so it re-learns what “bright” is. #### Error Conditions The clock will report most hardware / software errors, pause for a while, then reset in an attempt to keep being a clock. (If the halo turns dark blue for a few seconds, an error message is shown on the text display.) ## Thanks To Stewart Russell, for inspiration and technical help. MicroPython team for an acceptable development platform. You for your support of this functional artwork.