New Ham~Clock

         RPi Notes for    HamClock

These notes form a companion guide to the presentation “Building your Own HamClock” given by Alan, G4FZP at the Bury Radio Society meeting on 17th Jan 2023. All you need to know should be within. If you get stuck or have any questions, feel free to nab Alan down at the club or contact him via the club email facility.

Setting Up the Pi – Start Here

Download the free program Balena Etcher to your PC and install it.

Find and download the appropriate Raspberry Pi OS with Desktop image file for your model of Pi. You don’t need the one with recommended software included, just desktop.

Use Balena Etcher to burn the image file onto your SD Card.

Insert the card into the Pi along with a network connection (cable), a USB keyboard and mouse, and an HDMI connection to a monitor.

Power up. Watch the display and answer the questions as required to set up the RPi operating system.

When you have finished you should have a functioning Raspberry Pi with a graphical desktop environment. You don’t need to install any additional tools or programs beyond this.

If required, and if you haven’t already done so, now is the time to set up a WiFi connection and/or to enable remote access via SSH etc. If you’re not sure how to do this, Google is your friend.

Get everything the way you want it before you proceed any further.

Installing ZRAM (optional)

If you’re planning to build HamClock on an old model Pi then installing zram, as described here, right at the beginning will speed things up a fair bit.

zram, formerly called compcache, is a useful module for creating a compressed block device in RAM, like the RAM-Disks of old, but with on-the-fly “disk” compression. The block device created with zram can then be used by the computer as a swap file – much faster than a swap file on a hard disk and light-years faster than a swap file on an SD card (ugh!).

The RPI ZRAM from novaspirit improves this even more by automatically detecting the number of CPU cores to allocate to ZRAM computation, disabling the existing swap and enabling ZRAM swap all in one go. That’s what we want.

To install zram you need to open and use the command-line terminal which you can do from the graphical desktop. Do this by clicking on the red Raspberry → Accessories → Terminal.

Below are the commands to install RPI_ZRAM (use copy/paste to avoid typos):

Download the script and copy to /usr/bin/ folder

sudo wget -O /usr/bin/

make file executable

sudo chmod +x /usr/bin/

edit /etc/rc.local file to run script on boot

sudo nano /etc/rc.local

add this line before the line that says ‘exit 0’

/usr/bin/ &

Save the file and exit from the nano editor. Then reboot the pi with

sudo shutdown –r now

Installing HamClock

First, have a look at the HamClock website:

Lower down the page is a series of horizontal tabs with lots of useful info including the full operating manual. The Desktop tab gives installation instructions.

To install HamClock follow these steps. They assume your RPi is up and running Raspberry Pi OS with Desktop.

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.

Download the installer script by running the following commands (use copy/paste to avoid typos):


curl -O

chmod u+x install-hc-rpi

Now run the script by typing the following command.


As the installer runs answer each question by typing y or n followed by Enter:

If something goes wrong, look through the detailed instructions on the website. But if all goes well that's it! Be sure to read the User Guide to get the most from HamClock.

If you chose not to install a desktop icon, you can run HamClock from the terminal at any time by typing this command:

hamclock &

Uninstall HamClock

You can remove all traces of HamClock by typing the following commands in a terminal or ssh session:

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

rm -fr ~/.hamclock ~/ESPHamClock*

Configuring HamClock

Start HamClock for the first time and enter the setup program as prompted on the screen.

There are multiple pages of setup options. All of them are well documented at the beginning of the user manual.

Initially, set up only your callsign and home latitude/longitude then save and start HamClock.

Reason for this is that from experience some options will allow you to break things to the point where it all no longer works, and if you’ve done multiple things you’ll have no idea which of them is causing the problem. Customise your HamClock bit by bit until you get it the way you want. You’ll have the option to jump back into setup every time your HamClock starts up and all your previous settings will be remembered.

Install Xrandr

One of the HamClock options you’ll definitely be selecting is ‘Use Full Screen’.

But 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 around that image with black.

To fix this you can try a command line program called xrandr to expand HamClock to fill the entire monitor 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 to undo if you get the command wrong or 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 I can expand HamClock to fill the screen and eliminate those gaps.

The best way to try it is to log in from some other computer with SSH (you can use PuTTY) so we aren't trying to adjust the same screen we are using for typing our commands.

Run the following command while HamClock is running on the monitor 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 the value of scale-from a little.

If xrandr gives some other error, then make sure you're not using Wayland. To check, run sudo raspi-config, open Advanced Options and make sure Wayland is disabled.

If at any time you want to go back to normal display, just run xrandr again with your original screen size:

xrandr --output HDMI-1 --scale-from 1920x1080 --display :0

Modify these values to accommodate your particular combination of HamClock and display sizes as needed until you get HamClock just filling the entire monitor.

The display adjustment is done using non-square pixels within the X server. This doesn't usually matter much but if you often run the analogue Big Clock inside HamClock you may notice it is no longer circular. If this bothers you, adjust the xrandr dimensions to find a compromise between filling the whole 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 Pi, put the xrandr command you liked in the file ~/.xsessionrc using your favorite text editor (Nano will do, you used it earlier).

If you combine xrandr with autostart (see further instructions) you can arrange for HamClock to start up automatically at truly full screen size directly from RPi power up.

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

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

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

Icons and Autostart

If you would like a Desktop icon with which to start HamClock on RPi, try these commands:

cd ~/ESPHamClock

mkdir -p ~/.hamclock

cp hamclock.png ~/.hamclock

cp hamclock.desktop ~/Desktop

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

The above shows one method.

This next method is the one my HamClock uses. Basically autostart requires your filename.desktop file(s) to be located here for pi user: /home/pi/.config/autostart/

or here for any other user /home/{user}/.config/autostart/

You may need to create the autostart directory at the location if it is not already present.

If you look in there you should see the HamClock.desktop file that autostarts HamClock if you enabled that option in HamClock’s setup.

Copy and edit the contents of that file to create a second file called for example xrandr.desktop to also autostart xrandr. Note the sleep parameter in the file allows you to establish a suitable sequence as all the .desktop files are otherwise processed in parallel.

Here’s the HamClock.desktop file:

[Desktop Entry]


Exec=/bin/sh -c 'sleep 2; /usr/local/bin/hamclock'




And here is one I created from it to run xrandr:

[Desktop Entry]


Exec=/bin/sh -c 'sleep 20; xrandr --output HDMI-1 --scale-from 1600x960 --display :0'




HamClock Web Interface

Yes, HamClock has a web interface too!

Use a browser to load the page live.html on port 8080 from the Pi that is running hamclock. For example, if the IP of the Pi running HamClock is, then enter this URL to view it from your browser:

Some notes:

HamClock will be centered if smaller than the browser window, else it will be shrunk to fit. If the image looks chunky, build HamClock at a larger resolution.

Keyboard and mouse input work the same way if you first click on the HamClock image to give it focus.

Multiple simultaneous browser connections are supported if they each come from a different IP address. Multiple connections from the same host will appear at first to work, but they will soon become pixelated and out of sync with the real clock display.

To reset a browser session for any reason, just refresh the page.

Tested fine with Chrome 101 and Safari 15.5, Firefox 100 not so good however.

Screen blanking and timed on/off are not supported in the web page view -- use your host's facility.

If bandwidth is a concern, the lowest bandwidth occurs when the map Night option is off and HamClock is made at 800x480.

Why would you use this?

It's a convenient way to configure a HamClock that runs on a Pi to which you normally do not have a keyboard and mouse connected.

It's an easier alternative to VNC or remote X servers.

It allows displaying one HamClock on multiple monitors simultaneously.

You can even 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.

Plus, building HamClock this way can save significant storage space because you don't need any of the graphics packages mentioned in the Desktop build instructions (at least not for 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>:8080/live.html

Other browsers/systems likely have similar controls.

Controlling HamClock via the Web Interface

In addition to the live display, HamClock also provides a scripting RESTful command 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.

Syntax Summary
get_capture.bmp Save screen as bmp file
get_config.txt Report current HamClock configuration settings
get_de.txt Report DE info
get_dx.txt Report DX info
get_dxspots.txt Report current list of DX cluster spots
get_satellite.txt Report current satellite position 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
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).
set_livespots?spot=of|by&what=call|grid&data=psk|wspr&bands=all|160,... Change Live Spots configuration
set_mercenter?lng=X Set a new center for the Mercator map; not persistent across restarts.
set_mapcolor?setup_name=R,G,B Set one of the Setup colours, replace each space with underscore.
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_rss?reset|add=X|file|network|interval=secs Set local RSS 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_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 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=W&tz=DE|UTC Set VOACAP map band and/or power and/or timeline units; disable map if nothing
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:


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: this TLE will be out of date, it is shown just as an example of proper syntax.

curl ' 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 ' PLEASE&fg=255,255,255&bg=255,0,0'

... then restore call sign:

curl ''

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

curl ''

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 ' 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 ''

Set map grid colour to yellow:

curl ',255,0'

Note: as of curl 7.78 URLs with embedded spaces are no longer allowed. Spaces have always been illegal but curl was not enforcing the rule and now it is. To use curl 7.78 or newer when a URL must include embedded spaces:

specify --get to force curl to use the GET http method

break out the host spec and command portion of the URL as a separate argument to curl

set the remaining contents of the URL as a separate argument preceded with --data-urlencode

drop the ? altogether in the URL

Some examples above that are affected by this change would be rewritten as follows:

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'

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

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

Note also that the issue of embedded blanks does not apply if you send commands to HamClock by typing them into your browser. Browsers always perform the proper encoding so embedded spaces are still allowed.

You can change the port that HamClock uses for its web interface with the -w command line option. So for example, to change to port 8081, run HamClock as follows:

hamclock -w 8081