mhuxd - Daemon for microHam Keyers

©DJ5QV
Doc version 0.90

1. About

Mhuxd is a device router for microHam keyers. It runs on the Linux operating system only. Supported microHam keyers are:

micro KEYER
micro KEYER II
micro KEYER III
DIGI KEYER
DIGI KEYER II
MK2R & MK2R+
CW KEYER
Station Master / Station Master DeLuxe (experimental)

1.1. Features

Designed to run permanently in the background
Automatically detects any supported microHam keyer, once switched on or connected to the computer
Supports multiple keyers simultaneously
Built-in web server to perform configuration changes via a browser
Provides configurable virtual serial ports (VSP) and routes those to specific keyer channels (e.g. CAT, K1EL Winkey, PTT, FSK etc.)
Provides TCP/IP network ports (IPv4 and IPv6) if desired
Configuration of the K1EL Winkey chip, including CW/FSK message memories via browser
Supports configuration of the microKEYER II / III displays
RIG Mode Sync: keeps the keyer mode and the frequency known to the keyer in sync with the rig, either by decoding the CAT traffic of your applications (backend native) or through Hamlib’s rigctld
Several applications can share the rig’s CAT port, each on a port of its own (backend native)
Optionally starts and stops Hamlib’s rigctld together with the keyer
Antenna switching configuration for Station Master (experimental)
REST API and WebSocket interface, used by the web interface

1.2. License

Mhuxd is available under the GNU General Public License, version 2.

ClearSilver is licensed under the New BSD license. mhuxd still uses it to read the configuration file of older mhuxd versions.

1.3. Acknowledgements

microHam – For providing the protocol specification and support
Marc Lehmann and Emanuele Giaquinta – For libev
Brandon Long – For the ClearSilver template system
Igor Sysoev, Joyent Inc. et al. – For http_parser
Google Inc., Filipe Almeida – For streamhtmlparser
Petri Lehtinen - For libjansson

2. Installation

2.1. Installation from package

Binary packages for Debian and Debian based distributions (e.g. Ubuntu, Mint) are available. The home page http://mhuxd.dj5qv.de provides up-to-date installation steps.

Installing from a package is the easiest way. Everything is handled automatically: systemd integration, the “mhuxd” account, permissions of the virtual serial ports etc. After the installation mhuxd is already running. To use the virtual serial ports from your own account, see Port Permissions.

2.2. Compiling from Source

2.2.1. Prerequisites

To compile mhuxd you need a C compiler, make, pkg-config and the development packages for:

libudev (libudev-dev)
libfuse (libfuse-dev)
libev (libev-dev)
libjansson (libjansson-dev) – JSON configuration

The acl package provides setfacl, which is needed to give mhuxd access to /dev/cuse. If you build from the GitHub repository, you also need git, autoconf and automake.

On Debian/Ubuntu:

sudo apt install acl git pkgconf automake autoconf make gcc libev-dev libfuse-dev libudev-dev libjansson-dev

On Arch Linux:

pacman -S --needed pkgconf git automake autoconf make gcc libev fuse systemd-libs jansson

The web interface is built from Svelte sources. The source code ships with the compiled web interface (pure JavaScript), so nodejs and npm are only needed if you change the web interface yourself (make svelte-ui-build in the webui directory).

2.2.2. Building

Get the source code from GitHub:

git clone https://github.com/dj5qv/mhuxd.git
cd mhuxd
./autogen.sh

Note	`pkg-config` must already be installed when running `./autogen.sh`, otherwise it fails.

Or download a release archive from the home page, extract it and change into its directory, e.g.

tar -xzvf mhuxd-0.90.tar.gz
cd mhuxd-0.90

Then configure, build and install mhuxd:

mkdir build && cd build
../configure --prefix=/usr/local/mhuxd
make
sudo make install

With --prefix=/usr/local/mhuxd everything is installed into a single folder. Without it mhuxd is installed into /usr/local.

To build Debian packages instead, run ./make_deb.sh in the source directory. No configure is needed, but the packages dpkg-dev and debhelper.

2.2.3. Account and Permissions

mhuxd does not need to run as root, and it shouldn’t. Though possible, I’d also advise against running it under your normal account. Create a system account “mhuxd” instead. Its group will also own the virtual serial ports in /dev/mhuxd/. The commands below assume --prefix=/usr/local/mhuxd and that you are still in the build directory:

# Create user and group mhuxd, give it access to serial devices:
sudo useradd --system --home-dir /nonexistent --no-create-home --user-group mhuxd
sudo usermod -G dialout mhuxd    # on Arch Linux use 'uucp' instead of 'dialout'

# mhuxd stores its configuration, log file and PID file below var:
sudo chown -R mhuxd:mhuxd /usr/local/mhuxd/var

# Load the cuse kernel module, now and after every boot:
sudo modprobe cuse
echo cuse | sudo tee /etc/modules-load.d/cuse.conf

# Allow mhuxd to read/write /dev/cuse. This doesn't survive a reboot,
# the udev rule below takes care of that:
sudo setfacl -m u:mhuxd:rw /dev/cuse

# Install the udev rule and reload the udev rules (or reboot):
sudo cp ../debian/mhuxd.udev /usr/lib/udev/rules.d/59-mhuxd.rules
sudo udevadm control --reload-rules

The udev rule grants the mhuxd account access to /dev/cuse, makes group “mhuxd” the owner of the virtual serial ports, publishes them in /dev/serial/by-id/ as well (see Port Routing) and keeps ModemManager away from the keyers.

The keyers use the ftdi_sio driver, which the kernel loads by itself when a keyer is plugged in.

2.3. Running mhuxd

2.3.1. When installed from package

mhuxd runs as systemd service and is started at boot. The log file is /var/log/mhuxd/mhuxd.log.

sudo systemctl stop mhuxd
sudo systemctl start mhuxd

2.3.2. When compiled from source

Start mhuxd under the mhuxd account:

# In the foreground, log output goes to the terminal. Stop it with Ctrl-C:
sudo -u mhuxd /usr/local/mhuxd/sbin/mhuxd

# In the background, log output goes into /usr/local/mhuxd/var/log/mhuxd/mhuxd.log:
sudo -u mhuxd /usr/local/mhuxd/sbin/mhuxd -b

# Stop mhuxd running in the background:
sudo kill $(cat /usr/local/mhuxd/var/run/mhuxd/mhuxd.pid)

Once mhuxd runs, open the web interface at http://localhost:5052 (see The WebUI).

2.3.3. Command Line Options

Option Description

Option	Description
`-b`	Run in the background, log into the log file.
`-w <interface:port>`	Interface and port of the web server, default `localhost:5052`. `0.0.0.0:5052` makes the web interface reachable from other computers (IPv4 and IPv6). Don’t do this if your computer is directly connected to the internet or in an insecure network!
`-l <log level>`	Initial log level: MUTE, CRIT, ERROR, WARN, INFO, DEBUG0 or DEBUG1. A log level set in the web interface overrides this option.
`-h`	Print the options and exit.

-b

Run in the background, log into the log file.

-w <interface:port>

Interface and port of the web server, default localhost:5052. 0.0.0.0:5052 makes the web interface reachable from other computers (IPv4 and IPv6). Don’t do this if your computer is directly connected to the internet or in an insecure network!

-l <log level>

Initial log level: MUTE, CRIT, ERROR, WARN, INFO, DEBUG0 or DEBUG1. A log level set in the web interface overrides this option.

-h

Print the options and exit.

To give the packaged service other options, override its start command with sudo systemctl edit mhuxd, e.g.

[Service]
ExecStart=
ExecStart=/usr/sbin/mhuxd -b -w 0.0.0.0:5052

3. The WebUI

The WebUI provides a graphical interface to mhuxd. By default it is bound to the local machine only, that means it is reachable from the computer where mhuxd is running.

To access the WebUI make sure that mhuxd is running and open the following address in a browser:

http://localhost:5052

The address and port can be changed with the -w command line option, see Running mhuxd.

Starting with version 0.90 mhuxd ships a new web interface written in JavaScript (Svelte). It updates automatically as keyers appear, disappear or change state — no manual page refresh is required. The previous ("classic") interface has been removed.

If the browser loses the connection to mhuxd (e.g. mhuxd was stopped), the page is greyed out with the message “Can’t connect to mhuxd” and reconnects by itself once mhuxd is back.

3.1. Layout

Figure 1. WebUI home page

The window is divided into three areas:

a top bar showing the host name, the running mhuxd version and a Help link to this manual,
a row of tabs – a Daemon tab plus one tab for every keyer, and
a side menu on the left whose entries depend on the selected tab (and, for keyers, on the keyer type).

3.2. Daemon tab

The Daemon tab groups settings that are not specific to a single keyer:

Summary – mhuxd version, host name, process id, log file and current log level, plus the Keyer List and the Port List (see below).
Ports – create and route virtual serial ports and TCP network ports (see Port Routing).
Settings – set the log level (CRIT, ERROR, WARN, INFO, DEBUG0, DEBUG1). The log level is stored and overrides the -l command line option.

3.2.1. Keyer List

The Keyer List shows every keyer mhuxd knows, with name, model, serial number, firmware version and status. mhuxd remembers a keyer and its settings, including its ports, after it has been unplugged. The menu button at the end of each row offers Rename and Remove.

Rename gives a keyer a name of your choice, which helps to tell keyers of the same model apart. Keyers without a custom name go by their serial number. The name shows up on the keyer’s tab and in the port lists; it is stored by mhuxd, not in the keyer. Type the name in the list and press Enter to save it, or Esc to cancel. A name can have up to 32 characters. It must differ from the names and serial numbers of the other keyers, regardless of upper and lower case. Saving an empty name goes back to the serial number.

To remove a keyer from the configuration, unplug it and choose Remove. All settings of the keyer and its ports are discarded. When the keyer is plugged in again, it shows up with default settings. A keyer that is connected can’t be removed.

3.2.2. Port List

The Port List shows every configured port with its status and the application using it. The ports are set up on the Ports page, see Port Routing.

The Status column shows “ok”, or “failed” when mhuxd couldn’t create the port or the port stopped working (e.g. the TCP port number is in use; the log file tells why).

The Client column shows the application that has the port open, a port takes one application at a time. For a VSP it is the program, its process ID and the user it runs as, e.g. wsjtx (PID 4711, mattes). A script is shown with its interpreter, e.g. python3 myscript.py. For a TCP port it is the address and port the connection comes from, plus the user for a connection from the same computer, e.g. 127.0.0.1:53422 (mattes). Which program made a TCP connection mhuxd can’t tell, that would take permission to look into the processes of other users. Hover over the entry to see since when the application is connected.

3.3. Keyer tabs

Each keyer has its own tab allowing keyer specific configuration. The available side menu entries depend on the keyer type; see Keyer Configuration.

3.4. Keyer status

The status of each keyer is shown by a colored indicator:

ONLINE – Keyer is connected and online

OFFLINE – Keyer is connected but not online (powered off)

DISCONNECTED – Keyer is not connected

The status is updated automatically; no page refresh is necessary.

4. Port Routing

4.1. About Ports

Similar to the virtual COM ports of the microHam Windows Device Router mhuxd can provide virtual serial ports (VSP). VSPs are implemented using the Linux CUSE driver, hence the cuse kernel module must be loaded and the device /dev/cuse must exist.

Alternatively mhuxd also offers TCP/IP network ports (IPv4 and IPv6).

Ports persist even when the keyer is switched off or unplugged. Applications can keep them open meanwhile.

4.2. Port Page

To access the port page select tab “Daemon”, menu “Ports”. The first section, “Port Config”, shows the configured ports with their settings. With a new mhuxd installation this list is empty. Ports can be removed here by selecting them and pushing the “Remove” button.

Figure 2. Port Config with ports for a micro KEYER III

The Transceive / AI column applies to CAT ports, see below. Whether a port works and which application has it open is shown in the Port List on the Summary page, see The WebUI.

To create a port press the “Add” button. A dialog opens in which you choose the port type, the keyer to route to, the destination channel and the type-specific options described below. There are 2 types of ports available:

VSP – virtual serial port
TCP – TCP/IP network port

Press “Create” to add the port, or “Cancel” to discard.

Figure 3. Add Port dialog

4.3. Destination Channels

The Destination Channel is the keyer channel the port is connected to. Only the channels of the selected keyer are offered:

Channel	Use
CAT1, CAT2	CAT commands to the radio (CAT2: second radio of the MK2R/MK2R+)
PTT1, PTT2	PTT keying by applications, see below
WK	K1EL Winkey chip (CW)
FSK1, FSK2	FSK (RTTY) keying
AUX	AUX serial port (micro KEYER II/III, Station Master)
MCP	microHam control protocol (MCP) commands
ROTATOR	rotator control (Station Master)

Channel

Use

CAT1, CAT2

CAT commands to the radio (CAT2: second radio of the MK2R/MK2R+)

PTT1, PTT2

PTT keying by applications, see below

K1EL Winkey chip (CW)

FSK1, FSK2

FSK (RTTY) keying

AUX

AUX serial port (micro KEYER II/III, Station Master)

MCP

microHam control protocol (MCP) commands

ROTATOR

rotator control (Station Master)

4.4. Add a VSP Port

Select the VSP port type, the keyer the port should be routed to and the Destination Channel.

Specify the device name. VSP devices are always located in /dev/mhuxd/. The dialog suggests the channel name, e.g. cat1. Optionally you may select “PTT via RTS” and/or “PTT via DTR”. With this option set an application can key the PTT using the RTS and/or DTR signals.

It is not suggested to use PTT/RTS or PTT/DTR on the CAT channel. Better use a dedicated PTT VSP device (e.g. /dev/mhuxd/ptt1) and route it to the PTT channel.

Many applications build their list of serial ports from /dev/serial/by-id/ (e.g. fldigi, Hamlib, QLog). The udev rule of mhuxd therefore publishes every VSP there as well, e.g. /dev/mhuxd/cat1 as /dev/serial/by-id/mhuxd-cat1. If an application still doesn’t list a VSP, you can usually type its path.

4.5. Add a TCP Port

Select the TCP port type, the keyer to route to and the destination channel, then enter a TCP port number. You may select “Remote Accessible”. This would allow other computers to connect to this port. Don’t do this if your computer is directly connected to the internet or in an insecure network!

On a PTT channel, a TCP port keys PTT with the byte 0x01 and releases it with 0x00.

A port takes one application at a time, a second one is turned away: a virtual serial port fails to open with EBUSY, a TCP connection is closed. To share the radio between applications, give each its own port, see Several applications on one radio.

4.6. Common Options

Transceive / AI (CAT ports only, on by default) – when switched off, the port doesn’t get CI-V transceive and Auto Information messages, only the answers to its own commands. This needs RIG Mode Sync with backend “native”, see Transceive / AI.

4.7. PTT and closed ports

When an application closes a port, or its TCP connection drops, while it holds PTT, mhuxd releases the PTT.

5. Port Permissions

The VSP ports in /dev/mhuxd/ are owned by the user “root” and the group “mhuxd”:

# ls -la /dev/mhuxd/ drwxr-xr-x 2 root root 120 Oct 28 14:54 . drwxr-xr-x 20 root root 4620 Oct 28 14:54 .. crw-rw---- 1 root mhuxd 246, 0 Oct 28 14:54 cat1 crw-rw---- 1 root mhuxd 248, 0 Oct 28 14:54 fsk1 crw-rw---- 1 root mhuxd 247, 0 Oct 28 14:54 ptt1 crw-rw---- 1 root mhuxd 249, 0 Oct 28 14:54 wk

To make these ports accessible from your account you just need to make yourself member of the “mhuxd” group. Let’s say your user id is “johndoe” you can add yourself by this command:

sudo usermod -a -G mhuxd johndoe

You may need to re-login for the change to take effect.

5.1. When installed from Ubuntu/Debian package

The package creates the user and group “mhuxd” and installs the udev rule that sets the group of the ports.

5.2. When installed from compiled source code

Here you have to create the user and group “mhuxd” yourself and install the udev rule from the mhuxd source directory (debian/mhuxd.udev) as /usr/lib/udev/rules.d/59-mhuxd.rules. The steps are described in Installation, section “Account and Permissions”.

6. Keyer Configuration

6.1. Keyer Pages

Mhuxd supports multiple keyers simultaneously. Therefore for each detected keyer a separate page is created in the WebUI. Its tab shows the name of the keyer, which is the serial number unless you rename the keyer in the Keyer List.

The left side menu contains the configuration categories. Not all categories are available for each keyer type.

Figure 4. Menu for the micro Keyer II. The available categories depend on the keyer type.

Note	The screenshots in this chapter were taken with an earlier version of the interface and may differ from the current layout.

The serial parameters (Radio, AUX, FSK), RIG Mode Sync, rigctld, the messages and the All Parameters page are stored with an Apply button. All other settings are sent to the keyer as soon as they are changed.

6.2. Menu Keyer Mode

This menu is available for DIGI KEYER II, micro KEYER, micro KEYER II, micro KEYER III, MK2R and MK2R+. The MK2R(+) has a section for each radio.

Keyer Mode Follows RIG – Not available for the micro KEYER. With this option enabled the keyer sets the keyer mode according to the rig mode. For this to work you must have configured the rig type and serial parameters in the “Radio Menu”. Additionally the option “Use Decoder if Connected” must be enabled there. RIG Mode Sync (see RIG Mode Sync) works without it.
Current Mode – This shows the current keyer mode (CW, VOICE, FSK, DIGITAL) and allows to change it.

Like the microHam Router, mhuxd doesn’t choose the keyer mode of the CW KEYER and the DIGI KEYER: the CW KEYER works in CW, the DIGI KEYER in DIGITAL.

6.3. Menu Radio

This menu is not available for CW KEYER. This page allows to configure the serial parameters between the keyer and the transceiver:

Baud Rate
Data Bits
Stop Bits
RTS/CTS Handshake

Refer to your transceivers manual on how to set these parameters. The MK2R(+) has a section for each radio.

For DIGI KEYER II, micro KEYER II, micro KEYER III, MK2R(+) and Station Master additional options are available. These options affect the keyers capability to send CAT commands to the rig on its own:

Rig Type: Select your rig. This tells the keyers internal CAT decoder which rig is attached. If it is an Icom the selection will autofill the Icom Address field. You may choose “none” here which will reliably disable CAT queries from the keyer. RIG Mode Sync with backend native uses the rig type too.
Icom Address: If you use an Icom rig this field must contain the Icom address in decimal notation. Usually this field gets auto filled from the Rig Type selection.
PW1 Connected: Select this option if you have an Icom PW1 amplifier connected to the same bus as the rig. When enabled the keyer will periodically generate “auto-info”, preventing queries (and possible collisions) by PW1.
Digital Over Voice: Choose how LSB, USB and FM modes are interpreted:
- Band Map – set keyer mode according to band map
- Always VOICE – set keyer mode always to VOICE
- Always DIGITAL – set keyer mode always to DIGITAL
Use Decoder if Connected: Select this to enable the keyers CAT decoder even when the keyer is USB connected to a computer. The CAT decoder is used to synchronize the keyers mode with the rig mode. If disabled the keyer mode must be selected in the WebUI or by an application. The decoder is always active when the keyer is not USB connected to a computer. Enabling this may lead to interference. That is, CAT requests from the keyer colliding with CAT requests from an application like WSJT-X. RIG Mode Sync offers a more stable solution to provide the keyer with the current mode and frequency, see RIG Mode Sync.
Don’t Interfere USB control: Disable CAT queries by the keyer if it is USB connected to a computer. Only answers to the computer will be interpreted. This works with the older Yaesu radios (checked with a DIGI KEYER II and an FT-1000MP), but not with Icom: with an Icom rig selected the keyer polls anyway (DIGI KEYER II, IC-7300), probably to keep CI-V accessories like the PW1 informed.

The lower part of the page holds the sections RIG Mode Sync and rigctld, see RIG Mode Sync.

6.4. Menu AUX

This menu is only available for keyers with an AUX port (micro KEYER II, micro KEYER III, Station Master). Allows to specify the serial parameters of the AUX port.

6.5. Menu FSK

This menu is only available for keyers with an FSK channel (all but the CW KEYER and the Station Master). It configures the serial parameters of the FSK channel, the MK2R(+) has one for each radio. Refer to the original microHam documentation for your keyer.

Invert FSK – invert the FSK keying signal
Pseudo FSK – DIGI KEYER II and micro KEYER III only: the keyer keys its FSK output from an on/off keyed tone in the right sound card channel, e.g. fldigi’s “pseudo-FSK”. Refer to the keyer manual.

6.6. Menu PTT

This page allows the configuration of the PTT operation. The available options vary between keyer types; the MK2R(+) has a section for each radio.

Note	This is a very basic overview. Please refer also to the original microHam documentation for your keyer.

PTT CW – Select the PTT output for CW mode
PTT Voice – Select the PTT output for VOICE mode
PTT Digital – Select the PTT output for DIGITAL mode
LNA PTT – Enable LNA PTT relay
PA PTT – Enable PA PTT relay
PA PTT Tail (x 10ms) – PA PTT Tail time
LNA PTT Tail (x 10ms) – LNA PTT Tail time
PTT Lead (x 10ms) – PTT Lead time
CW in Voice – Allow CW operation in VOICE mode (micro KEYER II/III, MK2R(+) only)
Sound Card PTT – key PTT when soundcard produces audio (DIGI KEYER II, micro KEYER II/III only)
Downstream over Footswitch – when soundcard produces audio the audio source will be switched from microphone to sound card, even if the foot switch is pressed (untested, DIGI KEYER II, micro KEYER II/III only)

The PTT outputs offered:

Keyer	CW	Voice	Digital
CW KEYER	PTT, QSK	–	–
DIGI KEYER	–	–	PTT, No PTT
DIGI KEYER II	PTT, QSK, Semi Break-in	–	–
micro KEYER	PTT1, QSK, PTT2	PTT1, PTT2	PTT1, PTT2, PTT1+2
micro KEYER II/III, MK2R(+)	PTT1, QSK, Semi Break-in, PTT2	PTT1, PTT2	PTT1, PTT2, PTT1+2

Keyer

Voice

Digital

CW KEYER

PTT, QSK

–

DIGI KEYER

–

PTT, No PTT

DIGI KEYER II

PTT, QSK, Semi Break-in

–

micro KEYER

PTT1, QSK, PTT2

PTT1, PTT2

PTT1, PTT2, PTT1+2

micro KEYER II/III, MK2R(+)

PTT1, QSK, Semi Break-in, PTT2

PTT1, PTT2

PTT1, PTT2, PTT1+2

PTT1 is the PTT line of the mic jack, PTT2 the one on the rear panel jack.

6.6.1. Footswitch Sequencer

Additional functions for the footswitch (or the PTT of a hand microphone):

Mute serial CW – mute CW from an application (DTR or RTS) while the footswitch is pressed.
Mute serial FSK – block the FSK ports while the footswitch is pressed.
Restore serial PTT and audio – when the footswitch is released, restore the application’s PTT and the audio routing for it. Otherwise this only happens after the application has released PTT.
Restore serial CW – resume the application’s CW when the footswitch is released (if it has not ended yet). Otherwise it stays muted until the application releases PTT.
Restore serial FSK – the same for FSK.

6.7. Menu Audio

This menu is only available for keyers with audio switching (micro KEYER, micro KEYER II/III, MK2R/MK2R+). Refer to the original microHam documentation for your keyer.

Audio Switching selects for VOICE and DIGITAL mode where the audio goes when receiving, when transmitting and when transmitting with the footswitch. The MK2R(+) has a section for each radio, which also selects the microphone and the sound card codec. The options are:

A – microphone to the radio’s microphone input
B – sound card to the radio’s line input
C – sound card to the radio’s microphone input
D – like A + B (micro KEYER II/III)

On the micro KEYER II/III the Audio Options contain on air recording, the audio monitor level, the microphone selector (Auto, Front, Rear), Sound Card PTT and Downstream over Footswitch.

6.8. Menu Display

This menu is available for keyers with a display (micro KEYER II/III, Station Master). The first section “Display Options” allows configuration of the displays brightness, contrast and its default content.

In the second section “Display Reports” you can choose which events you want to have displayed.

6.9. Menu CW

This menu is only available for keyers containing a K1EL Winkey chip (all but the DIGI KEYER and the Station Master). In the first section, Winkey, the Winkey parameters can be configured: paddle mode (Iambic A/B, Ultimatic, Bug Keyer), PTT lead and tail, hang time, swap paddles, auto space, CT spacing, paddle watchdog, speed pot range, Farnsworth speed, DAH/DIT ratio, weighting, 1st extension, keying compensation and paddle setpoint.

Detailed description on the TODO list. Meanwhile please refer to your keyers documentation and/or to the Winkey documents at www.k1el.com.

The section Side Tone sets the side tone frequency (or Off). On the DIGI KEYER II and the micro KEYER II/III Paddle Only Side Tone limits the side tone to CW sent with the paddle.

6.10. Menu CW/FSK Messages

This menu is only available for keyers containing a K1EL Winkey chip. It stores the keyer’s CW and FSK message memories, 8 of each.

Enter the text for each message slot and press Apply to write the messages to the keyer. The Test button next to a slot plays the corresponding message so you can check it.

6.11. Menu Antenna Switching (Station Master)

These menus are only available for the Station Master / Station Master DeLuxe (experimental). The antenna switching configuration is split across several side menu entries:

Switching / Load, Store – load the current antenna switching configuration from the Station Master, or store the edited configuration back to it.
Switching / Settings – general parameters: CI-V function, baud rate and address of the PA connector, the D9 serial port function and baud rate, the switch and break-before-make delays, the inhibit lead time, the Key-In options and the sequencer lead/tail times.
Switching / Outputs – assign a class/function to each switch output.
Switching / Antennas – manage the antenna list.
Switching / Virt. Rotators – manage virtual rotators.
Switching / Ant. Groups – manage antenna groups.
Switching / Bands – per-band antenna assignment.

Note	Station Master support is experimental.

6.12. Menu All Parameters

A diagnostic page that lists all raw keyer parameters and their current values. They can be changed here, too. Mainly useful for troubleshooting.

7. RIG Mode Sync

mhuxd can keep the keyer mode (CW, VOICE, FSK, DIGITAL) in sync with the actual rig mode, and tell the keyer the rig’s frequency.

The keyer’s own CAT decoder (“Use Decoder if Connected”, see Menu Radio) can do that too, but its CAT queries collide with the queries of applications like WSJT-X when the keyer is connected to a computer. Measured with an IC-7300: the keyer polls the radio whenever the CAT line has been idle for about one second, the commands of the application fail on the CI-V bus meanwhile. mhuxd avoids these collisions.

RIG Mode Sync has two backends:

native – mhuxd decodes the CAT traffic between your applications and the radio on the keyer’s CAT channel. The applications keep using the virtual serial port of the CAT channel (e.g. /dev/mhuxd/cat1) directly. No additional software is needed.
rigctld – mhuxd polls Hamlib’s rigctld daemon. The applications connect to rigctld instead of the CAT port.

Note	Keep the keyer option “Use Decoder if Connected” off when RIG Mode Sync is used. With an Icom radio “Don’t Interfere USB control” doesn’t stop the keyer’s queries.

7.1. Settings

RIG Mode Sync is configured in the lower part of the keyer’s Radio page, section RIG Mode Sync:

Enabled – master switch for mode synchronization on this keyer.
Backend – native or rigctld, see below.

For each radio (Radio 1, and Radio 2 on the MK2R/MK2R+):

Enabled – synchronize this radio
Radio state – what mhuxd sees, e.g. “14.074.000 Hz PKTUSB → keyer DIGITAL”. That’s the first thing to check when the keyer mode doesn’t follow the rig.

The further settings depend on the backend. Press Apply to store the settings.

The mode mapping is as follows:

Keyer mode	Rig modes
CW	CW, CWR
VOICE	USB, LSB, AM, FM, WFM, AMS
FSK	RTTY, RTTYR
DIGITAL	PKTUSB, PKTLSB, PKTFM, PKTAM, FAX

Keyer mode

Rig modes

CW, CWR

VOICE

USB, LSB, AM, FM, WFM, AMS

FSK

RTTY, RTTYR

DIGITAL

PKTUSB, PKTLSB, PKTFM, PKTAM, FAX

Other modes (e.g. PSK on some radios) leave the keyer mode unchanged. The DIGI KEYER II has no VOICE mode, it gets FSK instead.

When the radio doesn’t answer for 10 s (e.g. switched off), its state expires and the keyer goes back to its configured mode.

7.2. Backend native

With backend native, mhuxd reads the CAT traffic between your applications and the radio, decodes frequency and mode and sets the keyer mode from it. The applications open the keyer’s CAT port as usual, e.g. WSJT-X configured as shown here:

Figure 5. WSJT-X using the CAT and PTT ports of mhuxd directly

Supported radios:

Icom (CI-V; the Ten-Tec OMNI VI speaks it too)
Kenwood
Elecraft K2/K3
the newer Yaesu radios with ASCII CAT (FT-450, FT-950, FT-991, FT-2000, FTdx101, FTdx1200/3000/5000/9000)
the older Yaesu radios with binary CAT (FT-757GXII, FT-817/818, FT-840, FT-847, FT-857, FT-890, FT-897, FT-900, FT-920, FT-990, FT-1000/1000D, FT-1000MP/MARK-V/Field)
Flex, ANAN (PowerSDR/Thetis) and other SDRs emulating a TS-2000

Only Icom is tested on a real radio so far, the others against Hamlib’s backends and simulators: reports are welcome, a CAT monitor trace (see below) helps most. Not supported are the Yaesu FT-767GX, Ten-Tec ORION/OMNI VII, JRC and Hilberling: use rigctld for these.

Select the rig type (and Icom address) in the keyer’s Radio section as usual. The settings for each radio:

Protocol – auto takes the protocol from the rig type of the CAT channel. Otherwise choose Icom CI-V, Kenwood, Elecraft, Yaesu (FT-450, FT-950, FT-991, FTdx…) or Flex / PowerSDR / Thetis (ANAN). The older Yaesu radios with binary CAT need auto.
CI-V address (hex, Icom) – overrides the address of the CAT channel. Leave it empty to use the channel’s address.
Query the radio (on by default) – see below.
Resend after collisions (Icom, on by default) – see below.
CAT monitor – shows the decoded CAT traffic live, see below.

7.2.1. Queries by mhuxd

While an application polls the radio (WSJT-X, fldigi and loggers do), mhuxd takes frequency and mode from its traffic and sends nothing itself. When the values are older than 1.5 s (nobody polls, or the application doesn’t ask for the data mode), mhuxd asks the radio itself, if Query the radio is enabled. It sends one command at a time, when the CAT line has been quiet for a moment or right after the radio answered an application. Commands of the applications wait meanwhile (a few ten ms), and the radio’s answers to mhuxd don’t reach them. On Icom mhuxd uses the CI-V controller address E5, the applications E0.

Without the queries, front panel changes are only seen from the radio’s own messages: CI-V transceive on Icom (“CI-V Transceive”, on by default on the IC-7300), Auto Information on the others when an application turned it on (AI).

7.2.2. Several applications on one radio

Like the “2nd CAT port” of the microHam Router, several applications can use the radio at the same time. Give each application a port of its own on the radio’s CAT channel, e.g. /dev/mhuxd/cat1 for WSJT-X and a second virtual serial port /dev/mhuxd/cat1_2 for the logger, or a TCP port (see Port Routing).

mhuxd then sends one command at a time to the radio: an application’s command waits until the radio has answered the other’s (a few ten ms), so they don’t collide on the CI-V bus. Echo and answers go only to the application that sent the command, CI-V transceive and Auto Information to all (unless switched off for a port, see below). Without an answer within 0.5 s, mhuxd gives the command up and lets the next application go on.

A port takes one application at a time: applications sharing a port couldn’t be told apart. An application that only listens on its port, to follow the frequency from another application’s polls, gets only transceive and AI messages this way.

7.2.3. Transceive / AI

The port option Transceive / AI (see Port Routing, on by default) can be switched off for a CAT port. The port then doesn’t get CI-V transceive and Auto Information messages, only the answers to its own commands. Hamlib and rigctld don’t cope well with transceive messages between their commands, so this lets the radio’s CI-V transceive stay on for the other applications (and for mhuxd, which still follows the radio from them). This works with a single port too.

7.2.4. Resend after collisions

With CI-V transceive on, an application’s command can collide with the radio’s transceive message on the CI-V bus, especially while the VFO knob turns (a message every 30-50 ms). The radio then drops the command and answers with FC. Hamlib doesn’t recover from that and reports a “Communication bus error” after 2 s. With Resend after collisions mhuxd sends such a command again itself once the bus is free, and the application only sees its answer a few ten ms later.

7.2.5. Notes on some radios

Older Yaesu radios: their answers carry no start or end marker, mhuxd frames them by the model’s answer lengths. So the rig type in the keyer’s Radio section must match the radio exactly. A memory dump (several seconds) keeps the CAT line for the application that asked for it. The FT-1000/1000D doesn’t report which VFO is selected; mhuxd assumes VFO A until an application selects one. The FT-847 ignores all commands until CAT ON: mhuxd sends it before its first query and again when the radio stops answering (switched off and on, or an application sent CAT OFF, as Hamlib does when it closes).
Kenwood: the data mode (USB-D, …) is known on the TS-590, TS-890, TS-950 and TS-990. The older Kenwoods have none, so their USB counts as voice.
Elecraft K3: DATA A, PSK D and AFSK A count as digital, FSK D as FSK. Until the radio has reported the data sub mode (DT), DATA counts as DATA A.

7.2.6. CAT monitor

The CAT monitor shows the decoded CAT traffic live below the checkbox and writes it to cat-<serial>-r1.trace (-r2 for radio 2) in mhuxd’s log directory. The applications are tagged H1, H2, … in the order they first send; the monitor names their ports. Clear empties the display.

If something isn’t decoded right, please send that file along with your report: it can be replayed by the tests in the mhuxd source (tests/cat/) as is.

7.3. Backend rigctld

With backend rigctld, mhuxd queries the rig through Hamlib’s rigctld and updates the keyer mode whenever the rig mode changes. rigctld occupies the keyer’s CAT port, the applications connect to rigctld instead. rigctld allows several applications to run CAT queries at the same time without interference, e.g. WSJT-X, fldigi and QLog.

Figure 6. mhuxd, rigctld and the applications

For each radio an endpoint can be configured:

Host / Port – where rigctld is listening (default 127.0.0.1, port 4532 for Radio 1 and 4533 for Radio 2)
Connect Timeout, I/O Timeout, Poll Interval – connection and polling timing in milliseconds

Figure 7. WSJT-X connected to rigctld

Although CAT PTT is enabled in this example, that is not really CAT PTT from the rig’s perspective. rigctld translates it to RTS on /dev/mhuxd/ptt1 if started with -p /dev/mhuxd/ptt1 -P RTS (see below), and the keyer keys the PTT line.

7.4. rigctld auto-start

mhuxd can start a Hamlib rigctld instance itself when the keyer comes online, and stops it when the keyer goes offline. This is independent of RIG Mode Sync and works with either backend: with backend rigctld mhuxd polls this rigctld, with backend native mhuxd decodes the CAT traffic rigctld sends through the keyer’s CAT port. If rigctld exits, mhuxd starts it again, waiting longer after each failed attempt (up to one minute).

The section rigctld is in the lower part of the keyer’s Radio page. For each radio:

Auto-start rigctld – let mhuxd run rigctld for this radio
Port – the TCP port rigctld listens on, passed as -t (default 4532 for Radio 1, 4533 for Radio 2). With RIG Mode Sync backend rigctld, its Port must be the same.
rigctld options – the further rigctld arguments, e.g.

-m 3073 -p /dev/mhuxd/ptt1 -P RTS -r /dev/mhuxd/cat1

-m 3073 is the Hamlib rig model number, IC-7300 in this case. Run rigctld -l to display a list of rigs and their numbers.
-r /dev/mhuxd/cat1 is the virtual serial port for CAT that you’ve configured in mhuxd.
-p /dev/mhuxd/ptt1 -P RTS tells rigctld the PTT port and to key PTT with RTS (the port needs “PTT via RTS”).

Press Apply to store the settings.