pikvm/docs/bluetooth_hid.md

# Bluetooth HID

PiKVM is able to emulate a Bluetooth keyboard & mouse.
This is not the main case of using PiKVM since you still need it to pair with a remote host, but can be used for something like mobile KVM.

!!! warning
    Using Bluetooth HID requires additional configuration of the operating system. For v2+, this means losing the UART port, since it will be used by Bluetooth. Also, Bluetooth operation was tested only on RPi4 and v2+ platform. Other boards may require different system service settings. Making the required changes for BT to work will also disable normal KB/MOUSE functionality therefor this will need to be disabled before normal operation can occur.

!!! note
    Bluetooth mouse can work only in [relative mode](mouse.md). The reason is that many Bluetooth host drivers do not correctly implement HID descriptors. Horizontal scrolling is not supported for the same reason.


## Configuring the OS

1. Switch filesystem to RW-mode, perform update and install some packages:

    ```
    # rw
    # pacman -Syu bluez bluez-utils raspberrypi-bluetooth
    ```

2. Edit `/boot/config.txt` and comment these lines:

    ```
    #enable_uart=1
    #dtoverlay=disable-bt
    ```

3. Create an empty directory `/var/lib/bluetooth` and add mountpoint to `/etc/fstab`:

    ```
    # mkdir /var/lib/bluetooth
    # echo 'tmpfs /var/lib/bluetooth tmpfs nodev,nosuid,mode=0755 0 0' >> /etc/fstab
    ```

4. Override and enable the services:

    ```
    # mkdir /etc/systemd/system/bluetooth.service.d
    # cat << EOF > /etc/systemd/system/bluetooth.service.d/override.conf
    [Service]
    ExecStart=
    ExecStart=/usr/lib/bluetooth/bluetoothd --noplugin=*
    EOF
    # systemctl enable bluetooth
    # systemctl enable raspberrypi-btuart
    ```

5. Override `kvmd` service:

    ```
    # mkdir /etc/systemd/system/kvmd.service.d
    # cat << EOF > /etc/systemd/system/kvmd.service.d/override.conf
    [Service]
    AmbientCapabilities=CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_ADMIN CAP_SETUID CAP_SETGID CAP_CHOWN
    CapabilityBoundingSet=CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_ADMIN CAP_SETUID CAP_SETGID CAP_CHOWN
    EOF
    ```

6. Add following lines to `/etc/kvmd/override.yaml`:

    ```yaml
    kvmd:
        hid:
            type: bt
    ```

7. Perform `reboot`.

8. To reverse, uncomment lines from Step 2 and remove lines in Step 6, and `reboot`.


## Using Bluetooth HID

* After a reboot, the PiKVM will be ready for detection and pairing with no auth. You will see the `PiKVM HID` device.

* Once the server is connected, PiKVM will no longer be discoverable and pairable to other clients until you unpair the server.

* If something went wrong, use the web menu `System -> Reset keyboard & mouse`. This will cause unpair the device and switch the PiKVM to public mode before the first client is connected.
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			`# Bluetooth HID`
docs.pikvm.org 2021-10-12 18:45:00 +00:00
rebranding 2021-09-26 08:47:33 +00:00			`PiKVM is able to emulate a Bluetooth keyboard & mouse.`
			`This is not the main case of using PiKVM since you still need it to pair with a remote host, but can be used for something like mobile KVM.`
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00
docs.pikvm.org 2021-10-12 18:45:00 +00:00			`!!! warning`
Update bluetooth_hid.md (#601) Added verbiage for clarity 2022-01-10 05:03:35 +00:00			`Using Bluetooth HID requires additional configuration of the operating system. For v2+, this means losing the UART port, since it will be used by Bluetooth. Also, Bluetooth operation was tested only on RPi4 and v2+ platform. Other boards may require different system service settings. Making the required changes for BT to work will also disable normal KB/MOUSE functionality therefor this will need to be disabled before normal operation can occur.`
docs.pikvm.org 2021-10-12 18:45:00 +00:00
			`!!! note`
			`Bluetooth mouse can work only in [relative mode](mouse.md). The reason is that many Bluetooth host drivers do not correctly implement HID descriptors. Horizontal scrolling is not supported for the same reason.`

Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00
docs.pikvm.org 2021-10-12 18:45:00 +00:00			`## Configuring the OS`
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00
			`1. Switch filesystem to RW-mode, perform update and install some packages:`
docs.pikvm.org 2021-10-12 18:45:00 +00:00
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			```
			`# rw`
update documentation to reflect best-practices (#857) * update tailscale.md to reflect best-practices The provided -Syy is supposed to be used to redownload all package databases, while the command chain itself is a partial upgrade which is not recommended either for rolling release distributions. Replace the full database redownload with a database update and run a system upgrade while installing tailscaled. * remove unnecessary sync command from video.md * remove unnecessary sync command from bluetooth_hid.md * remove unnecessary sync command from arduino_hid.md * update faq.md to reflect best practices * update letsencrypt.md to keep system up-to-date when installing packages 2022-11-09 19:16:22 +00:00			`# pacman -Syu bluez bluez-utils raspberrypi-bluetooth`
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			```
docs.pikvm.org 2021-10-12 18:45:00 +00:00
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			2. Edit `/boot/config.txt` and comment these lines:
docs.pikvm.org 2021-10-12 18:45:00 +00:00
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			```
			`#enable_uart=1`
			`#dtoverlay=disable-bt`
			```
docs.pikvm.org 2021-10-12 18:45:00 +00:00
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			3. Create an empty directory `/var/lib/bluetooth` and add mountpoint to `/etc/fstab`:
docs.pikvm.org 2021-10-12 18:45:00 +00:00
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			```
			`# mkdir /var/lib/bluetooth`
			`# echo 'tmpfs /var/lib/bluetooth tmpfs nodev,nosuid,mode=0755 0 0' >> /etc/fstab`
			```
docs.pikvm.org 2021-10-12 18:45:00 +00:00
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			`4. Override and enable the services:`
docs.pikvm.org 2021-10-12 18:45:00 +00:00
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			```
			`# mkdir /etc/systemd/system/bluetooth.service.d`
			`# cat << EOF > /etc/systemd/system/bluetooth.service.d/override.conf`
			`[Service]`
			`ExecStart=`
			`ExecStart=/usr/lib/bluetooth/bluetoothd --noplugin=*`
			`EOF`
			`# systemctl enable bluetooth`
			`# systemctl enable raspberrypi-btuart`
			```
docs.pikvm.org 2021-10-12 18:45:00 +00:00
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			5. Override `kvmd` service:
docs.pikvm.org 2021-10-12 18:45:00 +00:00
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			```
			`# mkdir /etc/systemd/system/kvmd.service.d`
Update bluetooth_hid.md 2020-11-07 22:57:24 +00:00			`# cat << EOF > /etc/systemd/system/kvmd.service.d/override.conf`
Create bluetooth_hid.md 2020-11-07 22:56:23 +00:00			`[Service]`
			`AmbientCapabilities=CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_ADMIN CAP_SETUID CAP_SETGID CAP_CHOWN`
			`CapabilityBoundingSet=CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_ADMIN CAP_SETUID CAP_SETGID CAP_CHOWN`
			`EOF`
			```
docs.pikvm.org 2021-10-12 18:45:00 +00:00
Update bluetooth_hid.md 2020-11-07 23:02:00 +00:00			6. Add following lines to `/etc/kvmd/override.yaml`:
docs.pikvm.org 2021-10-12 18:45:00 +00:00
Update bluetooth_hid.md 2020-11-07 23:02:00 +00:00			```yaml
			`kvmd:`
			`hid:`
			`type: bt`
			```

docs.pikvm.org 2021-10-12 18:45:00 +00:00			7. Perform `reboot`.

			8. To reverse, uncomment lines from Step 2 and remove lines in Step 6, and `reboot`.


			`## Using Bluetooth HID`

rebranding 2021-09-26 08:47:33 +00:00			* After a reboot, the PiKVM will be ready for detection and pairing with no auth. You will see the `PiKVM HID` device.
docs.pikvm.org 2021-10-12 18:45:00 +00:00
rebranding 2021-09-26 08:47:33 +00:00			`* Once the server is connected, PiKVM will no longer be discoverable and pairable to other clients until you unpair the server.`
docs.pikvm.org 2021-10-12 18:45:00 +00:00
rebranding 2021-09-26 08:47:33 +00:00			* If something went wrong, use the web menu `System -> Reset keyboard & mouse`. This will cause unpair the device and switch the PiKVM to public mode before the first client is connected.