Example: Diverted "Host Switch Channel" keys for common devices

Use Case

Assume there are two machines, one (“alpha”) and two (“beta”), and both use common HID devices. You want to control both machines with the same HID devices, a mouse and a keyboard. Both must support change host, the keyboard have “Host Switch Channel” keys to control attachment to host, and those keys can be diverted.

Prerequisite

The keyboard MX Keys has such keys that can be diverted, but not all keyboards has such divertable keys. In particular the keyboard MX Mechanical Mini don't have divertable keys, even if it has “Host Switch Channel” keys.

If your keyboard support divertable “Host Switch Channel” keys, running solaar show will give some variation of

     Has 24 reprogrammable keys:
         0: Host Switch Channel 1     , default: HostSwitch Channel 1        => HostSwitch Channel 1      
             nonstandard, divertable, persistently divertable, analytics key events, pos:0, group:0, group mask:empty
             reporting: default
         1: Host Switch Channel 2     , default: HostSwitch Channel 2        => HostSwitch Channel 2      
             nonstandard, divertable, persistently divertable, analytics key events, pos:0, group:0, group mask:empty
             reporting: diverted
         2: Host Switch Channel 3     , default: HostSwitch Channel 3        => HostSwitch Channel 3      
             nonstandard, divertable, persistently divertable, analytics key events, pos:0, group:0, group mask:empty
             reporting: default
         …

Both machines must run solaar for the rules to work properly, and the version must be 1.1.4 or higher.

Configuration

The id for the mouse and keyboard can be found in the info-pane as the “serial” value, or by running the command

solaar show | grep -iE '(serial|codename)'

This may give something like

  Serial       : 789ABDEF
     Codename     : MX Anywhere 3
     Serial number: 123456AB
     Codename     : MX Keys
     Serial number: 654321CD

On the first machine (“alpha”) a file is created as ~/.config/solaar/rules.yaml, or an existing one is edited

%YAML 1.3
---
- Key: [Host Switch Channel 2, released]
- Rule:
  - Active: 123456AB
  - Set: [123456AB, change-host, 1]
  - Set: [654321CD, change-host, 1]
  - Execute: [notify-send, --category=device, --expire-time=3000, --app-name=solaar,
    --icon=/usr/share/solaar/icons/solaar.svg, Change host, Switched keyboard and mouse to beta.]
- Set: [654321CD, change-host, 1]
- Execute: [notify-send, --category=device, --expire-time=3000, --app-name=solaar,
  --icon=/usr/share/solaar/icons/solaar.svg, Change host, Switched keyboard to beta. Mouse not active.]
...

In the rule it is checked whether the mouse is active, and if it is then it is changed to the new host. Then the keyboard is changed to the new host. Finalizing the two changes a notification is posted, and that terminates the processing.

If the mouse is not active, solaar will proceed with changing the host for the keyboard, and then finalizing the change with a notification before it terminates the processing.

The file on the second machine (“beta”) is created as

%YAML 1.3
---
- Key: [Host Switch Channel 1, released]
- Rule:
  - Active: 123456AB
  - Set: [123456AB, change-host, 0]
  - Set: [654321CD, change-host, 0]
  - Execute: [notify-send, --category=device, --expire-time=3000, --app-name=solaar,
    --icon=/usr/share/solaar/icons/solaar.svg, Change host, Switched keyboard and mouse to beta.]
- Set: [654321CD, change-host, 0]
- Execute: [notify-send, --category=device, --expire-time=3000, --app-name=solaar,
  --icon=/usr/share/solaar/icons/solaar.svg, Change host, Switched keyboard to beta. Mouse not active.]
...

Note that the hosts are zero-based in rules.yaml file, while they are one-based in the GUI.

In the GUI go to “Key/Button Diversion” for the keyboard, and change “Host Switch Channel 1” on beta to “Diverted”. Make a similar change for “Host Switch Channel 2” on alpha.

It should not be necessary to edit the rules with the Rule editor, but the rules could instead be created in the GUI. If the rules are not created in the Rule editor, they are not if you edit the file, then you should now restart solaar.

Issues

One of the devices can be offline, and then be left while the other does the change. Usually the mouse will wake up on the previous host when that happen, but occasionally I found the keyboard to be the one abandoned on the previous host. That is somewhat weird. Often the state is fixed by reattempting the change once more, or changing back end then retry the change once more.

To avoid typing passwords at the wrong host, possibly in some dangerous online application, it is best to use the keyboard as the controlling device. That is the last fallback device is the keyboard, as that would be the one always active during the process. The mouse is the device tested with active directive.