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.
https://www.balena.io/etcher/
u
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):
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:
https://www.clearskyinstitute.com/ham/HamClock/
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):
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:
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:
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.
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 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
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 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 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:
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_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
This website uses cookies to improve your experience. We'll assume you're ok with this, but you can opt-out if you wish. Cookie settingsACCEPT
Privacy & Cookies Policy
Privacy Overview
This website uses cookies to improve your experience while you navigate through the website. Out of these cookies, the cookies that are categorized as necessary are stored on your browser as they are essential for the working of basic functionalities of the website. We also use third-party cookies that help us analyze and understand how you use this website. These cookies will be stored in your browser only with your consent. You also have the option to opt-out of these cookies. But opting out of some of these cookies may have an effect on your browsing experience.
Necessary cookies are absolutely essential for the website to function properly. This category only includes cookies that ensures basic functionalities and security features of the website. These cookies do not store any personal information.
Any cookies that may not be particularly necessary for the website to function and is used specifically to collect user personal data via analytics, ads, other embedded contents are termed as non-necessary cookies. It is mandatory to procure user consent prior to running these cookies on your website.
