Merge pull request #45 from quaxalber/development

Create update & uninstall scripts

CONTRIBUTING.md

@@ -15,17 +15,50 @@ Thank you for considering contributing to Bluetooth 2 USB! We value your effort
   - [3.2. Code Formatting with Black](#32-code-formatting-with-black)
 - [4. Pull Requests](#4-pull-requests)
 - [5. Reporting Issues](#5-reporting-issues)
-- [6. Additional Resources](#6-additional-resources)
 
 ## 1. Code of Conduct
 
 By participating in this project, you are expected to uphold our [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## 2. Getting Started
 
-- Fork the repository on GitHub
-- Clone the forked repository to your machine
+- [Fork the repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) on GitHub
+
+- Install required packages to your Linux machine:
+
+  ```console 
+  sudo apt update && sudo apt install -y git python3.11 python3.11-venv python3.11-dev
+  ```
+
+- Clone the forked repository:
+
+  ```console
+  git clone https://github.com/YOUR-ACCOUNT/bluetooth_2_usb.git
+  ```
+
+- Initialize submodules:
+
+  ```console 
+  cd bluetooth_2_usb && git submodule update --init --recursive
+  ```
+
+- Create a virtual Python environment:
+
+  ```console 
+  python3.11 -m venv venv 
+  ```
+
+- Install submodules in virtual Python environment:
+
+  ```console 
+  venv/bin/pip3.11 install submodules/* 
+  ```  
+
 - Open the repo in your favorite IDE
+
+- Make sure that your IDE is using python3.11 from `bluetooth_2_usb/venv/bin/`, e.g. in VS Code:
+
+  `CTRL + SHIFT + P` > type `Python Select Interpreter` > `Enter interpreter path` 
 
 ## 3. Coding Style
 
@@ -80,17 +113,12 @@ This will automatically reformat your code to conform to the project's coding st
 - Create a new branch for each feature or bugfix you are working on.
 - Commit your changes following the [coding style](#3-coding-style) guidelines. Add concise commit messages. 
 - Push your changes to your fork.
-- Create a new Pull Request targeting the main branch of the official repository. A short description helps the maintainers reviewing the changes. 
+- [Create a new Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) targeting the main branch of the official repository. A short description helps the maintainers reviewing the changes. 
 
 ## 5. Reporting Issues
 
 Please use the GitHub [issue tracker](https://github.com/quaxalber/bluetooth_2_usb/issues) to report any bugs or to request new features. Make sure to check for existing issues that are related to yours before creating a new one.
 
-## 6. Additional Resources
-
-- [GitHub Pull Request documentation](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)
-- [GitHub Forking a repo documentation](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
-
 ---
 
 Thank you for taking the time to contribute!

README.md

@@ -13,18 +13,23 @@
   - [4.1. Prerequisites](#41-prerequisites)
   - [4.2. Setup](#42-setup)
 - [5. Usage](#5-usage)
-  - [5.1. Command-line arguments](#51-command-line-arguments)
-  - [5.2. Consuming the API from your Python code](#52-consuming-the-api-from-your-python-code)
-- [6. Troubleshooting](#6-troubleshooting)
-  - [6.1. The Pi keeps rebooting or crashes randomly](#61-the-pi-keeps-rebooting-or-crashes-randomly)
-  - [6.2. The installation was successful, but I don't see any output on the target device](#62-the-installation-was-successful-but-i-dont-see-any-output-on-the-target-device)
-  - [6.3. In bluetoothctl, my device is constantly switching on/off](#63-in-bluetoothctl-my-device-is-constantly-switching-onoff)
-  - [6.4. I have a different issue](#64-i-have-a-different-issue)
-  - [6.5. Everything is working, but can it help me with Bitcoin mining?](#65-everything-is-working-but-can-it-help-me-with-bitcoin-mining)
-- [7. Bonus points](#7-bonus-points)
-- [8. Contributing](#8-contributing)
-- [9. License](#9-license)
-- [10. Acknowledgments](#10-acknowledgments)
+  - [5.1. Connection to target device / host](#51-connection-to-target-device--host)
+    - [5.1.1. Raspberry Pi 4 Model B](#511-raspberry-pi-4-model-b)
+    - [5.1.2. Raspberry Pi Zero (2) W(H)](#512-raspberry-pi-zero-2-wh)
+  - [5.2. Command-line arguments](#52-command-line-arguments)
+  - [5.3. Consuming the API from your Python code](#53-consuming-the-api-from-your-python-code)
+- [6. Updating](#6-updating)
+- [7. Uninstallation](#7-uninstallation)
+- [8. Troubleshooting](#8-troubleshooting)
+  - [8.1. The Pi keeps rebooting or crashes randomly](#81-the-pi-keeps-rebooting-or-crashes-randomly)
+  - [8.2. The installation was successful, but I don't see any output on the target device](#82-the-installation-was-successful-but-i-dont-see-any-output-on-the-target-device)
+  - [8.3. In bluetoothctl, my device is constantly switching on/off](#83-in-bluetoothctl-my-device-is-constantly-switching-onoff)
+  - [8.4. I have a different issue](#84-i-have-a-different-issue)
+  - [8.5. Everything is working, but can it help me with Bitcoin mining?](#85-everything-is-working-but-can-it-help-me-with-bitcoin-mining)
+- [9. Bonus points](#9-bonus-points)
+- [10. Contributing](#10-contributing)
+- [11. License](#11-license)
+- [12. Acknowledgments](#12-acknowledgments)
 
 ## 1. Introduction
 
@@ -47,9 +52,19 @@ Sounds familiar? Congratulations! **You just found the solution!**
 
 ## 3. Requirements
 
-- ([Single-board](https://en.wikipedia.org/wiki/Single-board_computer)) computer with Bluetooth support, e.g. Raspberry Pi 4B (recommended) or Raspberry Pi Zero **_W_**
-- Linux OS with systemd support, e.g. [Raspberry Pi OS](https://www.raspberrypi.com/software/) (recommended)
-- Python 3.11 for using [TaskGroups](https://docs.python.org/3/library/asyncio-task.html#task-groups)
+- A Raspberry Pi with Bluetooth and [USB OTG support](https://en.wikipedia.org/wiki/USB_On-The-Go) required for [USB gadgets](https://www.kernel.org/doc/html/latest/driver-api/usb/gadget.html) in so-called device mode. Recommended models include:
+  - **Raspberry Pi 4 Model B**: Offers Bluetooth 5.0 and USB-C OTG support for device mode, providing the best performance (until the Pi 5 is available).
+  - **Raspberry Pi Zero W/WH**: Includes Bluetooth 4.1 and supports USB OTG with a lower price tag.
+  - **Raspberry Pi Zero 2 W**: Similar to the Raspberry Pi Zero W, it has Bluetooth 4.1 and USB OTG support while providing additional processing power.
+
+> [!NOTE]
+> Raspberry Pi 3 Models feature Bluetooth 4.2 but no native USB gadget mode support. Earlier models like Raspberry Pi 1 and 2 do not support Bluetooth natively and have no USB gadget mode support.
+
+- Linux OS with systemd support (e.g., [Raspberry Pi OS](https://www.raspberrypi.com/software/), recommended).
+- Python 3.11 for using [TaskGroups](https://docs.python.org/3/library/asyncio-task.html#task-groups).
+
+> [!NOTE]
+> The latest version of Raspberry Pi OS, based on Debian Bookworm, supports Python 3.11 through the official package repositories. For older versions, you may [build it from source](https://github.com/quaxalber/bluetooth_2_usb/blob/main/scripts/build_python_3.11.sh). 
 
 ## 4. Installation
 
@@ -100,7 +115,7 @@ Follow these steps to install and configure the project:
 7. Run the installation script as root: 
 
    ```console
-   sudo bash install.sh
+   sudo scripts/install.sh
    ```
 
 8.  Reboot:
@@ -164,22 +179,30 @@ Follow these steps to install and configure the project:
                 └─1664 /home/user/bluetooth_2_usb/venv/bin/python3.11 /usr/bin/bluetooth_2_usb.py -k /dev/input/event2 -m /dev/input/event3
 
     Nov 18 19:00:19 pi4b systemd[1]: Started bluetooth_2_usb.service - Bluetooth to USB HID proxy.
-    Nov 18 19:00:19 pi4b python3.11[1664]: 23-11-18 19:00:19 [INFO] Launching Bluetooth 2 USB v0.4.5
+    Nov 18 19:00:19 pi4b python3.11[1664]: 23-11-18 19:00:19 [INFO] Launching Bluetooth 2 USB v0.4.6
     Nov 18 19:00:22 pi4b python3.11[1664]: 23-11-18 19:00:22 [INFO] Starting event loop for [device /dev/input/event2, name "AceRK Keyboard", phys "0a:1b:2c:3d:4e:5f"] >> [Keyboard gadget (/dev/hidg1) + Consumer control gadget (/dev/hidg2)]
     Nov 18 19:00:22 pi4b python3.11[1664]: 23-11-18 19:00:22 [INFO] Starting event loop for [device /dev/input/event3, name "AceRK Mouse", phys "0a:1b:2c:3d:4e:5f"] >> [Boot mouse gadget (/dev/hidg0)]
     ```
 
 > [!NOTE]
-> Something seems off? Try yourself in [Troubleshooting](#6-troubleshooting)! 
+> Something seems off? Try yourself in [Troubleshooting](#8-troubleshooting)! 
     
 ## 5. Usage
 
-Connect the power USB port of your Pi (Micro-USB or USB-C) via cable with a USB port on your target device. You should hear the USB connection sound (depending on the target device) and be able to access your target device wirelessly using your Bluetooth keyboard or mouse. 
+### 5.1. Connection to target device / host
+
+#### 5.1.1. Raspberry Pi 4 Model B
+
+Connect the _USB-C power port_ of your Pi via cable with a USB port on your target device. You should hear the USB connection sound (depending on the target device) and be able to access your target device wirelessly using your Bluetooth keyboard or mouse. 
 
 > [!IMPORTANT]
 > It's essential to use the small power port instead of the bigger USB-A ports, since only the power port has the [OTG](https://en.wikipedia.org/wiki/USB_On-The-Go) feature required for [USB gadgets](https://www.kernel.org/doc/html/latest/driver-api/usb/gadget.html). 
 
-### 5.1. Command-line arguments
+#### 5.1.2. Raspberry Pi Zero (2) W(H)
+
+For the Pi0's, the situation is quite the opposite: Do _not_ use the power port to connect to the target device, _use_ the other port instead (typically labeled "DATA" or "USB"). The power port is solely used for power supply. 
+
+### 5.2. Command-line arguments
 
 Currently you can provide the following CLI arguments:
 
@@ -207,33 +230,49 @@ options:
   --list_devices, -l    List all available input devices and exit.
 ```
 
-### 5.2. Consuming the API from your Python code
+### 5.3. Consuming the API from your Python code
 
 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)! 
 
-## 6. Troubleshooting
+## 6. Updating 
+
+You may update to the latest stable release by running:
+
+```console
+sudo scripts/update.sh
+```
+
+## 7. Uninstallation 
+
+You may uninstall Bluetooth 2 USB by running:
+
+```console
+sudo scripts/uninstall.sh
+```
+
+## 8. Troubleshooting
 
-### 6.1. The Pi keeps rebooting or crashes randomly
+### 8.1. The Pi keeps rebooting or crashes randomly
 
-This is likely due to the limited power the Pi gets from the host's USB port. Try these steps:
+If you are using a Pi 4B, this is likely due to the limited power the Pi gets from the host's USB port. Try these steps:
 
-- If available, connect your Pi to a USB 3 port on the host  / target device (usually blue). 
+- If available, connect your Pi to a USB 3 port on the host / target device (usually blue) or preferably USB-C. 
 
 > [!IMPORTANT]
 > *Do not use* the blue (or black) USB-A ports *of your Pi* to connect. **This won't work.** 
 > 
-> *Do use* the small USB power port. 
+> *Do use* the small USB-C power port. 
 
 - Try to [connect to the Pi via SSH](#41-prerequisites) instead of attaching a display directly and remove any unnecessary peripherals.
 
 - Install a [lite version](https://downloads.raspberrypi.org/raspios_lite_arm64/images/) of your OS on the Pi (without GUI)
 
-- Get a [USB-C Data/Power Splitter](https://thepihut.com/products/usb-c-data-power-splitter) (or [Micro-USB](https://thepihut.com/products/micro-usb-data-power-splitter) respectively) and draw power from a sufficiently powerful power adaptor. This will ultimately resolve any power-related issues, and your Pi will no longer be dependent on the host's power supply. 
+- Get a [USB-C Data/Power Splitter](https://thepihut.com/products/usb-c-data-power-splitter) and draw current from a sufficiently powerful adaptor. This should ultimately resolve any power-related issues, and your Pi will no longer be dependent on the host's power supply. 
 
 > [!NOTE]
-> The Pi 4B requires 3A/15W for stable operation!
+> The Pi 4B requires 3 Amps for stable operation, while hosts may typically only deliver 0.5 to 0.9 Amps through USB-A 2.0/3.0 ports. 
 
-### 6.2. The installation was successful, but I don't see any output on the target device 
+### 8.2. The installation was successful, but I don't see any output on the target device 
 
 This could be due to a number of reasons. Try these steps:
 
@@ -297,7 +336,7 @@ This could be due to a number of reasons. Try these steps:
 
 - Try connecting to a different host 
 
-### 6.3. In bluetoothctl, my device is constantly switching on/off
+### 8.3. In bluetoothctl, my device is constantly switching on/off
 
 This is a common issue, especially when the device gets paired with multiple hosts. One simple fix/workaround is to re-pair the device:
 
@@ -324,7 +363,7 @@ exit
 > [!NOTE]
 > Replace `0A:1B:2C:3D:4E:5F` by your Pi's Bluetooth controller's MAC and `A1:B2:C3:D4:E5:F6` by your input device's MAC
 
-### 6.4. I have a different issue 
+### 8.4. I have a different issue 
 
 Here's a few things you could try:
 
@@ -366,7 +405,7 @@ Here's a few things you could try:
   user@pi4b:~/bluetooth_2_usb $ sudo venv/bin/python3.11 bluetooth_2_usb.py -k /dev/input/event2 -m /dev/input/event3 -d
   23-11-18 14:38:04 [DEBUG] CLI args: Namespace(keyboards=['/dev/input/event2'], mice=['/dev/input/event3'], sandbox=False, debug=True, log_to_file=False, log_path='/var/log/bluetooth_2_usb/bluetooth_2_usb.log', version=False, list_devices=False)
   23-11-18 14:38:04 [DEBUG] Logging to stdout
-  23-11-18 14:38:04 [INFO] Launching Bluetooth 2 USB v0.4.5
+  23-11-18 14:38:04 [INFO] Launching Bluetooth 2 USB v0.4.6
   23-11-18 14:38:04 [DEBUG] Available output devices: [Boot mouse gadget (/dev/hidg0), Keyboard gadget (/dev/hidg1), Consumer control gadget (/dev/hidg2)]
   23-11-18 14:38:07 [DEBUG] Sandbox mode disabled. All output devices activated.
   23-11-18 14:38:07 [DEBUG] Registered device link: [AceRK Keyboard]>>[/dev/hidg1+/dev/hidg2]
@@ -389,27 +428,27 @@ Here's a few things you could try:
 
 - For more help, open an [issue](https://github.com/quaxalber/bluetooth_2_usb/issues) in the [GitHub repository](https://github.com/quaxalber/bluetooth_2_usb)
 
-### 6.5. Everything is working, but can it help me with Bitcoin mining? 
+### 8.5. Everything is working, but can it help me with Bitcoin mining? 
 
 Absolutely! [Here's how](https://bit.ly/42BTC). 
 
-## 7. Bonus points 
+## 9. Bonus points 
 
-After successfully setting up your Pi as a HID proxy for your Bluetooth devices, you may consider making [Raspberry OS read-only](https://learn.adafruit.com/read-only-raspberry-pi/overview). That helps preventing the SD card from wearing out and the file system from getting corrupted when powering off the Raspberry forcefully.
+After successfully setting up your Pi as a HID proxy for your Bluetooth devices, you may consider making [Raspberry Pi OS read-only](https://learn.adafruit.com/read-only-raspberry-pi/overview). That helps preventing the SD card from wearing out and the file system from getting corrupted when powering off the Raspberry forcefully.
 
-## 8. Contributing
+## 10. Contributing
 
 Contributions are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines.
 
-## 9. License
+## 11. License
 
 This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
 
 "Bluetooth 2 HID" image [@PixelGordo](https://twitter.com/PixelGordo) is licensed under a [Creative Commons Attribution-NonCommercial 4.0 International License](http://creativecommons.org/licenses/by-nc/4.0/).
 
 ![License image.](https://i.creativecommons.org/l/by-nc/4.0/88x31.png)
 
-## 10. Acknowledgments
+## 12. Acknowledgments
 
 * [Mike Redrobe](https://github.com/mikerr/pihidproxy) for the idea and the basic code logic and [HeuristicPerson's bluetooth_2_hid](https://github.com/HeuristicPerson/bluetooth_2_hid) based off this.
 * [Georgi Valkov](https://github.com/gvalkov) for [python-evdev](https://github.com/gvalkov/python-evdev) making reading input devices a walk in the park. 

bluetooth_2_usb.py

@@ -29,7 +29,7 @@
 import lib.evdev_adapter as evdev_adapter
 import lib.logger
 
-_VERSION = "0.4.5"
+_VERSION = "0.4.6"
 _VERSIONED_NAME = f"Bluetooth 2 USB v{_VERSION}"
 
 _logger = lib.logger.get_logger()

install_python_3.11.sh → scripts/build_python_3.11.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Build Python 3.11 from source and install as Debian package. 
 
 # Temporarily disable history expansion
 set +H
@@ -25,6 +26,8 @@ colored_output() {
 abort_install() {
   local message="$1"
   colored_output ${RED} "Aborting installation. ${message}"
+  # Re-enable history expansion
+  set -H
   exit 1
 }