# π OpenHamClock
[](LICENSE)
[](https://nodejs.org/)
[](CONTRIBUTING.md)
**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**](https://openhamclock.up.railway.app) Β· [**Download**](#-installation) Β· [**Documentation**](#-features) Β· [**Contributing**](#-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
- **Zoom and pan** with full interactivity
### π Live Data Integration
| Source | Data | Update Rate |
|--------|------|-------------|
| NOAA SWPC | Solar Flux, K-Index, Sunspots | 5 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 |
### π 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)
```bash
# Clone the repository
git clone https://github.com/k0cjh/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:**
```bash
curl -fsSL https://raw.githubusercontent.com/k0cjh/openhamclock/main/scripts/setup-linux.sh | bash
```
**Windows (PowerShell as Admin):**
```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/k0cjh/openhamclock/main/scripts/setup-windows.ps1'))
```
### π Raspberry Pi
```bash
# Download and run the Pi setup script
curl -fsSL https://raw.githubusercontent.com/k0cjh/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)
```bash
# 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
```bash
# 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
[](https://railway.app/template/openhamclock)
Or manually:
1. Fork this repository
2. Create a new project on [Railway](https://railway.app)
3. Connect your GitHub repository
4. Deploy!
---
## βοΈ Configuration
Edit your callsign and location in `public/index.html`:
```javascript
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 |
---
## πΊοΈ 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
```bash
# Clone and setup
git clone https://github.com/k0cjh/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
βββ 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](CONTRIBUTING.md) for guidelines.
### Priority Areas
1. **Satellite Tracking** - TLE parsing and pass predictions
2. **Contest Calendar** - Integration with contest databases
3. **Rotator Control** - Hamlib integration
4. **Additional APIs** - QRZ, LoTW, ClubLog
5. **Accessibility** - Screen reader support, high contrast modes
6. **Translations** - Internationalization
### 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](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
- **GitHub Issues**: [Report bugs or request features](https://github.com/k0cjh/openhamclock/issues)
- **Discussions**: [Join the conversation](https://github.com/k0cjh/openhamclock/discussions)
---
**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."*