HamClock 4.

16 User Guide

Recent release notes: complete history at [Link]

Version 4.16: 2025-04-05

new: add DXPeditions data pane
new: add automatic upgrade option
new: add get_dxpeds RESTful command
new: add RTTY VOACAP mode
change: current satellite az and el are now shown above pass
change: RESTful set_bmp can now display any image in the map area
change: add support for more UDP XML packet formats
change: UDP spots may be filtered to only those made by own call
fix: more download speed improvements
fix: DX Cluster rounding could move spot time into the future
fix: DX Cluster spot was updated only if it moved to a different band
fix: SpcWx rankings were not initialized if not using Auto

Version 4.15: 2025-02-26

change: command radio before opening spot Bio page
fix: accommodate Alpine linux lacking linux-headers package
fix: accommodate the small Pi3 integer types used for disk info
fix: significantly reduce live web network load
fix: cursor roaming was still finding Live Spots after deselected
fix: broaden search for more Inovato wireless devices
fix: final solution for stalling DX Cluster pane

Version 4.14: 2025-02-23

new: add Clouds map style
change: add scrolling, Reset and Rename Configuration controls
change: Contests pane shows next on top regardless of Scroll dir
change: automatically remove old diag and cache files if disk fills
change: add percent disk full to messages below call sign
change: support linux wifi that reports signal strength as percentage
fix: Contests pane would not rotate or indicate active correctly
fix: web pages are now opened asynchronously
fix: possible fix for stalled DX Cluster pane
fix: better server load balancing
fix: pasting clipboard onto web page dropped space characters
 HamClock 4.16 User Guide

This and additional supporting material may be found at [Link]

HamClock is a kiosk-style application that provides real time space weather, radio propagation models,
operating events and other information particularly useful to the radio amateur. When started, you may enter
the Setup system. Setup is required if key entries are missing or invalid.
Setup provides several pages of configuration options. The exact choices available will depend on your
platform but all options are shown below for completeness. Orange text denotes passive prompts for the
corresponding White data fields to their right. Cyan text denotes on/off choices or other discrete options.
Clicking on a data entry field will place a green cursor where the next character will go. Click Delete to erase
the character to the left. Click the Page arrows to move to next or previous. When finished, click Done. If any
fields do not pass checks, they are marked with a red Err and you remain on the Setup screen until corrected.
Pages with text fields include a virtual keyboard for use on touch screens or with a mouse. On desktop
systems, a normal keyboard may also be used using tab to step to the next prompt; delete to erase a
character, space to toggle discrete options; arrow keys to edit; escape to change page and Return for Done.

Setup pages

Call: enter your call sign, up to 11 characters; at least 1 digit; length at least 3; no punctuation except /
The remaining fields allow setting location manually with lat/long or grid, or automatically with gpsd, NMEA
sentences or IP Geolocation; and time from gpsd, NMEA, NTP or the computer. The fields automatically
prevent selecting conflicting resources.
DE Lat, Long, Grid: these fields manually set the DE location. You may enter a maidenhead grid or enter
latitude and longitude with optional ± degrees or N/S suffix with Lat and E/W with Lng.
use gpsd? Allows connecting to a gpsd daemon on your local network for. Enter the host name of your gpsd
server; the port is fixed to 2947.
use NMEA? Allows reading NMEA sentences directly from a GPS device; see page 17.
Both gpsd and NMEA normally only set the time but selecting follow will also update the DE location
occasionally, handy if HamClock is in an RV for example.
IP Geolocate? If Yes, uses your public IP to set DE location once. This may not be accurate.
NTP? Built-in will use the best from among a default set of world-wide NTP servers; host allows entering the
IP or host address of any desired NTP server on the network; Computer uses the time from the computer
running HamClock (ok, not NTP but here for convenience).

Cluster? This section configures listening to an internet DX Cluster or a local program sending spots with UDP
packets. See page 10 for additional information.
watch: see page 13.
Cluster Commands can be entered in the table. Those marked On will be sent once to the cluster server right
after logging in. These must be in the native cluster syntax, HamClock does not check them. Commands
marked Off are saved but not sent. Click Pg to cycle through more entry lines.

Page 1
 HamClock 4.16 User Guide
Setup pages, continued

rotctld? rigctld? Whether and how to connect to hamlib for rotator and/or radio control. See pages 8 and 10.
flrig? Whether and how to connect to W1HKJ’s flrig for rig control. See page 10.
Radio: if using either rig connection, choose whether to set spot frequencies or just monitor PTT.
ADIF? Set file used by the ADIF pane; may include environment variables and ~. See page 9.
ADIF and ONTA watch: see page 13.

Map center lng: set desired center map longitude for the Mercator and Robinson projections.
GPIO? Controls whether the native RPi GPIO pins will be used by HamClock. See page 16.
I2C file? name of the local I2C bus connection, either native or via USB. See page 16.
dTemp, dPres: temperature and pressure corrections added to each BME280 sensor. See page 15.
KX3? Toggle direct KX3 frequency control and set serial baud rate. RPi only; see page 15.
Bright Min% and Max%: display brightness range, if supported, as percent of hardware total.

Date order? choose one of three formats for all date displays.
Log usage? choose whether to send us your HamClock settings anonymously to guide further development.
Week starts? choose whether the first calendar column is Sunday or Monday.
Demo mode? Yes causes HamClock to change its own settings automatically. See page 12.
Units? choose Metric, Imperial or British units for environment sensor, weather data, speed and distances.
Bearings? choose True or Magnetic North when displaying bearings to DX.
Show public IP? whether the main page shows the public network address (local address is always shown)
New DE/DX Wx? whether to temporarily show weather in left Pane when setting new DX or DE.
Spot labels? select whether and how to label Live Spots, On The Air and DX Cluster map locations.
Gray display? whether to render map or entire display in shades of gray
Scroll direction? whether scrolling panes fill from bottom-up or top-down.
Map rotation? select one of several map rotation periods.
Pane rotation? select one of several pane rotation periods.
Look up bio? select which online bio service to use when clicking a spot, if any
Show UDP spots? select whether to accept all incoming UDP spots or just those by your HamClock call
UDP sets DX? when Yes spots from any supported UDP logging program will automatically set the DX object.
Auto SpcWx map? turn on Aurora map if > 50% or DRAP if > 25 MHz; off if < 25% or < 15 MHz, with hysteresis.
Auto upgrade? select whether or when (DE timezone) to automatically upgrade if new version is available
Full scrn direct? set to Yes to force HamClock to fill all surrounding screen area with black, when applicable.
Full scrn web? set to Yes to enable full screen option on Live web connections.

Page 2
 HamClock 4.16 User Guide
Setup pages, continued

Color Editor: This page displays and controls the colors used for map paths and band indications. Click one of
the Edit buttons to display its RGB color definition in the edit box in the upper right. The box works by clicking
within a color bar or clicking a numeric value which can then be edited with the keyboard. Click Dash to toggle
whether map paths are drawn dashed or solid; Thin to set line and symbol size; and On to set whether the path
is drawn on the map (it always remains editable here). A sample of each color shows how the current choices
will appear over a full range of background intensities. The current palette and choices may be saved as A or B
then later these, or two read-only built-in palettes, may be loaded.

On/Off Times: Use this table to set desired DE on and off (or dim) times for each week day. Click just above or
below each number to increase or decrease. Left and Right arrows copy to the adjacent day. The On/Off pane
will also display, and allowed editing, the current day settings (only) (see page 5). The display is never turned
off if both times are set equal. Not available on all systems.

Page 3
 HamClock 4.16 User Guide

Click to cycle background color

Click to set message, see page 10
Big ? here if time is not syncing
Click to cycle text color
Current version. Red when
old. Click to update.

Up time; Local IP; Public IP; Red OFF if not UTC, click to reset
disk usage; WiFi signal; CPU temp.
red if trouble; click might show more Click to set lock, demo (page 13),
manage configurations, exit,
Click to shift time forward or back restart, or send diagnostics
Number of live web connections
Click to change time units and whether Read-Only or R-Write
Click for Stopwatch, count down
timer and Big Clock
Map style – see page 12

Sub-earth Moon location

Info table,
and phase from surface
see page 12
Long path

Short path

DE NCDXF beacon
Sun
Rotating RSS feeds
DX

Mercator projection centered at 0º longitude -- click anywhere to set DE, DX, pan or zoom, see page 10

Sat name and

next event time
unless in DX pane

Click Sat location

or name to see
Pass DXpedition
Ground track for
one future orbit

DX

DE antipode

Concentric circles show where Sat is

on horizon, 30º and 60º elevation

Azimuthal projection centered on DE

Page 4
 HamClock 4.16 User Guide
click to set format
click to manage DE time zone, see page 13
The DE panel shows HamClock’s idea of your location and local time. HamClock uses
this location for many purposes from lunar angles to spot bearings. In this default format
the panel shows local time and date, latitude and longitude, grid square and sun rise and
set events. Click DE: to select other formats or select Data Panes (listed starting on
page 6) that can overlay this and the DX panel. Click location to edit lat, long or grid, see
page 10. Click R or S to toggle showing the time at which the next or previous events
occur, or the interval in which they will or have occurred. Click the timezone offset to
update if necessary; see pages 11 and 13 for more about how HamClock manages time.
click to select at/in
click to set DE location, see page 10
click to manage DX time zone, see page 13
The DX panel shows HamClock’s definition of a second location independent from DE.
Controls and layout are similar to the DE panel except the rise/set table also has an
option to show the DX location prefix; clicking DE shows a list of satellites that can be
tracked; and clicking LP or SP toggles whether the data shown refers to long path or
short path. If a satellite has been selected, this panel changes to display its next pass;
see next.
click to choose satellite

click to toggle short or long path

The DX panel can be repurposed to show details of the next satellite pass as viewed
from DE. Below the satellite name is the time until the next Rise or Set event and current
az and el. Both events are based on the satellite passing above or below the ideal
geometric horizon without regard to refraction. The time format will be HHhMM if the
event is more than an hour away otherwise MM:SS. A schematic representation shows
how the pass will appear in the sky above DE oriented as shown by the compass
directions in each corner. Faint lines are drawn at 30° and 60° elevation and every 30° in
azimuth. The setting end of the pass is marked with an S. Midway along the pass are
shown the duration as MM:SS and maximum elevation in degrees. Click anywhere in
the circle for a menu of additional options such as the satellite planning tool (page 13).

click for more options

• Below are descriptions of the tall narrow pane in the upper right corner of HamClock.
• Click near the top for a menu of available choices; choose one, or more will cycle.
• Some choices also use lower click positions for specific functions as described below.

Display Brightness Control Display On/Off Timer NCDXF Beacons BME Env Space Wx stats DE/DX Wx
(see page 11) (see page 11) stats ranked by impact stats
if Auto
Optional light sensor reading

Period until
display Off if Click
no activity; just
0 disables above
or
DE On time below
today each
digit to
DE Off time
change
today

Indicates light sensor is Click value Click value to Click to

Times are reset from table in
present; see page 15 to set Pane set Pane, choose
Setup page 7 each midnight Map color key
or name to
Display brightness, scaled to choose,
brMin to brMax in Setup page 4. Frequency, MHz or Auto

Page 5
 HamClock 4.16 User Guide
Data panes
●
Click the top center of a pane for a menu of available choices; choose one, or more will cycle.
●
Choices may be assigned to one pane at a time, and most panes must be assigned at least one choice.
●
Some choices also use lower click positions for specific functions as described below.
click to clear list
* DX Cluster lists and maps spots from the cluster host defined in Setup page 2, subject
to age, any filters and watch list (see page 14). See page 10 for setup info and 13 for
scroll controls. Frequencies are colored by band as per Setup page 6. Only the latest
spot of a given call on the same frequency is shown. The host is shown in yellow while
connecting, green while functional. The columns are kHz, call and age. Click any row to
set DX, rotator (page 7), radio (page 8) and bio if configured. Click the host name to edit
the watch list. Roaming over a list entry will mark it on the map. Clear the list by clicking
on  . Set max age in Setup page 5.
click to set whether to show bio (if configured), set max age and edit watch list
click spot to set DX, radio and bio if enabled; roam over to mark on map

SDO shows current images from the Solar Dynamics Observatory satellite. The corners
show current information with respect to an observer located at DE including the
Azimuth, Elevation, time of next Rise or Set, and radial velocity where positive values
indicate the motion is away from the observer. Click near the center of the image to
display a menu allowing any one of several image types to be selected; select Rotate to
automatically cycle them all in turn; show a Grayline planning tool where DE and DX
share twilight whenever either of their rise/set lines are close together; or display a recent
solar Movie in a separate browser window.
click for menu

If an optional BME280 environmental sensor is installed and working (see page 11), then
several pane options are available whose names begin with ENV to display temperature,
humidity, dew point or station pressure. The current value is shown along with a 24 hour
history. Clicking near the bottom of the pane will cycle immediately to another ENV
choice without having to use the normal menu. If two sensors are installed, the pane is
split to show graphs from each, labeled with their respective I2C bus addresses.
click to cycle to next ENV pane

click to show date, only current; color-code if spotted by DX Cluster; or open provider’s web page.
* DXPeditions lists current, or upcoming, amateur DX expeditions. Click the credits line
for overall menu options. Click a specific contest to set a future alarm; assign to DX; or
display the expedition web page, if any. Roaming over a list entry will mark it on the map.
Data are kindly managed by DXNews and G3K.

click an expedition to set alarm, assign to DX, or open web page; roam over to mark on map

click to select whether to show date and timezone

* Contests lists amateur radio contests for the upcoming, or current, weekend. Click the
credits line to set whether to show dates in UTC or DE time zone. Click a specific contest
to set the one-time future alarm to the contest start time or display the WA7BNM web
page for the contest. Contests currently in progress are highlighted with a green
background. Data are kindly provided with permission by Bruce Horn, WA7BNM.
click a contest to set alarm or open contest on WA7BNM web page

✳ These choices may be displayed in a taller pane made from combined DE: and DX: panels (see page 5)
Page 6
 HamClock 4.16 User Guide
Data panes, continued

Bz Bt shows the strength of the interplanetary magnetic field near Earth in units of nano
Tesla. Bz is the strength of the field pointing north, the same direction as the Earth’s field.
Bt is the total vector sum in all directions, and thus is always the larger value. When Bz is
negative, the fields are in opposite directions, partially cancelling the net shielding effect
of the magnetosphere and negatively impacting HF propagation. Values of Bz < -10 can
be significant.

* On The Air rotates through a collection of spots from various organizations. Current
orgs are POTA, SOTA and WWFF; more may be added. The current org is shown below
the title. The table columns are kHz, activator call and code, and m if > 10 minutes or h if
> 1 hour old. Frequencies are colored by band as per Setup page 6. Click the org name
for a menu to select whether to show bio, max age, desired sort and to edit the Org filter
and watch list (see page 14). The Org filter may list multiple orgs separated by spaces;
an empty filter matches all. Click a spot row to set DX, radio (page 10), rotator (page 8)
and bio page if used. Spot locations are plotted but paths are not because the spotter
location is not usually available. See page 13 for scrolling.
click org to set whether to show bio (if configured), set max age, set sort and edit Org and watch lists
click spot to set DX, radio and show bio if enabled

DE Wx and DX Wx show the current weather at DE or DX from [Link]. If

the location is not changed for at least an hour, an up or down arrow may appear to
indicate the pressure trend direction. When either DE or DX is changed by any means
the left pane will temporarily show its weather, unless already selected on another pane
or disabled in Setup page 5.

Planetary K shows the Kp index now, with a graph extending from 7 days prior to 2 days
forecast. The color scheme matches the NOAA web page.

Moon displays a graphic of the lunar surface facing earth with the proper portion shown
in shadow. The image is oriented depending on the DE [Link] corners show
information with respect to an observer located at DE including the Azimuth, Elevation,
time of next Rise or Set, and radial velocity where positive values indicate the motion is
away from the observer. Click the lower half for a menu to display a full rotation movie or
display the EME planning tool (see page 13).
click to show EME planning tool

✳ These choices may be displayed in a taller pane made from combined DE: and DX: panels (see page 5)
Page 7
 HamClock 4.16 User Guide
Data panes, continued

Sunspot N shows the current SIDC sunspot number and 30 days history. Since one
solar revolution is approximately this period and solar features typically evolve fairly
slowly, the graph provides a crude prediction of solar activity for the next month. Click in
the lower half to show a longer history.

click to show historical values

Solar Flux shows the current 10.7 cm measurement from National Research Council
Canada, as well as a 30 day history and prediction for the next three days. Click in the
lower half to show a longer history.

click to show historical values

X-Ray shows the current solar X-Ray levels and flare classification as measured by the
GOES-16 satellite with a 24 hour history. The levels are the powers of a logarithmic scale
computed as log10 (W m-2). The blue line is the 0.05 - 0.4 nm band, red is the 0.1 - 0.8 nm
band.

The DRAP plot option shows the highest frequency that is attenuated by at least 1 db
anywhere on Earth over the past 24 hours. Although the plot does not indicate the
location where this occurred, it is usually centered on the Earth daylight side unless there
is a Polar Cap Absorption event in progress. Also see the DRAP map option on page 12.
The signal paths are for an angle of incidence, a, of 90 degrees (straight up). For
shallower angles, multiply the attenuation by 1/sin(a).

Space Wx shows the three main NOAA space weather scales. The left column is for the
current conditions, and columns to the right are predictions for each of the next three
days. All scales use the same range of values, zero through five, with larger numbers to
indicate greater severity and public impact.
R: Radio blackout
S: Solar radiation storm
G: Geomagnetic storm

Rotator control: If rotctld is set in Setup page 3 then a Rotator option is available as a
pane choice to control most rotators supported by hamlib. Set the host and port fields to
the address of rotctld on your network. You must get rotctld working on your system first,
then consider controlling it from HamClock. The Az row shows the rotator azimuth
reported by rotctld and an angle graphic. Click the arrows beneath to manually command
left and right rotations of 5 and 20 degrees, with the current commanded position shown
between in a smaller font. An azimuth beam will also be shown on the main map. If the
rotator includes an elevation axis a second row, labeled El, provides similar functions.
Clicking Auto will either track the current satellite, if one is set and there is an elevation axis, or keep azimuth
pointing toward the short path of the current DX location. If the elevation axis can rotate beyond vertical to 180
degrees, i.e., upside down, it will be used to avoid an azimuth wrap during tracking and will be indicated with a
red arrow arc on the El row. All motion will cease while the Stop button is active or the Rotator pane is not visible.
Sat tracking requires HamClock to be set to UTC (see page 9). Pointing direction honors the long or short path
setting (see page 5).
Page 8
 HamClock 4.16 User Guide
Data panes, continued

Live Spots shows personalized reports from [Link], [Link] or Reverse

[Link]. With WSPR and PSK you may choose spots posted by your own DE call or
from your grid; or spots which others post of your DE call or grid. Using your grid allows
you to explore propagation from your general location without receiving or transmitting. 4-
character grid precision is used to find spots near you. Note RBN only works with
skimmer spots of your call (not by) because grids of the spotted transmitter stations are
not available. Click the summary line to display a menu that controls these choices as
well as maximum age; whether to list count or distance to farthest spot; and which bands
to map. Paths show a circle ● at the TX end, a square ■ at the RX end and the farthest
path for each band is marked with a target ⊕ and labeled as per Setup page 5. Placing
click for menu
the cursor near either end will show the info table (see page 12).

click left half of a row to show map of path reliability for that band
click right half of a row to show map of take-off-angle for that band

VOACAP: This pane choice shows a graph of path percentage reliability predictions from
DE to DX spanning 24 hours for each HF ham band. Graph squares are black if reliability
is less than 10%; red if less than 33%; yellow if less than 66% and green if above 66%.
Predictions always use VOACAP configured for isotropic 0 dBi antennas on both ends;
quiet location noise (-153 db) and the current mean sunspot number. Variable parameters
may be set by clicking the fields across the bottom: transmit power, mode, Take-Off-Angle
at DE and SP/LP to select Short or Long path. The graph time axis always places now at
the left edge. Click the timeline to toggle labels in UTC or DE local time. Clicking the left
click power, mode, TOA, path half of a band row will show a marker and add a world map of path reliability from DE.
Clicking the right half will show a marker and add a map of TOA from DE using the path
click to show DE or UTC with the best reliability. Click again to remove.

Solar wind: This pane shows 24 hours history of solar wind activity. Solar wind is a good
predictor of geomagnetic disturbances such as auroral activity and unusual polar HF
propagation. The available real-time metrics are density, in protons cm-3, and speed, in km
s-1. The product of these values gives the flux rate, or number of protons flowing through a
unit square per unit time, which is often a better predictor than either value alone.
HamClock displays this product in units of 1012 protons m-2 s-1 for which values above five
or so suggest better chances for aurora.

click for menu to set sort, watch list and file name

*ADIF: This pane lists and maps all QSOs in the ADIF file named in Setup page 3. File
name is followed by total minus any malformed entries (details are in the diagnostic log,
see FAQ 18). Frequencies are colored by band as per Setup page 6. The file is reread
every 2 seconds for automatic monitoring. Click file name for menu to set sort and edit
watch list (see page 14) or file name. Click a row to assign the DX object. Each ADIF
record must define the fields CALL or CONTACTED_OP; QSO_DATE; TIME_ON; BAND or
FREQ; and MODE. GRIDSQUARE or LAT and LON are used if present else location is set
looking up CALL in cty list. OPERATOR or STATION_CALLSIGN are used if present else set
click to set DX
to DE; MY_GRIDSQUARE, MY_LAT and MY_LON are used if present else set using DE or
cty lookup if possible. All other fields are ignored.

Aurora shows the current and recent maximum percent chances of visible activity
anywhere on Earth. To see the current best location, change to the Aurora map style
(page 12). Active auroral regions can absorb HF but act as reflecting layers at VHF.

✳ These choices may be displayed in a taller pane made from combined DE: and DX: panels (see page 5)
Page 9
 HamClock 4.16 User Guide
Notes

Setting DE and DX: Clicking lat, long or grid in the DE: or DX: panes will display a
dialog where these values may be directly edited to full precision either by clicking
the virtual keyboard or using a real keyboard the same way as Setup.
Corresponding values will be computed automatically and invalid entries will be
flagged when clicking Ok. Grid coordinates are based on the SW corner.
HamClock always uses full precision internally but, due to limited screen space,
rounds the display to whole values. This may lead to unexpected results when
entering fractional lat or long values. For example, suppose they are set to 35N and
110.1W so the grid will be DM45ka. The main display will show 35N 110W grid DM45 which, unless one knows
the internal values, seems incorrect because 35N 110W exactly is actually in grid DM55. When in doubt, open the
dialog to review the values at full precision.

Clicking anywhere on the map brings up a multi-purpose popup menu. It always offers controls
to set the HamClock DE or DX object to the clicked location if desired. It may also offer controls
to set a specific Zoom factor and/or to Recenter the map at the clicked location, depending on
the current map projection. The Mercator projection implements all options although recentering
may not extend beyond the poles. Robinson can only shift the center longitude, it can not zoom.
The other projections can neither zoom nor recenter. The menu starts with the current zoom
factor preselected. Reset restores the map to full size centered on the longitude specified in
Setup page 4. DX can also be set immediately without using the menu by either clicking mouse
Button 2 (middle) alone, or Button 1 (left) in combination with the Control or meta key (names
vary depending on your keyboard).

Clicking near the center of the main call sign box brings up the menu
shown at left. Normally the box shows the DE call sign but it can
display any arbitrary text by selecting title and entering the desired text
here, or rotate between both. Also, if flrig or hamlib’s rigctld have been
configured (see Setup page 3) or the GPIO PTT line is used (see page 16), the call box normally displays “On the
Air” when the transmitter is keyed (known as PTT or Push-to-Talk) but this can also be changed by entering the
desired text here.

Rig control: Setup page 3 allows choosing rigctld or flrig for simple rig control. Set the host and port fields to the
program on your network. When set up correctly, clicking a DX Cluster or On The Air spot will send the frequency
to radio VFO A. HamClock also polls PTT to change your call sign to ON THE AIR while transmitting. Three
consecutive errors disables PTT polling until the next attempt to send a spot.

You can also monitor PTT using a hardware connection instead of using software rig control, see page 16. Also,
the RPi can control the frequency of a KX3 via an IO pin, see page 15 and Setup page 3.

DX Cluster: DX cluster control is on Setup page 2. Spider, AR and CC clusters are currently supported. Set host
to the internet name or IP address of the cluster and port to its TCP port number. Filtered and/or watched spots
will be listed in the DX Cluster pane as they arrive (see page 6) and displayed on the map according to options on
Setup pages 5 and 6. Paths mark the TX end with a circle ● and the RX end with a square ■ . If the cursor moves
over either end, additional information is shown in the cursor info table (see page 12). Locations are determined
using the AD1C cty file. Clicking an entry in the list will redefine HamClock’s DX to that location and may also
tune your radio (see page 10) or command your rotator (see page 8).
●
If you make multiple simultaneous connections to the same cluster, be sure they each use a unique login
SSID suffix.
Toggling UDP? to Yes on Setup page 2 will instead listen for network UDP packets sent from WSJT-X, N1MM,
DXLog, Logger32, Log4OM and possibly other programs on your local network. Set the port to match the value
used by the program for sending UDP packets. The host is only used to match a program sending packets to a
multicast address, otherwise it is ignored. Once set up properly, new UDP spots function the same as described
above for a DX Cluster.

Page 10
 HamClock 4.16 User Guide
Notes, continued

Time: The time shown in large white letters below your call always shows HamClock’s idea of UTC. If your DE
time is incorrect, click the timezone offset button, see page 13. If the UTC button is black-letters-on-white-
background then HamClock is using real UTC. But you may modify the time by clicking on various locations (see
page 4). This can be useful, for example, to show a satellite location, gray line or VOACAP prediction at some
moment in the past or future. Changing away from UTC causes the UTC button to flash red OFF as a stark
reminder HamClock is no longer tracking real UTC. Clicking the red button will return abruptly back to real UTC. A
large question mark is shown when time is unknown.
●
Do not change the large white time to your DE time nor adjust it to correct DE time, use the timezone button.

Stopwatch: Click the stopwatch icon (beneath UTC seconds) to enter. Displays elapsed time in HH:MM:[Link].
Clicking Run begins or resumes counting; Stop freezes display and counting; Lap freezes display but continues
counting; Reset starts over; click along the spectrum bar to adjust color; Exit returns to main HamClock screen.
Independent 24 hour daily and once-only alarms are available. They may use either DE or UTC time zones.
When either is armed, the alarm clock icon on the HamClock main screen will be green (instead of gray) and
the alarm time may be shown in Big Clock. When either alarm goes off it will be announced on the main
screen in the center pane; on the Stopwatch screen by highlighting its control button; and on Big Clock by
highlighting the alarm time. Clicking any of these will cancel the alarm; these alerts automatically time out after
60 seconds. See page 16 for hardware control.
Count down counts backwards from the value set at its right, click just above or below to increase or
decrease down to 1 minute. If counting down is active: the main HamClock screen shows the time remaining
in lieu of the stopwatch icon; Countdown may be chosen as a Pane option; and the value may be shown in Big
Clock. It may be restarted from any of these locations with a click. Hold the main icon for 3 seconds to enter
the Stopwatch screen. See page 16 for hardware control.
Big Clock shows a large dedicated clock. Click anywhere for a menu to control options including analog or
digital format, UTC or DE, 12 or 24 hour, date info, DE or space weather, seconds, and basic control over
alarm and count down.

click for format menu

Brightness and Light sensor controls: If a light sensor is installed (aka “photo resistor” for historical reasons)
and the Full scrn direct? option in Setup page 5 is Yes, then the right-most pane may be set to show two vertical
scales. The left shows the current display brightness and the right the current light sensor reading. Both include
their respective calibration markers. Brightness is scaled from, and limited to, Min% to Max% from Setup page 4.
If the display can only be turned on or off, the brightness scale will only show a marker at top or bottom. To
calibrate a desired brightness response, start by exposing the light sensor to a bright intensity then click in the
upper half of the left scale to set the desired display brightness at that intensity (or just “on”). Then expose the
sensor to a dim light and click in the lower half to set the desired brightness at that low intensity (or “off”). Systems
without a light sensor but with ability to control display brightness will provide a single slider to control display
brightness manually.
On/Off timers: The upper right-most HamClock pane may provide a table of DE clock On and Off times at which
the display may be set to Max% or Min%, respectively; set the times equal to disable. Idle sets the number of
minutes of no user activity after which the display may change to Min%; set to zero to disable. Changing the On
or Off times will also set the On/Off table in Setup page 7 to match for the current day. Conversely, the pane’s
values will be reset from this table at each local midnight. If these timers turn the display Off, the light sensor will
then not control display brightness again until either a timer commands the display back On or the user clicks
anywhere in HamClock to restore brightness.

Page 11
 HamClock 4.16 User Guide
Notes, continued

Info table: A box such as those at left will appear automatically in the upper left corner of
the map whenever the cursor is over the map, over a spot on the map or listed in a data
pane. The contents depend on context but may contain Latitude; Longitude; Grid; Local
Mean Time (does not account for savings time); CQ and ITU zone designations; Prefix;
TX and RX call and grid; Mode; Frequency; spot Age; Bearing and Distance from DE; and
weather conditions. The bearing degree symbol becomes M if referenced to magnetic
north (see Setup page 5). When displaying spot information the border color matches the
assigned band color and a red bullseye shows the corresponding map location.

Click the upper left map button for a menu of viewing options:
●
Style selects the overall map background from the following choices, rotating if multiple are set:
●
political Countries and natural Terrain
●
DRAP: This map style shows a near real-time display of the NOAA D Region Absorption
Predictions model, or DRAP. The model predicts HF propagation absorption caused by solar X-
ray and proton flux events. D layer absorption decreases with increasing frequency, so the map
color-codes the highest frequency ray that is attenuated by at least 1 dB while passing through
each location. Rays at lower frequencies will experience progressively greater attenuation of 30
dB or more. The color scale is gray for no absorption at any frequency progressing through a
spectrum to indicate higher frequencies. See also the DRAP pane (page 8) for a time history.
●
MUF-VCAP: This map style shows the VOACAP model for median Maximum Usable
Frequency between DE and other points in the world about half the time each month. This
model is useful for long term planning, such as for a DXpedition; the MUF-RT style is a better
indication of current conditions. Note even when a path seems promising, it may still not be
unusable due to low signal power, local noise or variable space weather conditions. The map is
color coded the same as DRAP.
●
MUF-RT: This style shows a real-time map of Maximum Usable Frequency based on a world-
wide consortium of ionosondes, those of which were active within in the last hour are labeled
with their reporting frequency. The data are updated every fifteen minutes. Note that since the
stations are not spaced uniformly, significant license was required to perform global
interpolation. At any given location, the MUF value is the highest frequency that will refract back
to Earth a wave launched 1500 miles away, thereby supporting a total single hop path of 3000 miles. Waves
higher in frequency will generally continue on to space and be lost. Using this basic model, one can imagine
where the hops will occur along a path from DE to DX and estimate whether they will be supported for a given
band. Note even when a path seems promising, it may still not be unusable due to low signal power or local
noise. This map is a good indication of current conditions; the MUF-VOACAP style is better suited for long
term planning such as for a DXpedition. Both use the same color key. Data for this map are from GIRO
collected and used by permission from KC2G.
●
Aurora: This map style shows the chances for aurora activity based on total ionospheric energy deposition.
High activity is often associated with geomagnetic storm conditions. This map is best viewed with the
Azimuthal projection.
●
Weather: shows color-coded temperature, pressure isobars and wind speed direction flags; updated hourly.
●
Clouds: shows global IR reflectance satellite imagery delayed by 1-2 hours.
●
Grid overlay:
●
Tropics draws global lines at ±23.5 degrees latitude
●
Lat/Long draws lines of constant latitude and longitude every 15 degrees
●
Maidenhead draws (and labels in Mercator projection) each top-level grid square
●
Azimuthal draws radial lines every 15 degrees of bearing and rings at constant distance from DE
●
CQ or ITU zones draws the boundaries of these global regions
●
Map Projection:
●
Mercator is the classic form with equally spaced lines of latitude and longitude; large distortion near poles.
●
Azimuthal shows front and back hemisphere views centered on DE and its antipode, respectively.
●
Azim One is one full globe centered on DE; the entire outer edge is the single antipode point.
●
Robinson is the popular projection often used in publishing; pleasing but has distortion everywhere.
●
RSS: overlays the lower map with live RSS feeds, cycling every 15 seconds. Click to show parent web page.
●
Night: select to darken the map where it is currently night time; good for showing current gray line boundary.
●
Cities: whether to display name and population of representative cities nearest to cursor, if any.
Page 12
 HamClock 4.16 User Guide
Notes, continued

The EME planning tool is shown by clicking in the

lower half of the Moon pane (see page 7). The tool
plots the lunar elevation at DE and DX for the next two
days starting now. The time axis is labeled in DE and
DX local time and UTC. The table in upper left shows
the next period when the moon is simultaneously up at
both DE and DX. All such periods are also marked
along the time line. Click the plot anywhere for
detailed information at that moment. Click Resume to
restore normal HamClock operation or let it time out.

The Satellite planning tool is shown by selecting it

from the DX pane when it is showing satellite info
(page 5). The tool plots the elevation at DE and DX for
the next day starting now. The time axis is labeled in
DE and DX local time and UTC. The table in upper left
shows the next period when the satellite is
simultaneously up at both DE and DX. All such periods
are also marked along the time line. Click the plot
anywhere for detailed information at that moment.
Click Resume to restore normal HamClock operation
or let it time out.

Scroll controls appear automatically when panes have too many lines to
display. Up shows how many more lines are above, Down shows the number
below. Clicking either shifts the list in the given direction, leaving one line for
context. Setup page 5 allows setting whether the list grows top-down or bottom-up. If the scroll entries are DX spots,
the arrow is red if there are any spots in that direction matching a Red watch list (see page 13). If new spots arrive
while scrolled away from the front of the list, the list position does not change but a button labeled New appears;
clicking it will jump immediately to the front of the list. Also while scrolled away the border is red, pane rotation is
suspended and clicking the title does not offer a menu to assign new choices.

Click the Time zone control for DE or DX to set a manual offset or automatic. Automatic sets the UTC
offset and adjusts for Daylight Savings Time based on approximate location; set an offset manually if
incorrect. The setting will persist across restarts but changing a location always resets to automatic.
Note the correction for DST may not engage until an hour or so after the official change.

Demo mode: Click the padlock to select this mode which means HamClock will autonomously make a
random setting change to itself every 30 seconds, including the plot panes, DX location and map view options.
When active, the padlock changes to a running figure to indicate demo mode is active. Meanwhile HamClock
may still be used normally. Click the figure again to turn off demo mode. Note that whether Demo mode is
chosen is not persistent, it must be selected again if desired each time HamClock starts.

Page 13
 HamClock 4.16 User Guide
Notes, continued

Watch lists are used to filter DX Cluster, On The Air and ADIF spots. They may be edited either in the Setup session
or within the popup menus for each pane. Each watch list consists of one or more specifications separated by
commas. Each specification may consist of any of the following requirements, all of which are optional:
●
band names in several formats:
●
a single band name followed by M for meters, such as 40M
●
multiple bands separated by hyphen in either order, such as 20-10M or 10-20M
●
a sub-band mode may be specified following the band number such as 40CW or 20SSB or 30FT8
●
multiple sub-band ranges separated with a hyphen, such as 160-10CW or 10-20DATA
●
exact frequency range:
●
min-max in MHz which may span multiple bands, such as 14-14.02MHZ or 7.0-10.15MHZ
●
ADIF keyword: predefined qualities of a spot which must not be found within the current ADIF file:
●
NADXCC: no ADIF entry matches the spot’s DXCC entity
●
NAPREF: no ADIF entry matches the spot’s prefix
●
NAGRID: no ADIF entry matches the spot’s grid (first 4 characters only)
●
NABAND: no ADIF entry matches the spot’s band
●
these may be combined, such as NAGRID NABAND to require no matching grid square or band
●
prefix: anything not fitting the above rules specifies the required leading characters of a call (see more below)
Notes:
●
Prefixes only check their number of characters for a match. Ex: prefix AA matches AA0 and AA1 but not A or AB.
●
Spot call signs containing a slash (/) are broken into “dx” and “home” portions. The “dx” portion is the shorter side
but is ignored if it consists of 1 character or digit, is one of the abbreviations /MM or /AM, or consists of 3 or more
characters without any digits such as /QRP. Calls without a slash are always considered to be “home” calls.
Ex: VK2/WB0OEW and WB0OEW/VK2 both assign “dx” to VK2 and “home” to WB0OEW, but WB0OEW/0
assigns “home” to WB0OEW but has no “dx” portion because /0 is ignored.
●
Watch list prefixes that end in a slash, /, apply only to the “dx” portion of a portable call. Prefixes without a slash
apply only to the “home” portion of a call. Ex: the prefix VK2 will match WB0/VK2ABC but not VK2/WB0OEW;
conversely prefix WB/ will match VK2ABC/WB0 but not WB0OEW/VK2.
●
A spot is considered a match if it is selected by all the given requirements within any of the given specifications.
●
Think carefully when mixing watch lists with native DX Cluster commands (see Setup page 2).
●
The ADIF keywords may not be used in the ADIF watch list.
●
The supported sub-band modes are based on those in DX clusters: CW, DATA, FT4, FT8, RTTY, SSB. Modes
are implemented as frequency boundaries, not actual transmission content, so may not be correct.
Each watch list can be set to control its display list in one of four ways:
Off: HamClock will save the watch list but it has no effect; all spots are displayed normally.
Red: all spots are displayed but those which match are highlighted in red in the display list.
Only: like Red but only the matching spots are displayed.
Not: the opposite of Only, i.e., only spots that do not match all specifications are displayed.

Example Watch List A spot matches if ...

30M ... it is on 30 meters
40-80M ... it is on 40 or 80 meters
20m WA WB K ... it is on 20 meters with home prefix WA or WB or K
7.0-7.01MHZ ... it is in the DX CW window of 40 meters
VK/ 20M 30M, ZL/ 30M ... it is a portable station in VK on 20 or 30, or a portable ZL station on 30
NADXCC ... its DXCC does not match any spot in the ADIF file on any band.
use this to look for new DXCC entities.
NADXCC NABAND ... both its DXCC and band do not match any one spot in the ADIF file.
use this to look for new band slots.
40M NAPREF ... it is on 40 and has a prefix not in the ADIF file.
use this to look for new prefixes on 40m
20-10M NAGRID ... it is on any band from 20 to 10 and no spots in the ADIF file have the same grid.
use this to look for new grids on these bands.

Page 14
 HamClock 4.16 User Guide
External IO Options
HamClock supports several optional external devices to enhance the operator experience. These include
●
one or or two BME280 environmental sensors for temperature, pressure and humidity;
●
LTR329 light sensor for automatic dimming depending on ambient lighting (see page 11);
●
several switches and LEDs to complement the ON THE AIR indicator, timer, alarm clock and satellite status;
●
time and location from NMEA sentences from the serial connection of a GPS receiver;
●
Elecraft KX3 serial frequency control, available only with RPi header pin 8.

These devices may be connected to HamClock in two different configurations, as shown below. Devices may be
connected in any order and all are optional.
●
to the 40 pin header of a Raspberry Pi
●
to any linux or Mac with a USB port using an I2CMini from [Link], including the Pi if preferred

Page 15
 HamClock 4.16 User Guide
External IO Options, continued

The discrete GPIO options are described in the table below. Each is independent and may be chosen separately
as desired. Connect the Terminal connections to either the Pi header or the MCP23017 port expander, depending
on the HamClock configuration used on page 15. The MCP23017 is not needed if none of these are used.
On a Raspberry Pi, Setup page 4 also includes a toggle named GPIO. Setting this Off prevents HamClock from
using any of the native pins in order that they may be used for something else. To use the I2C header pins on a
RPi the GPIO toggle must be set to Active in addition to setting the proper file name (see next).

GPIO Option Description Terminal Pi Header MCP23017

Pin Pin
A falling edge from a SPST switch or CD_1 17 VIN
PTT line on terminal CD_4 (re)starts the CD_2 33 A0
count down timer. Driving voltage, if any, CD_3 35 A1
must not exceed 3.3 V. The LEDs CD_4 37 A2
indicate the time remaining: green when
counting down; both when 1 minute or
less remains; red when timed out.

Output terminal SA_A indicates satellite SA_1 38 A5

visibility from DE. Normally low, it cycles
high at 1 Hz for 1 minute before rise,
stays high during the pass, cycles at 2
Hz during the last minute then stays low
again after set.
Grounding input terminal OA_1 with a OA_1 40 A6
switch or PTT line will change the call
sign text to “ON THE AIR”. Driving
voltage, if any, must not exceed 3.3 V.
Output terminal AL_1 will go high while AL_1 31 A3
either alarm is “ringing”. The schematic AL_2 29 A4
shows an LED but a piezo buzzer works
also. Briefly grounding input terminal
AL_2 will silence either alarm.

This flexibility does come at a price. You must determine and enter the name assigned by the host to the native or
bridged I2C bus in the I2C file field of Setup page 4. The table below shows a sample of systems and typical
names. One way to discover the exact name is to start a terminal session and run the command ls /dev. Look
for something similar or, in the case of a USB-I2C bridge, remove and plug the device back in and see what
changes. If you find both tty and cu names that are otherwise the same, always use the cu name.

Configuration Typical I2C File name

Raspberry Pi 40 pin header Debian /dev/i2c-1
FreeBSD /dev/iic0
USB-I2C bridge Debian /dev/ttyUSB0
FreeBSD /dev/cuaU0
macOS /dev/[Link]-DK0C3XGZ

Page 16
 HamClock 4.16 User Guide
External IO Options, continued

The serial output from a GPS module that sends the RMC NMEA sentence may be connected directly to
HamClock. The TX line from the module can be connected to Raspberry Pi header pin 10 or via any serial-USB
converter cable supported by your computer operating system.
● To use the RPi header, perform the following steps:
●
connect the TX line from the module to header pin 10. If needed, +5V can be taken from pin 2 and ground
from pin 14.
●
run sudo raspi-config, go to Interfaces and select Serial. Turn Off console and On hardware support;
finish and reboot
●
Got to HamClock Setup page 1, turn on NMEA, set the baud rate of the GPS module and enter file
/dev/serial0 on RPi 4 or earlier, or /dev/ttyAMA0 on RPi 5.
● To use a USB converter cable on any computer running HamClock:
●
connect cable +5V, ground and RX to the GPS module and plug the USB end into the computer.
●
run ls /dev before and after plugging in the USB to find the new entry. On RPi it might be /dev/ttyUSB0;
macOS something like /dev/[Link]-AL00FP5D; FreeBSD it might be /dev/cuaU0.
●
Go to HamClock Setup page 1, turn on NMEA, set the module baud rate and the file name found above.
● Bonus! Use a UNIX fifo:
●
Use mkfifo to create a fifo file anywhere
●
Enter the fifo path as the HamClock NMEA file. Baud rate does not matter.
●
Now any NMEA sentences piped into the fifo will be read and processed by HamClock.

Command Line Options

The hamclock program accepts the following optional arguments. For example: to skip the initial setup
screens (assuming all fields are valid) to immediately begin normal operation, change the read/write web
interface to port 20000, and throttle the CPU load to 20%, run hamclock as:

hamclock -k -w 20000 -t 20

-0 : restore all original default Setup values

-d d : set working directory to d; default is /Users/ecdowney/.hamclock/
-e p : set RESTful web server port to p or -1 to disable; default is 8080
-f o : force display full screen initially to "on" or "off"
-g : init DE using geolocation with current public IP; requires -k
-h : print this help summary then exit
-i i : init DE using geolocation with IP i; requires -k
-k : start in normal mode, ie, don't offer Setup or wait for Skips
-l l : set Mercator or Robinson center longitude to l degrees, +E; requires -k
-m : enable demo mode
-n t : set live web idle timeout to t minutes; default forever
-o : write diagnostic log to stdout instead of in /Users/ecdowney/.hamclock/
-p f : require passwords in file f formatted as lines of "category password"
changeUTC configurations exit newde newdx reboot restart setup shutdown unlock upgrade
-r p : set read-only live web server port to p or -1 to disable; default 8082
-s d : start time as if UTC now is d formatted as YYYY-MM-DDTHH:MM:SS
-t p : throttle max cpu to p percent; default is 80
-v : show version info then exit
-w p : set read-write live web server port to p or -1 to disable; default 8081
-x n : set n max live web connections; max 100; default 10
-y : activate keyboard cursor control arrows/hjkl/Return -- beware stuck keys!

Page 17