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/zram.sh https://raw.githubusercontent.com/novaspirit/rpi_zram/master/zram.sh
make file executable
sudo chmod +x /usr/bin/zram.sh
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/zram.sh &
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):
cd
curl -O http://www.clearskyinstitute.com/ham/HamClock/install-hc-rpi
chmod u+x install-hc-rpi
Now run the script by typing the following command.
./install-hc-rpi
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 1600×960 –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 1920×1080 –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]
Name=HamClock
Exec=/bin/sh -c ‘sleep 2; /usr/local/bin/hamclock’
Icon=/home/pi/.hamclock/hamclock.png
Terminal=false
Type=Application
And here is one I created from it to run xrandr:
[Desktop Entry]
Name=ScreenSize
Exec=/bin/sh -c ‘sleep 20; xrandr –output HDMI-1 –scale-from 1600×960 –display :0’
Icon=/home/pi/.hamclock/hamclock.png
Terminal=false
Type=Application
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 192.168.7.101, then enter this URL to view it from your browser:
http://192.168.7.101:8080/live.html
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 800×480.
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-1600×960
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.app/Contents/MacOS/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 ‘http://192.168.7.101:8080/get_time.txt’
Set display to turn on Wednesday at 8 AM and off at 10 PM, DE time, with 10 minutes idle time:
curl http://192.168.7.101:8080/set_displayTimes?on=8:00&off=22:00&day=Wed&idle=10′
Set a new DE location from latitude and longitude:
curl ‘http://192.168.7.101:8080/set_newde?lat=40.7&lng=-74’
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: this TLE will be out of date, it is shown just as an example of proper syntax.
curl ‘http://192.168.7.101:8080/set_sattle?name=ISS&t1=1 25544U 98067A 21320.06051688 .00001570 00000+0 37172-4 0 9998&t2=2 25544 51.6441 311.7573 0004586 201.9414 260.8823 15.48581357312130’
Set satellite to ISS and report current ephemeris with respect to DE:
curl ‘http://192.168.7.101:8080/set_satname?ISS’
Set Live Spots to report spots made by DE call using wspr on 40, 30 and 20m
curl ‘http://192.168.7.101:8080/set_livespots?spot=by&what=call&data=wspr&bands=40,30,20
Set Pane 3 to rotate through NOAA Space weather, X-Ray flux and DRAP trend:
curl ‘http://192.168.7.101:8080/set_pane?Pane3=Space_Wx,X-Ray,DRAP’
Toggle the screen lock padlock:
curl ‘http://192.168.7.101:8080/set_touch?x=224&y=132’
Change call sign to say QUIET PLEASE white on red:
curl ‘http://192.168.7.101:8080/set_title?msg=QUIET PLEASE&fg=255,255,255&bg=255,0,0’
… then restore call sign:
curl ‘http://192.168.7.101:8080/set_title?’
Change map to Azimuthal projection with Countries style and RSS on, leaving Grid unchanged:
curl ‘http://192.168.7.101:8080/set_mapview?RSS=on&Projection=Azimuthal&Style=Countries’
Turn off RSS network feed and clear the local title list:
curl ‘http://192.168.7.101:8080/set_rss?reset’
Turn off RSS network feed and add one RSS title to local list:
curl ‘http://192.168.7.101:8080/set_rss?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:
curl ‘http://192.168.7.101:8080/set_rss?network’
Set map grid colour to yellow:
curl ‘http://192.168.7.101:8080/set_mapcolor?Map_grid=255,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 ‘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’
curl –get ‘http://192.168.7.101:8080/set_title’ –data-urlencode ‘msg=QUIET PLEASE&fg=255,255,255&bg=255,0,0’
curl –get ‘http://192.168.7.101:8080/set_rss’ –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
