Example:-Diverted-"Host-Switch-Channel"-keys-for-common-devices.md

+## 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
+
+```text
+     Has 32 reprogrammable keys:
+         0: Host Switch Channel 1     , default: HostSwitch Channel 1        => HostSwitch Channel 1      
+             is FN, FN sensitive, analytics key events, pos:1, group:0, group mask:empty
+             reporting: default
+         1: Host Switch Channel 2     , default: HostSwitch Channel 2        => HostSwitch Channel 2      
+             is FN, FN sensitive, analytics key events, pos:2, group:0, group mask:empty
+             reporting: default
+         2: Host Switch Channel 3     , default: HostSwitch Channel 3        => HostSwitch Channel 3      
+             is FN, FN sensitive, analytics key events, pos:3, 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
+
+```bash
+solaar show | grep -iE '(serial|codename)'
+```
+In my case this gives
+
+```text
+  Serial       : 1E6B9EDF
+     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
+%YAML 1.3
+---
+- Key: [Host Switch Channel 2, pressed]
+- 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 then 
+
+and on the second machine a file is created as
+
+```yaml
+%YAML 1.3
+---
+- Key: [Host Switch Channel 1, pressed]
+- 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. 
\ No newline at end of file