Skip to content

Commit d7d2d86

Browse files
quaxalberquaxalber
authored
Monitor USB connectivity (#133)
* Implement UDC state monitor * Set default interrupt shortcut * Release all buttons on shortcut trigger * Rename relay_active_event * Make ContextManagers async * Remove unused imports * Remove unnecessary code * Adapt logging * Update docs
1 parent e24475c commit d7d2d86

File tree

4 files changed

+452
-345
lines changed

4 files changed

+452
-345
lines changed

‎README.md

+63-76
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,8 @@ Linux's gadget mode allows a Raspberry Pi to act as USB HID (Human Interface Dev
2727
- [4.1.1. Raspberry Pi 4B/5](#411-raspberry-pi-4b5)
2828
- [4.1.2. Raspberry Pi Zero (2) W(H)](#412-raspberry-pi-zero-2-wh)
2929
- [4.2. Command-line arguments](#42-command-line-arguments)
30-
- [4.3. Consuming the API from your Python code](#43-consuming-the-api-from-your-python-code)
30+
- [4.3. Shortcut Feature for Quick Pi Administration](#43-shortcut-feature-for-quick-pi-administration)
31+
- [4.4. Consuming the API from your Python code](#44-consuming-the-api-from-your-python-code)
3132
- [5. Updating](#5-updating)
3233
- [6. Uninstallation](#6-uninstallation)
3334
- [7. Troubleshooting](#7-troubleshooting)
@@ -48,7 +49,7 @@ Linux's gadget mode allows a Raspberry Pi to act as USB HID (Human Interface Dev
4849
- Supports [146 multimedia keys](https://github.com/quaxalber/bluetooth_2_usb/blob/8b1c5f8097bbdedfe4cef46e07686a1059ea2979/lib/evdev_adapter.py#L142) (e.g., mute, volume up/down, launch browser, etc.)
4950
- Auto-discovery feature for input devices
5051
- Auto-reconnect feature for input devices (power off, energy saving mode, out of range, etc.)
51-
- Pause/resume relaying input devices via configurable shortcut
52+
- Pause/resume relaying input devices via [configurable shortcut](#43-shortcut-feature-for-quick-pi-administration)
5253
- Robust error handling and logging
5354
- Installation as a systemd service
5455
- Reliable concurrency using state-of-the-art [TaskGroups](https://docs.python.org/3/library/asyncio-task.html#task-groups)
@@ -206,7 +207,11 @@ options:
206207
--help, -h Show this help message and exit.
207208
```
208209

209-
### 4.3. Consuming the API from your Python code
210+
### 4.3. Shortcut Feature for Quick Pi Administration
211+
212+
A key challenge when using Bluetooth 2 USB on a Raspberry Pi as systemd service is being able to temporarily disable input relaying so you can administer the Pi locally. The shortcut feature solves this by allowing you to specify a keyboard shortcut that toggles the relaying on or off at any time. For example, you might configure `CTRL` + `SHIFT` + `F12` (default set in `bluetooth_2_usb.service`) as a global interrupt shortcut. While relaying is active, pressing that key combination will instantly halt relaying, allowing the Pi to receive keyboard input locally. Pressing the same shortcut again re-enables relaying.
213+
214+
### 4.4. Consuming the API from your Python code
210215

211216
The API is designed such that it may be consumed both via CLI and from within external Python code. More details on this [coming soon](https://github.com/quaxalber/bluetooth_2_usb/issues/16)!
212217

@@ -361,84 +366,66 @@ Here's a few things you could try:
361366
- For easier degguging, you may temporarily stop the service and run the script manually, modifying arguments as required, e.g., increase log verbosity by appending `-d`:
362367

363368
```console
364-
sudo service bluetooth_2_usb stop && sudo bluetooth_2_usb -ad ; sudo service bluetooth_2_usb start
369+
{ sudo service bluetooth_2_usb stop && sudo bluetooth_2_usb -gads CTRL+SHIFT+F12 ; } ; sudo service bluetooth_2_usb start
365370
```
366371

367372
- When you interact with your Bluetooth devices with `-d` set, you should see debug output in the logs such as:
368373

369374
```console
370-
user@pi0w:~ $ sudo service bluetooth_2_usb stop && sudo bluetooth_2_usb -gads "CTRL+SHIFT+F12" ; sudo service bluetooth_2_usb start
371-
25-01-26 13:21:39 [DEBUG] CLI args: device_ids=None, auto_discover=True, grab_devices=True, interrupt_shortcut=['CTRL', 'SHIFT', 'F12'], list_devices=False, log_to_file=False, log_path=/var/log/bluetooth_2_usb/bluetooth_2_usb.log, debug=True, version=False
372-
25-01-26 13:21:39 [DEBUG] Logging to stdout
373-
25-01-26 13:21:39 [INFO] Launching Bluetooth 2 USB v0.9.0
374-
25-01-26 13:21:39 [DEBUG] Configuring global interrupt shortcut: {'KEY_F12', 'KEY_LEFTCTRL', 'KEY_LEFTSHIFT'}
375-
25-01-26 13:21:42 [DEBUG] USB HID gadgets re-initialized: [boot mouse gadget (/dev/hidg0), keyboard gadget (/dev/hidg1), consumer control gadget (/dev/hidg2)]
376-
25-01-26 13:21:42 [DEBUG] UdevEventMonitor initialized (observer not started yet).
377-
25-01-26 13:21:42 [DEBUG] UdevEventMonitor started observer.
378-
25-01-26 13:21:42 [DEBUG] RelayController: TaskGroup started.
379-
25-01-26 13:21:42 [DEBUG] Created task for device /dev/input/event2, name "AceRK Keyboard", phys "b8:27:eb:be:dc:81".
380-
25-01-26 13:21:42 [DEBUG] Created task for device /dev/input/event3, name "AceRK Mouse", phys "b8:27:eb:be:dc:81".
381-
25-01-26 13:21:42 [INFO] Activated relay for device /dev/input/event2, name "AceRK Keyboard", phys "b8:27:eb:be:dc:81"
382-
25-01-26 13:21:42 [INFO] Activated relay for device /dev/input/event3, name "AceRK Mouse", phys "b8:27:eb:be:dc:81"
383-
25-01-26 13:21:53 [DEBUG] Received event at 1737894113.194308, code 04, type 04, val 458756 from AceRK Keyboard
384-
25-01-26 13:21:53 [DEBUG] Received key event at 1737894113.194308, 30 (KEY_A), down from AceRK Keyboard
385-
25-01-26 13:21:53 [DEBUG] Converted evdev scancode 0x1E (KEY_A) to HID UsageID 0x04 (A)
386-
25-01-26 13:21:53 [DEBUG] Pressing A (0x04)
387-
25-01-26 13:21:53 [DEBUG] Received synchronization event at 1737894113.194308, SYN_REPORT from AceRK Keyboard
388-
25-01-26 13:21:53 [DEBUG] Received event at 1737894113.243246, code 04, type 04, val 458756 from AceRK Keyboard
389-
25-01-26 13:21:53 [DEBUG] Received key event at 1737894113.243246, 30 (KEY_A), up from AceRK Keyboard
390-
25-01-26 13:21:53 [DEBUG] Converted evdev scancode 0x1E (KEY_A) to HID UsageID 0x04 (A)
391-
25-01-26 13:21:53 [DEBUG] Releasing A (0x04)
392-
25-01-26 13:21:53 [DEBUG] Received synchronization event at 1737894113.243246, SYN_REPORT from AceRK Keyboard
393-
25-01-26 13:22:02 [DEBUG] Received relative axis event at 1737894122.359603, REL_X from AceRK Mouse
394-
25-01-26 13:22:02 [DEBUG] Moving mouse (x=125, y=0, mwheel=0)
395-
25-01-26 13:22:02 [DEBUG] Received synchronization event at 1737894122.359603, SYN_REPORT from AceRK Mouse
396-
25-01-26 13:22:21 [DEBUG] Received event at 1737894141.518490, code 04, type 04, val 458977 from AceRK Keyboard
397-
25-01-26 13:22:21 [DEBUG] Received key event at 1737894141.518490, 42 (KEY_LEFTSHIFT), down from AceRK Keyboard
398-
25-01-26 13:22:21 [DEBUG] Converted evdev scancode 0x2A (KEY_LEFTSHIFT) to HID UsageID 0xE1 (LEFT_SHIFT)
399-
25-01-26 13:22:21 [DEBUG] Pressing LEFT_SHIFT (0xE1)
400-
25-01-26 13:22:21 [DEBUG] Received synchronization event at 1737894141.518490, SYN_REPORT from AceRK Keyboard
401-
25-01-26 13:22:22 [DEBUG] Received event at 1737894142.444821, code 04, type 04, val 458976 from AceRK Keyboard
402-
25-01-26 13:22:22 [DEBUG] Received key event at 1737894142.444821, 29 (KEY_LEFTCTRL), down from AceRK Keyboard
403-
25-01-26 13:22:22 [DEBUG] Converted evdev scancode 0x1D (KEY_LEFTCTRL) to HID UsageID 0xE0 (CONTROL)
404-
25-01-26 13:22:22 [DEBUG] Pressing CONTROL (0xE0)
405-
25-01-26 13:22:22 [DEBUG] Received synchronization event at 1737894142.444821, SYN_REPORT from AceRK Keyboard
406-
25-01-26 13:22:24 [INFO] ShortcutToggler: Relaying is now OFF.
407-
25-01-26 13:22:24 [DEBUG] Ungrabbed device /dev/input/event2, name "AceRK Keyboard", phys "b8:27:eb:be:dc:81"
408-
25-01-26 13:22:34 [DEBUG] Ungrabbed device /dev/input/event3, name "AceRK Mouse", phys "b8:27:eb:be:dc:81"
409-
25-01-26 13:22:46 [INFO] ShortcutToggler: Relaying is now ON.
410-
25-01-26 13:22:46 [DEBUG] Grabbed device /dev/input/event2, name "AceRK Keyboard", phys "b8:27:eb:be:dc:81"
411-
25-01-26 13:22:46 [DEBUG] Received key event at 1737894166.576799, 88 (KEY_F12), down from AceRK Keyboard
412-
25-01-26 13:22:46 [DEBUG] Converted evdev scancode 0x58 (KEY_F12) to HID UsageID 0x45 (F12)
413-
25-01-26 13:22:46 [DEBUG] Pressing F12 (0x45)
414-
25-01-26 13:22:46 [DEBUG] Received synchronization event at 1737894166.576799, SYN_REPORT from AceRK Keyboard
415-
25-01-26 13:22:46 [DEBUG] Received event at 1737894166.625320, code 04, type 04, val 458821 from AceRK Keyboard
416-
25-01-26 13:22:46 [DEBUG] Received key event at 1737894166.625320, 88 (KEY_F12), up from AceRK Keyboard
417-
25-01-26 13:22:46 [DEBUG] Converted evdev scancode 0x58 (KEY_F12) to HID UsageID 0x45 (F12)
418-
25-01-26 13:22:46 [DEBUG] Releasing F12 (0x45)
419-
25-01-26 13:22:46 [DEBUG] Received synchronization event at 1737894166.625320, SYN_REPORT from AceRK Keyboard
420-
25-01-26 13:22:49 [DEBUG] Received event at 1737894169.452812, code 04, type 04, val 458976 from AceRK Keyboard
421-
25-01-26 13:22:49 [DEBUG] Received key event at 1737894169.452812, 29 (KEY_LEFTCTRL), up from AceRK Keyboard
422-
25-01-26 13:22:49 [DEBUG] Converted evdev scancode 0x1D (KEY_LEFTCTRL) to HID UsageID 0xE0 (CONTROL)
423-
25-01-26 13:22:49 [DEBUG] Releasing CONTROL (0xE0)
424-
25-01-26 13:22:49 [DEBUG] Received synchronization event at 1737894169.452812, SYN_REPORT from AceRK Keyboard
425-
25-01-26 13:22:50 [DEBUG] Received event at 1737894170.378918, code 04, type 04, val 458977 from AceRK Keyboard
426-
25-01-26 13:22:50 [DEBUG] Received key event at 1737894170.378918, 42 (KEY_LEFTSHIFT), up from AceRK Keyboard
427-
25-01-26 13:22:50 [DEBUG] Converted evdev scancode 0x2A (KEY_LEFTSHIFT) to HID UsageID 0xE1 (LEFT_SHIFT)
428-
25-01-26 13:22:50 [DEBUG] Releasing LEFT_SHIFT (0xE1)
429-
25-01-26 13:22:50 [DEBUG] Received synchronization event at 1737894170.378918, SYN_REPORT from AceRK Keyboard
430-
25-01-26 13:22:52 [DEBUG] Grabbed device /dev/input/event3, name "AceRK Mouse", phys "b8:27:eb:be:dc:81"
431-
25-01-26 13:22:52 [DEBUG] Received relative axis event at 1737894172.475360, REL_X from AceRK Mouse
432-
25-01-26 13:22:52 [DEBUG] Moving mouse (x=50, y=0, mwheel=0)
433-
25-01-26 13:22:52 [DEBUG] Received synchronization event at 1737894172.475360, SYN_REPORT from AceRK Mouse
434-
25-01-26 13:23:07 [DEBUG] Received signal: SIGINT. Requesting graceful shutdown.
435-
25-01-26 13:23:07 [DEBUG] Shutdown event triggered. Cancelling relay task...
436-
25-01-26 13:23:07 [DEBUG] Relay cancelled for device device /dev/input/event3, name "AceRK Mouse", phys "b8:27:eb:be:dc:81".
437-
25-01-26 13:23:07 [DEBUG] Cancelling relay for /dev/input/event3.
438-
25-01-26 13:23:07 [DEBUG] Relay cancelled for device device /dev/input/event2, name "AceRK Keyboard", phys "b8:27:eb:be:dc:81".
439-
25-01-26 13:23:07 [DEBUG] Cancelling relay for /dev/input/event2.
440-
25-01-26 13:23:07 [DEBUG] RelayController: TaskGroup exited.
441-
25-01-26 13:23:07 [DEBUG] UdevEventMonitor stopped observer.
375+
user@pi0w:~ $ { sudo service bluetooth_2_usb stop && sudo bluetooth_2_usb -gads CTRL+SHIFT+F12 ; } ; sudo service bluetooth_2_usb start
376+
25-01-31 13:16:14 [DEBUG] CLI args: device_ids=None, auto_discover=True, grab_devices=True, interrupt_shortcut=['CTRL', 'SHIFT', 'F12'], list_devices=False, log_to_file=False, log_path=/var/log/bluetooth_2_usb/bluetooth_2_usb.log, debug=True, version=False
377+
25-01-31 13:16:14 [DEBUG] Logging to stdout
378+
25-01-31 13:16:14 [INFO] Launching Bluetooth 2 USB v0.9.0
379+
25-01-31 13:16:17 [DEBUG] USB HID gadgets re-initialized: [boot mouse gadget (/dev/hidg0), keyboard gadget (/dev/hidg1), consumer control gadget (/dev/hidg2)]
380+
25-01-31 13:16:17 [DEBUG] Configuring global interrupt shortcut: {'KEY_LEFTCTRL', 'KEY_LEFTSHIFT', 'KEY_F12'}
381+
25-01-31 13:16:17 [DEBUG] Detected UDC state file: /sys/class/udc/fe980000.usb/state
382+
25-01-31 13:16:17 [DEBUG] UdevEventMonitor started observer.
383+
25-01-31 13:16:17 [DEBUG] UDC state changed to 'configured'
384+
25-01-31 13:16:17 [DEBUG] RelayController: TaskGroup started.
385+
25-01-31 13:16:17 [DEBUG] Created task for device /dev/input/event4, name "AceRK Keyboard", phys "e4:5f:01:01:c4:8c".
386+
25-01-31 13:16:17 [DEBUG] Created task for device /dev/input/event5, name "AceRK Mouse", phys "e4:5f:01:01:c4:8c".
387+
25-01-31 13:16:17 [INFO] Activated relay for device /dev/input/event4, name "AceRK Keyboard", phys "e4:5f:01:01:c4:8c"
388+
25-01-31 13:16:17 [INFO] Activated relay for device /dev/input/event5, name "AceRK Mouse", phys "e4:5f:01:01:c4:8c"
389+
25-01-31 13:16:38 [DEBUG] Received key event at 1738325798.022707, 30 (KEY_A), down from AceRK Keyboard (/dev/input/event4)
390+
25-01-31 13:16:38 [DEBUG] Converted evdev scancode 0x1E (KEY_A) to HID UsageID 0x04 (A)
391+
25-01-31 13:16:38 [DEBUG] Pressing A (0x04) via keyboard gadget (/dev/hidg1)
392+
a25-01-31 13:16:38 [DEBUG] Received key event at 1738325798.071509, 30 (KEY_A), up from AceRK Keyboard (/dev/input/event4)
393+
25-01-31 13:16:38 [DEBUG] Converted evdev scancode 0x1E (KEY_A) to HID UsageID 0x04 (A)
394+
25-01-31 13:16:38 [DEBUG] Releasing A (0x04) via keyboard gadget (/dev/hidg1)
395+
25-01-31 13:16:39 [DEBUG] Received relative axis event at 1738325799.972492, REL_WHEEL from AceRK Mouse (/dev/input/event5)
396+
25-01-31 13:16:39 [DEBUG] Received relative axis event at 1738325799.972492, REL_WHEEL_HI_RES from AceRK Mouse (/dev/input/event5)
397+
25-01-31 13:16:40 [DEBUG] Received relative axis event at 1738325800.801245, REL_X from AceRK Mouse (/dev/input/event5)
398+
25-01-31 13:16:40 [DEBUG] Received relative axis event at 1738325800.801245, REL_Y from AceRK Mouse (/dev/input/event5)
399+
25-01-31 13:16:44 [DEBUG] Received key event at 1738325804.311271, 114 (KEY_VOLUMEDOWN), down from AceRK Keyboard (/dev/input/event4)
400+
25-01-31 13:16:45 [DEBUG] Received key event at 1738325805.578790, 114 (KEY_VOLUMEDOWN), down from AceRK Keyboard (/dev/input/event4)
401+
25-01-31 13:16:45 [DEBUG] Converted evdev scancode 0x72 (KEY_VOLUMEDOWN) to HID UsageID 0xEA (VOLUME_DECREMENT)
402+
25-01-31 13:16:45 [DEBUG] Pressing VOLUME_DECREMENT (0xEA) via consumer control gadget (/dev/hidg2)
403+
25-01-31 13:16:45 [DEBUG] Received key event at 1738325805.579166, 114 (KEY_VOLUMEDOWN), up from AceRK Keyboard (/dev/input/event4)
404+
25-01-31 13:16:45 [DEBUG] Converted evdev scancode 0x72 (KEY_VOLUMEDOWN) to HID UsageID 0xEA (VOLUME_DECREMENT)
405+
25-01-31 13:16:45 [DEBUG] Releasing VOLUME_DECREMENT (0xEA) via consumer control gadget (/dev/hidg2)
406+
25-01-31 13:16:59 [DEBUG] Received key event at 1738325819.472779, 29 (KEY_LEFTCTRL), down from AceRK Keyboard (/dev/input/event4)
407+
25-01-31 13:16:59 [DEBUG] Converted evdev scancode 0x1D (KEY_LEFTCTRL) to HID UsageID 0xE0 (CONTROL)
408+
25-01-31 13:16:59 [DEBUG] Pressing CONTROL (0xE0) via keyboard gadget (/dev/hidg1)
409+
25-01-31 13:17:00 [DEBUG] Received key event at 1738325820.545488, 42 (KEY_LEFTSHIFT), down from AceRK Keyboard (/dev/input/event4)
410+
25-01-31 13:17:00 [DEBUG] Converted evdev scancode 0x2A (KEY_LEFTSHIFT) to HID UsageID 0xE1 (LEFT_SHIFT)
411+
25-01-31 13:17:00 [DEBUG] Pressing LEFT_SHIFT (0xE1) via keyboard gadget (/dev/hidg1)
412+
25-01-31 13:17:02 [DEBUG] Received key event at 1738325822.349053, 88 (KEY_F12), down from AceRK Keyboard (/dev/input/event4)
413+
25-01-31 13:17:02 [INFO] ShortcutToggler: Relaying is now OFF.
414+
25-01-31 13:17:02 [DEBUG] Ungrabbed device /dev/input/event4, name "AceRK Keyboard", phys "e4:5f:01:01:c4:8c"
415+
25-01-31 13:17:02 [DEBUG] Received key event at 1738325822.397839, 88 (KEY_F12), up from AceRK Keyboard (/dev/input/event4)
416+
25-01-31 13:17:09 [DEBUG] Received key event at 1738325829.466866, 29 (KEY_LEFTCTRL), up from AceRK Keyboard (/dev/input/event4)
417+
25-01-31 13:17:10 [DEBUG] Received key event at 1738325830.441662, 42 (KEY_LEFTSHIFT), up from AceRK Keyboard (/dev/input/event4)
418+
25-01-31 13:17:12 [DEBUG] Received key event at 1738325832.781695, 29 (KEY_LEFTCTRL), down from AceRK Keyboard (/dev/input/event4)
419+
25-01-31 13:17:13 [DEBUG] Received key event at 1738325833.756742, 42 (KEY_LEFTSHIFT), down from AceRK Keyboard (/dev/input/event4)
420+
25-01-31 13:17:15 [DEBUG] Received key event at 1738325835.414227, 88 (KEY_F12), down from AceRK Keyboard (/dev/input/event4)
421+
25-01-31 13:17:15 [INFO] ShortcutToggler: Relaying is now ON.
422+
25-01-31 13:17:15 [DEBUG] Grabbed device /dev/input/event4, name "AceRK Keyboard", phys "e4:5f:01:01:c4:8c"
423+
^C25-01-31 13:17:27 [DEBUG] Received signal: SIGINT. Requesting graceful shutdown.
424+
25-01-31 13:17:27 [DEBUG] Shutdown event triggered. Cancelling relay task...
425+
25-01-31 13:17:27 [DEBUG] Cancelled relay for /dev/input/event5.
426+
25-01-31 13:17:27 [DEBUG] Cancelled relay for /dev/input/event4.
427+
25-01-31 13:17:27 [DEBUG] RelayController: TaskGroup exited.
428+
25-01-31 13:17:27 [DEBUG] UdevEventMonitor stopped observer.
442429
```
443430

444431
- Still not resolved? Double-check the [installation instructions](#3-installation)

0 commit comments

Comments
 (0)