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

Ham Clock

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. HamClock was introduced in my QST article in the October 2017 issue and has been actively developed and expanded ever since.

For quick start on Raspberry Pi or other UNIX-like operating systems see the Desktop tab below. The User Guide tab provides detailed operating instructions. Explore the additional tabs for further supporting information.

73, Elwood Downey, WBØOEW

News highlights: See the complete version history in the Download tab and details in the User Guide.
  • Load ADIF files for listing and mapping
  • Show world map of DE Take-Off-Angle from any location
  • Mollweide equal-area world map projection
  • Show solar magnetosphere Bz and Bt
  • Live POTA, SOTA, RBN, WSPR and PSKReporter maps
  • Now manufactured by Veritium Research rebranded as HFClock. Available direct or in Europe from Lutz Electronics.

Original QST Article proof


Download current stable HamClock release source code as zip or tgz.

Revision history:

Version 3.01: 2023-10-14 Version 3.00: 2023-09-16 Version 2.99: never released Version 2.98: never released Version 2.97: 2023-08-08 Version 2.96: 2023-08-05 Version 2.95: 2023-07-08 Version 2.94: 2023-06-25 Version 2.93: 2023-06-09 Version 2.92: 2023-05-13 Version 2.91: 2023-04-09 Version 2.90: 2023-03-25 Version 2.89: 2023-02-25 Version 2.88: 2023-02-14 Version 2.87: 2023-02-02 Version 2.86: 2022-12-25 Version 2.85: 2022-10-21 Version 2.84: 2022-09-17 Version 2.83: 2022-09-04 Version 2.82: 2022-08-29 Version 2.81: 2022-08-27 Version 2.80: 2022-07-15 Version 2.79: 2022-06-18 Version 2.78: 2022-05-22 Version 2.77: 2022-04-17 Version 2.76: 2022-03-15 Version 2.75: 2022-03-12 Version 2.74: 2022-02-12 Version 2.73: 2022-01-15 Version 2.72: 2021-12-18 Version 2.71: 2021-12-11 Version 2.70: 2021-11-26 Version 2.69: 2021-10-16 Version 2.68: 2021-09-11 Version 2.67: 2021-09-06 Version 2.66: 2021-08-08 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* ~/.config/autostart/hamclock.desktop ~/Desktop/hamclock.desktop

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

  1. If you are absolutely completely new, start at
  2. If you don't have a Pi yet, I would start with a model 4b with 1 GB RAM. The smaller Pi models such as Zero W will work, but the 4b is definitely more responsive. Many places sell Pis or you can see the official list of vendors here. Pis are a little hard to find now but a current list of vendors with stock is here.
  3. For a display you can use a small touch screen such as the official Pi 7" LCD. Or you can use any HDMI LCD display you might have or buy one such as this one with which you will also need a keyboard, mouse and perhaps a micro HDMI adaptor.
  4. If you don't already have one, buy a microSD card such as this one.
  5. Insert the microSD card into your desktop computer. If your computer does not have uSD port, you can try a USB adaptor such as this one.
  6. Download and install the Raspberry Pi Imager.
  7. 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
  8. Insert the microSD card into your RPi
  9. Connect a keyboard, mouse, ethernet and display to your RPi
  10. Connect power to the RPi
  11. After a minute or so you will see the Desktop
  12. Work through the setup menus
  13. Start a browser by clicking the red raspberry in the upper left corner then Internet ⇒ Chromium
  14. Go to my project web page at
  15. Start a terminal by clicking the red raspberry again then Accessories ⇒ Terminal
  16. Follow the instructions on my Desktop tab
  17. Read the User Guide to get the most from HamClock

What can I do if a self-update reports FAIL with a message about SSL certificate?

This error means your system is using a version of openssl (used by curl) that is older than 1.1.1. This occurs because a prominent high level SSL certificate expired on Sept 30 2021 and openssl was updated to use the replacement certificate. You can find your version by opening a terminal command line and typing this command:

        openssl version

To update openssl on an RPi you can try

        sudo apt upgrade openssl

To update on macOS try these possibilities:

  • If you use macports update openssl as follows:
        sudo port upgrade openssl
    (be sure /opt/local/bin is before /usr/bin in your PATH)
  • or try this direct method (suggested by AL7CR):
    • Rename /etc/ssl/cert.pem to something else such as /etc/ssl/
    • Download the latest cacert.pem from
    • Rename it to cert.pem
    • Copy it to /etc/ssl/cert.pem

After the update, repeat the openssl command and you should see version 1.1.1 or larger. If so, repeat your HamClock version update and it should work.

HamClock is displaying a big black screen with a cryptic message, what do I do?

It depends on the message.

  • permission error
    The most likely cause is you ran hamclock previously with or without sudo and now you are running it the opposite way. When installed per the Desktop tab directions you should never run hamclock using sudo. It's possible to straighten it out but if you are unfamiliar with linux file system permissions it's probably easiest to just start all over. For that, see FAQ 3 about removing HamClock then go over to the Desktop tab and follow the instructions carefully.
  • Address already in use
    This means HamClock is unable to use a TCP networking port because another program is already using it. The message will include the particular port number at issue. You must either find this other program and stop it or tell HamClock to use a different port. It can also happen if you run more than one hamclock at the same time; see FAQ 43 for the proper way to do that.

    To find the other program using the port, suppose the offending port is 8080. Then either of the following commands should provide clues to the other program:

                    sudo lsof -i :8080
                    sudo netstat -tulpn | grep :8080
  • sh: 0: illegal option -p
    This happened in Version 2.58 on RPi if you are running an os version earilier than Buster. It is now fixed so the easiest solution is to remove your current ESPHamClock (see FAQ 3) and install fresh using the instructions in the Desktop tab.
  • No memory for satellite
    This only happens on the ESP because of its very limited amount of RAM. Restart then turn off some panes that can scroll lists such as Contests, POTA, SOTA and DX Cluster.
  • time is running backwards
    The cause is discussed below but for now just restart. But first, I would appreciate if you would email me the exact message containing the two time values.

    Trapping this event is new starting in version 3.00 of HamClock. Before then, I had indirect evidence of this from my server logs because when it occurs, HamClock suddenly thinks all content is out of date and floods my server with retries. I had to do something to prevent this so I added the strict time check.

    The root cause is because NTP uses UDP which does not guarantee packet delivery, order or absense of duplicates. Thus it's possible for a router somewhere to send an old packet resulting in stale NTP time values. Statistics I've collected here from google NTP show one backwards event about every 10^11 packets. That works out to about one bad packet every 2000 days. But since there are well over 2000 HamClocks running the world over, one of them is likely to experience this each day.

    After I gather more statistics I will try to make HamClock more tolerant to this. For now, thank you for your patience and cooperation.

  • Something else?

    Copy it down exactly and email it to me. Also, please attach the diagnostic file $HOME/.hamclock/diagnostic-log.txt.

Can HamClock run on Windows?

No, you can't run it natively on Windows but you can use it if it is already running somewhere else on your network by using any desktop browser. See FAQ 14 about the hamclock web interface for details.

For another approach, see the User Contrib tab for a suggestion on how to use WSL.

Can HamClock run on iPhone or iPad or Android?

No, you can't run it natively on an iPad but you can use it if it is already running somewhere else on your network by using your iPad's browser. See FAQ 14 about the hamclock web interface for details.

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. customized VOACAP predictions for MUF, TOA and path reliability
  2. trend plots and predictions for solar flux, solar wind, sunspot, XRay, Kp index and DRAP
  3. short and long path antenna beam heading and distance to any DX location
  4. display future satellite rise/set times and next overhead pass (not just global track)
  5. hamlib and flrig rig and rotator control for chasing DX spots
  6. display DE time in digital, analog or calendar formats
  7. list upcoming weekend contests
  8. azimuthal world maps centered on any location
  9. local weather, time, grid square, prefix and sun rise/set times at any DX location
  10. live display of DX Cluster, WSJT-X and JTDX FT8 contacts
  11. live solar images from Solar Dynamics Observatory and STEREO-A
  12. live quantitative Lunar data and EME planning tool
  13. live NCDXF beacon location, time and frequency schedule
  14. live RSS feeds from popular ham web sites
  15. live listing of POTA and SOTA activators
  16. live D layer absorption map
  17. live auroral map
  18. several map projections including Azimuthal, Mercator and Mollweide
  19. Display headings from either true north or magnetic north
  20. Optional time scales including sidereal, Julian date and UNIX
  21. stopwatch and station ID count-down timer with optional color LED and switch control
  22. adjust time forward or back to explore Moon, gray line, satellite orbits etc
  23. Elecraft KX3 transceiver frequency control from DX Cluster spot
  24. 2 BME280 sensors for temperature, pressure and humidity real-time and 25 hour trend plots
  25. Personalized WSPR, PSKReporter and RBN spot maps
  26. photosensor to adjust display brightness with changes in room lighting
  27. "On The Air" indicator controlled by GPIO pin from radio
  28. RESTful API remote control functions from any browser or curl command line
  29. can display on and be controlled from any web browser
  30. 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

I have nothing against Geochron. 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 Setup page 2, 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 because AR and CC clusters are not supported for now. You may also enter a login different from your call, such as an SSID like WB0OEW-1. In Setup page 5 you can control whether spots are labeled on the map as complete call signs or just the prefix and whether and how the full path is drawn. Note that only the DX side is labeled since it rarely matters who exactly made the spot, just where.
  2. You can also enter up to four arbitrary spider commands. A nice filter primer is here. Those commands that are set On will be sent one time when HamClock logs into the node. HamClock will store all the commands for you, whether they or set On or Off.
  3. It is important to understand that spider commands are saved on the node and remain in effect even if you log out and log back in. It is not enough to just not send them to get the opposite effect. For example, suppose you want to reject all spots of US amateurs, you could enter this command and set it On:
        rej/spot 0 call_dxcc 226
    Because it is marked On HamClock will send this command when it logs in. Now suppose you restart HamClock and just turn this command Off. This tells HamClock to not send this command when it logs in. That's fine, but since spider remembers your settings across logins, the filter will still remain in effect! To turn off this filter, you need another command to explicitly clear it, such as
        clear/spot 0
    Thus, it's a good idea to create pairs of spider commands, one to engage and one to cancel each filter type.
  4. Once HamClock is up and running, select the DX Cluster pane in either of the two right panes. The name of the host will be shown in yellow while a connection attempt is in progress, then it will turn green when the connection is established. If the connection fails, it will show an error in red.
  5. Once connected, just leave it run, new spots will be listed, scrolling down when full. Tap on a spot to set HamClock's DX to that location. The tap can also set the frequency of your radio, see the User Guide for details.
  6. HamClock stores several more spots than those listed; use the Up and Down arrows to scroll backwards and forwards through time. HamClock always adds new spots to the end of the list, but if you have scrolled Up HamClock will not automatically scroll down to show them. To ensure you will see new spots immediately, just make sure the Down arrow is not drawn.
  7. Beware: HamClock stays logged into the cluster node with your call sign as long as the DX Cluster pane is visible. So do not use this feature if you want to use the unassisted category in a contest -- some judges do check!
  8. The same mechanism can communicate with WSJT-X or JTDX. Instead of showing cluster spots, it shows each FT8 station you log. 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 on a Pi, log in from some other computer with ssh (or putty) 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

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

  • If xrandr gives an error about bad parameter match, try changing scale-from a little.
  • If at any time you want to go back to normal run xrandr again with your original screen size:
    xrandr --output HDMI-1 --scale-from 1920x1080 --display :0
  • The xrandr change does not survive logging out or rebooting. To make the change permanent, put the exact xrandr command you liked in the file ~/.xsessionrc using your favorite text editor.

On RPi version bookworm things are different because the default window system has become Wayland. You can either use raspi-config to change back to X11 so the above will work, or you can use Wayland's alternative command called wlr-randr as follows:

  1. Open a terminal window directly on the pi. Unfortunately you can't use ssh so you must juggle everything on screen at once.
  2. Run wlr-randr with no arguments to get a list of supported sizes.
  3. Look through the list and find the name of the display (at the left of the first line) and the smallest size that is larger than your hamclock.
  4. Run the command again but this time adding more arguments for your chosen values, using the following example as a guide:
    wlr-randr --output HDMI-A-1 --mode 1680x1050
  5. The effect will only last until you log out. To make the change permanent, edit the file ~/.config/wayfire.ini and add two lines at the bottom; again for the same example:
    mode = 1680x1050
  6. There is supposed to be a way to set any size as a custom mode but so far it doesn't work for me as of Oct 2023.

xrandr works on macOS too with XQuartz but it only allows choosing from a fixed set of sizes. So you can still reduce the border but you may not be able to eliminate it altogether. The general idea is to use the following procedure, again adjust sizes to fit your situation:

  1. Run xrandr with no arguments for a list of available sizes; pick one at or slightly larger than your hamclock.
  2. Start HamClock and enter Setup.
  3. Go to Page 5, click Full Screen to Yes; now just leave it there for the moment and go to the next step.
  4. In another terminal run xrandr --size 1600x1200. You'll see the hamclock size jump.
  5. Now back in HamClock, click Done and HamClock should now occupy almost the entire screen.
  6. To get your screen back to normal, hold HamClock's padlock for 3 seconds, then choose exit.
  7. If you get really stuck in full-screen mode, type Option-Command-A to force XQuartz back to normal.

Can you bring back the old VOACAP pane? I liked it much better.

In a word, no. I have two reasons.

One is the previous version provided precision far beyond what is real. The VOACAP model is based on monthly averages, so several tens of percentage point changes can easily occur due to solar flares, geomagnetic disturbances and other effects that happen very rapidly. So although the model does generate percentage values, they don't really have as much meaning as the precision implies. I think of the VOACAP model as similar to climate. As the saying goes "climate is what you expect, weather is what you get".

The second reason is I think seeing the daily trends adds greatly to the value of the display. For example, at a glance you can tell whether conditions will improve or get worse in the next few hours, or quickly pick a time of day that offers the best chances to contact a given location. These trends and planning capabilities were not possible when only the present hour values were shown.

Having said this, I will allow that it was nice to see just the current conditions at a glance. This is why I added a small marker below the new graph to show the current time. This way, you can just scan your eye up that column to see basically the same information as presented previously, with precision that represents reality just as well. Granted they are not numbers, but the color choices remain the same as before: red < 33%, yellow < 66% and green above 66%, with one change that I now make < 10% black.

Give it more time and perhaps you will come to like the new graph as much as I do.

Does HamClock have a web interface?

If you are looking for the RESTful API command interface, see FAQ 42.

Yes. Use a browser to load the page live.html on port 8081 from the host running hamclock. For example, if the IP of the computer running HamClock is, then enter this URL to run it from your browser:

Some notes:

  • HamClock will be centered if smaller than the browser window, or shrunk to fit if the browser window is smaller. If the image looks chunky, build HamClock at a larger resolution.
  • Keyboard and mouse input work if you first click on the HamClock window to give it focus.
  • Multiple simultaneous browser connections are supported, with no limit other than the capability of the computer running hamclock.
  • To reset a browser session for any reason, refresh the page.
  • Screen blanking and timed on/off are not supported -- use your host's facility.
  • If bandwidth is a concern, the lowest bandwidth occurs when HamClock is made 800x480 and the map Night option is off.
  • start hamclock with -c to create a read-only web experience.
  • Not available from an ESP HamClock.

Why would you use this?

  • It's an easier alternative to VNC or remote X servers.
  • It allows displaying one HamClock on multiple monitors simultaneously for, say, a contest group.
  • To run multiple independent instances from the same URL see the User Contrib entry for the web proxy.
  • You can see and control HamClock with your phone (if you dare).
  • It's a far more efficient way to run HamClock on a headless Pi. To try this, build one of the hamclock-web-XXX versions and run as follows: (type make help for a complete list)
        cd ~/ESPHamClock
        make -j 4 hamclock-web-1600x960
        sudo make install
        hamclock &
    You won't see anything on your screen now, but browse to the host running hamclock as described above and voilà! you will find a live HamClock.
  • It may be an easier way than using xrandr to get full screen. Most browsers have View menu controls to zoom in or out and some even have a kiosk mode that completely removes all decorations.

    For example on macOS you can also start Chrome in real kiosk mode from the terminal command line as

        /Applications/Google\\ Chrome --kiosk http://<hamclock-address>:8081/live.html
    Other browsers/systems likely have similar controls.

Can I change the port?

  • Yes, by using the -w command line option. For example, to change to port 7000, run hamclock as follows:
        hamclock -w 7000

Can I connect with https?

No, hamclock only supports http connections. But if you have administrative access to a web site running apache, you can set up a reverse https proxy as follows:

  • You must use HamClock version 2.96 or newer.
  • Find the apache configuration file containing the section for your VirtualHost *:443. On Ubuntu, it's somewhere in /etc/apache2.
  • Within this section insert the following:
        # allow https access to http hamclock
        <Location /hamclock-live/live.html>
        <Location /hamclock-live/live-ws>
            ProxyPass ws://
  • Make sure a few modules are loaded:
        a2enmod proxy proxy_wstunnel proxy_http
  • Restart apache, typically with apachectl graceful.
  • Build and run hamclock on the same machine running apache.
  • Now use any browser and surf to your new HamClock web site with the following URL:
  • Note: if multiple users connect at the same time, they will all be controlling the same hamclock and chaos will soon erupt. Consider running a read-only version of hamclock by adding -c. Or give everyone their own instance by running my hcwebproxy tool as described in tab 12 of the User Contrib tab of the HamClock web site.

Cheers, and thanks for using HamClock.

Why do I get an error when displaying a satellite or it disappears after a while?

Probably because your time is off. If the button below and to the right of your call sign says OFF then tap it so it says UTC and try again.

The error occurs because sat elements are only good for a few days so if the clock's time has been adjusted outside the valid range you'll get an error message. Time can be adjusted away from UTC if you click any of the time fields. That can be handy to intentionally move time forward or backwards to explore gray line, VOACAP predictions etc. See page 7 of the User Guide for more details.

Why do I have two HamClocks with identical settings showing slightly different VOACAP maps?

Because they are showing maps for two adjacent hours.

Ideally all Clocks would update at the top of the hour. But with several thousand Clocks running the world over that would overwhelm the backend server. In order to spread out server hits, Clocks intentionally randomize their VOACAP updates throughout each hour. This means the map shown by any given Clock might be up to one hour late.

So in your case, one clock is showing a map for the current hour, and the other is still showing from the previous hour. When the Clock that happens to be updating later updates, it will then show the same map until the cycle repeats next hour.

Why is my grid square wrong?

It's probably not wrong but I can think of two possibilities why you might think so:

  1. You are near a grid boundary and the HamClock display is misleading because of rounding.

    For example, suppose you set your location to 35.1N 110.1W which is in grid DM45. HamClock will display this in the main DE pane as 35N 110W grid DM45. But taken at face value 35N 110W is in grid DM55 so the grid appears to be wrong because the location is rounded for display. When in doubt, open the lat/long dialog to review the values as they are stored internally.

    Note that displaying more precision would not eliminate this issue entirely, it can only reduce the region where this occurs.

  2. There are two different algorithms for exactly where a grid square is located.

    Some programs use the center of a grid for their position, others use the SW corner. HamClock uses the corner because that is the historical technique described in this paper published in January 1989 QST. My personal favorite web site that uses this technique is here. But other popular web sites use the center, such as this one on So it depends which you consider correct.

If you still feel HamClock is in error, please send me the exact details.

What is the HamClock diagnostic output?

It is additional detailed status and diagnostic information HamClock writes to the file $HOME/.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:


The followng command will collect all these files into one bundle:

        cd; tar cfz hcdiags.tgz .hamclock/diagnostic-log*.txt

Sometimes it can be helpful to watch the file in real time which you can do with the following command; type Control-C to quit.

        tail -f $HOME/.hamclock/diagnostic-log.txt

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, the following commands may help for 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 most functions. But note if you perform sudo make install again in the future 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 back to 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.

You might also consider setting your own titles locally using the set_rss web command (see FAQ 14) or run the contributed script (see the User Contrib tab).

Is it possible to speed up the pane rotation?

In principle, yes. But it would add more stress to my backend server.

With few exceptions, HamClock does not store pane content. This is because the code base is still designed to run on the ESP8266 which has very limited storage. Each time HamClock draws such panes it must refresh the contents from scratch. For most panes this means a query is sent to my server for that pane's content. With several thousand clocks running the world over, if they all wanted faster pane rotation it would push my server beyond its capacity.

Even the default update interval of 30 seconds can cause high load if too many updates happen to occur at once. When this occurs, HamClock temporarily extends the update interval even longer until the server load goes back down.

Occasionally I see "WX too fast" or similar -- What does that mean?

It means either my connection to Open Weather Map is overloaded or your clock is making queries too rapidly.

In order to stay within the usage limits of my OWM subscription, my backend server will deny all HamClock weather queries if they arrive faster than 200 per minute.

My server also limits the request rate from any one public IP. Note if you have more than one HamClock at your shack, they all count as one for this limit because they each report the same public IP address.

Why is the pane choice menu not working as I expect?

Because you are forgetting the rules about pane choices covered in the User Guide. So again:

  1. Each pane must have at least one choice enabled at all times. To enforce this policy, you are not allowed to turn off the only remaining choice. The correct procedure is to first select another choice, then turn off the one you no longer want.
  2. On the other hand, a given choice may only be assigned to one pane at a time. To enforce this policy, the menus automatically remove choices that are already assigned to other panes. So the correct procedure to move a choice to a different pane is to first turn it off in its current pane, then select it in the desired pane.

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 back to 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 4, 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.

What if my BME280 always reads 100% humidity?

This may mean your device has become saturated. According to the data sheet page 46, you can try reconditioning the device by baking it at 120 C for 2 hours, then letting it slowly cool to 25 C over 24 hours. If this doesn't help then your device may be broken.

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 X11 GUI.

If you have fb0 installed, please remove it before installing any new versions. This requires the following steps:

  1. log into your RPi with ssh
  2. stop automatically starting hamclock, for example if you used crontab, type crontab -e and remove the line that runs hamclock
  3. Make sure the GL driver is enabled by running sudo raspi-config and doing

    Advanced Options ⇒ GL driver ⇒ OpenGL with fake KMS ⇒ Ok
    don't reboot yet

  4. Restore using the GUI by doing

    System Options ⇒ Boot ⇒ Desktop Autologin ⇒ Ok ⇒ Finish ⇒ Reboot? Yes

Must I use /usr/local/bin for the executable?

No. To build hamclock and put it in, say, /usr/bin, use the following steps:

        cd ESPHamClock
        make -j 4 hamclock-1600x960
        sudo mv hamclock-1600x960 /usr/bin/hamclock
        sudo chown root /usr/bin/hamclock
        sudo chmod u+s /usr/bin/hamclock

Why does my screen go blank after a short while or not blank at all?

Screen blanking control is a complex dance between the host and hamclock.

Let's check the host first.

  1. On RPi running Bullseye start a terminal
    1. run sudo raspi-config then
      1. Go to Display Options ⇒ Screen Blanking ⇒ Enable
      2. Go to Advanced Options ⇒ Wayland ⇒ Disable
      3. exit
    2. also, HamClock and xscreensaver do not mix. To make sure you don't have it installed, run these commands:
      1. sudo apt remove xscreensaver
      2. sudo apt autoremove
    3. now reboot
  2. On RPi running Bookworm, or any system running Wayland, screen blanking is broken which means the Idle timer and On/Off controls do nothing. For now, if you really need these functions to work, I can only suggest that you run sudo raspi-config and change back to X11 in the Advanced section.

As for HamClock, it will only blank the screen if it is in Full Screen mode (set in Setup). If not in Full screen mode, then the blanking must be caused by the host system, not HamClock. Follows are the HamClock settings that control whether it will blank the screen; these settings are only present when in Full screen mode (or on the ESP platform):

  • Check the Idle time in the upper right corner. You may have to click the region to change options to find the value. Click just above or below the Idle number to increase or decrease by 5 minutes. Set to 0 to display idle blanking.
  • Check the Off and On (or Dim) times in the same area. Change them the same way; set the times equal to disable blanking. These can also be set on a daily basis in Setup.

Why is the CPU usage so high on the Pi and other UNIX platforms?

This is a consequence of HamClock being originally written for the ESP8266 embedded processor. I wrote a porting layer that allows me to use the same application code on the Pi. This saves me a lot of effort but since the ESP8266 code is fundamentally an infinite loop, the result is the UNIX program runs all the time also.

It's not usually a big deal in practice but if it bothers you, use the hamclock -t command line argument to set the desired CPU percentage. For example, to limit cpu usage to about 50%, run hamclock as follows:

        hamclock -t 50

Note that lower limits will result in more sluggish performance.

What are rigctld and rotctld?

Rigctld is hamlib's rig control daemon, and rotctld is the rotator control daemon. They provide a device independent network protocol to control several brands of radios and single and dual axis antenna rotators without having to know their individual commands. On RPi you can install them with sudo apt install hamlib.

HamClock can create a network connection to these programs for automatic control of any radio or rotator* supported by hamlib. To get a list of all supported equipment run the programs with -l, such as rigctld -l. You must get these hamlib programs working with your equipment before you can use them with HamClock.

For practice, you can run either program in simulation mode by specifying model one, such as rotctld -m 1. Then enter the program's host and port number in HamClock's Setup, page 3. The rotator simulator is particularly fun. Start the simulator, then select the Rotator pane and get acquainted with the controls before connecting to your real rotator. There is no pane dedicated to rig control, it is only used to automatically set the radio frequency of a DX Cluster spot.

Do not confuse rigctld (or rotctld) with another hamlib program named rigctl (or rotctl). This program, without the trailing d, provides direct radio (or rotator) control using the command line, not a network connection. Both the command line and the network program use the same control libraries under the hood, so if one works the other will also. It can be a good idea to use rigctl (or rotctl) for initial testing, then once that works, change to rigctld (or rotctld) using the same -m model selector to allow network control from HamClock.

* Note as a special case, although the Yaesu G5500 rotator is not supported by hamlib because it has no serial or networked computer interface, there is a project that provides a drop-in replacement for rotctld for the G5500 here .

What is flrig?

flrig is w1hkj's program to provide network control of many ham radio transceivers. It historically provided rig control to fldigi but works very well on its own. Unlike the hamlib tools, flrig includes its own GUI so many consider it easier to use.

You can download packages for several platforms here or on RPi you can install it with the command sudo apt install flrig. Once installed, just type flrig and go to Config → Setup → Transceiver to prepare for your radio.

Can HamClock run without a network connection?

It will run but you won't see much.

HamClock connects to for all the data plots, real-time images and maps and to various NTP servers for time. That just leaves the moon, NCDXF beacons, and BME environment data that is sourced locally.

You could get time without a net connection by using a GPS antenna and running gpsd.

On the other hand if you have a slow network connection, see FAQ 46.

Why does HamClock report K index and not A?

Because K is more timely. The K index is reported every three hours while the A index is only updated once per day. You can find the exact relationship between A and K in the WikiPedia article.

Why does HamClock report a different space weather value compared to XYZ?

It could be a different source or different timing.

There are multiple primary resources for some statistics so it depends on which you are comparing with. For example, the sun spot numbers are determined and reported independently by NOAA in the US and SILSO in Belgium.

It can also be due to timing. The various primary data sources publish at different times during the day and they are not always exactly on time. The secondary data consumers also have their own schedule of picking up the values which can also vary. For example, even WWV sources are not always in sync. Typically their Sun Spot Number json feed is several hours ahead of their text feed. Another example are their Kp numbers from here and here are often out of sync by half an hour or more.

What are JD, MJD, LST, Solar and UNIX times?

These are time scales useful in various applications other than ham radio. They are included with HamClock because of its general role as a time keeping device.

  • JD is Julian Date. It is a steady continuous time scale for marking astronomical phenomenon spanning millennia. The value starts at noon Jan 1 4713 BC and increments by one each day thereafter. The Wikipedia entry is here.
  • MJD is Modified Julian Date. It is the same as JD but rebased to midnight Nov 17, 1858, by subtracting 2400000.5. This produces a more manageable number and starts each day at the more familiar midnight.
  • LST is Local Sidereal Time. This is the value of Right Ascension currently passing through the local meridian. It is used by astronomers to quickly determine what portion of the celestial sphere is currently visible from a given location. One day on this scale is about 23:56 so it slowly advances during the year compared to civil time. The Wikipedia entry is here.
  • AST is Apparent Solar Time. It is the local time referenced from the actual location of the sun, not the mean location used by civil time systems. The difference between these two is known as the Equation of Time. The Wikipedia entry is here.
  • Unix time is the number of seconds since Jan 1 1970 UTC, not including leap seconds. It was created as a simple means of determining absolute time on early UNIX operating systems. It remains in commom use today because of its simplicity and convenience. The Wikipedia entry is here.
  • Day of Year is often used for research data, time stations, and in military planning tools. For example see its usage at NSIDC, CHU and the Wikipedia entry here.

Why isn't the Idle timeout and/or the On/Off timers working?

HamClock only supports the Idle timeout and On/Off timers in the following situations:

  • HamClock is running on the ESP8266.
  • The display is connected to a Pi using the DSI ribbon connector or the first HDMI connector.
  • The Setup setting for Full screen is Yes.
  • HamClock on Pi must be using xorg with screen blanking enabled. To check, run sudo raspi-config then
    Advanced Options ⇒ Wayland ⇒ disabled.
    Display ⇒ Screen blanking ⇒ enabled.

Can HamClock run on the Raspberry Pi Pico?

Maybe, but I haven't been excited enough to try for several reasons:

  • There is no HDMI video so the only display option would be the same SPI LCD used on the ESP8266 version. This glacial interface is the main reason it takes 30-60 seconds to render a single map view.
  • The Pico clock speed is only 133 MHz, even slower than the ESP8266 160.
  • The small amount of FLASH would not support OTA updates.

But if I were to try, I'd start with this port of the Arduino ecosystem. Note this path would mimic the ESP8266 HamClock, not the RPi version. I'm not aware of any path to achieve the latter.

Can HamClock be controlled via a RESTful API interface?

Yes. HamClock provides a RESTful API scripting interface, with which it can be controlled and queried over a network. These commands can be sent with command line tools such as curl or wget or with a browser. The list of commands below is followed by several examples.

By default, the RESTful API interface uses port 8080 but this can be changed with the -e command line argument. For example, to change to port 9000, run hamclock as follows:

        hamclock -e 9000

Syntax Summary
get_capture.bmp Save screen as bmp file
get_config.txt Report current HamClock configuration settings
get_contests.txt Report current contests if pane has been shown
get_de.txt Report DE info
get_dx.txt Report DX info
get_dxspots.txt Report current list of DX cluster spots
get_livespots.txt Report current Live Spots list, if active (not ESP)
get_livestats.txt Report current Live Spots stats, if active
get_ontheair.txt Report current POTA/SOTA activators, if active
get_satellite.txt Report current satellite position and passes, if defined
get_satellites.txt Show a list of all available satellites.
get_sensors.txt Generate list of BME280 sensor values, if attached
get_spacewx.txt Get last-known pane data and age
get_sys.txt Report some basic HamClock system information
get_time.txt Report HamClock's idea of UTC
get_voacap.txt Report current band conditions percent reliability matrix, if active
set_adif?file POST Load an ADIF file, see example below
set_alarm?state=off|armed&time=HR:MN Set alarm off or arm at the given optional time
set_auxtime?format=[one_from_menu] Set the auxiliary time format (beneath UTC)
set_cluster?host=xxx&port=yyy Set a different DX cluster node
set_defmt?fmt=[one_from_menu]&atin=RSAtAt|RSInAgo Set DE pane time format to one of its menu choices, and rise/set if All info
set_displayOnOff?on|off Turn display on or off
set_displayTimes?on=HR:MN&off=HR:MN&day=[Sun..Sat]&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).
Change Live Spots configuration
set_mapcenter?lng=X Set a new center for the Mercator or Mollweide map; not persistent across restarts.
set_mapcolor?setup=name&color=R,G,B Set one of the Setup map colors. Color may be 0..255 RGB or common color
names (leave blank for list).
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?grid=AB12&lat=X&lng=Y&TZ=local-utc Define a new DE location using grid or latitude+longitude and optional time zone
set_newdx?grid=AB12&lat=X&lng=Y&TZ=local-utc Define a new DX location using grid or latitude+longitude and optional time zone
set_pane?Pane[123]=X,Y,Z... any set from:

VOACAP DE_Wx DX_Cluster DX_Wx Solar_Flux Planetary_K
Moon Space_Wx Sunspot_N X-Ray Rotator ENV_Temp ENV_Press
ENV_Humid ENV_DewPt SDO_Comp SDO_6173A SDO_Magneto
SDO_193A, Solar_Wind, DRAP, Countdown, STEREO-A

Set the specified plot pane content, if allowed.
set_rotator?state=[un]stop|[un]auto&az=X&el=X Control rotator, if pane is visible and connection is established.
set_rss?reset|add=X|network|interval=secs|on|off|file POST Control RSS including local titles; see examples below.
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_screenlock?lock=on|off Control screen lock
set_senscorr?sensor=76|77&dTemp=X&dPres=Y Set the given BME280 temperature and/or pressure correction in current units
set_stopwatch?reset|run|stop|lap|countdown=mins Stopwatch commands
set_time?change=delta_seconds Change time by the given number of +- seconds.
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. Missing args are left unchanged. Changes are not persistent
and do not effect real call. Colors may be 1-255 RGB or common color names
(leave blank for list). All default settings are restored 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 model parameters. X are same as VOACAP pane.
exit tells HamClock to exit (not ESP)
live.html page with which HamClock can be controlled from a browser (not ESP)
restart Restart HamClock
updateVersion Check for new version and update if found
any command not recognized Show this help

Examples; change the IP to match your hamclock host address.

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

Specify an earth satellite with its TLE:
Note 1: This TLE will be out of date by the time you read this, it is shown just as an example of proper syntax.
Note 2: This elaborate curl syntax is required whenever the payload includes spaces. See User Contrib #13 for a small script that helps with this curl syntax.

        curl --get '' --data-urlencode 'name=ISS&t1=1 25544U 98067A   21320.06051688  .00001570  00000+0  37172-4 0  9998&t2=2 25544  51.6441 311.7573 0004586 201.9414 260.8823 15.48581357312130'

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

        curl ''

Set Live Spots to report spots made by DE call using wspr on 40, 30 and 20m

        curl ',30,20

Set Pane 3 to rotate through NOAA Space weather, X-Ray flux and DRAP trend:

        curl ',X-Ray,DRAP'

Toggle the screen lock padlock:

        curl ''

Change call sign to say QUIET PLEASE white on red:

        curl --get '' --data-urlencode 'msg=QUIET PLEASE&fg=255,255,255&bg=red'

... then restore as per Setup:

        curl ''

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

        curl ''

Turn off RSS network feed and clear the local title list:

        curl ''

Turn off RSS network feed and add one RSS title to local list:

        curl --get '' --data-urlencode 'add=This is a new RSS title'

Turn off RSS network feed and load a file containing up to 15 lines into the RSS title list:

        curl --data-binary '@mytitles.txt' ''

Restore normal network RSS operation:

        curl ''

Load the ADIF file named myfile.adi, also selects ADIF in pane 3.

        curl --data-binary '@myfile.adi' ''

Set map grid color to yellow:

        curl ''

Can I run more than one instance of HamClock at the same time?

Yes but you must arrange that they each use different ports and working directories.

You do this using command line switches when you start each hamclock. Use -e to set a different REST API port; -w to set a web port; and -d to set a working directory. Type hamclock -help for a full list of switches and their respective default values.

For example, to run hamclock using port 9080 for the RESTful API, 9081 for the web interface and /tmp/hamclock2 for the working directory, start hamlock as follows:

        hamclock -e 9080 -w 9081 -d /tmp/hamclock2

If you don't need one or both of the networking options, specify port -1 to turn either one off completely. For example:

        hamclock -e -1 -w -1 -d /tmp/hamclock2

Can you make an option that shows the map full size?

In theory, yes, but given the current internal software architecture this would be very difficult.

A key difficulty is that HamClock has no menu bar. This means there would be no way to control features that currently use the surrounding panes which, when you think about it, is almost everything. And adding a menu bar would require changing the internal structure of the program so completely it might as well become a separate program.

Another challenge would be the need for yet another set of map resolutions. This means all the various map styles (MUF, Auroras, Weather, etc etc) would all need to be generated at the new resolutions for each of the four basic build sizes. Generating the maps on demand is already the single highest load on my backend server, so adding more sizes would further increase this load.

So again, yes it's possible because HamClock is afterall "just" software, but for now it's well beyond my available resources.

Can I use a CH341T to access the BME280 via USB on my linux system?

Yes, but you must do some preparation work.

First, to be clear, the CH341T is a chip that creates an I2C bus and makes it appear as a USB peripheral. This topology is intended for motherboards that do not have any external I2C ports. It is available on a breakout board from several vendors such as Amazon or AliExpress.

To make this work requires some glue logic, it is not a transparent proces. The required steps are as follows. These were tested on Ubuntu 22.04 running on an Asus motherboard.

  1. Download the linux driver from Note that standard linux already includes a CH341 driver, but it only supports the tty capability of the chip, not the I2C.
  2. Edit i2c-ch341-usb.c line 660 from
        ch341_dev->irq_descs[i] = irq_to_desc(ch341_dev->irq_base + i);
        ch341_dev->irq_descs[i] = irq_data_to_desc(irq_get_irq_data(ch341_dev->irq_base + i));
  3. Now you can follow the build and install instructions on the github site.
  4. Run lsmod and check the i2c_ch341_usb module is installed.
  5. Attach your BME280 to the CH341 and plug it into a USB port. I don't know why, but I find that using a USB 3 port is much more reliable than a USB 2 port.
  6. Run ls /dev and confirm there is a node named i2c-1.
  7. Run sudo i2cdetect -y 1 and confirm it shows the I2C address of your BME280, either 77 or 76.
  8. Start HamClock and go to Setup page 4. You will notice the usual prompt GPIO? has changed to IIC? because full GPIO is not supported. Toggle IIC? to Active then click Done.
  9. That's it. HamClock should now offer the usual ENV pane options for the BME280. See the User Guide for more info on using Panes.

Note: I have tested this on a Raspberry Pi 4 and it does work fine. However, to use it for the BME280 in HamClock required editing line 75 in the source code file ArduinoLib/Wire.cpp because it creates a new I2C bus HamClock does not expect. Run the command ls /dev/i2c* to check which name it creates. In my case I had to change to /dev/i2c-22 but your device name may well be different.

Why does the time stall occasionally?

It is because HamClock is only a single thread of execution so it can only do one thing at a time. Thus, if the network connection is slow everything hangs during file downloads and it can't update the time digits. HamClock tries to reduce this effect by reading in fairly small chunks and updating the time after each chunk completes, but it can still look jerky.

Note the stalling does not affect the accuracy of the internal time keeping because that uses a hardware interrupt, so time proceeds apace regardless of the display.

How accurate is HamClock weather data?

The accuracy of the reports depends on several factors.

  • The data plan I have with Open Weather Map provides updates at least every two hours and uses a grid spacing of about ten miles. They do offer plans that provide much shorter delays and smaller grids but I am not willing to pay for them just for HamClock.
  • Some of their data comes from models, not actual measurements. This allows them to appear to offer seamless global coverage even in areas that clearly could not have any measuring capabilities, but at the risk of modeling errors.
  • HamClock queries for weather using the latitude and longitude given for DE. So the more accurate you specify your location, the better will be the results.

Can I copy a configuration to another computer?

Yes, but first a little background.

Each instance of HamClock needs its own working directory for supporting files. By default this is $HOME/.hamclock (note the leading dot). One file therein is called eeprom which contains all the configuration settings. This file is used a lot at runtime so don’t change it while hamclock is running.

So, to copy a hamclock configuration from computer A to B:

  • create or use an existing directory $HOME/.hamclock on B
  • copy the file eeprom from A to B in said directory

You don’t have to copy any of the other files in the directory, they take care of themselves automatically. And, again, don’t perform this copy while a hamclock is running on either system.

If you would like to keep multiple configurations on the same computer, use the command line option -d to specify some other working directory. Hamclock will create the specified directory if it doesn’t already exist. So for example, to use a separate working directory for someone with a call W9ABC, they could run hamclock like this:

        hamclock -d $HOME/.hamclock-w9abc

You can even run several hamclocks at the same time on the same machine, see FAQ 43 and User Contrib item 12.

Can I control HamClock with just a keyboard (no mouse)?

Almost on the native GUI interface, definitely not on ESP8266 or the web browser interface.

The reason for "almost" is that the HamClock window must have what's called the "focus" in order for it to receive any keyboard events, and usually the only way to do that is to click the mouse once inside the HamClock window! The only way around this catch I know of is that most window managers have options such as "focus follows mouse" or "focus on new windows" which may help if you can find them.

But once HamClock has the focus then yes indeed, it can be completely controlled from the keyboard as follows:

  • hjkl or arrow keys move the red arrow cursor left-down-up-right (same as the vi editor)
  • accompanying these with shift and/or control will multiply the step size by 2 and/or 4, respectively
  • space or Enter will do the same as a mouse click at the current cursor location
  • accompanying these with shift and/or control will function as a long hold
  • If you enter a menu then:
    • hjkl or arrow keys will navigate the items as a matrix
    • space will toggle selections
    • Enter will function as "Ok"
    • ESC will function as "Cancel".

Historical note: Even though keyboard cursor control has been available by default for a long time, starting with version 3.01 it will require that you start hamclock with the ‑y command line option. I decided to disable it by default because too many people are laying things on their keyboard causing it to repeat endlessly, which sends zillions of commands to my server for hours on end without their realizing it. Note that ‑y only applies to cursor control; the Setup pages and menus continue to work the same as always with or without ‑y.

Can I connect the photocell to an RPi hamclock?

No. The Pi does not have an ADC channel with which to read an analog voltage. It could be done with an external I2C board but I have not been motivated to do so.

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

Send me a note at but beware:

  1. Be polite or your email will simply be discarded.
  2. If you installed or purchased HamClock using someone else's instructions, contact them, not me.

If you are submitting a bug report, always include:

  1. HamClock version
  2. platform: ES8266 or UNIX/linux distro and version
  3. a clear and concise statement of what you expected to see ...
  4. ... what you actually saw ...
  5. ... and instructions for how to reproduce the unexpected result.

If using any UNIX system, also include the following as you feel might be helpful:

  • which make target you built
  • display screen size and video type such as DSI or HDMI
  • whether you are using VNC
  • whether you are using GUI in Full-screen mode
  • pertinent Setup settings
  • a copy of all ~/.hamclock/diagnostic-log*.txt log files

Thank you. Your coorperation will help us both find a resolution to your issue more quickly.

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-800x480
  11. sudo make install
  12. export DISPLAY=:0
  13. /usr/local/bin/hamclock

More tips for Executing and Displaying HamClock on Windows 10

Contributed by Thanasis, M7SYR

HamClock Windows10.txt.

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. The script needs to know the directory containing the source files and the path to the eeprom file. By default these are assumed to be the current directory and ~/.hamclock/eeprom, respectively, but these can be changed with the -s and -e options. Run the script with no args or --help for a complete 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

Set a new call sign: NV_CALLSIGN AB1XYZ

Set the DX cluster host: NV_DXHOST
        NV_DXHOST =

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

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

Script to query for any space weather datum

Contributed by Elwood Downey,

This script queries HamClock for the most recent value of any space weather data it provides. Run the script with -help for a complete list.

Script to send any RSS feed to HamClock

Contributed by Elwood Downey,

HamClock does not allow setting individual RSS feeds, see FAQ 20 for the reason why. But this script uses the web-based RSS title loading facility set_rss to read any RSS feed and load its titles into HamClock.

To use the script, just give it the host name (or IP) of your HamClock followed by the full URL of the RSS to load. For example:

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.

Arch User Repository

Contributed by KJ7RRV.

HamClock is available in the Arch User Repository here. The package names are:

  • hamclock (800x480)
  • hamclock-big (1600x960)
  • hamclock-bigger (2400x1440)
  • hamclock-huge (3200x1920)

Running HamClock on ProxMox

Contributed by NI2O.

This pdf shows how to configure HamClock to operate in an LXC container on a ProxMox server.

Compile HamClock statically so it will run on e.g. TrueNAS.

Contributed by M1JKL.

TrueNAS allows you to run Docker containers and VMs of all sorts; in my case, all I wanted to do was to run Hamclock as a service and hence it seemed a massive overkill to go down the VM/Docker route - hundreds of MB of installed space used up for a simple executable.

So this is what I did:

  1. edit the Makefile to say CXX = g++ -static
  2. run make with the hamclock configuration of your choice e.g.
    make -j 4 hamclock-web-1600x960
  3. copy the resulting hamclock executable to your truenas directory of choice, maybe in your home and make it executable
  4. go to ~/ and check it runs
    $ ./hamclock
  5. Truenas natively contains tmux which is a terminal multiplexer, so running something like
    $ tmux ./hamclock
    allows you to close the truenas login session whilst detaching from the still-running hamclock.

I did this a few weeks ago so the description above is from memory. Anyone with a bit of linux knowledge (I have almost none!) will work out a more elegant approach to establish it as a true service by using things like init.d or /etc/rc.local.

Web proxy to control multiple independent web hamclocks from the same URL

Contributed by WB0OEW.

Suppose you wanted to provide one URL for club members to access HamClock from anywhere they could access a browser. You could start one HamClock and publish its live web connection directly but as soon as more than one person connected they would interfere and things will get confusing and frustrating pretty quickly.

This little program solves that by functioning as a multiplexing proxy. It listens to the same port 8081 as a real HamClock, but runs a separate instance of hamclock for each IP reported by connecting browsers.

To give it a try, extract the program from the contrib collection mentioned at the top of this tab. The entire program is self-contained in a single file named hcwebproxy.cpp. Also, since the hamclocks that the proxy will run are only useful on the web, it is recommended to build a web-only hamclock just for use by the hcwebproxy. If this is how you normally build hamclock anyway then you can continue to use that one.

Putting it all together, assuming you want to use a different hamclock just for hcwebproxy, the procedure might go something like this:

        cd ~
        curl -O ''
        cd hamclock-contrib
        make hcwebproxy
        sudo make install
        cd ~/ESPHamClock
        make hamclock-web-1600x960
        sudo mv hamclock-web-1600x960 /usr/local/bin
        sudo chown root /usr/local/bin/hamclock-web-1600x960
        sudo chmod u+s /usr/local/bin/hamclock-web-1600x960
        hcwebproxy -d ./hcwebproxy-hamclocks -h hamclock-web-1600x960 -i 240 -m 3 -v -- -t 50 > x.hcwp &

The main reason for escalating to root privilege is to allow remote updates. See FAQ 19 for more information.

Now surf to the usual URL such as http://your-host:8081/live.html and you should get a new HamClock.

Try these additional tests to understand different use cases:

  • Open another tab on the same browser to the same URL and you will share the same HamClock because the browser is reporting the same IP. Any changes in one tab will be immediately reflected in the other. You can have as many connections as desired open at the same time.
  • Now close all connection tabs then open a new connection to the same URL. You will be reconnected to the same instance already running because the browser reports the same IP.
  • Open the URL from a different computer and you will get a completely new HamClock with default settings, different from the instance from the first computer. Opening additional connections will connect to the same instance. Also see the note below regarding NAT routers.

Futher notes:

  • This requires running HamClock version 2.91 or newer.
  • Remember that all computers behind a NAT router connecting to a public IP will report as coming from the same public IP of the NAT. Thus, they will all share the same hamclock instance.
  • Many simultaneous running hamclocks can be a large system load, so consider using the -m option to limit the maximum number accordingly. The default is 10 processes. Attempts to connect when this maximum has been reached will result in a brief informative message. Also see -i, next.
  • If the -m limit is reached when a new connection is attempted, hamclock processes that have been idle longer than -i hours are eligible for reassignment to handle the new connection. The default is 24 hours.
  • Another way to mitigate high system load is to throttle back the maximum CPU usage for each HamClock. This is controlled by HamClock's own -t option which you can set using hcwebproxy's -- option. Note well that this will reduce the responsiveness of each hamclock so use wisely. For example, to limit each hamclock to no more than 20% CPU:
        hcwebproxy -h hamclock-web-1600x960 -- -t 20 &
  • Since more than one HamClock may well be running on the same host, note well that the features that use external hardware should only be activated on at most one at a time. This refers to everything on the last page of User Guide. HamClock itself tries to enforce single access but beware of this limitation.
  • I actually find this so useful that I now always use this to access HamClock running on my RPi even if I just run one hamclock. Reason being that the hamclock processes are sleeping when I am not connected and the Pi runs much cooler most of the time. Plus it's super handy to check propagation conditions and my WSPR reports using my iPhone when away from the shack.
  • If something goes terribly wrong, hcwebproxy will try to kill all the hamclock processes it knows about before it exits. To investigate why, run hcwebproxy again with -v for debug info and try to reproduce the problem. Send me the log if it seems like a bug.
  • Even if hcwebproxy dies and all hamclocks get killed, their settings will be restored after a restart because all hamclock working directories are stored in separate directories named by the connection IP. The directory in which these are created can be set with the -d option, the default is $HOME/hcwebproxy-hamclocks.
  • Since all hamclock instances share the same program file, when any one of them performs a remote update, all subsequent hamclocks will use the newer version as well. Thus, after one hcwebproxy client does an update, merely restarting the others will update them also without requiring an actual update.
  • Normally hcwebproxy disables the RESTful API ports on the hamclocks it starts because it is awkward to find the one you want. Nevertheless, if this is important for your use case, you can use the -a option to assign each hamclock its own RESTful API port. The port numbers are assigned sequentially starting with the value given with -a. No attempt is made to avoid ports already in use by other applications so choose wisely. The problem remains how to know which hamclock is using which port; this is left as an exercise for the reader.
  • You can see what hcwebproxy is doing with a shell command such as:
        ps ax | egrep 'hamclock|hcwebproxy' | grep -v egrep
    The processes with status T are sTopped.

Script to simplify running curl

Contributed by WB0OEW.

Copy/paste the following into a file named hccurl and use it to send commands to hamclock that require embedded spaces.

# run curl with spaces

if [ $# -lt 3 ] || [ $# -gt 4 ] ; then
    echo Purpose: curl wrapper for sending hamclock commands with or without embedded spaces
    echo Usage: hccurl host port command '[value]'
    echo Example set: hccurl 8080 set_title "'"'msg=QUIET PLEASE&fg=255,255,255&bg=red'"'"
    echo Example get: hccurl 8080 get_config.txt
    if [ $# -eq 3 ] ; then
        curl --get "http://$HOST:$PORT/$CMD"
        curl --get "http://$HOST:$PORT/$CMD" --data-urlencode "$VALU"

Install HamClock using Docker

Contributed by Julius, DO7JZ.

I’ve got no Pi but servers and Linux machines. So I thought, I’d create an easy way to run HamClock using Docker, exposing it as a website. The code and instructions can be found at

I have not tested it on Windows, but potentially it’ll run in WSL2. Works fine on my MacBook as well as my Linux-Server. I’m pretty sure it’s an easy way to install/run on Raspberry Pi, or NAS Systems that support Docker/Docker-Compose as well.


Please note that development has ceased for changes specific to the ESP8266 model of HamClock. Consider using the UNIX/Linux model for all new builds.

Building the ESP8266 software

  1. Install the Arduino IDE from here. I am currently using version 1.8.16.
  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 -- do NOT use any of the 3.0 series.
  6. Open Tools → Manage Libraries, set Type and Topic to All, then search for and install the following libraries and versions. Other versions may work but these are the versions I am using now.
    • 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

  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.
  • HB9CEY shared his tilt stand front, rear, inside and on display.
  • 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:

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 PDF version is also available.

HamClock may be built for Raspberry Pi, macOS, Ubuntu, FreeBSD, Windows WSL or most any other UNIX-like system supporting the X11 Windows system.

To install HamClock on a Raspberry Pi follow these steps:

  1. These instructions assume your RPi is up and running Bullseye. If not, first see the FAQ 4, then come back here.
  2. Open a terminal on the target system GUI desktop by clicking on the red Raspberry → Accessories → Terminal. This will give you a command line prompt for the next step.
  3. Download and run the installer script by entering the following commands (use copy/paste to avoid typos):
    curl -O
    chmod u+x install-hc-rpi
  4. Answer each question by typing y or n followed by Enter.
  5. If you chose not to install a desktop icon, you can run HamClock from the terminal at any time by typing this command:
    hamclock &
  6. If no errors then that's it! Be sure to read the User Guide to get the most from HamClock. If something did go wrong, try working through the manual steps in the next section.

To install HamClock on other UNIX-like systems follow these steps:
(works for RPi too if you prefer the scenic route)

  1. Open a terminal directly on the target system GUI desktop to get a command line prompt.
  2. Run these commands (use copy/paste to avoid typos):
    rm -fr ESPHamClock
    curl -O
    cd ESPHamClock
    make -j 4 hamclock-800x480
    sudo make install
    • If you get errors:
      • on Raspberry Pi or other Debian try loading these packages:
            sudo apt-get update
            sudo apt-get -y install curl make g++ libx11-dev xserver-xorg linux-libc-dev lightdm lxsession openssl
      • on Ubuntu try loading these packages:
            sudo apt install curl make g++ xorg-dev libx11-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 RedHat or Fedora try loading these packages:
            sudo yum install gcc-c++ libX11-devel
  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. 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
  7. If you would like to operate HamClock from any browser on your LAN, see FAQ 14.
  8. If you would like HamClock to fill the screen, set that option on Page 5 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 12 about xrandr.
  9. If your system is XDG compliant and you would like a Desktop icon with which to start HamClock, try these commands:
    cd ~/ESPHamClock
    mkdir -p ~/.hamclock
    cp hamclock.png ~/.hamclock
    cp -p hamclock.desktop ~/Desktop
  10. Similarly, if you would like HamClock to start automatically when you boot your system, 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.