diff --git a/docs/cheatsheet.md b/docs/cheatsheet.md index 36a174d0..001a8e34 100644 --- a/docs/cheatsheet.md +++ b/docs/cheatsheet.md @@ -121,6 +121,8 @@ Here are **first steps guides** for each PiKVM device: PiKVM V3 and V4 will automatically reboot after several minutes of being halted. DIY PiKVM will need a power cord reconnection to become available again. +??? note "Sending keyboard shortcuts to target host systems" + {!shortcuts.md!} ----- ## Getting User Support diff --git a/docs/shortcuts.md b/docs/shortcuts.md new file mode 100644 index 00000000..96cf90a3 --- /dev/null +++ b/docs/shortcuts.md @@ -0,0 +1,85 @@ +--- +title: Sending Shortcuts +description: "How to send shortcuts to atarget host system with PiKVM" +--- + +Operating systems deal with modifier keys differently, so it's difficult to get the same user experience across all possible target hosts. This is why PiKVM uses a keyboard shortcuts system built around these three concepts: + +- **Magic key**. A special-purpose key, typically the one you use the least when you connect to a remote target host. A good example is the right `Shift` key for right-handed people. +- **Modifier keys**. Typically, it's e.g. `Ctrl`, `Alt`, `Cmd`, etc. +- **Non-modifier keys**. These are all the other keys on your keyboard: alphanumeric keys, function keys, `Backspace`, `Del`, `Esc`, and `Enter`. + +## Sending a shortcut + +When you press a magic key, the web UI starts accumulating a sequence of modifier keys you press, for example, `Ctrl L` and `Alt L` in `Ctrl+Alt+Del`, and displays a guiding overlay: + +![Shortcuts overlay](shortcuts/shortcut-overlay.png) + +As soon as you press one non-modifier key, the web UI stop accumulating keys and sends the entire sequence of the keys you pressed to the target host system. + +Let's send a `Ctrl+Alt+Del` shortcut to the target host running Windows. Here is the correct sequence of actions: + +1. Press and release the magic key. +2. Press and release `Ctrl`. +3. Press and release `Alt`. +4. Press and release `Del`. + +Here is another example. Let's send a shortcut to a host system running macOS to open the Force Quit Applications window: + +1. Press and release the magic key. +2. Press and release `Command`. +3. Press and release `Option`. +4. Press and release `Esc`. + +## Using multiple non-modifier keys in one shortcut + +In some cases you may need to press a non-modifier key two or more times. A common example is cycling through the list of opened windows using `Alt+Tab`. To achieve that, use the alternative behavior where non-modifier keys are continuously sent as you press them: + +1. Press and _hold_ the magic key. +2. Press and release `Alt`. +3. Press and release `Tab` ← at this point the target host system will display a list of windows to choose from. +4. Continue pressing and releasing `Tab` until you get to the right window. +5. _Release the magic key_. + +## Overriding the desktop environment + +Some desktop environments claim modifier keys for themselves, so those keys can't be used in a shortcut. For example, if you are trying to open the Start menu on a host Windows-based system using the `Win` key and you do it from GNOME on Linux, PiKVM web UI will not register the `Win` key press. Instead, your local GNOME environment will show an overview of locally opened windows instead. + +To override that, you can use the alternative behavior outlined above. Let's say you need to minimize all windows and show the desktop on a target host running Windows. Do this: + +1. Press and _hold_ the magic key. +2. Press and release `Win`. +3. Press and release `D`. +4. _Release the magic key._ + +PiKVM will send `Win+D` to the target host system which will minimize all windows. + +## Using shortcuts with just the modifier keys + +Some shortcuts don't use non-modifier keys at all. For example, `Ctrl+Shift` and `Alt+Shift` commonly change the keyboard layout, and `Win` opens the Start menu on Windows. This means you need to tell the web UI to stop accumulating modifiers and send what you have already pressed to the target host. To do that, simply press the magic key twice without a pause. + +For example, to open the Start menu on Windows: + +1. Press and hold the magic key. +2. Press and release `Win`. +3. Quickly press and release the magic key twice. + +PiKVM will send `Win` to the target host system which open the Start menu. + +## Setting up a magic key + +You can define which key to use as the magic key. Follow these steps: + +1. In the web UI, open the **System** menu. + +2. Click on the drop-down list next to **Shortcuts magic**. + +3. Select the key the you will use as the magic key. + +![Selecting the magic key](shortcuts/web-ui-magic-key-selector.png) + +PiKVM defaults to `Ctrl Right` on all major desltop systems, but the list of available keys is platform-specific: + +- **Windows**: `Ctrl`, `Alt`, `Shift`, and `Meta`. +- **macOS**: `Ctrl`, `Option`, and `Shift`. +- **Linux**: `Ctrl`, `Alt`, `Shift`, and `Meta`. \ No newline at end of file diff --git a/docs/shortcuts/shortcut-overlay.png b/docs/shortcuts/shortcut-overlay.png new file mode 100644 index 00000000..2bf9aa71 Binary files /dev/null and b/docs/shortcuts/shortcut-overlay.png differ diff --git a/docs/shortcuts/web-ui-magic-key-selector.png b/docs/shortcuts/web-ui-magic-key-selector.png new file mode 100644 index 00000000..3ae3a940 Binary files /dev/null and b/docs/shortcuts/web-ui-magic-key-selector.png differ diff --git a/docs/v1.md b/docs/v1.md index 368ee576..977e2b94 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -264,6 +264,8 @@ To do that: - **Get to know PiKVM Web UI**: read [this help section](webui.md) to better understand all the possibilities of the web user interface. +- **Configure the magic key**: define which key to use to start [sending shortcuts](shortcuts.md) to the target host system. + - Tune the HDMI dongle capture device if you're using it: ??? note "Persistent HDMI cable connection with USB dongle" diff --git a/docs/v2.md b/docs/v2.md index 094058b3..c270ced9 100644 --- a/docs/v2.md +++ b/docs/v2.md @@ -295,6 +295,8 @@ To do that: - **Get to know PiKVM Web UI**: read [this help section](webui.md) to better understand all the possibilities of the web user interface. +- **Configure the magic key**: define which key to use to start [sending shortcuts](shortcuts.md) to the target host system. + - Tune the HDMI dongle capture device if you're using it: ??? note "Persistent HDMI cable connection with USB dongle" diff --git a/docs/v3.md b/docs/v3.md index b18123a2..c6e0e269 100644 --- a/docs/v3.md +++ b/docs/v3.md @@ -250,6 +250,8 @@ To do that: - **Get to know PiKVM Web UI**: read [this help section](webui.md) to better understand all the possibilities of the web user interface. +- **Configure the magic key**: define which key to use to start [sending shortcuts](shortcuts.md) to the target host system. + - **Set up [ATX connection](atx_board.md)** if you need to control the power of the remote system. diff --git a/docs/v4.md b/docs/v4.md index 51180d86..7ac5e6d8 100644 --- a/docs/v4.md +++ b/docs/v4.md @@ -234,6 +234,8 @@ To do that: - **Get to know PiKVM Web UI**: read [this help section](webui.md) to better understand all the possibilities of the web user interface. +- **Configure the magic key**: define which key to use to start [sending shortcuts](shortcuts.md) to the target host system. + - **Set up an [ATX connection](atx_board.md)** if you need to control the power of the remote system. diff --git a/mkdocs.yml b/mkdocs.yml index 422e28eb..6f012b2c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -109,6 +109,7 @@ nav: - "Getting started": - "Cheat Sheet": cheatsheet.md - "Web UI Overview": webui.md + - "Sending Shortcuts": shortcuts.md - "Configuring PiKVM": config.md - "Authentication & 2FA": auth.md - "FAQ & Troubleshooting": faq.md