piWebCAT

8.1  Hamlib and piWebCAT  - introduction

From the Hamlib website:   https://github.com/Hamlib/Hamlib

Most recent amateur radio transceivers allow external control of their functions through a serial interface.

Unfortunately, control commands are not always consistent across a manufacturer's product line

and each manufacturer's product line differs greatly from its competitors.

Hamlib attempts to solve this problem by presenting a "virtual radio" to the programmer by providing

an API to actions such as setting a given VFO's frequency, setting the operating mode, querying the radio
 of its current status and settings,and giving the application a list of a given radio's capabilities.

Unfortunately, what can be accomplished by Hamlib is limited by the radios themselves
and some offer very limited capability.

Hamlib and piWebCAT - connection issues.

Hamlib has been growing for 12 years and now supports 250 radios.

I am indebted to one the main current developers, Michael Black, W9MDB for his help with connecting
to the rigctld API on the RPi.

piWebCAT commands all originate in the client (web browser). The commands from client to RPi server
are familiar internet URL of the form:  

   http://192.168.1.117/cat/phpfiles/wcajaxdata.php?rig=FTdx101D-H&param=METR.....

This launches a PHP program file on the server (here: wcajaxdata.php).

For each command, the PHP code has to create and open a communication socket to the Hamlib rigctld API.

Once the command is completed, the PHP process must die and so the socket is lost.
The next command has its own PHP process and must create  a new socket  etc etc.
This is how web servers operate and I have to live with this.

Hamlib's rigctl can be run at the RPi terminal command line.   See Section 8.5 rigctl at the command line
This is a very convenient way of testing command syntax on your rig,  eg:    \set_freq VFOA 3760000

Programs running on the RPi communicate with rigctl using rigctld via internet protocol socket localhost:4532.
piWebCAT's PHP code web server processes create and open a serial connection to this socket.

Hamlib does not support every available CAT command for a radio. For example, with the FTdx101D,
the contour control is not supported and neither are most of the very large list of menu settings.
However, the command \send_cmd_rx can be used to send rig-specific commands direct to the rig.
Examples, FTdx101D-H : contour is supported this way.  Also I have a button to toggle SSB audio input 

between front panel microphone socket and rear panel audio input (for use with Mumble VOIP)
- see section 8.14 unsupported commands

Hamlib - example - Applying FTdx101D configuration to my FT920.

CAT control of these two radios is very different. Key differences are:

• The F920 has Yaesu 5 byte command system. The FTdx101D has modern Yaesu ASCII text commands.  
• The FT902 has a very limited command set.
  The FTdx101D has a large CAT command set  - and I had configured a large number of these with Hamlib.

Experiment

I modified the FTdx101D-H configuration to communicate with the FT920 but did not change any commands.

..ie:  I changed:  USB to SERIAL, Baud rate from 38400 to 4800 and Hamlib rig number from 1040 to 1014.

Result: Slow intermittent start as Hamlib stalls on failing to process commands with no FT920 version.

       Intermittently able to tune, switch VFO and change band and mode  (intermiitent ... because stalls on

       control sync commands.) ,.... but at least we have some control, despite a very different CAT system.

The intial way forward is to disable all the controls that are not supported in FT920 CAT.

Hamlib - DUAL VFO issues

Hamlib rigctld has two modes of configuration in relation to dual VFO control:

• --vfo mode (where the rigctld start up commands includes --vfo.)
  This is appropriate for dual VFO / dual receiver transceivers which have separate CAT control access
  code for the currently selected foreground receiver AND for the background receiver.
  My FTdx101D is in this category and is used in the examples in this section.
  Note that some modern Yaesu transceivers need to use the terms Main and Sub in Hamlib's command
  strings, whereas many other use VFOA / VFOB. I have provided SQL scripts to automatically modify
  a transceiver configuration between the two options.
• not --vfo mode. Most Icom transceivers do not provide CAT access to the background VFO and so
  are probably better configured without --vfo mode. My example IC7000 configuration is in this catogory.
  piWebCAT can switch between the two VFOs but cannot access the background VFO.

--vfo mode is selected by setting vfomode = Y in the rig's record in the radios table.

Note that piWebCAT only has one set of controls which connect to the current VFO. The important issue
is  the fact that --vfo mode compatible transceivers have different commands for their two VFOs.
The CAT software therefore has to have a means of configuring these two command sets and for issuing the

appropriate commands for the current VFO.

I provide example configurations of --vfo mode and none --vfo mode on the SD card.

• Hamlib transceivers: Transceiver-H-A, Transceiver-H-B and Transceiver-H-C are a developing
  progression of three configurations using --vfo mode. (They use VFOA / VFOB. They will work with my
  FTdx101D but with slight VFO switching anomalies......until you change them to Main /Sub.)
• Hamlib transceivers: Transceiver-H-A-NV, Transceiver-H-B-NV and Transceiver-H-C-NV are a developing
  progression of three configurations in  none --vfo mode. (They use VFOA / VFOB). They will operate ok
  with my IC7000.

Hamlib rigctl documentation    https://manpages.debian.org/unstable/libhamlib-utils/rigctl.1.en.html

Hamlib example:

Setting noise reduction level in the FTdx101D and the IC7000.

The FTdx101D contains two completely separate receivers, Main and Sub.
They have their own separate NR level settings.

The IC7000 has two VFO settings but only a single receiver with a single NR level setting.

For the FTdx101D, the command for Main receiver is in text:   RL007;    first 0 for Main rx   07  is level (01 - 15)      

For the IC7000, the command is in hexadecimal digits:  FE  FE  70  E0 1A  05  05  01  14  07  FD   

07 is the data (00 - 15   bcd)    

Using Hamlib  rigctld:

For the FTdx101D (and many dual receiver rigs), I send:   \set_level Main NR 0.500  

Hamlib converts the range to 0.067  - 1.000  (piWebCAT can scale it to 1 -15 for display)

For the IC7000  (and many single receiver rigs)  I send:  \set_level NR 0.500

For the FTdx101D, I use --vfo mode which handles Main and Sub receivers. I have to insert 'Main' in all commands.

I could have used --vfo mode for the IC7000.  Its command would be  \set_level Main NR 0.500
 ...now identical to the FTdx101D command.

So, in summary, we can use the same command for 250 radios.
piWebCAT's data scaling and display facilities then tailor displayed data ranges to match the radio's levels.