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

Ham Clock

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

News highlights: See the complete version history in the Download tab and details in the User Guide.
  • New background map and plot options showing live D layer absorption
  • Support up to 2 BME280 sensors
  • Separate on/off times can be set for each day of the week
  • GUI now supports full screen -- fb0 is deprecated
  • Separate analog or digital Big Clock when you just want a simple clock
  • 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 as zip or tgz.

Revision history:

Version 2.65: 2021-07-04 Version 2.64: 2021-07-03 Version 2.63: 2021-06-18 Version 2.62: 2021-05-23 Version 2.61: 2021-04-10 Version 2.60: 2021-03-21 Version 2.59: 2021-02-27 Version 2.58: 2021-02-18 Version 2.57: 2021-01-24 Version 2.56: 2021-01-09 Version 2.55: 2020-12-13 Version 2.54: 2020-12-05 Version 2.53: 2020-10-28 Version 2.52: 2020-10-10 Version 2.51: 2020-08-08 Version 2.50: 2020-07-26 Version 2.49: 2020-07-10 Version 2.48: 2020-07-03 Version 2.47: 2020-06-19 Version 2.46: 2020-05-29 Version 2.45: 2020-05-13 Version 2.44: 2020-05-07 Version 2.43: 2020-04-16 Version 2.42: 2020-04-02 Version 2.41: 2020-03-04 Version 2.40: 2020-01-19 Version 2.39: 2020-01-18 Version 2.38: 2020-01-01 Version 2.37: 2019-12-27 Version 2.36: 2019-12-21 Version 2.35: 2019-12-15 Version 2.34: 2019-12-02 Version 2.33: 2019-11-28 Version 2.32: 2019-11-26 Version 2.31: 2019-11-11 Version 2.30: 2019-10-25 Version 2.29: 2019-10-11 Version 2.28: 2019-10-11 Version 2.27: 2019-10-10 Version 2.26: 2019-10-09 Version 2.25: 2019-10-07 Version 2.24: 2019-10-02 Version 2.23: 2019-09-28 Version 2.22: 2019-09-23 Version 2.21: 2019-09-20 Version 2.20: 2019-09-14 Version 2.19: 2019-09-10 Version 2.18: 2019-08-18 Version 2.17: 2019-08-16 Version 2.16: 2019-08-10 Version 2.15: 2019-08-07 Version 2.14: 2019-08-05 Version 2.13: 2019-08-05 Version 2.12: 2019-08-05 Version 2.11: 2019-08-04 Version 2.10: 2019-08-03 Version 2.09: 2019-07-27 Version 2.08: 2019-07-19 Version 2.07: 2019-07-14 Version 2.06: 2019-07-11 Version 2.05: 2019-07-10 Version 2.04: 2019-07-06 Version 2.03: 2019-07-03 Version 2.02: 2019-06-20 Version 2.01: 2019-06-10 Version 2.00: 2019-05-27 Version 1.94: 2019-05-13 Version 1.93: 2019-05-10 Version 1.92: 2019-05-09 Version 1.91: 2019-04-24 Version 1.90: 2019-03-31 Version 1.89: 2019-03-15 Version 1.88: 2019-01-20 Version 1.87: 2018-12-25 Version 1.86: 2018-12-23 Version 1.85: 2018-12-17 Version 1.84: 2018-12-11 Version 1.83: 2018-12-10 Version 1.82: 2018-12-03 Version 1.81: 2018-12-01 Version 1.80: 2018-11-24 Version 1.79: 2018-11-23 Version 1.78: 2018-11-21 Version 1.77: 2018-11-04 Version 1.76: 2018-10-08 Version 1.75: 2018-10-05 Version 1.74: 2018-09-29 Version 1.73: 2018-09-28 Version 1.72: 2018-09-25 Version 1.71: 2018-09-23 Version 1.70: 2018-09-22 Version 1.69: 2018-09-19 Version 1.68: 2018-09-17 Version 1.67: 2018-09-15 Version 1.66: 2018-09-12 Version 1.65: 2018-09-09 Version 1.64: 2018-09-06 Version 1.63: 2018-09-04 Version 1.62: 2018-09-02 Version 1.61: 2018-09-01 Version 1.60: 2018-08-25 Version 1.59: 2018-08-22 Version 1.58: 2018-08-19 Version 1.57: 2018-08-19 Version 1.56: 2018-08-19 Version 1.55: 2018-08-16 Version 1.54: 2018-06-30 Version 1.53: 2018-06-19 Version 1.52: 2018-06-03 Version 1.51: 2018-06-01 Version 1.50: 2018-05-29 Version 1.49: 2018-05-13 Version 1.48: 2018-05-12 Version 1.47: 2018-05-05 Version 1.46: 2018-05-01 Version 1.45: 2018-04-29 Version 1.44: 2018-04-27 Version 1.43: 2018-04-20 Version 1.42: 2018-04-10 Version 1.41: 2018-03-25 Version 1.40: 2018-03-18 Version 1.39: 2018-02-17 Version 1.38: 2018-02-10 Version 1.37: 2018-02-04 Version 1.36: 2018-01-24 Version 1.35: 2018-01-19 Version 1.34: 2018-01-10 Version 1.33: 2017-12-30 Version 1.32: 2017-12-08 Version 1.31: 2017-11-26 Version 1.30: 2017-11-25 Version 1.29: 2017-11-17 Version 1.28: 2017-11-10 Version 1.27: 2017-10-19 Version 1.26: 2017-10-05 Version 1.25: 2017-10-04 Version 1.24: 2017-10-02 Version 1.23: 2017-09-30 Version 1.22: 2017-09-30 Version 1.21: 2017-09-23 Version 1.20: 2017-09-21 Version 1.19: 2017-09-20 Version 1.18: 2017-09-19 Version 1.17: 2017-09-17 Version 1.16: 2017-08-20

How do I build the ESP8266 software?

See the ESP8266 Notes tab.

How do I build the Desktop software?

See the Desktop tab.

How do I uninstall HamClock?

Assuming you only ever installed HamClock according to my instructions in the Desktop tab, you can remove all traces by typing the following two commands in a terminal or ssh session:

    sudo sh -c 'rm -fr ~/.hamclock ~/ESPHamClock* /usr/local/bin/hamclock*'
    rm -fr ~/.hamclock ~/ESPHamClock*

I'm new to Raspberry Pi -- how do I get started?

  1. Buy a microSD card such as this one
  2. Insert the microSD card into your computer
  3. Download and install the Raspberry Pi Imager
  4. Start the program and burn your microSD card with RPi operating system as follows:
    1. click Choose OS
    2. select the first choice on top
    3. click Choose Storage
    4. select the microSD you just inserted
    5. click Write
    6. wait for it to complete writing and verifying
    7. remove the microSD card when it says it is finished
  5. Insert the microSD card into your RPi
  6. Connect a keyboard, mouse, ethernet and HDMI monitor to your RPi
  7. Connect power to the RPi
  8. After a minute or so you will see the Desktop
  9. Work through the setup menus
  10. Start a browser by clicking the red raspberry in the upper left corner then Internet ⇒ Chromium
  11. Go to my project web page at
  12. Start a terminal by clicking the red raspberry again then Accessories ⇒ Terminal
  13. Follow the instructions on my Desktop tab
  14. Read the User Guide to get the most from HamClock

I'm getting a big black screen on my RPi with a cryptic message, what do I do?

It depends on the message.

  • If it says there is a permission error related to a certain file, look at the permissions of the file, and each directory leading up to it, and make changes as necessary so the effective user id of hamclock has sufficient authority to access the file.

    Or just start all over. See the separate FAQ about removing HamClock. Then go over to the Desktop tab and follow the instructions.

  • The message is sh: 0: illegal option -p ?

    This happened in Version 2.58 on RPi if you are not running Buster. It is now fixed so the easiest solution is to remove your current ESPHamClock (see separate FAQ) and install fresh using the instructions in the Desktop tab.

    And while you're at it, if you are using the fb0 version, change to the GUI version, again see instructions and the other FAQ here about fb0 for details.

  • Something else?

    Copy it down exactly and email it to me.

Can HamClock run on Windows?

No, it can not run natively on Windows but it can display on Windows by using an X Server. The idea is to run the HamClock program on a UNIX-like system, such as an RPi or WSL (Windows Subsystem for Linux) then run HamClock in such a way that it displays on the X Server running on Windows.

For example:

  • I downloaded and installed VcXsrv on an old XP system I have here.
  • I ran the installer which places a shortcut on the desktop named XLaunch
  • I double clicked XLaunch and I accepted all defaults except I set Display Number 1 and I disabled access control for now.
  • Then on an RPi on the same network, I built HamClock and ran it as follows:
        make -j 4 hamclock-800x480
        sudo make install
        export DISPLAY=""
  • whence HamClock immediately appeared on the Windows machine and worked fine

Note in the example above, is the IP of the Windows machine, so change that to match your system configuration. Also note the ":1" of the DISPLAY environment variable. That says to use X Server display 1, which corresponds to the selection I made while running XLaunch. If you find it won't connect, it might be due to your Windows firewall. X Window servers listen on port 6000 + display_number, so in this case be sure Windows is allowing incoming connections on port 6001.

Also see the User Contrib pane for a suggestion on how to use WSL.

Can HamClock run on iPhone or iPad?

Similar answer as previous FAQ but you'll need an X server app for iPad. I find Mocha X11 works well.

How does HamClock compare to Geochron 4k?

I do not have a Geochron 4K but from its literature I can think of the following functions related to ham radio that HamClock offers but Geochron does not:

  1. VOACAP propagation predictions for any HF band or path at several power levels
  2. trend 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 DE time in digital, analog or calendar formats
  6. azimuthal world maps centered on any location
  7. local weather, time, grid square, prefix and sun rise/set times at any DX location
  8. live scrolling DX cluster display
  9. live display of WSJT-X and JTDX FT8 contacts
  10. live solar images from Solar Dynamics Observatory
  11. live quantitative Moon info useful for EME
  12. live NCDXF beacon location, time and frequency schedule
  13. live RSS feeds from popular ham web sites
  14. live D layer absorption map
  15. stopwatch and station ID count down timer with optional color LED and switch control
  16. adjust time forward or back to explore Moon, gray line, satellite orbits etc
  17. Elecraft KX3 transceiver frequency control from DX Cluster spot
  18. BME280 sensor for temperature, pressure and humidity real-time and 25 hour trend plots
  19. photosensor to adjust display brightness with changes in room lighting
  20. "On The Air" indicator controlled by GPIO pin from radio
  21. remote control functions from any browser or curl command line
  22. can become just a simple old fashioned time-and-temperature clock

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, population and pandemic maps

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

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 pane until the DX Cluster page 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. The tap can also set the frequency of an Elecraft KX3, see the User Guide for details.
  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 and 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 a second time simultaneously from a different application or telnet session. You should use the same call but add an SSID suffix like "-1" so the spider software won't detect a duplicate and disconnect HamClock. Now from this second connection, make the desired settings and most nodes will carry them over to all login sessions, including the HamClock session. 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
  6. The same mechanism can communicate with WSJT-X or JTDX. Instead of showing cluster spots, it shows each FT8 station you attempt to work and also immediately loads DX with its location. Details for doing this are in the User Guide.

Can I make different sizes other than those in the Makefile?

No, it's not that simple. Each size requires its own custom fonts, graphics symbols, maps and images in order to take proper advantage of the different resolutions. Otherwise, these would be very pixelated 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.

What is xrandr, or How do I get rid of the full-screen black border?

Even though full screen mode uses the entire screen, HamClock still only uses the pixels specified in the make command size, filling the remaining space with black. With the GUI configuration (not fb0) you can try a command line program called xrandr to expand HamClock to fill the screen by changing the effective display resolution to match HamClock.

Xrandr works by changing how the X server maps pixels to the display hardware. It's easy to try and undo if you decide you don't like it.

For example, my display is 1920 x 1080. The closest I can build HamClock is 1600 x 960. If I run this size with the Full screen option in setup set to Yes, HamClock will still be that size but will fill the surrounding gaps with black. With xrandr one can expand HamClock to fill the screen and eliminate those gaps.

To try it, log in with ssh so we aren't trying to adjust the same screen we are using for commands. Run the following command while HamClock is running in its full screen mode:

        xrandr --output HDMI-1 --scale-from 1600x960 --display :0

(it's better to think of that argument as meaning scale-to)

That's it, the effect should be immediate but ...

  • If xrandr gives an error about failing to get size of gamma, check the GL driver is installed with sudo raspi-config as:

    Advanced Options ⇒ GL driver ⇒ OpenGL with fake KMS ⇒ Ok ⇒ Ok ⇒ Finish ⇒ Reboot now

  • If xrandr gives an error about bad parameter match, try changing scale-from a little.
  • If you want to go back to normal run
        xrandr --output HDMI-1 --scale-from 1920x1080 --display :0

Modify these values to accommodate your particular combination of HamClock and display sizes as needed.

The display aspect change is accomplished using non-square pixels within the X server. This doesn't usually matter much but if you often run analog Big Clock you may notice it is no longer circular. Adjust the xrandr dimensions to find a compromise between filling the screen and making the circle look nice.

The xrandr changes do not survive logging out or rebooting. If you want the resolution change to happen automatically every time you start your GUI, put the xrandr command in the file ~/.xsessionrc. Combine this with using autostart (see Desktop instructions) and you can arrange for HamClock to start automatically at truly full screen size directly from RPi power up.

One final point for the RPi. If you still have a small black border, you may have video underscan compensation turned on. To turn it off run sudo raspi-config then work through

Display Options ⇒ Underscan ⇒ enable? ⇒ No ⇒ Ok ⇒ Finish

and run sudo reboot if it doesn't ask you to reboot on the way out.

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 would 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.

Does the HamClock have a web interface?

Yes, but it's not for interactive use as you might expect, it provides a simple means of connecting with HamClock over a network. HamClock listens on port 8080 for http connections from a browser or command line tools such as curl or wget. Using a RESTful command interface, HamClock can be controlled, queried and the screen can be captured as an image file.

To try the following examples, you will need a computer on the same network as your HamClock. Here we will use curl but the same URLs will work in your browser as well (although some browsers are getting more cautious about accessing a web site with http and you may be asked once to trust the site).

Start by querying HamClock for a list of all its commands as follows: (actually any unrecognized command will produce this help text)

        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. Do not include these when using a browser.

The output will be a list of all supported commands as follows:

Syntax Summary
get_capture.bmp Save screen as bmp file
get_config.txt Report current HamClock configuration settings
get_de.txt Report DE info
get_dx.txt Report DX info
get_dxspots.txt Report current list of DX cluster spots
get_satellite.txt Report current satellite position, if one is defined
get_sensors.txt Generate list of BME280 sensor values, if attached
get_spacewx.txt Get last-known pane data and age
get_stopwatch.txt Report stopwatch state and timer value
get_sys.txt Report some basic HamClock system information
get_time.txt Report HamClock's idea of UTC
set_displayOnOff?on|off Turn display on or off
set_displayTimes?on=HR:MN&off=HR:MN&day=DOW&idle=mins Set display on and off DE times for the specified day, or today if not specified.
DOW is Sun..Sat. Optionally set display idle time (not saved on per-day basis).
set_mapview?Style=S&Grid=G&Projection=P&RSS=on|off&Night=on|off Change 1 or more map settings. S, G and P must match View menu text exactly.
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&lng=Y Define a new DX location using latitude/longitude
set_newdxgrid?AB12 Define a new DX location using its maidenhead grid square
set_pane?Pane[123]=one of ...

VOACAP, DE_Wx, DX_Cluster, DX_Wx, Solar_Flux, Planetary_K,
Moon, Space_Wx, Sunspot_N, X-Ray, Gimbal, ENV_Temp,
ENV_Press, ENV_Humid, ENV_DewPt, SDO_Comp, SDO_6173A,
SDO_Magneto, SDO_193A, Solar_Wind, DRAP, rotate

Set the specified plot pane content, if allowed.
set_satname?abc|none Select satellite from built-in list, or none
set_sattle?name=abc&t1=line1&t2=line2 Define a satellite using TLE values
set_stopwatch?reset|run|stop|lap|countdown=mins Stopwatch commands
set_time?ISO=YYYY-MM-DDTHH:MM:SS Set UTC to the given time
set_time?Now Set UTC to current time from NTP or gpsd
set_time?UNIX=secs_since_1970 Set UTC to the given UNIX time
set_title?msg=my message&fg=R,G,B&bg=R,G,B|rainbow Set call text to msg with fg and bg 0-255 RGB colors; missing args are
left unchanged; changes are not persistent and do not effect real call;
restores all default settings if no args
set_touch?x=X&y=Y&hold=0|1 Virtually touch, or hold, screen coordinate X, Y; scaled to 800 x 480
set_voacap?band=80-10|off Set VOACAP map band, or restore default background
restart Restart HamClock
updateVersion Check for new version and update if found
exit tells HamClock to exit (not on ESP)
any command not recognized Show this help


Get the current clock UTC time:

        curl ''

Set display to turn on Wednesday at 8 AM and off at 10 PM, DE time, with 10 minutes idle time:

        curl ''

Set a new DE location from latitude and longitude:

        curl ''

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

        curl '' > hcscreen.bmp

Set satellite to ISS and report current ephemeris with respect to DE:

        curl ''

Set Pane 3 to show NOAA Space weather:

        curl '

Toggle the screen lock padlock:

        curl ''

Change call sign to say ON AIR white on red:

        curl ' AIR&fg=255,255,255&bg=255,0,0'

... then restore call sign:

        curl ''

Change map to Azimuthal projection with Countries style and RSS on, leaving Grid unchanged:

        curl ''

Why is my grid square wrong?

Probably because you are very near a grid boundary and you need to enter more precision in Setup for your latitude and longitude. For more discussion on this topic, see the User Guide section on Maidenhead grid squares.

What is the HamClock diagnostic output?

It is additional detailed status and diagnostic information HamClock writes to the file ~/.hamclock/diagnostic-log.txt. It is not intended for general consumption but contains lots of good info for troubleshooting. You may be asked to email me this file if you submit a request for help.

The previous 3 logs are also stored in a rolling set with the following names:


If preferred, the diagnostics information can be written to stdout by invoking HamClock as follows:

        hamclock -o

What is sudo and set-uid and why should I use them with HamClock, or not?

Sudo stands for "super-user do". In UNIX, the super user refers to extra privileges bestowed upon the root user. Rather than actually logging out and logging back in as user root to gain these privileges, this command arranges for you to have these greater privileges just long enough to run the command that follows on the same line. After that command completes, you are again restricted back to the normal privileges of your current user login.

Another effect of the sudo command is to temporarily change the HOME directory to /root. HamClock creates and uses a working directory named .hamclock (note the leading dot) in the HOME directory. HOME for the normal pi user is /home/pi. Thus, if you run HamClock without sudo it uses /home/pi/.hamclock but if you run it with sudo it uses /root/.hamclock and files therein are not accessible to the normal pi user. This duality can cause much confusion so beware.

set-uid refers to an automatic mechanism engaged by setting the mode of a program file in such a way that when the process runs, it has the same permissions as the owner of the file. Normally, the process has the permissions of the user running the file. Thus by making the program file owned by root, it has super-user privileges no matter what user runs it. Using this mechanism for HamClock allows it to have super-user privileges without using sudo. Unlike sudo, using set-uid does not change HOME, so HamClock will still use your /home/pi/.hamclock directory for its support files, although they will still be owned by root when they are created.

The reason to escalate privileges with either of these methods in the first place is that HamClock requires super-user privileges to perform certain external IO and protected file system operations. It is possible in some configrations for someone with sufficient UNIX administrative knowledge to make adjustments so HamClock can run without super-user privileges, but this is beyond what most users want to deal with. So in the interest of providing the simplest and most enjoyable experience possible for the majority of users, the install instructions use set-uid root.

For those still interested in eliminating the need for root privileges, run the following commands on RPi. They perform the following functions:

  1. add user pi to various groups to allow necessary IO access
  2. remove the set-uid bit from the executable file
  3. change the group ownership of /usr/local/bin to user pi
  4. allow any user in group pi (specifically user pi) to modify /usr/local/bin
    sudo usermod --append --groups video,input,gpio,i2c pi
    sudo chmod u-s /usr/local/bin/hamclock
    sudo chgrp pi /usr/local/bin
    sudo chmod g+w /usr/local/bin

The last two steps are required so automatic updates may write a new version of the executable file in /usr/local/bin.

After executing these commands, subsequent instances of hamclock will no longer run as root but should be able to perform all functions.

Note that if you perform the install step again in the future sudo make install this will set the set-uid bit again so remember to perform command 2 again.

Is it possible to change the RSS feeds?

No. RSS feed formats are surprisingly inconsistent so I perform all the heavy lifting on my server and only send the plain titles to the HamClock. Plus, most now use https which uses too much memory for the little ESP processor.

That said, if you have a feed in mind that is of general interest to the global ham community, send me your suggestion and I will consider adding it to the server processing.

Is it possible to change the set of satellites?

No. The list is maintained on my server which performs all the heavy lifting of discovery and updating, sending only the TLEs to the HamClock.

That said, if you have a satellite in mind that is of general interest to the global ham community, send me your suggestion and I will consider adding it to the server list.

How are the background maps managed?

As of Version 2.52, the background map images are downloaded and stored as local files as needed. In previous versions they were embedded within the executable image and were thus immutable and limited by size of non-volatile memory.

This meant the ESP HamClocks could only ever support one map style, and even that was only at half the available screen resolution. ESP HamClocks now use the extended FLASH file system to store the map images at full resolution. The improved resolution is especially apparent in the night portion of the Terrain style map. Unfortunately, more pixels and slower FLASH access means the display update rate on the ESP is about 30% slower now but the added flexibility and visual results seem worth it.

The UNIX versions of HamClock store their map files in ~/.hamclock so the number of files is limied only by available disk space.

If you run HamClock without a network connection, you will be limited to map styles already downloaded.

The maps are stored in .bmp format, version 4, using 16 bit RG565 pixels. There are separate files for day and night for each map style. HamClock uses these to render the day and night regions and blends them in a 12° band to simulate civil twilight.

How does the self-update facility work?

When asked to update itself, HamClock checks the support server if there is a newer version available. If so, for the ESP systems this is a binary file that is downloaded directly into FLASH and that's all there is to it.

But for the Desktop UNIX systems, this is a zip file containing the source code that requires many more steps:

  1. the zip is downloaded into a unique directory within /tmp
  2. it is exploded with unzip which creates the source tree
  3. make is run within the source tree, using the same target that was used to build the currently running program
  4. the resulting program file effectly overwrites the currently running program file.

These steps present two challenges: how to find the full path of the program file to a running program and how to update its program file while it is still running.

To find the program file full path, HamClock first checks the argv[0] path given when it was executed, digging through symlinks if necessary to find the real program file. If this is already a full path, indicated by beginning with a slash (/), we are done. If not, then a test is made whether a file with that name exists with respect to the current working directory of HamClock. If so, we are done. If it still is not found, then the argv[0] name is checked for in each of the directories named in the PATH environment variable. If still not found, the update fails.

To update the program file, we have to deal with the fact that it is not possible on UNIX to modify the program file of a running program (even as root). So instead, HamClock does it indirectly by first removing the program file then copying in the new one created by make so it has the same name. To remove the current program file, HamClock requires write permission on its containing directory because removing a file actually just edits it out of its containing directory. If HamClock does not have this permission, the update fails. Copying in the new file then edits the same name back into the same directory, so it looks like it was overwritten when actually it was deleted and added again. Meanwhile, HamClock can continue to run because a deleted file still actually exists in memory until the last process with it open either closes it or exits, even if it is not named by any directory.

How do I use the Bosch BME280 environment sensor on RPi?

On the Raspberry Pi running linux, proceed as follows:

  1. connect the sensor to the RPi using the 40 pin connector as follows:

    BME label RPi Header pin
    Vin 1
    SDI 3
    SCK 5
    GND 9

  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 different numbers, not just all XX
  5. Start HamClock. Enter Setup, go to Page 2, tap GPIO so it says Active. Also select whether you want metric or imperial units. For now leave the delta values set to zero. Click Done.
  6. After HamClock is up and running again, tap any pane and select one of the ENV plots.
  7. If you have some means of measuring temperature and pressure independent of the BME280, note the errors, restart HamClock and enter the corrections in page 2 of Setup.
  8. Finally, you may add a second BME280 as shown in the following schematic. Note that each has a different I2C bus address depending on whether SDO is grounded.

On a Raspberry Pi running FreeBSD 13.0-RELEASE, proceed as follows:

  1. Connect the hardware the same as above
  2. Test by running sudo i2c -s which should immediately report the device address(es).
  3. Edit /boot/msdos/config.txt to add the following line to the [all] section then reboot and try HamClock.

How long can the cable be?

I have used a direct connection of ten feet without any problem. I have also successfully used 100 feet of Cat 5 using a pair of these extenders from Sparkfun.

How do I exit HamClock?

Click and hold the padlock for 3 seconds, then select Exit.

What happened to fb0?

Nothing, it's still supported for legacy users, but now that the GUI version can display full screen it is no longer recommended for new installations.

For those new to HamClock who may not know about fb0, it was an early attempt to provide a full screen experience by turning off the GUI and accessing the RPi video frame buffer directly. This was accessed through the special file /dev/fb0, and hence the name. This allowed HamClock to fullfill its charter purpose on RPi of being a stand-alone appliance for ham radio information. Although successful, it required a lot of special programming and could be a challenge for users to install. It is now replaced by using atoms to accomplish the same full screen functionality with the normal GUI.

My question is not here and I can not find the answer after studying everything on this site, where can I get help?

Send a polite note to me at

All contributed scripts referred to below are available in this zip file

Tips for Executing and Displaying HamClock on Windows 10

Contributed by Joeri van Dooren, ON3URE

  1. In windows download
  2. Install; choose single windows
  3. In Windows install WSL2 with ubuntu.
  4. Start wsl.exe
  5. sudo apt update
  6. sudo apt -y install g++ libx11-dev wget
  7. wget
  8. unzip
  9. cd ESPHamClock
  10. make hamclock-800x400
  11. sudo make install
  12. export DISPLAY=:0
  13. hamclock

Automating qrz page from spots

Contributed by Hans Klausmann, DL5RAZ


Script to simplify sending web commands from command line

Script by Barry, N0NZ

Documentation here.


Script to read and write the eeprom config file

Contributed by Elwood Downey,

Someone asked if they could edit the eeprom config file. Normally no, but since I enjoy writing perl, I couldn't resist writing to do exactly that. You can download it within the contrib collection here.

Save the script anywhere in your PATH and make it executable as usual. Cd into the ESPHamClock source directory to run it. This location is required because the script needs to read the HamClock.h and nvram.cpp source files to find the symbolic names, lengths and descriptions of the various parameters saved in eeprom. The script assumes the eeprom file itself is located in ~/.hamclock/eeprom. The type of the parameter is not saved in the eeprom file, so the script also needs to know the data type, which you must include on the command line using i for integral, f for float or s for string. Run the script with no args or --help for a usage summary.

Note well: you are hacking a file not intended for human consumption, so you can easily mess things up. There's no validation checking whatsoever, so you could go right ahead and set preposperous values such as a longitude of 10000 or inconsistent values such as a lat/long that doesn't match the grid square sending HamClock into unexplored territory. Save a copy of eeprom before starting, or remove it and HamClock will build a new one when it starts containing all defaults. Never edit the file while HamClock is running because HamClock often updates it, but only reads it once when starting up. You have been warned.

No matter, let's try it! Here are some examples:

Read the call sign: NV_CALLSIGN s

Set a new call sign: NV_CALLSIGN s AB1XYZ

Set the DX cluster host: NV_DXHOST s
        NV_DXHOST =

Set DX spots to show as full call sign NV_MAPSPOTS i 2
        NV_MAPSPOTS = 2

Set the BME280 at I2C address 77 temperature correction: NV_TEMPCORR2 f -0.23
        NV_TEMPCORR2 = -0.23

Here's the script:


Script to automatically rotate pane contents

Contributed by Chris Myers, AF6RF

Note for macOS users: POSIX sed has no -i but you can accomplish those lines with perl such as:

        perl -i -p -e "/#will be incremented$/ and s/p1=\d+/p1=$p1_next/" ${0}


Script to query for any space weather datum

Contributed by Elwood Downey,


Instructions for macOS dual screen

Contributed by AL7CR.

These settings allow a full screen Hamclock with no menu or borders on one display and a fully useable Mac desktop on the other. Tested on XQuartx 2.7.11 under High Sierra 10.13.6. The steps are:

  1. Set "Displays have separate spaces" otherwise running HamClock will cause the second screen to be black whether or not it is set to full screen mode.
  2. Set "Assign to Display" to the desired display. This is done by right clicking the XQuartz icon in the dock and selecting the desired display. This option only appears if you have multiple displays.
  3. Autohide Dock and Menubar as for a single screen. Note that this setting is system wide and not per screen as you might expect.
  4. And the key point, in XQuartz preferences disable full screen mode. If this is not done Hamclock will disappear when it's window loses the system focus. Command-Option-A will make it reappear however you will not be able to work in one screen with Hamclock in the other unless XQuartz full screen is disabled.

Building the ESP8266 software

  1. Install the Arduino IDE from here. I am currently using version 1.8.13.
  2. Open Preferences. In the field labeled Additional Boards Manager URLs copy/paste the following line then click Ok:
  3. Open Tools → Boards → Boards Manager
  4. Search for "esp8266"
  5. Select version 2.7.4 then click Install.
  6. Open Tools → Manage Libraries, set Type and Topic to All, then search for and install the following libraries:
    • Adafruit GFX (all), version 1.10.2
    • Adafruit Unified Sensor, version 1.1.4
    • Adafruit BME280, version 2.1.1
    • Adafruit RA8875 (only), version 1.4.0
    • Time, version 1.6.0

    Other versions might work but these are the versions I am using now.

  7. Quit and reopen the Arduino IDE
  8. Connect your computer to the Huzzah with a USB port
  9. Open Tools → Board → ESP8266 Boards and select Adafruit Feather Huzzah ESP8266
  10. Download current stable HamClock release here. Unzip it anywhere you wish, but probably best to use the default sketch folder.
  11. Use File → Open and find the ESPHamClock.ino file you just unzipped. This will create a new project.
  12. In the IDE Tools menu make the following selections (click for larger view):


    Set the port to match the USB connection of your Huzzah.

  13. Run Sketch → Verify/Compile then Sketch → Upload
  14. Your HamClock should start running. Read the User Guide and have fun.

Using the 9" display

To use a 9" ER-TFTM090-2 from

Select these options during purchase:

  • Pin header 4 wire SPI
  • VDD 5 V
  • Touch panel 9" resistive
  • Micro SD - none
  • Font chip - none

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


  • Larger, brighter, richer colors
  • Simpler wiring because you do not need the RA8875 or flat cable


  • Requires a very good USB supply, at least 2 A. This one from Adafruit is known to work well.

Stand ideas

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.

  • One alternative I found is this video that suggests normal picture framing components could be used.
  • The stand from Adafruit is actually made by Pimoroni so I asked them for better suggestions. They said they know of no stand suitable for the Adafruit LCD but thought this one might be pressed into service with less effort.
  • G3XOU used this RPi screen support with some assembly details here .
  • KF5LW suggests adopting this RPi screen support. He said he 3D-printed a piece to the RPi dimensions then it worked well.
  • W3TMC sent a photo of the nice looking oak stand he built.
  • N2YTF did a nice job with some simple wood and a breadboard. He sent photos here and here.
  • N6ROB attached the components and display to the stand with hot glue after sanding and wiping down with alcohol. The result looks clean and efficient.
  • N7EEK has taken a minimalist approach that works well using a $9 stand from Amazon. See his photos here.
  • ON4AEY made a nice clock and sent me this link to share.
  • N7LVS made this YouTube video showing his construction technique.
  • HB9AJG shared his very nice arrangement from the front, back and in his shack.
  • WA1TOV put his in a clear frame he found here. He comments: The back of the display is glued to the face of the frame. You might be able to see round glue dots in the rear view photos. I used E6000 glue. To do this I had to cut a 1.5" slot in the frame to feed the ribbon through. This was done with a Dremel and cut off wheel, just working very carefully and then cleaning it up with a jeweler's file. Photos: front, side and rear.

If you find your display idea works better when 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

HamClock would not be possible without the following resources (listed in no particular order):

And big Shoutouts to Adafruit and Raspberry Pi Foundation for great products and support.

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

HamClock was originally developed for the ESP8266 such as the Adafruit Huzzah. But after I created a porting layer, it may now also be built for Raspberry Pi, macOS, Ubuntu, FreeBSD, Windows WSL or most any other UNIX-like system supporting the X11 Windows system.

Instructions are below, but first a few preliminaries:

To install HamClock follow these steps:

  1. Open a terminal directly on the target system GUI desktop to get a command line prompt.

    Do not use ssh unless you know what ssh -X means.

  2. Run these commands (use copy/paste to avoid typos):
    cd ~
    rm -fr ESPHamClock
    curl -O
    cd ESPHamClock
    make -j 4 hamclock-800x480
    sudo make install
  3. Now run HamClock by typing:
    hamclock &
  4. Be sure to read the User Guide to get the most from HamClock!
  5. To exit hamclock, click and hold the padlock icon for three seconds, then choose Exit.
  6. If you get build errors during make:
    • on RPi try loading these packages:
      sudo apt-get -y install make g++ libx11-dev xserver-xorg raspberrypi-ui-mods lightdm lxsession
      If still trouble, note I only test on the latest desktop release of Raspberry Pi OS so if you are running something older it might help to upgrade.
    • on Ubuntu try loading these packages:
      sudo apt install curl make g++ xorg-dev
    • on macOS try installing XQuartz and Xcode. Then run
    • xcode-select --install
    • on FreeBSD try loading these packages:
      sudo pkg install gcc libX11 gmake curl
      then use gmake instead of make.
    • on Fedora 34 try loading these packages:
      sudo yum install gcc-c++ libX11-devel
      Regardless, in their infinite wisdom Wayland does not support xrandr -- it's called progress.
  7. The example make command above will build HamClock with 800x480 pixels. You can also make these sizes:
    • hamclock-1600x960
    • hamclock-2400xx1440
    • hamclock-3200x1920
    If you do, redo both make commands again, for example:
    cd ~/ESPHamClock
    make -j 4 hamclock-1600x960
    sudo make install
  8. If you would like HamClock to fill the screen, set that option on Page 4 of Setup. With this option HamClock will still be the same screen size you built, but it will fill any surrounding gap with black so there is nothing else showing. If you really want HamClock to use all available screen space, see the FAQ about making different sizes with xrandr.

    Note that if never run previously, HamClock will automatically set the full screen option if the display size is the same as the size specified in the make command.

  9. If you would like a Desktop icon with which to start HamClock on RPi, try these commands:
    cd ~/ESPHamClock
    mkdir -p ~/.hamclock
    cp hamclock.png ~/.hamclock
    cp hamclock.desktop ~/Desktop
  10. If you would like HamClock to start automatically when you boot your RPi, try these commands:

    cd ~/ESPHamClock
    mkdir -p ~/.config/autostart
    cp hamclock.desktop ~/.config/autostart
  11. On macOS, you can turn the bare executable into a clickable App on your Desktop as follows:
    cd ~/ESPHamClock
    mkdir -p $HCDIR
    echo '#!/bin/bash' > $HCDIR/HamClock
    echo '/usr/local/bin/hamclock &' >> $HCDIR/HamClock
    chmod u+x $HCDIR/HamClock

    To give it a proper icon:

    1. open hamclock.png with Preview
    2. click on the image
    3. type ⌘-A to select the image
    4. type ⌘-C to copy the image to the clipboard
    5. right-click the new Desktop item and select Get Info
    6. click the existing default icon in the upper left corner
    7. type ⌘-V to paste a new icon
    8. close Get Info
    9. close Preview

    To put it in the Dock:

    1. edit the script and temporarily remove the trailing & (dock icons bounce until the parent process exits)
    2. double-click to launch
    3. while it's bouncing in the dock, right-click and select Options → Keep in Dock
    4. exit HamClock
    5. remember to put back the &

    For a little more decorum, create a bona fide app using Platypus. I tried it briefly on Big Sur and found it easy to use and worked well. Use the same 2-line script as above but without the & so Platypus can properly inform the OS when you exit HamClock.

This site does not use cookies.