9M2PJU HamClock Installer

The Quintessential Space Weather, Radio Propagation & Telemetry Dashboard for Amateur Radio

Origin & Tribute • OHB Migration • Features • Quick Install • Android App • Windows • Docker Setup • Rotator & Radio • Docs • Manual Build • CLI & Web Server

🕊️ Origin & The Silent Key Legacy

HamClock was conceived, architected, and brought to life by Elwood Downey (WB0OEW) under the banner of Clear Sky Institute.

Elwood—an accomplished astronomer, software architect (renowned creator of XEphem), and passionate radio amateur—originally designed HamClock as a compact, self-contained microcontroller project for the Adafruit Feather HUZZAH ESP8266 paired with an Adafruit RA8875 TFT driver.

As the project gained massive popularity across the global amateur radio community, Elwood continuously expanded its capabilities, developing an elegant POSIX abstraction layer (ArduinoLib) that allowed the exact same codebase to compile natively on Linux, Raspberry Pi, Inovato Quadra, macOS, and FreeBSD. For years, Elwood personally financed and hosted the high-reliability Clear Sky Institute backend servers that parsed NOAA space weather, satellite TLEs, VOACAP models, and solar imagery for tens of thousands of clocks worldwide.

With Elwood Downey becoming Silent Key (SK), the original Clear Sky Institute infrastructure ceased operations. Rather than letting this indispensable amateur radio instrument fade into history, the worldwide ham radio community mobilized to keep his legacy alive.

In Memory of Elwood Downey, WB0OEW (Silent Key - SK) "His signals continue to propagate across the globe."

🌐 The Open HamClock Backend (OHB) Era

To ensure HamClock remains fully functional, reliable, and open for future generations of radio operators, an international collective of amateur radio enthusiasts developed the Open HamClock Backend (OHB).

What Changed in Version 4.24+ (Current: 4.32)

Hard-Coded Community Backend: HamClock now connects directly to ohb.hamclock.app:80 by default.
No Switching Scripts or DNS Redirection Required: Older transitional scripts (sudo ohb, sudo fix-hosts, sudo csi) and manual /etc/hosts modifications are no longer required.
Seamless Upgrade: Full backward compatibility with existing user configurations, callsign profiles, and NVRAM settings in ~/.hamclock/.
Modern Service Restorations: Space weather feeds, NOAA alerts, SDO solar imagery, VOACAP HF propagation models, DX cluster spots, satellite orbital TLEs, and contest calendars are completely restored and maintained on high-availability community servers.

📊 Feature Matrix

Subsystem	Capabilities & Integrations
☀️ Space Weather	Live Solar Flux Index (SFI), Sunspot Number (SSN), Planetary Kp & Ap indices, NOAA GOES-18 X-ray solar flare flux, solar wind velocity & density, interplanetary magnetic field ($B_z$ / $B_t$), NOAA alerts, and real-time Solar Dynamics Observatory (SDO) EUV imagery.
📻 Propagation & Bands	VOACAP point-to-point HF propagation prediction engine, real-time 2200m–10m & 630m band condition matrix, Take-Off Angle (TOA) adjustments, live band activity pane, and live synchronized NCDXF/IARU international beacon monitoring.
🗺️ Cartography & Grayline	High-resolution Mercator, Robinson, and Azimuthal (Great Circle / beam heading) projections centered on your DE (QTH). Live day/night terminator (grayline) mapping, Maidenhead 6-character grid overlays, CQ zones, ITU zones, and Country/State borders toggle badge.
📡 DX Cluster, APRS & Alerts	Live DX cluster telnet/web ingestion (IOTA, WWBOTA, POTA, SOTA, ONTA), nearby APRS tracking, High Altitude Balloon (HAB) telemetry, HamAlert.org integration, PSK Reporter FT8/FT4/CW real-time spot pins, and custom callsign watchlists with audio/visual alerts.
🚨 Emergency & Environmental	Real-time global active wildfire mapping, Fire Weather (FireWx) warnings, NWS Marine Warnings, live USGS Earthquake tracking, and Weather Fax (WeFax) charts.
🛰️ Satellites, EME & Rotators	Orbit calculation via Plan-13 algorithm for ISS and amateur satellites, next pass predictions, Doppler shift estimation, Earth-Moon-Earth (EME) mutual visibility windows, and automated Az/El antenna rotor/gimbal control (rotctld, Yaesu, Easycomm).
📜 Logbook & Rig Control	Real-time ADIF log ingestion from WSJT-X, N1MM Logger+, and standard loggers; on-air QSO pins plotted live; Flrig and rigctld CAT transceiver tracking.
⌨️ Touch & UI Usability	On-screen modal virtual keyboard for editing station settings, callsigns, and Wi-Fi on touchscreens; QR code modal generation for quick RSS news reading and local Wi-Fi sharing.
⏱️ Clocks & Geolocation	Dual DE/DX local timezones, UTC precision display, sub-second NTP synchronization, hardware NMEA GPS & `gpsd` daemon support, IP geolocation, and stopwatch/timer controls.
🌐 Built-in Web Server	Interactive WebSocket remote mirror (port `8081`) for touch/click browser control, read-only monitor (port `8082`), and RESTful HTTP API (port `8080`) for screenshots and automation.

⚡ One-Liner Quick Install

Use the universal automated installation script to install build dependencies, compile the optimized binary for your hardware, create application menu shortcuts, and optionally configure auto-start on login:

Linux / Raspberry Pi / Inovato Quadra / Ubuntu / Debian / Arch / Fedora

curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | bash

macOS (Apple Silicon & Intel)

Requires Homebrew and XQuartz.

curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | bash

Android (Official Native App - APK) ⭐

100% Native Embedded C++ Engine — No Termux or root required. Download the latest APK directly from GitHub Releases:

📥 Download Universal APK (9M2PJU-HamClock.apk)

Android (Termux CLI)

Turns any Android phone or tablet into a dedicated, low-power (<3W) touch clock via Termux.

pkg update -y && pkg install -y curl && bash -c "$(curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/termux/install.sh)"

FreeBSD

curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | bash

Local Execution

git clone https://github.com/9M2PJU/9M2PJU-HamClock-Installer.git
cd 9M2PJU-HamClock-Installer
./install.sh

🔁 Auto-Start on Login

The installer asks whether to auto-start HamClock on login. The available options depend on your OS:

OS	Auto-Start Methods
Linux	XDG autostart (`~/.config/autostart/hamclock.desktop`), systemd user service (`~/.config/systemd/user/hamclock.service`)
macOS	launchd LaunchAgent (`~/Library/LaunchAgents/local.hamclock.plist`)
FreeBSD	XDG autostart (`~/.config/autostart/hamclock.desktop`), `~/.xinitrc` (for `startx` sessions)
Android (Termux)	Use Termux:Boot; see Android & Termux Guide

Non-Interactive Auto-Start Selection

Skip the prompt by setting the AUTOSTART environment variable. Note: the variable must be set for bash (the right side of the pipe), not curl:

# Linux: XDG autostart
curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | AUTOSTART=xdg bash

# Linux: systemd user service
curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | AUTOSTART=systemd bash

# macOS: launchd LaunchAgent
curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | AUTOSTART=launchd bash

# FreeBSD: ~/.xinitrc
curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | AUTOSTART=xinitrc bash

# Disable auto-start (default)
curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | AUTOSTART=none bash

You can combine with target/resolution selection:

curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | TARGET=1600x960 AUTOSTART=xdg bash

Removing Auto-Start

# Linux (XDG)
rm -f ~/.config/autostart/hamclock.desktop

# Linux (systemd)
systemctl --user disable --now hamclock.service
rm -f ~/.config/systemd/user/hamclock.service
systemctl --user daemon-reload

# macOS (launchd)
launchctl unload ~/Library/LaunchAgents/local.hamclock.plist
rm -f ~/Library/LaunchAgents/local.hamclock.plist

# FreeBSD (~/.xinitrc)
# Edit ~/.xinitrc and remove the HamClock line manually

▶️ Running HamClock

After installation, start HamClock by running:

hamclock

If the hamclock command is not found, run hash -r or open a new terminal, then try again. You can also launch a specific resolution directly (if installed via package manager):

hamclock -r 1600x960      # Recommended for 1080p monitors
hamclock -r 2400x1440     # 2K displays
hamclock -r 3200x1920     # 4K displays
hamclock -r 800x480       # Small touchscreens

For headless / web-only builds, access the web UI at http://localhost:8081/live.html.

🐛 Support & Reporting Issues

If you encounter any problems, bugs, or have feature requests, please open an issue on GitHub:

https://github.com/9M2PJU/9M2PJU-HamClock-Installer/issues

Please include your OS, architecture, the install command you ran, and any error output. 73!

📦 Pre-Built Linux Packages (.deb, .rpm, .AppImage)

For instant installation without compiling from source, pre-built binary packages are available directly from GitHub Releases for amd64, arm64, and armhf:

Package Format	Target Operating Systems	Supported Architectures
`Android (.apk)`	Android Phones, Tablets, Android TV Boxes (Android 5.0+)	Universal, `arm64-v8a`, `armeabi-v7a`, `x86_64`, `x86`
`AUR`	Arch Linux, Manjaro, EndeavourOS, CachyOS	`x86_64`, `aarch64`, `armv7h`
`Snap`	Ubuntu, Debian, Fedora, Arch Linux, Manjaro, openSUSE	`amd64`, `arm64`, `armhf`
`.deb`	Debian, Ubuntu, Raspberry Pi OS, Armbian, Linux Mint	`amd64`, `arm64`, `armhf`
`.rpm`	Fedora, RHEL, CentOS, Rocky Linux, openSUSE	`x86_64`, `aarch64`, `armhfp`
`.AppImage`	Universal (Runs on any Linux distribution)	`x86_64`, `aarch64`, `armhf`

📦 Snap Store (Ubuntu / Universal Linux)

sudo snap install hamclock
Track build: GitHub Actions — Snap Build

🏹 Arch Linux (AUR)

# Using yay
yay -S hamclock-git

# Using paru
paru -S hamclock-git

🐧 Debian / Ubuntu / Raspberry Pi OS (`.deb`)

# Download and install for your architecture
sudo dpkg -i hamclock_4.32-1_amd64.deb    # x86_64 PCs
sudo dpkg -i hamclock_4.32-1_arm64.deb    # Raspberry Pi 4/5 / 64-bit ARM
sudo dpkg -i hamclock_4.32-1_armhf.deb    # Raspberry Pi 2/3 / 32-bit Raspbian
sudo apt-get install -f                   # Resolve any missing dependencies

🎩 Fedora / RHEL / openSUSE (`.rpm`)

sudo rpm -Uvh hamclock-4.32-1.x86_64.rpm  # x86_64
sudo rpm -Uvh hamclock-4.32-1.aarch64.rpm # ARM64

🚀 Universal AppImage (Single-File Executable)

chmod +x HamClock-4.32-x86_64.AppImage
./HamClock-4.32-x86_64.AppImage

# Launch with custom resolution
./HamClock-4.32-x86_64.AppImage -r 1600x960

🪟 Windows Support (Native .exe, PowerShell & WSL2)

HamClock now builds as a native Windows .exe - no WSL, Docker, or X11 required. The executable runs a headless web server; you view the dashboard in any browser at http://localhost:8081/live.html.

Option A: Download Pre-Built .exe from GitHub Releases

Download the latest HamClock-4.32-windows-*.exe from the GitHub Releases page. Four resolutions are available:

Executable File	Resolution	Recommended Use
`HamClock-4.32-windows-800x480.exe`	800 × 480	Standard, smaller displays
`HamClock-4.32-windows-1600x960.exe`	1600 × 960	Large, recommended default
`HamClock-4.32-windows-2400x1440.exe`	2400 × 1440	Hi-DPI
`HamClock-4.32-windows-3200x1920.exe`	3200 × 1920	4K UHD

Run the .exe from Command Prompt or PowerShell, then open http://localhost:8081/live.html in any browser. No installation required - the executable is statically linked and only depends on Windows system DLLs.

Option B: Build from Source (MinGW-w64 Cross-Compile)

Build from Linux using MinGW-w64:

# Install MinGW-w64 toolchain
# Arch:   sudo pacman -S mingw-w64-gcc
# Debian: sudo apt install g++-mingw-w64-x86-64

# Build all four resolution variants:
make mingw-all-web

# Or build a single resolution:
make mingw-web-800x480

Copy the resulting HamClock-4.32-windows-*.exe to your Windows machine and run it.

Option C: PowerShell Installer (WSL2 or Docker)

irm https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/scripts/install.ps1 | iex

WSL2 / WSLg: Runs as a seamless, hardware-accelerated native desktop window.
Docker Desktop: Deploys the isolated headless container and opens http://localhost:8081/live.html.
For detailed instructions, see the Windows User Guide.

📱 Android Support (Native APK & Termux)

Turn spare Android tablets, phones, or TV boxes into permanent, low-power (<3W) shack touch clocks with two installation methods:

Option A: Official Standalone Android App (.apk) [Recommended] ⭐

The official standalone Android APK runs a 100% native embedded C++ engine directly on Android. No Termux, root, or Linux chroot needed!

🚀 100% Native Embedded C++ Engine: Runs the full HamClock backend natively.
📍 GPS & Maidenhead Locator Sync: Auto GPS coordinates acquisition & real-time station DE grid locator sync.
📦 Config Backup & Restore (SAF): One-tap export/import of station EEPROM, presets, and preferences via ZIP & Share Sheet.
🌙 OLED Burn-in Care & Night Dimmer: Pixel-shift anti-burn-in protection and auto nighttime dimming schedule (10PM–6AM).
📺 Android TV & Car Ready: Full D-Pad remote navigation support and automatic USB charger power wake/sleep.
📱 Edge-to-Edge Fullscreen Display: Hardware-accelerated UI with responsive multi-touch.
🔋 24/7 Background Foreground Service: Built-in WakeLock/WifiLock support to prevent sleep.
🌐 Multi-Device LAN Streaming: View and control HamClock over WiFi at http://<PHONE-IP>:8081/live.html.
🇲🇾 Bahasa Melayu Localization: Native Malaysian Malay language translations.
🔄 Auto-Start on Boot: Toggle in settings for dedicated tablet monitors.

📥 Download Packages from GitHub Releases:

📥 Download Universal APK (9M2PJU-HamClock.apk) (Recommended — Universal for all devices)
Architecture-Specific APKs: arm64-v8a (64-bit ARM), armeabi-v7a (32-bit ARM), x86_64, x86

Option B: Android via Termux CLI (DIY)

pkg update -y && pkg install -y curl && bash -c "$(curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/termux/install.sh)"

Quick Non-Interactive Target Selection:

# 1600x960 (Recommended for Tablets & 1080p Screens)
TARGET=1600x960 bash -c "$(curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/termux/install.sh)"

# 800x480 (Recommended for Phones & Compact Screens)
TARGET=800x480 bash -c "$(curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/termux/install.sh)"

Full-Screen & 24/7 Shack Operation:

Background Running & Battery Saver: Run termux-wake-lock && hamclock -k & and set Android Settings ➔ Apps ➔ Termux ➔ Battery ➔ Unrestricted (disable Battery Saver so Android does not suspend HamClock).
Best Full-Screen & Auto-Fit View: Install Fully Kiosk Browser from Google Play and set Start URL to http://localhost:8081/live.html.
For detailed kiosk settings, autostart on boot, and native X11 guides, see the Android & Termux Guide.

🐳 Docker & Docker Compose

Docker is the easiest way to deploy HamClock in Headless / Server Mode on home servers, NAS devices (Synology, TrueNAS, Unraid), Proxmox, and mini PCs without installing GUI or X11 dependencies.

Multi-architecture images are built automatically via GitHub Actions and hosted on GitHub Container Registry (GHCR):

Supported Architectures: linux/amd64 (x86_64 PCs & Servers), linux/arm64 (Raspberry Pi 4/5, Apple Silicon), and linux/arm/v7 (Raspberry Pi 2/3, 32-bit ARM).

Option A: 1-Line Automated Docker Installer (Quickest)

Run this single command to pull the multi-arch container, select your resolution, and start HamClock:

curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install-docker.sh | bash

Or pass your desired resolution directly:

RESOLUTION=1600x960 curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install-docker.sh | bash

Option B: Using Docker Compose

Save the docker-compose.yml file:

services:
  hamclock:
    image: ghcr.io/9m2pju/9m2pju-hamclock-docker:latest
    container_name: hamclock
    restart: unless-stopped
    ports:
      - "8080:8080" # RESTful API & Live Screenshot (/live.png)
      - "8081:8081" # Real-time Interactive Web UI (/live.html)
      - "8082:8082" # Read-Only Web Monitor
    environment:
      - RESOLUTION=1600x960  # Options: 800x480, 1600x960, 2400x1440, 3200x1920
      - EXTRA_ARGS=-k
    volumes:
      - hamclock_data:/home/hamclock/.hamclock

volumes:
  hamclock_data:

Start the container:
```
docker compose up -d
```
Open your browser to http://<server-ip>:8081/live.html to interact with HamClock!

Option C: Using Standalone `docker run`

docker run -d \
  --name hamclock \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 8081:8081 \
  -p 8082:8082 \
  -e RESOLUTION=1600x960 \
  -v hamclock_data:/home/hamclock/.hamclock \
  ghcr.io/9m2pju/9m2pju-hamclock-docker:latest

📐 Resolution Guide & Switching

HamClock supports four distinct display resolutions tailored for different screen sizes:

Resolution	Width × Height	Best Suited For
`800x480`	800 × 480 px	Standard definition, smaller 5"–7" Raspberry Pi displays, low-bandwidth web access.
`1600x960` (Recommended)	1600 × 960 px	Full HD (1080p) monitors, desktop windows, iPads, tablets, and wall dashboard screens.
`2400x1440`	2400 × 1440 px	2K / QHD monitors, high-DPI displays.
`3200x1920`	3200 × 1920 px	4K UHD large televisions and ultra-high-resolution displays.

How to Change Resolution in Docker

All four resolutions are pre-compiled inside the Docker image. You can switch resolutions instantly by updating the RESOLUTION environment variable—no container rebuild needed:

Edit RESOLUTION in docker-compose.yml:

environment:
  - RESOLUTION=1600x960   # Choose: 800x480, 1600x960, 2400x1440, 3200x1920

Apply the change:
```
docker compose up -d
```

How Resolution Works in Package Managers (AUR `yay`, `.deb`, `.rpm`, Snap, AppImage)

Note

Why doesn't yay / pacman / apt ask for screen resolution during installation? Standard Linux package managers require non-interactive, unattended builds so automated system updates (yay -Syu) never hang waiting for user prompts.

Therefore, package managers build and install all 6 resolutions simultaneously into /usr/lib/hamclock/. You choose or change your resolution at runtime using the universal launcher:

Launch a specific resolution on demand:

hamclock -r 1600x960     # Recommended for 1080p Desktop Monitors
hamclock -r 2400x1440    # 2K Quad HD
hamclock -r 3200x1920    # 4K Ultra HD
hamclock -r 800x480      # Standard Definition / Touchscreens

Or use direct binary symlinks:
```
hamclock-1600x960
hamclock-800x480
```
Set a permanent default resolution in your shell: Add to ~/.bashrc or ~/.profile:
```
export HAMCLOCK_RES=1600x960
```
Then running hamclock will always open in 1600x960 automatically.
List all available resolutions:
```
hamclock --list-resolutions
```

How to Change Resolution with One-Liner Script (`install.sh`)

Method 1: Interactive Menu

Simply run ./install.sh and select your preferred resolution target from the numbered prompt:

./install.sh

Method 2: Non-Interactive One-Liner (Environment Variable or Argument)

Pass TARGET or resolution directly into the command:

# Desktop X11 1600x960 (Large)
TARGET=1600x960 curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | bash

# Desktop X11 2400x1440 (2K Hi-DPI)
TARGET=2400x1440 curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | bash

# Web Server Only 1600x960 (Headless)
TARGET=web-1600x960 curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | bash

# Raspberry Pi Direct Framebuffer 800x480 (/dev/fb0)
TARGET=fb0-800x480 curl -fsSL https://raw.githubusercontent.com/9M2PJU/9M2PJU-HamClock-Installer/main/install.sh | bash

📻 Rotator & Radio CAT Integration

HamClock is not just a display—it is a complete, real-time command center for your ham shack. Built by Elwood Downey (WB0OEW)—the creator of the renowned XEphem astronomical telescope software—HamClock features native TCP/IP socket integration for:

🧭 Antenna Rotator Control (rotctld):
- Automatically commands 1-axis and 2-axis rotators (Yaesu, AlfaSpid, Easy-Comm, Green Heron, etc.).
- Auto-Turn to DX: Click anywhere on the world map or enter a callsign to immediately point your directional beam antenna to the short-path (SP) or long-path (LP) bearing.
- Live Satellite Tracking: Automatically tracks active amateur satellites (ISS, AO-91, RS-44, IO-117) across both Azimuth and Elevation in real-time.
📻 Transceiver CAT Control (rigctld / flrig):
- Dynamic VOACAP Band Matching: Spinning your physical radio's VFO dial instantly switches the on-screen VOACAP propagation map to the active band.
- Click-to-Tune (QSY): Clicking any DX Cluster, POTA, SOTA, or PSK spot prompts you to QSY, immediately tuning your radio to the spotted frequency.
- Live ON AIR Badge: Visual red transmitter PTT indicator on the clock display when keying the mic.

👉 Read the complete guide: docs/ROTATOR_AND_RADIO.md

📚 Documentation Library

Explore comprehensive guides and documentation in the docs/ directory:

Guide	Description
📖 Installation Guide	Step-by-step installation for Linux, Raspberry Pi, Inovato Quadra, macOS, FreeBSD, and Docker.
📱 Android & Termux Guide	Turn Android phones & tablets into dedicated, low-power shack touch clocks.
🪟 Windows Setup Guide	Setup on Windows 10 & 11 via PowerShell, WSL2/WSLg, and Docker Desktop.
📦 Snap Store Guide	Canonical Snap package maintainer and user deployment guide.
📻 Rotator & Radio CAT Guide	Setup and usage for `rotctld`, `rigctld`, `flrig`, satellite tracking, and click-to-tune QSY.
⚙️ Configuration & Settings	Guide to all setup pages, station coordinates, map layers, DX clusters, and ADIF loggers.
💡 Usage, Tips & CLI Reference	Touch gestures, mouse controls, keyboard shortcuts, command line options, and REST APIs.

🔨 Manual Compilation & Build Matrix

HamClock compiles natively on Unix-like operating systems. You can select your display resolution and output mode depending on your hardware:

1. Install Prerequisites

Debian / Ubuntu / Raspberry Pi OS / Inovato Quadra

sudo apt update
sudo apt install -y build-essential make g++ libx11-dev libgpiod-dev curl unzip pkg-config

Arch Linux / CachyOS / Manjaro

sudo pacman -Syu --needed base-devel libx11 libgpiod curl unzip

Fedora / RHEL

sudo dnf install -y gcc-c++ make libX11-devel libgpiod-devel curl unzip

macOS

brew install make gcc
brew install --cask xquartz

FreeBSD

sudo pkg install -y gmake gcc libX11 libgpio curl unzip

2. Choose Build Target & Resolution

HamClock provides three output architectures across four resolutions, plus a native Windows cross-compile target:

Target Resolution	X11 Desktop GUI	Headless Web Server Only	RPi Direct Framebuffer (`/dev/fb0`)	Native Windows `.exe` (MinGW)
800 × 480 (Standard)	`make hamclock-800x480`	`make hamclock-web-800x480`	`make hamclock-fb0-800x480`	`make mingw-web-800x480`
1600 × 960 (Large)	`make hamclock-1600x960`	`make hamclock-web-1600x960`	`make hamclock-fb0-1600x960`	`make mingw-web-1600x960`
2400 × 1440 (Hi-DPI)	`make hamclock-2400x1440`	`make hamclock-web-2400x1440`	`make hamclock-fb0-2400x1440`	`make mingw-web-2400x1440`
3200 × 1920 (4K UHD)	`make hamclock-3200x1920`	`make hamclock-web-3200x1920`	`make hamclock-fb0-3200x1920`	`make mingw-web-3200x1920`

Windows cross-compile requires the MinGW-w64 toolchain (mingw-w64-gcc on Arch, g++-mingw-w64-x86-64 on Debian/Ubuntu). The resulting .exe is a statically linked PE32+ executable that runs the web-only backend natively on Windows 10/11 without WSL or Docker. See docs/WINDOWS.md for details.

Build Example (800x480 Desktop GUI)

make clean
make hamclock-800x480 -j$(nproc)

Install System-Wide

sudo make install

Copies the binary to /usr/local/bin/hamclock with setuid privileges if required for native GPIO/framebuffer access.

🕹️ CLI Options & Runtime Flags

Purpose: Display space weather, propagation, and telemetry for radio amateurs
Usage:   hamclock [options]

Flag	Argument	Description	Example
`-k`	none	Skip initial setup countdown and boot immediately	`hamclock -k`
`-g`	none	Auto-initialize DE location using public IP geolocation (requires `-k`)	`hamclock -k -g`
`-b`	`<host:port>`	Override backend server (default: `ohb.hamclock.app:80`)	`hamclock -b ohb.hamclock.app:80`
`-f`	`on` / `off`	Force initial fullscreen display mode	`hamclock -f on`
`-d`	`<directory>`	Specify working directory (default: `~/.hamclock/`)	`hamclock -d /opt/hamclock_data`
`-e`	`<port>`	RESTful web server port (default: `8080`, `-1` to disable)	`hamclock -e 8080`
`-w`	`<port>`	Read-write live web server port (default: `8081`, `-1` to disable)	`hamclock -w 8081`
`-r`	`<port>`	Read-only live web server port (default: `8082`, `-1` to disable)	`hamclock -r 8082`
`-t`	`<percent>`	Throttle maximum CPU usage percentage (default: `80`)	`hamclock -t 50`
`-m`	none	Enable demo mode	`hamclock -m`
`-v`	none	Display version and build information	`hamclock -v`
`-h`	none	Display comprehensive help and command options	`hamclock -h`

🌐 Remote Web Interface & REST API

When HamClock is running (either locally or on a remote server/Raspberry Pi), open any web browser:

Interactive Live Mirror (Read/Write):
```
http://<clock-ip-address>:8081/live.html
```
Provides a real-time, touch- and click-interactive mirror of the screen over WebSocket.

Read-Only Monitor:

http://<clock-ip-address>:8082/live.html

RESTful Snapshot / Image Endpoint:

http://<clock-ip-address>:8080/live.png

🔄 Systemd Service & Autostart

1. Desktop GUI Autostart

To start HamClock automatically upon graphical desktop login:

mkdir -p ~/.config/autostart
cp hamclock.desktop ~/.config/autostart/
chmod +x ~/.config/autostart/hamclock.desktop

2. Headless or Kiosk Systemd Service

To run HamClock automatically in the background at boot:

sudo cp hamclock.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now hamclock
sudo systemctl status hamclock

📂 Repository Layout

src/ - C++ implementation source files (main entry point, telemetry, map engines, rotator and CAT radio controllers, WebSocket and REST servers)
include/ - C++ header files and global definitions
ArduinoLib/ - POSIX / Linux Arduino hardware abstraction
wsServer/ - Real-time WebSocket server library
zlib-hc/ - Embedded data decompression library
packaging/ - .deb, .rpm, and AppImage package builders
deploy/ - Linux desktop launchers, icons, systemd units
docker/ - Dockerfile, entrypoint, and compose configs
scripts/ - Native and Docker automated 1-line installers
termux/ - Dedicated Android Termux installer and build helpers
docs/ - Comprehensive documentation library and GitHub Pages
Makefile - Standard POSIX build system

🛠️ Microcontroller Support (ESP8266)

For legacy standalone microcontroller builds on the Adafruit Feather HUZZAH ESP8266 with Adafruit RA8875 driver:

Install and open the Arduino IDE.
Install the ESP8266 board definitions and required libraries (Adafruit_RA8875, Adafruit_BME280).
Open src/ESPHamClock.cpp (or ESPHamClock.ino).
Select Adafruit Feather HUZZAH ESP8266, CPU Frequency 160 MHz, Flash Size 4M (3M SPIFFS).
Compile and upload.

🤝 Contributing & Community

Contributions, bug fixes, and feature enhancements are welcome!

Fork the repository.
Create your feature branch from Staging (git checkout -b feature/my-new-feature).
Commit your changes.
Push to your branch and open a Pull Request.

💖 Sponsor & Support

If you find this installer, packaging suite, and the Open HamClock Backend useful for your amateur radio shack, please consider supporting ongoing maintenance and development:

_{🇲🇾 DuitNow / Touch 'n Go (TNG) QR (Scan with any Malaysian Banking / eWallet App)}

Your sponsorship helps cover server costs for the Open HamClock Backend (OHB) and ongoing packaging maintenance. Thank you for your support! 73 de 9M2PJU.

📄 License & Acknowledgments

Original Creator: Elwood Downey, WB0OEW, SK (Clear Sky Institute).
Backend & Community Maintenance: 9M2PJU & The Open HamClock (OHB) amateur radio community.
License: MIT License (see LICENSE).

73 to all Radio Amateurs worldwide! de 9M2PJU

Name		Name	Last commit message	Last commit date
.github		.github
ArduinoLib		ArduinoLib
aur		aur
deploy		deploy
docker		docker
docs		docs
include		include
packaging		packaging
scripts		scripts
snap		snap
src		src
termux		termux
wsServer		wsServer
zlib-hc		zlib-hc
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
PROGRESS.md		PROGRESS.md
README		README
README.md		README.md
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
install-docker.sh		install-docker.sh
install.sh		install.sh

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

9M2PJU HamClock Installer

The Quintessential Space Weather, Radio Propagation & Telemetry Dashboard for Amateur Radio

🕊️ Origin & The Silent Key Legacy

🌐 The Open HamClock Backend (OHB) Era

What Changed in Version 4.24+ (Current: 4.32)

📊 Feature Matrix

⚡ One-Liner Quick Install

Linux / Raspberry Pi / Inovato Quadra / Ubuntu / Debian / Arch / Fedora

macOS (Apple Silicon & Intel)

Android (Official Native App - APK) ⭐

Android (Termux CLI)

FreeBSD

Local Execution

🔁 Auto-Start on Login

Non-Interactive Auto-Start Selection

Removing Auto-Start

▶️ Running HamClock

🐛 Support & Reporting Issues

📦 Pre-Built Linux Packages (.deb, .rpm, .AppImage)

📦 Snap Store (Ubuntu / Universal Linux)

🏹 Arch Linux (AUR)

🐧 Debian / Ubuntu / Raspberry Pi OS (.deb)

🎩 Fedora / RHEL / openSUSE (.rpm)

🚀 Universal AppImage (Single-File Executable)

🪟 Windows Support (Native .exe, PowerShell & WSL2)

Option A: Download Pre-Built .exe from GitHub Releases

Option B: Build from Source (MinGW-w64 Cross-Compile)

Option C: PowerShell Installer (WSL2 or Docker)

📱 Android Support (Native APK & Termux)

Option A: Official Standalone Android App (.apk) [Recommended] ⭐

Option B: Android via Termux CLI (DIY)

Quick Non-Interactive Target Selection:

Full-Screen & 24/7 Shack Operation:

🐳 Docker & Docker Compose

Option A: 1-Line Automated Docker Installer (Quickest)

Option B: Using Docker Compose

Option C: Using Standalone docker run

📐 Resolution Guide & Switching

How to Change Resolution in Docker

How Resolution Works in Package Managers (AUR yay, .deb, .rpm, Snap, AppImage)

How to Change Resolution with One-Liner Script (install.sh)

Method 1: Interactive Menu

Method 2: Non-Interactive One-Liner (Environment Variable or Argument)

📻 Rotator & Radio CAT Integration

📚 Documentation Library

🔨 Manual Compilation & Build Matrix

1. Install Prerequisites

Debian / Ubuntu / Raspberry Pi OS / Inovato Quadra

Arch Linux / CachyOS / Manjaro

Fedora / RHEL

macOS

FreeBSD

2. Choose Build Target & Resolution

Build Example (800x480 Desktop GUI)

Install System-Wide

🕹️ CLI Options & Runtime Flags

🌐 Remote Web Interface & REST API

🔄 Systemd Service & Autostart

1. Desktop GUI Autostart

2. Headless or Kiosk Systemd Service

📂 Repository Layout

🛠️ Microcontroller Support (ESP8266)

🤝 Contributing & Community

💖 Sponsor & Support

📄 License & Acknowledgments

About

Topics

Resources

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Contributors

🐧 Debian / Ubuntu / Raspberry Pi OS (`.deb`)

🎩 Fedora / RHEL / openSUSE (`.rpm`)

Option C: Using Standalone `docker run`

How Resolution Works in Package Managers (AUR `yay`, `.deb`, `.rpm`, Snap, AppImage)

How to Change Resolution with One-Liner Script (`install.sh`)