This page refers to my QST article in the October 2017 issue. All updates will be posted here.
News highlights: See the complete version history in the Download tab and details in the User Guide.
http://Your-HamClock-IP/set_sattle?name=abc&t1=line1&t2=line2Like all the server commands, you can send this with most browsers or with curl or wget from the command line.
hamclock-fb0-smallMakefile target for RPi's with 7" screens
See the ESP8266 Notes tab.
See the Desktop tab.
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*
This error means your system is using a version of openssl that is older than 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:
To update openssl on an RPi you can try
sudo apt upgrade openssl
To update openssl on macOS using macports you can try
sudo port upgrade openssl
(be sure /opt/local/bin is before /usr/bin in your PATH)
After the update, repeat the openssl command and you should see version 1.1 or larger. If so, repeat your HamClock version update and it should work.
It depends on the message.
Or just start all over. See the separate FAQ about removing HamClock. Then go over to the Desktop tab and follow the instructions.
sh: 0: illegal option -p?
This happened in Version 2.58 on RPi if you are not running Buster. It is now fixed so the easiest solution is to remove your current ESPHamClock (see separate FAQ) and install fresh using the instructions in the Desktop tab.
And while you're at it, if you are using the fb0 version, change to the GUI version, again see instructions and the other FAQ here about fb0 for details.
Copy it down exactly and email it to me.
No, it can not run natively on Windows but it can display on Windows by using an X Server. The idea is to run the HamClock program on a UNIX-like system, such as an RPi or WSL (Windows Subsystem for Linux) then run HamClock in such a way that it displays on the X Server running on Windows.
make -j 4 hamclock-800x480 sudo make install export DISPLAY="192.168.7.129:1" hamclock
Note in the example above, 192.168.7.129 is the IP of the Windows machine, so change that to match your system configuration. Also note the ":1" of the DISPLAY environment variable. That says to use X Server display 1, which corresponds to the selection I made while running XLaunch. If you find it won't connect, it might be due to your Windows firewall. X Window servers listen on port 6000 + display_number, so in this case be sure Windows is allowing incoming connections on port 6001.
Also see the User Contrib pane for a suggestion on how to use WSL.
Similar answer as previous FAQ but you'll need an X server app for iPad. I find Mocha X11 works well.
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:
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:
If I have misrepresented Geochron in any way, please tell me how and I will correct immediately.
filter1 reject not by_zone 3,4,5 filter2 reject not on hf/cw filter3 reject on hf/rtty filter4 reject on hf/ssb filter5 reject info ft8
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.
Even though full screen mode uses the entire screen, HamClock still only uses the pixels specified in the make command size, filling the remaining space with black. With the GUI configuration (not fb0) you can try a command line program called xrandr to expand HamClock to fill the screen by changing the effective display resolution to match HamClock.
Xrandr works by changing how the X server maps pixels to the display hardware. It's easy to try and undo if you decide you don't like it.
For example, my display is 1920 x 1080. The closest I can build HamClock is 1600 x 960. If I run this size with the Full screen option in setup set to Yes, HamClock will still be that size but will fill the surrounding gaps with black. With xrandr one can expand HamClock to fill the screen and eliminate those gaps.
To try it, log in with ssh so we aren't trying to adjust the same screen we are using for commands. Run the following command while HamClock is running in its full screen mode:
xrandr --output HDMI-1 --scale-from 1600x960 --display :0
(it's better to think of that argument as meaning scale-to)
That's it, the effect should be immediate but ...
Advanced Options ⇒ GL driver ⇒ OpenGL with fake KMS ⇒ Ok ⇒ Ok ⇒ Finish ⇒ Reboot now
xrandr --output HDMI-1 --scale-from 1920x1080 --display :0
Modify these values to accommodate your particular combination of HamClock and display sizes as needed.
The display aspect change is accomplished using non-square pixels within the X server. This doesn't usually matter much but if you often run analog Big Clock you may notice it is no longer circular. Adjust the xrandr dimensions to find a compromise between filling the screen and making the circle look nice.
The xrandr changes do not survive logging out or rebooting.
If you want the resolution change to happen automatically every time you start your GUI,
put the xrandr command in the file
Combine this with using autostart (see Desktop instructions)
and you can arrange for HamClock to start automatically at truly full screen size directly
from RPi power up.
One final point for the RPi.
If you still have a small black border, you may have video underscan
compensation turned on.
To turn it off run
sudo raspi-config then work through
Display Options ⇒ Underscan ⇒ enable? ⇒ No ⇒ Ok ⇒ Finish
sudo reboot if it doesn't ask you to reboot on the way out.
Yes, but it's not for interactive use as you might expect, it provides a simple means of connecting with HamClock over a network. HamClock listens on port 8080 for http connections from a browser or command line tools such as curl or wget. Using a RESTful command interface, HamClock can be controlled, queried and the screen can be captured as an image file.
To try the following examples, you will need a computer on the same network as your HamClock. Here we will use curl but the same URLs will work in your browser as well (although some browsers are getting more cautious about accessing a web site with http and you may be asked once to trust the site).
Start by querying HamClock for a list of all its commands as follows: (actually any unrecognized command will produce this help text)
The output will be a list of all supported commands as follows:
|get_capture.bmp||Save screen as bmp file|
|get_config.txt||Report current HamClock configuration settings|
|get_de.txt||Report DE info|
|get_dx.txt||Report DX info|
|get_dxspots.txt||Report current list of DX cluster spots|
|get_satellite.txt||Report current satellite position 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_stopwatch.txt||Report stopwatch state and timer value|
|get_sys.txt||Report some basic HamClock system information|
|get_time.txt||Report HamClock's idea of UTC|
|set_alarm?state=off|armed&time=HR:MN||Set alarm off or arm at the given optional time|
|set_displayOnOff?on|off||Turn display on or off|
Set display on and off DE times for the specified day, or today if not specified.
DOW is Sun..Sat. Optionally set display idle time (not saved on per-day basis).
|set_mapview?Style=S&Grid=G&Projection=P&RSS=on|off&Night=on|off||Change 1 or more map settings. S, G and P must match View menu text exactly.|
|set_newde?lat=X&lng=Y||Define a new DE location using latitude/longitude|
|set_newdegrid?AB12||Define a new DE location using its maidenhead grid square|
|set_newdx?lat=X&lng=Y||Define a new DX location using latitude/longitude|
|set_newdxgrid?AB12||Define a new DX location using its maidenhead grid square|
| set_pane?Pane=X,Y,Z... any set from:
VOACAP DE_Wx DX_Cluster DX_Wx Solar_Flux Planetary_K
|Set the specified plot pane content, if allowed.|
|set_satname?abc|none||Select satellite from built-in list, or none|
|set_sattle?name=abc&t1=line1&t2=line2||Define a satellite using TLE values|
|set_time?ISO=YYYY-MM-DDTHH:MM:SS||Set UTC to the given time|
|set_time?Now||Set UTC to current time from NTP or gpsd|
|set_time?UNIX=secs_since_1970||Set UTC to the given UNIX time|
|set_title?msg=my message&fg=R,G,B&bg=R,G,B|rainbow||Set call text to msg with fg and bg 0-255 RGB colors; missing args are
left unchanged; changes are not persistent and do not effect real call;
restores all default settings if no args
|set_touch?x=X&y=Y&hold=0|1||Virtually touch, or hold, screen coordinate X, Y; scaled to 800 x 480|
|set_voacap?band=80-10&power=p||Set VOACAP map band and/or power, or restore default background if neither|
|updateVersion||Check for new version and update if found|
|exit||tells HamClock to exit (not ESP)|
|any command not recognized||Show this help|
Get the current clock UTC time:
Set display to turn on Wednesday at 8 AM and off at 10 PM, DE time, with 10 minutes idle time:
Set a new DE location from latitude and longitude:
Save the current display to a file named hcscreen.bmp:
curl 'http://192.168.7.101:8080/get_capture.bmp' > hcscreen.bmp
Set satellite to ISS and report current ephemeris with respect to DE:
Set Pane 3 to rotate through NOAA Space weather, X-Ray flux and DRAP trend:
Toggle the screen lock padlock:
Change call sign to say ON AIR white on red:
curl 'http://192.168.7.101:8080/set_title?msg=ON AIR&fg=255,255,255&bg=255,0,0'
... then restore call sign:
Change map to Azimuthal projection with Countries style and RSS on, leaving Grid unchanged:
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.
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.
I can think of two possibilities why you might think so:
If you still feel HamClock is in error, please send me the exact details.
It is additional detailed status and diagnostic information HamClock writes to the file
~/.hamclock/diagnostic-log.txt. It is not intended for general
consumption but contains lots of good info for troubleshooting. You may be asked to
email me this file if you submit a request for help.
The previous 3 logs are also stored in a rolling set with the following names:
If preferred, the diagnostics information can be written to stdout by invoking HamClock as follows:
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
HamClock creates and uses a working directory named
.hamclock (note the leading dot)
in the HOME directory. HOME for the normal pi user is
Thus, if you run HamClock without sudo it uses
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:
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.
No. RSS feed formats are surprisingly inconsistent so I perform all the heavy lifting on my server and only send the plain titles to the HamClock. Plus, most now use https which uses too much memory for the little ESP processor.
That said, if you have a feed in mind that is of general interest to the global ham community, send me your suggestion and I will consider adding it to the server processing.
In principle, yes. But it would add more stress to my backend server.
Each time HamClock updates a pane it must query 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 to the limit.
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 to no more than once every five seconds to limit abuse. This means if you have more than one HamClock at your home they all count as one for this limit.
Because it's the last one. Panes must always have at least one choice active. If you no longer want the last choice, first select another one, then you can turn off this one.
No. The list is maintained on my server which performs all the heavy lifting of discovery and updating, sending only the TLEs to the HamClock.
That said, if you have a satellite in mind that is of general interest to the global ham community, send me your suggestion and I will consider adding it to the server list.
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
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.
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:
makeis run within the source tree, using the same target that was used to build the currently running program
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 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 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
|BME label||RPi Header pin|
sudo apt-get install i2c-tools
sudo raspi-configand set the following options:
Interface Options ⇒ I2C: enabled
sudo i2cdetect -y 1you should see 77 in lower right corner of matrix; then
sudo i2cdump -y 1 0x77 byou should see a matrix of different numbers, not just all XX
sudo i2c -swhich should immediately report the device address(es).
/boot/msdos/config.txtto add the following line to the
[all]section then reboot and try HamClock.
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.
Click and hold the padlock for 3 seconds, then select Exit.
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
/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
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:
crontab -eand remove the line that runs hamclock
sudo raspi-configand doing
Advanced Options ⇒ GL driver ⇒ OpenGL with fake KMS ⇒ Ok
don't reboot yet
System Options ⇒ Boot ⇒ Desktop Autologin ⇒ Ok ⇒ Finish ⇒ Reboot? Yes
Send me at note at firstname.lastname@example.org but beware
If you are submitting a bug report, always include:
If using any UNIX system, also include the following as you feel might be helpful:
maketarget you built
All contributed scripts referred to below are available in this zip file
Contributed by Joeri van Dooren, ON3URE
Contributed by Hans Klausmann, DL5RAZ
Script by Barry, N0NZ
Contributed by Elwood Downey, email@example.com
Someone asked if they could edit the
eeprom config file.
Normally no, but since I enjoy writing perl,
I couldn't resist writing
hceeprom.pl to do exactly that.
You can download it within the contrib collection
Save the script anywhere in your PATH and make it executable as usual.
Cd into the ESPHamClock source directory to run it.
This location is required because the script
needs to read the HamClock.h and nvram.cpp source files to find the symbolic
names, lengths and descriptions of the various parameters saved in eeprom.
The script assumes the eeprom file itself is located in
The type of the parameter is not saved in the eeprom file, so the script also needs to know
the data type, which you must include on the command line using
i for integral,
f for float or
s for string.
Run the script with no args or
--help for a usage summary.
Note well: you are hacking a file not intended for human consumption, so you can easily mess things up. There's no validation checking whatsoever, so you could go right ahead and set preposperous values such as a longitude of 10000 or inconsistent values such as a lat/long that doesn't match the grid square sending HamClock into unexplored territory. Save a copy of eeprom before starting, or remove it and HamClock will build a new one when it starts containing all defaults. Never edit the file while HamClock is running because HamClock often updates it, but only reads it once when starting up. You have been warned.
No matter, let's try it! Here are some examples:
Read the call sign:
hceeprom.pl NV_CALLSIGN s NV_CALLSIGN = WB0OEW
Set a new call sign:
hceeprom.pl NV_CALLSIGN s AB1XYZ NV_CALLSIGN = AB1XYZ
Set the DX cluster host:
hceeprom.pl NV_DXHOST s usdx.w1nr.net NV_DXHOST = usdx.w1nr.net
Set DX spots to show as full call sign
hceeprom.pl NV_MAPSPOTS i 2 NV_MAPSPOTS = 2
Set the BME280 at I2C address 77 temperature correction:
hceeprom.pl NV_TEMPCORR2 f -0.23 NV_TEMPCORR2 = -0.23
Here's the script:
Contributed by Elwood Downey, firstname.lastname@example.org
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:
Contributed by KJ7RRV.
HamClock is available in the Arch User Repository. The package names are:
Other versions might work but these are the versions I am using now.
Set the port to match the USB connection of your Huzzah.
To use a 9" ER-TFTM090-2 from buydisplay.com:
Select these options during purchase:
This is the wiring list:
EP = ESP Huzzah BM = BME280 sensor PC = photo cell DP = display EP_SCL BM_SCK EP_SDA BM_SDI EP_3V BM_VIN EP_GND BM_GND EP_ADC PC_1, 330k EP_GND PC_2 EP_3V 330k EP_SCK DP_8 EP_MO DP_7 EP_MI DP_6 EP_2 DP_5 EP_16 DP_11 EP_USB DP_3, 4, 37, 38 EP_GND DP_1, 2, 13, 31, 39, 40
The display stand from Adafruit can be made to work with a little ingenuity but is not perfect for the LCD. Send suggestions for better ideas and I will post here.
If you find your display idea works better 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:
HamClock would not be possible without the following resources (listed in no particular order):
HamClock was originally developed for the ESP8266 such as the Adafruit Huzzah. But after I created a porting layer, it may now also be built for Raspberry Pi, macOS, Ubuntu, FreeBSD, Windows WSL or most any other UNIX-like system supporting the X11 Windows system.
~/.hamclock/eeprom. Removing this file and restarting HamClock will reset it back to all default values.
cd curl -O https://www.clearskyinstitute.com/ham/HamClock/install-hc-rpi chmod u+x install-hc-rpi
nfollowed by Enter:
Do not use ssh unless you know what
ssh -X means.
cd rm -fr ESPHamClock curl -O https://www.clearskyinstitute.com/ham/HamClock/ESPHamClock.zip unzip ESPHamClock.zip cd ESPHamClock make -j 4 hamclock-800x480 sudo make install
openssl versionIf you see less than version 1.1 you really should update your system. But for now you can force an insecure connection by adding -k to the curl command like this:
curl -k -O https://www.clearskyinstitute.com/ham/HamClock/ESPHamClock.zipthen proceed with the same subsequent steps as above.
sudo apt-get -y install make g++ libx11-dev xserver-xorg raspberrypi-ui-mods lightdm lxsessionIf still trouble, note I only test on the latest desktop release of Raspberry Pi OS so if you are running something older it might help to upgrade.
sudo apt install curl make g++ xorg-dev
sudo pkg install gcc libX11 gmake curlthen use gmake instead of make.
sudo yum install gcc-c++ libX11-devel
makecommand above will build HamClock with 800x480 pixels. You can also make these sizes:
cd ~/ESPHamClock make -j 4 hamclock-1600x960 sudo make install
Note that if never run previously, HamClock will automatically set the full screen
option if the display size is the same as the size specified in the
cd ~/ESPHamClock mkdir -p ~/.hamclock cp hamclock.png ~/.hamclock cp hamclock.desktop ~/Desktop
If you would like HamClock to start automatically when you boot your RPi, try these commands:
cd ~/ESPHamClock mkdir -p ~/.config/autostart cp hamclock.desktop ~/.config/autostart
cd ~/ESPHamClock HCDIR=~/Desktop/HamClock.app 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:
To put it in the Dock:
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.