Build Your Own HamClock Pi

Just want it to work? Grab a pre-built image, flash it, and you're done — no command line at all. This page is for folks who'd rather build it themselves or run a board the images don't cover.

Building HamClock from source isn't hard, but most guides bury it under Linux jargon. Here's the honest, start-to-finish version. Read it once, then work through it in order. Type every command exactly as shown — Linux is case-sensitive and unforgiving of typos.

00What you'll need

A Raspberry Pi. A Pi 4 or 5 with 2–8 GB RAM is the sweet spot. A Pi 3 or Zero 2 W works but builds slower and wants a smaller resolution.
An SD card, 16 GB or larger. A name-brand card matters — cheap cards are the top cause of "it worked yesterday."
Power, network, and a display if you want a screen. No display? Build the web version and view it in a browser — covered below.

01Flash Raspberry Pi OS

Install Raspberry Pi Imager from raspberrypi.com/software. Choose your Pi model, then Raspberry Pi OS (64-bit) with the desktop — the Bookworm release, not the newer Trixie (it moved things HamClock's autostart depends on). Open the gear menu to set hostname, Wi-Fi, locale, and enable SSH before writing. Pick your SD card carefully (it gets erased), write, and boot the Pi.

02First boot and update

$ sudo apt update && sudo apt upgrade -y
$ sudo reboot

03Get HamClock

Two ways — the easy one most people should use, and the manual route.

Option A — Our install script Recommended

$ curl -OL https://hamclock.com/build-hc-rpi
$ chmod u+x build-hc-rpi
$ ./build-hc-rpi

Type y to proceed. It installs the build tools, downloads the source, and builds it. Three notes: it may look like it's hanging on "installing helper packages" (it isn't — that step is slow); it asks whether you want a web-only build (answer n for a screen, y for headless); and it asks what resolution — pick the largest your display supports, usually 1600×960. When it finishes, skip to Step 04.

Option B — Build it by hand

$ curl -OL https://hamclock.com/ham/HamClock/ESPHamClock.zip
$ unzip ESPHamClock.zip
$ cd ESPHamClock
$ make help

Three target families matter:

hamclock-1600x960 — normal desktop version drawn on the Pi's screen. Swap the numbers for another size (800x480, 2400x1440, 3200x1920).
hamclock-web-1600x960 — web-only, no local screen. Open http://<pi-ip>:8080/live.html from any browser.
hamclock-fb0-1600x960 — draws straight to the framebuffer, no desktop.

$ make hamclock-1600x960
$ sudo make install

If the build stops on a missing library, install that package with apt and run make again — it picks up where it left off.

04Point it at hamclock.com

This is the whole reason your clock survives June 2026. If you built from our source, it likely already defaults here — launch it and check the header. To be sure, add the -b flag:

$ /usr/local/bin/hamclock -b hamclock.com:80 &

If the public IP and feeds populate, you're talking to the backend. Close it and make it permanent.

05Desktop icon

Copy the launcher to your desktop, then right-click it → Properties → Desktop Entry, and set the command to /usr/local/bin/hamclock -b hamclock.com:80.

$ cd ~/ESPHamClock
$ mkdir -p ~/.hamclock
$ cp hamclock.png ~/.hamclock
$ cp hamclock.desktop ~/Desktop

06Start automatically on boot

$ mkdir -p ~/.config/autostart
$ nano ~/.config/autostart/hamclock.desktop

Paste this in (change pi to your username if needed), save with Ctrl+O, Enter, Ctrl+X:

[Desktop Entry]
Name=HamClock
Exec=/usr/local/bin/hamclock -b hamclock.com:80
Icon=/home/pi/.hamclock/hamclock.png
Terminal=false
Type=Application

Running as a systemd service or from crontab instead? The same -b hamclock.com:80 flag goes on the end of your launch line.

07Confirm it's using this backend

Reboot, then glance at the HamClock header — public IP filled in, band-condition and space-weather panels carrying fresh values, maps rendering. If that's all alive, you're done. Your clock pulls everything from hamclock.com and keeps working long after the old server is gone.

Heads up — logs and SD cards. If HamClock runs fine for days then drops to the desktop, it's usually log files filling the card. Check with df -h, clear old logs, and disable logging. Not a build problem.

Lost anywhere? Hand this page to a club member — none of these steps are exotic, they just have to be done in order. Or skip it all with a pre-built image.

73 — W4BAE