Topic	Installing Hamclock & Hamlib on a Raspberry Pi 4
Subtopic	CAT Control
Equipment Required	Computer + Internet+Raspberry Pi (Pi 4 preferred but should work on Pi 3b)
Costs	SD Card + Raspberry Pi 4
Document last reviewed and updated (reviewed each year)	3rd September 2023 – tested all Instructions for accuracy
	



Introduction

If you have read the previous article (https://vkhamradio.com/hamlib-or-flrig-or-omnirig-for-transceiver-cat-control/), we spoke about a Raspberry PI and using it for Hamlib (Rigctl). However it would be a waste to use the Raspberry Pi just for Rigctl.

Installing HamClock on the Raspberry Pi as well would make good use of the Raspberry Pi. I have had this running on Ubuntu on a desktop as well, but thought since Raspberry Pi availability is back, the costs are now back in a realm that you always keep a spare ready for the next project, it was now time to put an article up on the setup.

Now you are probably thinking that there are a few distros out there that have at least Hamlib and some have HamClock installed on them (even some on the Pi). You are absolutely right and I have tried a number of them. If you are after a Windows Desktop replacement and want a Linux system with everything installed, these systems are great, especially if you have limited experience with Linux. However I grabbed a few of them and spent many hours resolving build faults as some of the scripts are out of date due to updates to the Operating System causing failures, or when trying to perform updates to the installed applications, but as you have gone for a prepackaged / everything installed package, you did not know that package xyz had a directory structure change a year or so ago, which needed to be manually completed and now you sit with an application that is now broken.

For this reason, you learn much more about applications if you install and compile them yourself. Now with Hamlib/Rigctl, that is exactly what we are going to do. With Hamclock we are going to use a script which is from the HamClock site. It is more to save time and you can look at the script if you have problems. In fact if you want to look at the script via your browser, just drop this address onto your address bar of your browser https://www.clearskyinstitute.com/ham/HamClock/install-hc-rpi, and you will see a well documented script, and you will see that it downloads and compiles the latest hamclock on your Pi, the rest of the script is automation, saving you time.

So to cover why it is better to build and compile is the following

• Downloading the latest version
• Access to the information on the build process from the developer
• Using a current and updated operating system
• You can see compile errors and ask other users and the developers questions
• You understand the application better

I fully recommend the use of Dummy load connected to your Rig whilst you are testing CAT control applications. Whilst you would generally be careful, it is possible that with incorrect serial settings, that it could accidentally transmit at 100W or more. Remember CAT controls the power settings as well.

So lets build!

You are going to need an 8Gb MicroSD Card but better off with a 16Gb or 32Gb card for possible future growth.

We are going use the standard Pi operating system as at September 2023 which is the Raspian Pi (32-Bit) – a port of Debian Bullseye

It was released on 2023-05-03

We are going to use the Raspberry Pi Imager which you can get for your Operating system from this URL

https://www.raspberrypi.com/software/

Build Bullseye using Pi Imager

1) Choose OS – Select Bullseye 32 Bit

2) Choose Storage – Select your SD Card – Double check it is the right card

3) Click on the Setup Cog Icon

4) Select the settings you want to use – an example is shown below

Naturally if you are going to use a Wireless connection, add your SSID and Password for your wireless

If you have solid wireless at home, why not setup the Pi for wireless reducing one more cable.

5) Click on Write and go an make a cup of coffee

When it is completed, now add the SD Card to your Pi (with the Pi turned off for safety)

Turn on your Raspberry Pi and it will automatically login on boot

Go to terminal screen on the Raspberry Pi and run the command

sudo ifconfig

to confirm IP address unit has (if you have wireless and wired connections on the Pi, you may have two IP addresses – select the one you will probably use)

Once we have this IP address, we can do the rest of the setup remotely from your favourite workstation (or you can can do it on the Raspberry Pi – your choice)

SSH to the Pi from another workstation (if you are doing it remotely)

Use the login and password you set in Pi Imager

issue the following commands

sudo raspi-config

Now Select the following

Select 8 – update – this will update the raspi-config to the latest

Select 3 – Interface options

Select I3 – VNC

Answer “Would you like the VNC Server to be enabled?” Yes

On your remote workstation download RealVNC from

https://www.realvnc.com/en/connect/plan/lite/

Don’t worry about the pop-ups telling you about a 14 day trial, VNC Connect is a different product to what we are using.

Install and execute – the following screen should appear

Enter your IP address of your Raspberry Pi that you got earlier

Now the following screen with appear

Enter the username and password that you added in the Pi Imager settings

You should now see the next screen

You should now see the Rraspberry Pi screen remotely on your workstation, similar to below

If this working, then we need to bring Bullseye up to date. Now you have two choices, you can open a terminal window on the Pi desktop or you can use your favourite SSH Client on your remote workstaion and issue these following commands

sudo apt update
sudo apt upgrade

Press Y at the “Do you want to Continue? [Y/n]

This will bring the Bullseye Operating System up to date.

Now we download the current latest version of Hamlib with the following command

sudo wget https://github.com/Hamlib/Hamlib/releases/download/4.5.5/hamlib-4.5.5.tar.gz

Now to unpack it

cd ~/
tar -zxvf hamlib-4.5.5.tar.gz

and now to compile it

d hamlib-4.5.5
./configure
make -j 4
sudo make install
sudo ldconfig

Once it is finished compiling, if you want to check that it has compiled and installed correctly and the screen should look similar to the one below

Lets perform a reboot now and as soon as it is rebooted, open a terminal window again and just issue the command

rigctl

and it should come back with Rig Command: as per the image

if this works, just press Control-C to exit as we still have a little work to do

So what we need to do now is a series of items, so that we can confirm the correct command line we will need

So what we have installed can be activated by two commands

rigctl – application that just like an exe file, when you are finished you close it and it is no longer running
or
rigctld – Service application daemon – we can leave this running as a service

Now to get things tested first, we are going to use rigctl

Confirming your Rig Number

type

rigctl -l

this will list off all the rig configurations compiled in this version of hamlib

We are going to improve on this command by using grep to search for the exact rig I am using (you will look for yours)

rigctl -l | grep FTDX10

This will then provide a small list where I can confirm the correct rig number.

So in my case, the rig number is 1042 – Note this number down (your rig of course) – we are going to need it
If grep is not showing your rig, try the manufacturer instead (e.g rigctl -l | grep Icom)…this will be a longer list to search through…but may assist you finding your RIG

Finding your USB Port

perform the following commands at the Linux command line

cd /dev
ls

This is with the USB unplugged from the Pi (the red square indicates the area we are looking at)

Now plug in the CAT USB Cable from your rig

cd /dev
ls

This is with the USB plugged into the Pi, as you can see we now have two additional virtual USB Ports showing up

So we are going to use the first Virtual USB port which is

ttyUSB0

Confirm your Baudrate for your CAT interface

Read you manual or check google for your default baud rate for your CAT interface. In some cases, this can be set in the radio configuration, so you might get it from there.

In my case, the manual for my rig says 38400

So make sure you document these items

Your table should look similar, possibly with different settings……

Building our command line and testing

Now we have those deatils lets build our command line…..

So with those details above, my command line will be the following

/usr/local/bin/rigctl -m 1042 -r /dev/ttyUSB0 -s 38400

which if I execute this on the command line, it should come up with the following screen if everything is working correctly

lets do a couple of simple commands

f – will get the current frequency of the rig (usually VFO A)
v – will return the current VFO
m – will return the current mode and passband

If everything is working then that is great!.

Our final command line

/usr/local/bin/rigctld -m 1042 -r /dev/ttyUSB0 -t 4532 -s 38400

As you can now see, all those settings now feed into the final command line.

If you are observant, you will notice some changes….

• We have changed the command from rigctl to rigctld – changing to using the daemon.
• We have added -t 4532 to the command – telling rigctld what port to listen on for commands, in this case TCP port 4532

Some final housekeeping

We need to create the rigctld service, so at the command line the following command

sudo nano /etc/systemd/system/rigctld.service

This will open the Nano editor. Add the following lines….

[Unit]
Description=rigctld Hamlib
After=syslog.target network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/rigctld -m 1042 -r /dev/ttyUSB0 -t 4532 -s 38400
ExecReload=/bin/kill -HUP $MAINPID
RestartSec=60
Restart=always
User=rigctld
Group=rigctld
[Install]
WantedBy=multi-user.target

Remember, your command line will be different based on your settings, so substitute your values on the ExecStart line

now we need to setup a user to run the service under, so issue each of these commands in order….

sudo adduser rigctld –system –group –home /var/lib/rigctld
sudo adduser rigctld dialout
sudo usermod rigctld –expiredate 1
sudo systemctl daemon-reload
sudo systemctl enable rigctld.service
sudo systemctl start rigctld.service

The final line starts the rigctld service, so it should now be functional

we can check the service is running by

sudo ps aux | grep rigctld

and we should see it listed as a running process as below

sudo netstat -anp | grep 4532

which should show that rigctld is listening on port 4532 as below

and finally lets use your favourite terminal application (e.g. Putty or similar) to confirm that we can perform commands remotely (e.g. great if you can do this on a different machine

just remember, we are not doing SSH, we are just telneting via port 4532, so putty needs to be setup as per the example and click on open

you should see a similar screen to this after you have tested with the couple of commands we used before.

Now lets perform a full reboot and confirm that it comes back online and rigctld is contactable

Again use Putty and confirm your hamlib connection is working.

If this is working, now we can move onto the next section which is installing HamClock

Installing HAMCLOCK

Again you can do this remotely using SSH or the terminal open on the Pi OS

the following command will download the script from the ClearSkyInstitute site

curl -O https://www.clearskyinstitute.com/ham/HamClock/install-hc-rpi

The next command will make the script executable

chmod u+x install-hc-rpi

Now finally we are going to execute the script

./install-hc-rpi

click on yes to proceed

Now it ask a series of questions

Screen display size
Select 1 800 x 480 if not sure about your screen size capability
Select 2 1600 x 960 if you have a screen with that or larger resolution

Now don’t panic about getting this right – I will show you how to change this very easily later on.

Next questions are
Hamclock Desktop Icon : Y
Install user guide on Desktop : Y
Install HamClock Man Page : Y
Try running hamclock now : Y

As soon you answer the last one, it will start up HamClock

NOW let me say this, we don’t want to perform Hamclock internal setup yet – resist the urge as you will spend longer and possibly not
achieve the results that you want. At this point we just want to get the best possible screen layout, and we want
to be able to close the window, adjust, recompile, test in a matter of seconds….if you start to setup, the process
will take longer…..

So, let it complete its countdown, do not a button orclick on screen. It will start up in an unconfigured mode, which is what we want…..

So have a look at the screen…..
1) Does it fill out most of the screen?? (don’t panic if not….it does have a padding option)
2) Does it overflow the screen?? (We may need a new resolution setting for Linux or Hamclock)

Look at the next screenshot and confirm that you can see all of it on your screen.

Now I can’t tell you step by step on how to achieve the best screen layout outcome as everyones system will be different but I can tell you the steps that you will need to take (of which there are two main steps…..)

Adjusting Screen – Screen Configuration

This is access via the PI Menu under >> Preferences >> Screen Configuration

You are looking for the highest resolution where it will display hamclock you compiled

As you can see from mine, I utilsed the highest, but I tried several others beforehand finding this worked for me in the end.

Recompiling HamClock for different sizes

open up a terminal screen

And these are the three lines that you need to recompile a new size

cd ~/ESPHamClock
make -j 4 hamclock-1680×960
sudo make install

and these are four options

hamclock-800×480
hamclock-1600×960
hamclock-2400xx1440
hamclock-3200×1920

e.g. replace the hamclock-1600×960 with one of these sizes.

Now you may find that it will take several goes of finding the right/best combination of screen sizes in Linux and resoutions in Hamclock and you will see the reason why I said RESIST setup of Hamclock until we had the right screen size. The reason is that we still have hamclock in a window, which we can shift the Windows and quickly close HamClock by clicking on X to close the Window.

To start the clock again, you just click on the Hamclock icon. Being able to open and close in seconds will reduce your frustration in getting it looking the best.

Once you have it displaying a good as possible (it might still be in a Window which we will change in Setup), we are now going to perform the setup. Now I am not going to go through all of the Hamclock internal configuration, as this is covered by HamClock Guide – HamClockKey.pdf which is sitting on your desktop and there are many specific guides on HamClock internal setup on Websites or Youtube.

However I will give you a couple of pointers

When the main setup screen appears click in the middle of the screen to start Setup on Page 1

• Update the call sign to your own
• Update the Latitude and Longitude (in Decimal) – surely you have a document or page by now that has all of your Long/Lat Grid settings in the various formats – Hamclock setup will update the grid correctly
• If you have a GPS connected , you can have it use this for your setings – but if you are stationary, entering the settings correctly above, will be fine and you generally do not want to use IP Geolocate using your ISP’s IP address which is probably the least accurate.
• Leave Wifi as No (even if you have wifi setup on the PI)

NOW DON’T CLICK DONE – the PAGE 1 up the top is a button, click on the less than sign to go backwards or the greater than sign to go to the next page

On Page 3, there is one option you can select which is

rigctld : Y
Once you do this, it will show up Port : 4532 and Host: Localhost automatically as these are the defaults and what we setup rigctld to work with.

On Page 4,

Under the Map Centre lng (no this is not language – but Longitude of your location for centering of the map
this will be e.g. 153E

on Page 5,

Date Order : Day Mon Year – the correct way for Australia 🙂
Week Starts : Monday – the correct day for Australia along with the majority of other countries
Units : Metric – The correct standard for Australia
and the the rest you can leave as default except for the last line
Full Scrn : Yes (this is important if you want Hamclock to take over the screen

Finally, you can page through and look at other pages, but it will finally come back round to page 1, where if you are finished for the moment, you can SELECT DONE

Even using the defaults and the changes that I have recommended….it is mostly completed

Once you have got it looking good….we just need a few more lines, so that the hamclock auto starts

So again at the Linux prompt issue the following commands

cd ~/ESPHamClock
mkdir -p ~/.config/autostart
cp hamclock.desktop ~/.config/autostart

Now perform a reboot and make sure it starts up. Two things should occur

1. On boot the Pi should immediately start up HamClock
2. With your Rig On, you should be able to Telnet from a remote PC and issue CAT Commands

If this is all working, you are complete

Final Recommendations

Now I have two recommendations before you put this into service.

The first one is very important. Our Pi is currently getting our IP address (Wireless or Wired) as a dynamic IP address from our home router. Now this address could stay the same for months, possibly years, but at sometime, it will change, and it will be when you least expect it and you will spend hours trying to resolve the fault to find that your router gave your Pi a new IP address, after the last power outage, or when you upgraded the firmware on your router. There are several ways to do this, however, the safest, absolute way is to set a static IP address on the Network interface on the Pi. There are sites dedicated to this process, so I won’t replicate here…..but your starting point is the Raspberry Pi GUI, clicking on the network icon at the top right – yours may be two arrows or a Wireless symbol. From there you can set a permanent static ip address.

The second is not as critical, but still important, and this is to do with the USB port name. If you do not touch your Pi, it will probably never change. Again, writing an article on how to perform these changes goes well out of the scope of this article, but a pointer to a site that provides this information is

https://www.freva.com/assign-fixed-usb-port-names-to-your-raspberry-pi/

But for your benefit, I have not used this in this project, making sure that I check this whenever I make hardware changes to the Pi.

A few notes on Connecting Common applications with Hamlib/RigCtl

Here a few examples of applications that utilise Hamlib CAT Control showing their config pages. There are probably many more, but these will give you the idea and show you that Hamlib/RigCTL is one of the more popular methods of network based CAT control.

WSJTX

Fldigi

Log4OM

Just not a quick note the LOG4OM config page, if you have started CAT control, you will see the page is greyed out and no changes can be made. If this is the case, go back to settings and select CAT Engine back to nothing (Save and Apply). You will see it will disconnect CAT and the page will be available to make changes again.

Postscript

Finally one more important note and the fact that it happened to me, shows it can happen to anyone.

Backup your SD Card with Win 32 Disk imager once you have a working system. Working in IT for 40+ years, I always have backups or rollback plans. Today I broke my rule and did some experimentation without a backup (sure I had all the instructions and it was a good way to test those instructions), but it was time consuming doing it all over again and their are opportunites for mistakes.

You can download the Win 32 Disk Image from https://sourceforge.net/projects/win32diskimager/

You can find guides on the web, but above are the settings I used. It will take a while depending on the size of your SD Card, but I think it is worth it. If an upgrade goes wrong or your SD Card suffers a corruption common to power issues with the Pi, you will feel a whole lot better knowing you can restore it back to the way it was.