🌐 OpenHamClock

A modern, open-source amateur radio dashboard with real-time space weather, band conditions, DX cluster, and interactive world maps.

In loving memory of Elwood Downey, WB0OEW, creator of the original HamClock

Live Demo · Download · Documentation · Contributing

---

📡 About

OpenHamClock is a spiritual successor to the beloved HamClock application created by Elwood Downey, WB0OEW. After Elwood's passing and the announcement that HamClock will cease functioning in June 2026, the amateur radio community came together to create an open-source alternative that carries forward his vision.

Why OpenHamClock?

• Open Source: MIT licensed, community-driven development
• Cross-Platform: Runs on Windows, macOS, Linux, and Raspberry Pi
• Modern Stack: Built with web technologies for easy customization
• Real Maps: Actual satellite/terrain imagery, not approximations
• Live Data: Real-time feeds from NOAA, POTA, SOTA, and DX clusters
• Self-Hosted: Run locally or deploy to your own server

---

✨ Features

🗺️ Interactive World Map

• 8 map styles: Dark, Satellite, Terrain, Streets, Topo, Ocean, NatGeo, Gray
• Real-time day/night terminator (gray line)
• Great circle paths between DE and DX
• Click anywhere to set DX location
• POTA activators displayed on map with callsigns
• DX cluster paths - Lines connecting spotters to DX stations with band colors
• Moon tracking - Real-time sublunar point with phase display
• Zoom and pan with full interactivity

📡 Propagation Prediction

• Hybrid ITU-R P.533-14 - Combines professional model with real-time data
  • ITURHFProp engine provides base P.533-14 predictions
  • KC2G/GIRO ionosonde network provides real-time corrections
  • Automatic fallback when services unavailable
• Real-time ionosonde data from KC2G/GIRO network (~100 stations)
• Visual heat map showing band conditions to DX
• 24-hour propagation chart with hourly predictions
• Solar flux, K-index, and sunspot integration

📊 Live Data Integration

Source	Data	Update Rate
NOAA SWPC	Solar Flux, K-Index, Sunspots	5 min
KC2G/GIRO	Ionosonde foF2, MUF data	10 min
POTA	Parks on the Air spots	1 min
SOTA	Summits on the Air spots	1 min
DX Cluster	Real-time DX spots	30 sec
HamQSL	Band conditions	5 min

🔍 DX Cluster

• Real-time spots from DX Spider network
• Visual paths on map with band-specific colors
• Hover highlighting - Mouse over spots to highlight on map
• Grid square display - Parsed from spot comments
• Filtering by band, mode, continent, and search
• Spotter locations shown on map

🕐 Station Information

• UTC and Local time with date
• Maidenhead grid square (6 character)
• Sunrise/Sunset times for DE and DX
• Short path/Long path bearings
• Great circle distance calculation
• Space weather conditions assessment

📻 Band Conditions

• Visual display for 160m through 70cm
• Color-coded: Good (green), Fair (amber), Poor (red)
• Based on real propagation data

---

🚀 Installation

Quick Start (Any Platform)

# Clone the repository
git clone https://github.com/accius/openhamclock.git
cd openhamclock

# Install dependencies
npm install

# Start the server
npm start

# Open http://localhost:3000 in your browser

One-Line Install

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/accius/openhamclock/main/scripts/setup-linux.sh | bash

Windows (PowerShell as Admin):

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/accius/openhamclock/main/scripts/setup-windows.ps1'))

🍓 Raspberry Pi

# Download and run the Pi setup script
curl -fsSL https://raw.githubusercontent.com/accius/openhamclock/main/scripts/setup-pi.sh -o setup-pi.sh
chmod +x setup-pi.sh

# Standard installation
./setup-pi.sh

# Or with kiosk mode (fullscreen, auto-start on boot)
./setup-pi.sh --kiosk

Supported Pi Models:

• Raspberry Pi 3B / 3B+ ✓
• Raspberry Pi 4 (2GB+) ✓✓ (Recommended)
• Raspberry Pi 5 ✓✓✓ (Best performance)

🖥️ Desktop App (Electron)

# Development
npm run electron

# Build for your platform
npm run electron:build

# Build for specific platform
npm run electron:build:win   # Windows
npm run electron:build:mac   # macOS
npm run electron:build:linux # Linux

🐳 Docker

# Build the image
docker build -t openhamclock .

# Run the container
docker run -p 3000:3000 openhamclock

# Or use Docker Compose
docker compose up -d

☁️ Deploy to Railway

Full Deployment (3 Services)

For the complete hybrid propagation system, deploy all three services:

1. Deploy ITURHFProp Service First (enables hybrid propagation)

├── Go to railway.app → New Project → Deploy from GitHub repo
├── Select your forked repository  
├── Click "Add Service" → "GitHub Repo" (same repo)
├── In service settings, set "Root Directory" to: iturhfprop-service
├── If Root Directory option not visible:
│     - Go to Service → Settings → Build
│     - Add "Root Directory" and enter: iturhfprop-service
├── Deploy and wait for build to complete (~2-3 min)
└── Copy the public URL (Settings → Networking → Generate Domain)

2. Deploy DX Spider Proxy (optional - for live DX cluster paths)

├── In same project, click "Add Service" → "GitHub Repo"
├── Set "Root Directory" to: dxspider-proxy  
└── Deploy

3. Deploy Main OpenHamClock

├── In same project, click "Add Service" → "GitHub Repo"
├── Leave Root Directory empty (uses repo root)
├── Go to Variables tab, add:
│     ITURHFPROP_URL = https://[your-iturhfprop-service].up.railway.app
└── Deploy

Alternative: Separate Projects

If Root Directory doesn't work, create separate Railway projects:

1. Fork the repo 3 times (or use branches)
2. Move each service to its own repo root
3. Deploy each as separate Railway project
4. Link via environment variables

---

⚙️ Configuration

Edit your callsign and location in public/index.html:

const CONFIG = {
  callsign: 'YOUR_CALL',
  location: { lat: YOUR_LAT, lon: YOUR_LON },
  defaultDX: { lat: 35.6762, lon: 139.6503 },
  // ...
};

Environment Variables

Variable	Default	Description
PORT	3000	Server port
NODE_ENV	development	Environment mode
ITURHFPROP_URL	null	ITURHFProp service URL (enables hybrid mode)

---

🗺️ Map Styles

Style	Provider	Best For
Dark	CartoDB	Night use, low-light shacks
Satellite	ESRI	Terrain visualization
Terrain	OpenTopoMap	SOTA operations
Streets	OpenStreetMap	Urban navigation
Topo	ESRI	Detailed terrain
Ocean	ESRI	Maritime operations
NatGeo	ESRI	Classic cartography
Gray	ESRI	Minimal, distraction-free

---

🛠️ Development

# Clone and setup
git clone https://github.com/accius/openhamclock.git
cd openhamclock
npm install

# Start development server
npm run dev

# Run Electron in dev mode
npm run electron

Project Structure

openhamclock/
├── public/             # Static web files
│   ├── index.html      # Main application
│   └── icons/          # App icons
├── electron/           # Electron main process
│   └── main.js         # Desktop app entry
├── dxspider-proxy/     # DX Cluster proxy service
│   ├── server.js       # Telnet-to-WebSocket proxy
│   ├── package.json    # Proxy dependencies
│   └── README.md       # Proxy documentation
├── iturhfprop-service/ # HF Propagation prediction service
│   ├── server.js       # ITU-R P.533 API wrapper
│   ├── Dockerfile      # Builds ITURHFProp engine
│   └── README.md       # Service documentation
├── scripts/            # Setup scripts
│   ├── setup-pi.sh     # Raspberry Pi setup
│   ├── setup-linux.sh
│   └── setup-windows.ps1
├── server.js           # Express server & API proxy
├── Dockerfile          # Container build
├── railway.toml        # Railway config
└── package.json

---

🤝 Contributing

We welcome contributions from the amateur radio community! See CONTRIBUTING.md for guidelines.

Priority Areas

1. Satellite Tracking - TLE parsing and pass predictions
2. Rotator Control - Hamlib integration
3. Additional APIs - QRZ, LoTW, ClubLog
4. Accessibility - Screen reader support, high contrast modes
5. Translations - Internationalization
6. WebSocket DX Cluster - Direct connection to DX Spider nodes

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Elwood Downey, WB0OEW - Creator of the original HamClock. Your work inspired thousands of amateur radio operators worldwide. Rest in peace, OM. 🕊️
• Leaflet.js - Outstanding open-source mapping library
• OpenStreetMap - Community-driven map data
• ESRI - Satellite and specialty map tiles
• NOAA Space Weather Prediction Center - Space weather data
• Parks on the Air (POTA) - Activator spot API
• Summits on the Air (SOTA) - Summit spot API
• The Amateur Radio Community - For keeping the spirit of experimentation alive

---

📞 Contact

• Email: chris@cjhlighting.com
• GitHub Issues: Report bugs or request features
• Discussions: Join the conversation

---

73 de K0CJH and the OpenHamClock contributors!

"The original HamClock will cease to function in June 2026. OpenHamClock carries forward Elwood's legacy with modern technology and open-source community development."