Hollow Clock

This Arduino project implements a hollow clock using an ESP8266, and other libraries. The clock's hands move to display the current time, and it is designed to be configurable for different WiFi networks. The project is based on this project on instructables.

Features

• Displays the time on a hollow clock face using stepper motors.
• Connects to multiple WiFi networks for flexibility.
• Dashboard-based calibration flow (Hour + Minute + Start Reset) so startup alignment is easier.
• Modernized web dashboard UI with improved layout and automatic dark-mode support (prefers-color-scheme).
• Configurable NTP server and intuitive timezone settings via UTC_OFFSET_HOURS and UTC_OFFSET_MINUTES.
• Optional static IP mode via USE_STATIC_IP and configurable address/gateway/subnet/DNS values.
• Modularized code structure for easier maintenance (web_ui, wifi_service, clock_time).

Hardware Requirements

• ESP8266 microcontroller
• Stepper motors
• Other hardware components as required

Installation and Setup

1. Clone this repository.

2. Copy config_CUSTOMIZE_ME.h to config.h and update the WiFi credentials.

3. Set UTC_OFFSET_HOURS and UTC_OFFSET_MINUTES in config.h for your local timezone. China Standard Time is 8 hours and 0 minutes.

4. Set NTP_SERVER in config.h if you want to override the default time source. The default is ntp.aliyun.com.

5. Optional: enable static IP by setting USE_STATIC_IP to 1 and filling these values in config.h:

   • STATIC_IP_ADDRESS
   • STATIC_IP_GATEWAY
   • STATIC_IP_SUBNET
   • STATIC_IP_DNS1
   • STATIC_IP_DNS2

   Leave USE_STATIC_IP as 0 to keep DHCP behavior.

6. Open hollow_clock_wifi.ino in Arduino IDE, or use Arduino CLI.

Build and Flash

GitHub Actions also builds the firmware automatically on every push and pull request. The compiled files are uploaded as the firmware-esp8266-nodemcuv2 artifact. When you publish a GitHub Release, the workflow also attaches the generated .bin and .elf firmware files directly to that release.

You can flash the clock in two ways:

Option 1: Compile and upload from source

1. Install the ESP8266 board package:

   arduino-cli core install esp8266:esp8266 \
     --additional-urls https://arduino.esp8266.com/stable/package_esp8266com_index.json

2. Compile the sketch:

   arduino-cli compile --fqbn esp8266:esp8266:nodemcuv2 \
     --additional-urls https://arduino.esp8266.com/stable/package_esp8266com_index.json \
     /home/uniqueding/Workspace/hollow_clock_wifi

3. Find the serial port:

   arduino-cli board list

4. Upload to the board:

   arduino-cli upload -p /dev/ttyUSB0 --fqbn esp8266:esp8266:nodemcuv2 \
     /home/uniqueding/Workspace/hollow_clock_wifi

   If your user does not have serial-port permissions yet, either log in again after joining the correct device group or use sudo together with the same --additional-urls value used above.

Option 2: Flash a prebuilt .bin firmware directly

1. Download the .bin file from the GitHub Actions artifact or GitHub Release.

2. Install esptool if needed:

   python -m pip install esptool

3. Find the serial port:

   arduino-cli board list

4. Write the firmware directly to flash:

   python -m esptool --port /dev/ttyUSB0 --baud 460800 write_flash 0x0 firmware.bin

   Replace firmware.bin with the actual downloaded .bin filename.

5. If flashing fails because the board is not in bootloader mode, hold the FLASH or BOOT button while resetting the ESP8266, then run the command again.

Usage

1. Power on the ESP8266 with the uploaded firmware.

2. Open the dashboard page from your browser.

3. In Calibration, enter the current hand position (Hour and Minute).

4. Click Start Reset.

5. The clock moves from the entered hand position to the current NTP time and then keeps tracking normally.

Project Structure

• hollow_clock_wifi.ino - Main application flow and motor control loop.
• web_ui.h / web_ui.cpp - Dashboard rendering and web route wiring (including calibration endpoint).
• wifi_service.h / wifi_service.cpp - WiFi connection helper logic.
• clock_time.h / clock_time.cpp - Time-sync, uptime formatting, and time-to-step calculations.
• dashboard.h / dashboard.cpp - Reusable lightweight dashboard component and page template.

License

This project is licensed under the MIT License.