Add documentation. Make the BT controller MAC configurable.

BluetoothHID.py

@@ -47,10 +47,10 @@ class BluetoothHIDService(object):
     HOST = 0
     PORT = 1
 
-    def __init__(self, service_record):
+    def __init__(self, service_record, MAC):
         self.P_CTRL = 0x0011
         self.P_INTR = 0x0013
-        self.SELFMAC = "7C:67:A2:94:6B:B8"
+        self.SELFMAC = MAC
         bus = dbus.SystemBus()
         bluez_obj = bus.get_object("org.bluez", "/org/bluez")
         manager = dbus.Interface(bluez_obj, "org.bluez.ProfileManager1")

README.md

@@ -0,0 +1,78 @@
+# EmuBTHID
+
+## Description
+
+This tool emulates a simple bluetooth HID device (keyboard + mouse) based on bluez and xserver from linux. It was orignally designed for a poor student cannot afford a bluetooth keyboard. That poor student used laptop keyboard/mouse to control an android phone via bluetooth.
+
+Via bluez, EmuBTHID registers a special bluetooth service ("00001124-0000-1000-8000-00805f9b34fb") which can serve as a HID device and be discoverable by other users.
+
+Via Xlib, EmuBTHID creates a X window, which grabs keyboard/mouse input and send them to remote.
+
+This tool requires "root" to listen to priviledged bluetooth ports, which communicate with remote devices.
+
+## Dependencies
+
+This tool is recently tested under Archlinux:
+
+kernel: 5.7.7
+
+bluez: 5.54-2
+
+xorg-server: 1.20.8
+
+
+
+python libraries:
+
+python-xlib 0.27
+dbus-python 1.2.16
+
+
+
+The client who uses the emulated HID device is an android 9 phone.
+
+## How to Use
+
+### Update the bluetooth controller MAC in `main.py`
+
+Edit `main.py` and change the `CONTROLLER_MAC` variable in the beginning to your own MAC. You can find the MAC of the bluetooth controller in `bluetoothctl`. E.g. the "5C:87:9C:96:BE:5E" shown in the screenshot below is the MAC.
+
+### Enable bluetooth
+
+1. make sure bluetooth service is running (systemctl status bluetooth)
+2. enter `bluetoothctl` and do `power on`
+3. make sure the bluetooth controller is not blocked by software (check rfkill or enable bluetooth in your desktop manager, e.g. gnome)
+4. Run `xhost +` to enable root user also draw something on a non-root user's X session. (see [this stackoverflow](https://stackoverflow.com/questions/31902846/how-to-fix-error-xlib-error-displayconnectionerror-cant-connect-to-display-0))
+5. Run `sudo python3 main.py`
+
+In bluetoothctl, it should look like this, where a lot of UUIDs are registered
+
+![bluetoothctl_1](imgs/bluetoothctl-1.png)
+
+And you can find this specific `Class` value and UUID for a "Human Interface Device" appears in `show`
+
+![bluetoothctl-2](imgs/bluetoothctl-2.png)
+
+On the other hand, you should be able to see the main window of EmuBTHID which will capture your keyboard/mouse input:
+
+![MainWindow](imgs/MainWindow.png)
+
+6. Now go back to bluetoothctl, enable discoverable
+
+   ![bluetoothctl-3](imgs/bluetoothctl-3.png)
+
+7. Now you should be able to discover a new HID device on other devices (e.g. an android phone). Now pair or re-connect. You should finish the pairing procedure in bluetoothctl (there will be a prompt). It looks like this:
+
+   ![bluetoothctl-4](imgs/bluetoothctl-4.png)
+
+8. Final step, go back to the main window. enter "Ctrl+Alt+Shift+B" as shown in the window to grab keyboard as well as mouse input. Press the same combination again to un-grab.
+
+## Known Issues
+
+1. The `xhost +` is pretty hacky and may raise security concerns. But I am personally fine with that.
+
+2. After pairing or connecting to this emulated HID device, `bluetoothctl` will show a lot of authorize prompt, which I normally ignore.
+
+   ![bluetoothctl-authorize-prompt](imgs/bluetoothctl-authorize-prompt.png)
+
+3. Even though the keyboard usually works pretty well, the mouse sometimes becomes lagging. But I normally only use the keyboard feature.

TODO

@@ -3,6 +3,5 @@
 1. modularize main X application window and the key/mouse event parsing.
 2. modify sdp record so we won't need the privilege to bind low L2CAP port.
 3. make the wheel (touchpad swipe gesture) work
-4. write a readme
-5. summarize keyboard shortcut, [reference](https://forum.xda-developers.com/showthread.php?t=1672281)
-6. low resolution of pointer events in Xlib
+4. summarize keyboard shortcut, [reference](https://forum.xda-developers.com/showthread.php?t=1672281)
+5. low resolution of pointer events in Xlib

main.py

@@ -9,6 +9,11 @@ import keymap
 from Xlib import X, display, Xutil
 from dbus.mainloop.glib import DBusGMainLoop
 
+"""
+Change this CONTROLLER_MAC to the mac of your own device
+"""
+CONTROLLER_MAC = "5C:87:9C:96:BE:5E"
+
 usbhid_map = {}
 with open("keycode.txt") as f:
     for line in f.read().splitlines():
@@ -223,7 +228,7 @@ if __name__ == '__main__':
     d = display.Display()
     d.change_keyboard_control(auto_repeat_mode=X.AutoRepeatModeOff)
     try:
-        bthid_srv = BluetoothHIDService(service_record)
+        bthid_srv = BluetoothHIDService(service_record, CONTROLLER_MAC)
         Window(d).loop(bthid_srv.send)
         #Window(d).loop(print)
     finally: