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.
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 (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:
To update openssl on an RPi you can try
sudo apt upgrade openssl
To update on macOS try these possibilities:
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.1 or larger. If so, repeat your HamClock version update and it should work.
It depends on the message.
permission errorrelated to a certain file, probably you ran hamclock some time before directly or using sudo. If so, it's probably easiest to just start all over. See FAQ 3 about removing HamClock then go over to the Desktop tab and follow the instructions carefully.
Address already in useit means HamClock is unable to use a 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 (see FAQ 43 for how to run multiple hamclocks simultaneously).
To find the other program, 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.
Copy it down exactly and
email it to me.
Also, please attach the diagnostic file
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.
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.
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:
I have nothing against Geochron. If I have misrepresented Geochron in any way, please tell me how and I will correct immediately.
rej/spot 0 call_dxcc 226Because 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 0Thus, it's a good idea to create pairs of spider commands, one to engage and one to cancel each filter type.
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 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 ...
sudo raspi-config, open Advanced Options and make sure Wayland is disabled.
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 you liked in the file
~/.xsessionrc using your
favorite text editor.
Combine xrandr with 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.
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:
xrandr --size 1600x1200. You'll see the hamclock size jump.
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.
If you are looking for the RESTful API command interface, see FAQ 42.
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 192.168.7.101, then enter this
URL to run it from your browser:
Why would you use this?
make helpfor 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.
For example on macOS you can also start Chrome in real kiosk mode from the terminal command line as
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --kiosk http://<hamclock-address>:8081/live.htmlOther browsers/systems likely have similar controls.
Can I change the port?
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:
# allow https access to http hamclock <Location /hamclock-live/live.html> ProxyPass http://127.0.0.1:8081/live.html </Location> <Location /hamclock-live/live-ws> ProxyPass ws://127.0.0.1:8081/live-ws </Location>
a2enmod proxy proxy_wstunnel proxy_http
-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.
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.
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.
It's probably not wrong but I can think of two possibilities why you might think so:
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.
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 QRZ.com. So it depends which you consider correct.
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
$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:
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:
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 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 hcrss.pl (see the User Contrib tab).
In principle, yes. But it would add more stress to my backend server.
With few exceptions, HamClock does not store pane content. Each time HamClock updates such 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 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.
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.
Because you are forgetting the rules about pane choices covered in the User Guide. So again:
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.
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.
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.
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
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
It's either your host system or HamClock.
Let's check the host first. On RPi running Bullseye start a terminal
sudo apt remove xscreensaver
sudo apt autoremove
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):
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.
rig control daemon,
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
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
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 .
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
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.
It will run but you won't see much.
HamClock connects to clearskyinstitute.com 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.
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.
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.
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.
HamClock only supports the Idle timeout and On/Off timers in the following situations:
Maybe, but I haven't been excited enough to try for several reasons:
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.
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
|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_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 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=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_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|file|network|interval=secs|on|off||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_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|
|exit||tells HamClock to exit (not ESP)|
|live.html||page with which HamClock can be controlled from a browser (not ESP)|
|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:
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
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 'http://192.168.7.101:8080/set_sattle' --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:
Set Live Spots to report spots made by DE call using wspr on 40, 30 and 20m
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 QUIET PLEASE white on red:
curl --get 'http://192.168.7.101:8080/set_title' --data-urlencode 'msg=QUIET PLEASE&fg=255,255,255&bg=red'
... then restore as per Setup:
Change map to Azimuthal projection with Countries style and RSS on, leaving Grid unchanged:
Turn off RSS network feed and clear the local title list:
Turn off RSS network feed and add one RSS title to local list:
curl --get 'http://192.168.7.101:8080/set_rss' --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' 'http://192.168.7.101:8080/set_rss?file'
Restore normal network RSS operation:
Set map grid color to yellow:
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
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
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.
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.
i2c-ch341-usb.cline 660 from
ch341_dev->irq_descs[i] = irq_to_desc(ch341_dev->irq_base + i);to
ch341_dev->irq_descs[i] = irq_data_to_desc(irq_get_irq_data(ch341_dev->irq_base + i));
lsmodand check the
i2c_ch341_usbmodule is installed.
ls /devand confirm there is a node named
sudo i2cdetect -y 1and confirm it shows the I2C address of your BME280, either 77 or 76.
GPIO?has changed to
IIC?because full GPIO is not supported. Toggle
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.
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.
The accuracy of the reports depends on several factors.
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:
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.
Send me a 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
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
Contributed by Joeri van Dooren, ON3URE
Contributed by Thanasis, M7SYR
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.
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
but these can be changed with the
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:
hceeprom.pl NV_CALLSIGN NV_CALLSIGN = WB0OEW
Set a new call sign:
hceeprom.pl NV_CALLSIGN AB1XYZ NV_CALLSIGN = AB1XYZ
Set the DX cluster host:
hceeprom.pl NV_DXHOST usdx.w1nr.net NV_DXHOST = usdx.w1nr.net
Set DX spots to show as full call sign
hceeprom.pl NV_MAPSPOTS 2 NV_MAPSPOTS = 2
Set the BME280 at I2C address 77 temperature correction:
hceeprom.pl NV_TEMPCORR2 -0.23 NV_TEMPCORR2 = -0.23
Contributed by Elwood Downey, firstname.lastname@example.org
hcgetsw.sh queries HamClock for the most recent value of any space weather
data it provides.
Run the script with -help for a complete list.
Contributed by Elwood Downey, email@example.com
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:
hcrss.pl 192.168.7.117 https://www.arrl.org/news/rss
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.
Contributed by NI2O.
This pdf shows how to configure HamClock to operate in an LXC container on a ProxMox server.
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:
make -j 4 hamclock-web-1600x960
$ tmux ./hamclockallows 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.
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
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 'https://clearskyinstitute.com/ham/HamClock/hamclock-contrib.zip' unzip hamclock-contrib.zip 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
and you should get a new HamClock.
Try these additional tests to understand different use cases:
-moption 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.
-ihours are eligible for reassignment to handle the new connection. The default is 24 hours.
-toption 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 &
-vfor debug info and try to reproduce the problem. Send me the log if it seems like a bug.
-doption, the default is
-aoption 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.
ps ax | egrep 'hamclock|hcwebproxy' | grep -v egrepThe processes with status T are sTopped.
Contributed by WB0OEW.
Copy/paste the following into a file named
hccurl and use
it to send commands to hamclock that require embedded spaces.
#!/bin/bash # 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 192.168.7.101 8080 set_title "'"'msg=QUIET PLEASE&fg=255,255,255&bg=red'"'" echo Example get: hccurl 192.168.7.101 8080 get_config.txt else HOST="$1" PORT="$2" CMD="$3" if [ $# -eq 3 ] ; then curl --get "http://$HOST:$PORT/$CMD" else VALU="$4" curl --get "http://$HOST:$PORT/$CMD" --data-urlencode "$VALU" fi fi
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 https://github.com/zeidlos/hamclock-docker.
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.
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:
HamClock may be built for Raspberry Pi, macOS, Ubuntu, FreeBSD, Windows WSL or most any other UNIX-like system supporting the X11 Windows system.
cd curl -O http://www.clearskyinstitute.com/ham/HamClock/install-hc-rpi chmod u+x install-hc-rpi ./install-hc-rpi
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
sudo apt-get update sudo apt-get -y install curl make g++ libx11-dev xserver-xorg linux-libc-dev lightdm lxsession openssl
sudo apt install curl make g++ xorg-dev libx11-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
cd ~/ESPHamClock mkdir -p ~/.hamclock cp hamclock.png ~/.hamclock cp -p hamclock.desktop ~/Desktop
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
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.