Section 14
Ref
Reference
Scan, don't read. Complete .env variable table, keyboard shortcuts, all data sources, a ham radio glossary, and credits.
Complete .env Variable Reference
Every variable OpenHamClock reads from .env, with its default value and valid options.
Station
| Variable | Default | Description |
|---|---|---|
CALLSIGN | required | Your amateur radio callsign (e.g. K0CJH) |
LOCATOR | required | Maidenhead grid locator, 4 or 6 characters (e.g. IO91wm) |
LATITUDE | from LOCATOR | Override latitude in decimal degrees |
LONGITUDE | from LOCATOR | Override longitude in decimal degrees |
Server
| Variable | Default | Description |
|---|---|---|
PORT | 3000 | Web server port |
HOST | localhost | Bind address. Use 0.0.0.0 for network access |
TRUST_PROXY | false | Set true behind nginx / Caddy / Railway |
Security
| Variable | Default | Description |
|---|---|---|
API_WRITE_KEY | none | Secret key for POST endpoints. Required for internet-facing installs. |
CORS_ORIGINS | none | Comma-separated extra CORS origins (e.g. https://yourdomain.com) |
Display Defaults
| Variable | Default | Valid values |
|---|---|---|
THEME | dark | dark · light · legacy · retro · custom |
LAYOUT | modern | modern · classic · dockable · tablet · compact · emcomm |
DISTUNITS | imperial | imperial · metric |
TEMPUNITS | imperial | imperial · metric |
TIME_FORMAT | 24 | 12 · 24 |
Settings Sync
| Variable | Default | Description |
|---|---|---|
SETTINGS_SYNC | false | Save display settings server-side. Enable for single-operator Pi/self-hosted installs. |
SETTINGS_FILE | ./data/settings.json | Path to the settings file when SETTINGS_SYNC is enabled |
DX Cluster
| Variable | Default | Description |
|---|---|---|
DX_CLUSTER_SOURCE | auto | auto · proxy · hamqth · dxspider |
SPOT_RETENTION_MINUTES | 30 | How long to keep spots in the panel (minutes) |
DXSPIDER_PROXY_URL | none | URL of a self-hosted DX Spider telnet-to-HTTP proxy |
WSJT-X
| Variable | Default | Description |
|---|---|---|
WSJTX_ENABLED | false | Enable WSJT-X UDP listener |
WSJTX_UDP_PORT | 2237 | UDP port for WSJT-X packets |
WSJTX_MULTICAST_ADDRESS | none | Multicast group address for multi-instance WSJT-X setups |
WSJTX_RELAY_KEY | none | Authentication key for the wsjtx-relay agent (cloud installs) |
Rig Control
| Variable | Default | Description |
|---|---|---|
RIG_ENABLED | false | Enable direct server-side rig control |
RIG_TYPE | none | yaesu-cat · icom-ci-v · kenwood · elecraft · tci · hamlib |
RIG_SERIAL_PORT | none | Serial port (e.g. /dev/ttyUSB0, COM4) |
RIG_BAUD_RATE | 9600 | Serial baud rate |
RIG_CI_V_ADDRESS | 0x94 | Icom CI-V address (hex). IC-7300=0x94, IC-705=0xA4, IC-9700=0xA2 |
External API Keys
| Variable | Default | Description |
|---|---|---|
QRZ_USERNAME | none | QRZ.com username for callsign lookups |
QRZ_PASSWORD | none | QRZ.com password |
VITE_AMBIENT_APP_KEY | none | Ambient Weather application key |
VITE_AMBIENT_API_KEY | none | Ambient Weather API key |
Auto-Update
| Variable | Default | Description |
|---|---|---|
AUTO_UPDATE_ENABLED | false | Enable automatic git-based updates |
AUTO_UPDATE_INTERVAL_MINUTES | 60 | How often to check for updates (minutes) |
AUTO_UPDATE_ON_START | false | Check for updates at startup |
AUTO_UPDATE_EXIT_AFTER | true | Exit after updating so systemd/pm2 can restart |
Keyboard Shortcuts
| Key | Action |
|---|---|
| ? | Show keyboard shortcut help overlay |
| S | Open Settings panel |
| M | Focus / centre the world map |
| F | Toggle map fullscreen |
| L | Open Layers panel (map overlays) |
| Esc | Close any open panel or popup |
| 1 – 9 | Switch to layout preset 1–9 (if configured) |
| ← → | Step through Solar panel views |
Data Sources & APIs
| Data | Source | Licence / Terms |
|---|---|---|
| DX Cluster spots | DX Spider network, HamQTH | Amateur radio public network |
| Space weather (SFI, Kp, SSN) | NOAA / N0NBH Solar Indices | US Government open data |
| Band conditions | N0NBH / NOAA | US Government open data |
| Solar image | NASA SDO / Helioviewer | NASA open data |
| X-ray flux | NOAA GOES satellites | US Government open data |
| POTA activations | POTA API (pota.app) | POTA public API |
| SOTA activations | SOTAwatch API | SOTA public API |
| WWFF activations | WWFF API | WWFF public API |
| Satellite TLEs | CelesTrak | Public domain |
| PSKReporter | PSKReporter MQTT / HTTP API | Philip Gladstone, free use |
| RBN spots | Reverse Beacon Network | Amateur radio public network |
| WSPR reports | WSPRnet | WSPRnet public API |
| Weather | Open-Meteo | CC BY 4.0 — free, no key |
| Aurora | NOAA OVATION model | US Government open data |
| Earthquakes | USGS Earthquake Hazards Program | US Government open data |
| Wildfires | NASA FIRMS | NASA open data |
| Propagation model | ITU-R P.533-14 / iturhfprop | ITU model, open-source implementation |
| Callsign lookup | QRZ.com XML API | QRZ account required (free) |
| Map tiles | OpenStreetMap / CARTO | ODbL / Carto ToS |
Ham Radio Glossary
Quick definitions for terms used throughout this manual.
| Term | Definition |
|---|---|
| APRS | Automatic Packet Reporting System. A digital protocol used to transmit position, weather, and text data over radio. |
| AOS | Acquisition of Signal — the moment a satellite rises above your horizon and becomes workable. |
| Azimuth | Compass bearing in degrees (0° = North, 90° = East, 180° = South, 270° = West). Used for antenna pointing. |
| Band | A range of radio frequencies allocated by the ITU for amateur use. e.g. "20 m band" = 14.0–14.35 MHz. |
| Callsign | A unique identifier assigned to a licensed amateur radio station by its national authority (e.g. W1AW, G4ABC, JA1ZZZ). |
| CQ | A general call inviting any station to respond. "CQ DX" specifically invites distant stations. |
| CW | Continuous Wave — Morse code. Still widely used for DX and contesting due to its efficiency. |
| Doppler shift | The change in received frequency caused by relative motion between transmitter and receiver. Significant for satellite contacts. |
| DX | Distant station. In HF operating, typically means a station in another country or rare entity. |
| DXCC | DX Century Club — the ARRL award for working 100+ countries. Also used as shorthand for "country" in the context of rare DX entities. |
| EME | Earth-Moon-Earth (moonbounce). Contacts made by bouncing signals off the moon's surface. |
| FT8 | A weak-signal digital mode (Franke-Taylor design, 8-FSK) with 15-second periods. The most widely used HF mode worldwide as of 2024. |
| Great-circle path | The shortest distance between two points on a sphere — the actual path radio waves travel around the Earth. |
| Grid square | A Maidenhead Locator System cell used to describe geographic position. 4-character (e.g. IO91) or 6-character (IO91wm) resolution. |
| Grey line | The twilight boundary between day and night. A zone of enhanced HF propagation, especially on 80 m and 40 m. |
| HF | High Frequency — 3–30 MHz. The primary amateur radio spectrum for worldwide contacts via ionospheric propagation. |
| Ionosphere | Layers of the upper atmosphere (60–600 km) ionised by solar radiation, enabling HF radio signals to travel around the Earth. |
| K-index / Kp | A measure of geomagnetic disturbance (0–9). High values indicate solar storm activity that degrades HF propagation. |
| LEO | Low Earth Orbit — typically 200–2000 km altitude. Most amateur satellites are in LEO, with pass windows of 5–15 minutes. |
| LOS | Loss of Signal — the moment a satellite sets below your horizon. |
| Maidenhead locator | See Grid square. |
| POTA | Parks on the Air — an amateur radio programme where operators activate national parks and similar areas. |
| Propagation | How radio waves travel from transmitter to receiver. HF propagation relies on reflection from the ionosphere. |
| QSO | A two-way radio contact between two stations. |
| RBN | Reverse Beacon Network — a global network of automated CW/RTTY receivers that spot CQ calls automatically. |
| SFI | Solar Flux Index (F10.7) — a measure of solar radio emission and proxy for ionospheric conditions. Higher = better HF propagation. |
| SGP4 | Simplified General Perturbations 4 — the standard orbital propagation model used to predict satellite positions from TLE data. |
| SOTA | Summits on the Air — an amateur radio programme where operators activate qualifying mountain summits. |
| SSN | Sunspot Number (Wolf Number) — a daily count of visible sunspot groups. Correlates with SFI and HF propagation quality. |
| TLE | Two-Line Elements — a standardised format for describing a satellite's orbital parameters, used by SGP4 to predict positions. |
| VHF/UHF | Very High Frequency (30–300 MHz) and Ultra High Frequency (300 MHz–3 GHz). Most amateur satellites use these bands. |
| WSPR | Weak Signal Propagation Reporter — a beacon mode used to map HF propagation by reporting who hears whom. |
| WWFF | World Wide Flora & Fauna — an amateur radio programme activating nature reserves and protected areas. |
Contributing
OpenHamClock is open-source (MIT licence) and welcomes contributions. Whether you want to fix a bug, add a feature, improve a translation, or just report a problem:
- Bug reports & feature requests — GitHub Issues
- Code contributions — fork the repo, work on a branch, open a pull request against
main. See CONTRIBUTING.md for guidelines. - Translations — translation files live in
src/lang/. 16 languages are currently at 100% coverage. New languages are very welcome. - Documentation — this manual lives at github.com/accius/openhamclock-manual. Pull requests for corrections and improvements are appreciated.
Credits & Licence
OpenHamClock
Created and maintained by Chris Hetherington, K0CJH.
MIT Licence — free to use, modify, and self-host.
Original HamClock
Elwood Downey, WB0OEW created the original HamClock —
a standalone C application for Raspberry Pi that inspired this project.
A different program with a different codebase, but the same spirit.
clearSkyInstitute.com/ham/HamClock
Libraries used
React, Vite, Express, Leaflet.js, i18next, FlexLayout-React, Helmet, MQTT.js, Axios, and many others.
Full list in package.json.
This manual
MIT Licence. Source at github.com/accius/openhamclock-manual.
Screenshots and diagrams are welcome contributions — see the README.