This live screen grab is from one of my HamClocks. It updates automatically every minute after making a random tap.

Ham Clock

This page refers to my QST article in the October 2017 issue. All updates will be posted here.

Click on the tabs below for more information.

I would like to give Shoutouts to Adafruit and the Raspberry Pi Foundation for their great electronics, software and tutorials.

News highlights. See the complete version history in the Download tab, below.

  • DX Spider spots are an option in the center plot area. Tap to set DX and KX3 frequency. See FAQ for details.
    Note: You are logged into a cluster while this pane is visible.
  • UNIX gpsd daemon is supported on all platforms for setting DE location and time from a GPS receiver.
  • General purpose Stopwatch, tap the icon below the seconds to activate.
  • Display VOACAP band path reliability predictions from DE to DX at various power levels. See the Operation tab for details.
  • Now manufactured by Veritium Research and marketed by Gigaparts rebranded as HFClock.

73, Elwood Downey, WBØOEW

Original QST Article proof


Download current stable HamClock release source code here.

Revision history:

Version 2.46: Version 2.45: Version 2.44: Version 2.43: Version 2.42: Version 2.41: Version 2.40: Version 2.39: Version 2.38: Version 2.37: Version 2.36: Version 2.35: Version 2.34: Version 2.33: Version 2.32: Version 2.31: Version 2.30: Version 2.29: Version 2.28: Version 2.27: Version 2.26: Version 2.25: Version 2.24: Version 2.23: Version 2.22: Version 2.21: Version 2.20: Version 2.19: Version 2.18: Version 2.17: Version 2.16: Version 2.15: Version 2.14: Version 2.13: Version 2.12: Version 2.11: Version 2.10: Version 2.09: Version 2.08: Version 2.07: Version 2.06: Version 2.05: Version 2.04: Version 2.03: Version 2.02: Version 2.01: Version 2.00: Version 1.94: Version 1.93: Version 1.92: Version 1.91: Version 1.90: Version 1.89: Version 1.88: Version 1.87: Version 1.86: Version 1.85: Version 1.84: Version 1.83: Version 1.82: Version 1.81: Version 1.80: Version 1.79: Version 1.78: Version 1.77: Version 1.76: Version 1.75: Version 1.74: Version 1.73: Version 1.72: Version 1.71: Version 1.70: Version 1.69: Version 1.68: Version 1.67: Version 1.66: Version 1.65: Version 1.64: Version 1.63: Version 1.62: Version 1.61: Version 1.60: Version 1.59: Version 1.58: Version 1.57: Version 1.56: Version 1.55: Version 1.54: Version 1.53: Version 1.52: Version 1.51: Version 1.50: Version 1.49: Version 1.48: Version 1.47: Version 1.46: Version 1.45: Version 1.44: Version 1.43: Version 1.42: Version 1.41: Version 1.40: Version 1.39: Version 1.38: Version 1.37: Version 1.36: Version 1.35: Version 1.34: Version 1.33: Version 1.32: Version 1.31: Version 1.30: Version 1.29: Version 1.28: Version 1.27: Version 1.26: Version 1.25: Version 1.24: Version 1.23: Version 1.22: Version 1.21: Version 1.20: Version 1.19: Version 1.18: Version 1.17: Version 1.16:

• How do I build the ESP8266 software?

  1. Install the latest Arduino IDE with these these instructions. I am currently using version 1.8.10.
  2. Load up the ESP extension described here then Exit the Arduino IDE.
  3. Download and install the following Arduino libraries:

    Do not use newer versions, these are the versions I have tested extensively.

    If you need help with libraries in general try here .

  4. Connect your computer to the Huzzah with a USB port
  5. Download current stable HamClock release here, unzip it any place you wish.
  6. Start the Arduino IDE. Open the ESPHamClock.ino file you just unzipped. This will create a new project.
  7. In the IDE Tools menu make the following selections (click for larger view):


    If the options you see do not look exactly like mine do these steps:

    1. open Tools → Board → Boards Manager...
    2. In the search box type esp. Look for esp8266
    3. Click More Info
    4. Click Select version and select 2.4.0 (not newer versions)
    5. Click Update
    6. Click Close

    Again, do not use a newer version, this is the version I know and trust.

  8. Run Sketch → Compile then Sketch → Upload
  9. Your HamClock should start running. Follow the touch screen and setup functions carefully.

• How do I build the Raspberry Pi Desktop or fb0 software?

See the Desktop tab, on the right.

• How does the DX Cluster feature work?

  1. In the Setup page, tap the Cluster? button then set the internet host name and port for your desired DX Spider node. A good list is here. Be sure to choose a Spider node, AR and CC clusters are not supported. Turn off the Cluster? button if you don't want to use a cluster.
  2. Once HamClock is up and running, tap the center plot until the DX Cluster pane appears. The name of the host will be shown in yellow, and it will turn green when a connection is established. If the connection fails, it will show an error in red.
  3. Once connected, just leave it run, new spots will be listed, scrolling when full. Tap on a spot to set DX to that location. Pretty neat!
  4. Beware: HamClock stays logged into the cluster node with your call sign as long as the DX Cluster pane is active. So do not use this feature if you want to use the unassisted category in a contest -- some judges do check!
  5. Spider nodes support a lot of options and settings but HamClock makes no attempt to control any of them. But you may still be able to set them by logging in to the same cluster with the same call sign from a different application or telnet session. Make the desired settings and most nodes will carry them over to all login sessions, so the settings will apply to the HamClock session as well. Here is just one example of a set of filters that will show only CW spots from operators in US or southern Canada:
        filter1 reject not by_zone 3,4,5
        filter2 reject not on hf/cw
        filter3 reject on hf/rtty
        filter4 reject on hf/ssb
        filter5 reject info ft8

Starting with Version 2.44, you can connect an Elecraft KX3 to an ESP Huzzah or RPi HamClock so when you tap a DX Cluster spot the frequency is assigned to transmit VFO A. I think this will work with all Elecraft radios that have CAT control but this is the only radio I have to test and I do not know how to make the other cables.

To make the connection, build a cable as follows:

DISCLAIMER: Do this at your own risk, I take no responsibility for anything.

  1. Find an old 1/8" (3.5 mm) stereo cable.
  2. Chop off the stereo plug, discard the other end, and expose the inner wires.
  3. Find the wire connected to the plug tip.
  4. Connect it to Huzzah pin 15, or RPi header pin 8.
  5. Connect the cable shield to ground.
  6. Insert the plug into the KX3 ACC 1 socket.
  7. Check the KX3 RS232 menu is set to 38400.
  8. Tap a DX spot and the radio will change to the spot frequency using VFO A.

• Can I make different sizes beyond those in the Makefile?

Not easily. Each size requires its own custom fonts, symbols, maps and solar images in order to take full advantage of the higher resolutions. Otherwise, these would be very chunky if they were just multiples of the base images. Plus, if the aspect ratio changes, the layout would need to be rebalanced. This is why all sizes are multiples of 2 of the base size in order to maintain the same layout proportions.

• Why can I click on the DE or DX grid square and sometimes get a second value?

Because displaying location only to a whole degree, or any finite precision, can be ambiguous. Suppose you use the Setup screen to enter location 40N and 100.1W. This is in grid square DN90. But this location will be rounded to 40N 100W for display and this location is in grid square EN00. Just looking at the rounded HamClock display values you can't tell what the original location is, so HamClock gives you the choice of selecting the grid according to your intended usage.

The reason this happens is because grid squares increase from west to east, starting at 180W, and the major longitude grid boundaries are on even integral values. Thus 100W is in one grid and 100.1W is in a different grid. This becomes easier to see when using signed notation. You might expect moving from -100 to -100.1 to stay in the same grid but it doesn't because it is more westward and crosses the boundary at -100. But there is no ambiguity going from -101 to -101.1 because these are both near the center of the same grid, DN90. There is also no grid change going from the eastern longitude of positive 100 to 100.1 because the numeric increase is eastward and both locations are in the same grid, ON00.

The exact same thing happens with latitudes except they grow northwards from 90S and grid boundaries are on every integral line.

In addition to being set from the Setup screen, fractional coordinates can also result when setting location with other methods as well, such as IP Geolocation, gpsd or the remote web socket interface -- in all cases the full precision is maintained internally but only displayed to whole degrees. However, if you set a location by tapping the map or tapping the coordinate values to increment or decrement them then HamClock discards any fractional coordinate values so these methods never lead to a grid square ambiguity.

• Occasionally you mention web interface to the HamClock, what is this?

It allows you to remotely control your HamClock over a network using a browser or command line tool such as curl or wget. This is possible because HamClock responds to its network IP address on port 80, the default for http web servers. To try the following examples, you will need a computer on the same network as your HamClock. We will use curl but the same URLs will work in your browser as well (although some browsers are getting more paranoid about accessing a web site with http and you may be asked to trust the site).

Start by querying HamClock for a list of all its commands as follows:

	curl ''

You must change the example address to the IP your HamClock displays periodically just below your call sign. Note the good practice of surrounding the URL with apostrophes to insure it is not interpreted with shell metacharacters. The output will be a list of all supported commands. As of version 2.38, this list is as follows:

Syntax Summary
/get_capture.bmp Save screen as bmp file
/get_satellite Report current satellite position, if one is defined
/get_sensors Generate list of sensor values, if one is attached
/get_stats Report some basic HamClock operational statistics
/help Print list of available commands
/reboot Restart HamClock
/set_display?on/off Set display brightness
/set_newde?lat=X&lng=Y Define a new DE location using latitude/longitude
/set_newdegrid?AB12 Define a new DE location using its maidenhead grid square
/set_newdx?lat=X&long=Y Define a new DX location using latitude/longitude
/set_newdxgrid?AB12 Define a new DX location using its maidenhead grid square
/set_satname?abc Select the active satellite by name, name must be in the predefined list
/set_sattle?name=abc&t1=line1&t2=line2 Define the active satellite by using its TLE values
/set_time?ISO=YYYY-MM-DDTHH:MM:SS Set UTC to the given time
/set_time?Now Set UTC from network
/set_time?unix=s Set UTC to the given UNIX time
/set_touch?x=X&y=Y Act as if touched at the given screen coordinates, scaled to 800 x 480

For example, turn the display brightness down:

	curl ''

and back up:

	curl ''

Set a new DE location:

	curl ''

Save the current display to a file named hcscreen.bmp:

	curl '' > hcscreen.bmp

• Holding the padlock does not restart ESP, what's going on?

For some unknown reason, this feature does not work the first time you try it after flashing the ESP Huzzah via USB from your computer. Use the reset button on Huzzah once then the padlock will work from then on. This issue does not occur if the Huzzah was reflashed remotely.

• How do I shut off HamClock on the RPi fb0?

Log in and kill the process with the following command:

        sudo pkill 'hamclock.*'

If running HamClock and you want to shutdown the whole RPi, hold the padlock for 3 seconds then choose Shutdown.

• How do I safely power off my RPi?

    1. If running fb0 HamClock:
      hold padlock for 3 seconds, then select Shutdown
    2. otherwise in general:
      Log in and type the following command:
      sudo halt
  1. Then either way, watch the green LED, when it stops blinking it is safe to remove power.
  2. Note you do not need to bother shutting off HamClock before powering off RPi, it won't hurt the Clock in any way.

• My question is not here, where can I get help?

Send me a polite note at

To use a 9" ER-TFTM090-2 from

Select these options during purchase:

This is the wiring list:

    EP = ESP Huzzah
    BM = BME280 sensor
    PC = photo cell
    DP = display

    EP_SCL    BM_SCK
    EP_SDA    BM_SDI
    EP_3V     BM_VIN
    EP_GND    BM_GND

    EP_ADC    PC_1, 330k
    EP_GND    PC_2
    EP_3V     330k

    EP_SCK    DP_8
    EP_MO     DP_7
    EP_MI     DP_6
    EP_2      DP_5
    EP_16     DP_11
    EP_USB    DP_3, 4, 37, 38
    EP_GND    DP_1, 2, 13, 31, 39, 40



The display stand from Adafruit can be made to work with a little ingenuity but is not perfect for the LCD. Send suggestions for better ideas and I will post here.

If you find your display idea works better if the cable exits from the top, there is an option in the Setup screen that allows you to flip the display upside down.

Here is how I built my first two prototypes:

Shack photo showing 7" version.

Rear of 7" version

Both the 7" and 9" versions.

Rear of 9" version

This is a guide to the touch controls and map symbols of HamClock. A printable view is also available.

I am being asked more and more often how HamClock compares to the Geochron 4K. I do not have a Geochron but from its literature I can think of the following display functions HamClock offers that Geochron does not:

  1. VOACAP predictions for any path at several power levels
  2. history plots and predictions for solar flux, sunspot, XRay and Kp index
  3. short and long path antenna beam heading and distance to any DX location
  4. display next satellite rise/set times and overhead pass (not just global track)
  5. display local time in HH:MM digital, analog or calendar formats
  6. azimuthal world maps centered on any location
  7. weather, local time, grid square, prefix and sun rise/set times at any DX location
  8. live scrolling DX cluster display
  9. live solar images from Solar Dynamics Observatory
  10. live NCDXF beacon schedule
  11. live RSS feeds from popular ham web sites
  12. show Moon rise/set and overhead passes for EME
  13. adjust time forward or back to explore gray line location, satellite orbits etc
  14. optional Elecraft KX3 transceiver frequency control from DX Cluster spot
  15. optional local temperature, pressure and humidity sensor for real-time and 25 hour trend plots
  16. optional photosensor to adjust display brightness with changes in room lighting
  17. adjustable scheduled display On and Off times
  18. remote control from any browser or curl command line
  19. RPi version can use any HDMI display up to 4k

Conversely, Geochron can do things HamClock can not. These items are certainly interesting but to me they do not seem specifically useful to the typical amateur radio operator:

  1. air and sea traffic
  2. pollution and population maps
  3. different landform map styles

If I have misrepresented Geochron in any way, please let me know and I will correct immediately.

HamClock may also be built for Raspberry Pi, macOS, linux, FreeBSD or any other UNIX-like system in two ways:

HamClock may be built in the following sizes. If the display is larger, HamClock will center itself within a black background.

Operation of HamClock on these platforms is exactly the same as the ESP8266 version with the following exceptions:

• To give it a try on your GUI desktop, follow these steps:

  1. open a terminal on the target system desktop to get a command line prompt
  2. run these commands:
    curl -o
    cd ESPHamClock
    make -j 4 hamclock
    sudo ./hamclock
  3. If you get errors during make:
    • on RPi try updating and loading more packages such as
      sudo apt-get update
      sudo apt-get -y install make g++ libx11-dev
    • on Ubuntu try loading more packages such as
      sudo apt install curl make g++ xorg-dev
    • on macOS try installing XQuartz and Xcode. Then run
      xcode-select --install
  4. The example make command above will build HamClock at 800x480 pixels for X11. Type make help for a list of other sizes and desktop environments available.
  5. On macOS, you can turn the bare executable into a clickable App and test it as follows:
    mkdir -p
    cp hamclock

• To try it on an RPi using a dedicated HDMI or DSI 7" display, follow these steps:

Note: the following instructions use ssh for a reason, do not try to use the RPi display for these commands. The HamClock must have the fb0 display all to itself.

  1. log in via ssh (or putty, etc)
  2. run sudo raspi-config one time and set the following options:
    1. Boot Options -> Desktop/CLI -> Console
    2. For HDMI only, not for DSI 7": Advanced options -> Resolution -> choose any 1600x960 or larger
  3. reboot
  4. connect to your RPi again with ssh and run the following commands:
    curl -o
    cd ESPHamClock
    make -j 3 hamclock-fb0
    sudo ./hamclock-fb0
  5. The example make command above will build HamClock at 1600x960 pixels for RPi HDMI. If you want the smaller size 800x480 for the DSI 7" touch screen, change the make target to hamclock-fb0-small. Type make help for a list of other sizes and desktop environments available.
  6. If you see a little blinking line near the left edge, try running this command:
    sudo bash -c "echo 0 > /sys/class/graphics/fbcon/cursor_blink"
  7. Note that all UNIX versions of HamClock emulate the ESP non-volatile EEPROM with the file ~/.rpihamclock_eeprom. Removing this file and restarting HamClock will reset it back to all default values.

• If you want to use the Bosch BME280 environment sensor on RPi, follow these steps:

  1. connect the sensor to the RPi using the 40 pin connector as follows:
        Pin 1    BME Vin
        Pin 3    BME SDI
        Pin 5    BME SCK
        Pin 9    BME GND
  2. install i2c-tools:
        sudo apt-get install i2c-tools
  3. run sudo raspi-config and set the following options:
        Interface Options: I2C: enabled
  4. Check the Bosch is connected correctly with these tests:
        sudo i2cdetect -y 1
    you should see 77 in lower right corner of matrix; then
        sudo i2cdump -y 1 0x77 b
    you should see a matrix of numbers, NOT XX
  5. Restart hamclock by tapping and holding the padlock for 3 seconds.
  6. After HamClock is running again, click in the lower half of SDO image pane to see environmental plots.

• To start hamclock-fb0 automatically when the system boots, consider using crontab.

For example:

  1. Start crontab with the edit option:
    crontab -e
  2. Add this one line:
    @reboot cd ESPHamClock; sudo ./hamclock-fb0 > /dev/null 2>&1
  3. Save and exit the editor. Test by rebooting. This example assumes ESPHamClock is in your home directory
    and you want to run hamclock-fb0 therein. Adjust as necessary to match your configuration.
    This example also discards the diagnostic output. If you want to save it, change /dev/null to a file name of your choice.
  4. To learn more about crontab type:
    man 5 crontab