Example:-Diverted-"Smart-Shift"-button-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 mouse have a “Smart Shift” button, and that button can be diverted.
+
+The scheme can be confusing with more than two machines.
+
+## Prerequisite
+
+The mouse _MX Anywhere 3_ has a button that can be diverted, but not all mice has such divertable buttons. Some mice may have other buttons that can be used for the same purpose. Using the “Smart Shift” will override the default free-wheeling of the scroll wheel on the _MX Anywhere 3_ mouse.
+
+To check whether your mouse support a divertable “Smart Shift” button, running `solaar show` will give some variation of
+
+```text
+     Has 7 reprogrammable keys:
+         …
+         5: Smart Shift               , default: Smart Shift                 => Smart Shift               
+             mse, reprogrammable, divertable, raw XY, analytics key events, pos:0, group:2, group mask:g1,g2
+             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)'
+```
+This may give something like
+
+```text
+  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
+%YAML 1.3
+---
+- Key: [Smart Shift, released]
+- Rule:
+  - And:
+    - Active: 654321CD
+    - Active: 123456AB
+  - Set: [654321CD, change-host, 1]
+  - Set: [123456AB, change-host, 1]
+- Execute: [notify-send, --category=device, --expire-time=3000, --app-name=solaar,
+    --icon=/usr/share/solaar/icons/solaar.svg, Change host, Not done – some device not active.]
+...
+```
+
+The _rule_ is checkng whether the keyboard is active, and if it is then it is changed to the new host. Then the mouse is changed to the new host. Finalizing the two changes a notification is posted, and that terminates the processing.
+
+If the mouse keyboard not active, solaar will proceed with changing the host for the mouse, and then finalizing the change with a notification before it terminates the processing.
+
+The file on the second machine (“beta”) is created as
+
+```yaml
+%YAML 1.3
+---
+- Key: [Smart Shift, released]
+- Rule:
+  - And:
+    - Active: 654321CD
+    - Active: 123456AB
+  - Set: [654321CD, change-host, 0]
+  - Set: [123456AB, change-host, 0]
+- Execute: [notify-send, --category=device, --expire-time=3000, --app-name=solaar,
+    --icon=/usr/share/solaar/icons/solaar.svg, Change host, Not done – some device 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 mouse, and change “Smart Shift” on beta to “Diverted”. Make a similar change for “Smart Shift” 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 keyboard will wake up on the previous host when that happen, but occasionally I found the mouse 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 if possible. That is the last fallback device is the keyboard, as that would be the one always active during the process. The keyboard is the device tested with `active` directive. 
\ No newline at end of file