From b33f1cc674efa89982b686a3a35eb2dae873d27d Mon Sep 17 00:00:00 2001 From: "Bahador.I" Date: Sun, 10 Nov 2024 13:33:04 -0500 Subject: [PATCH] chore: script and readme improvements - Add Caution and Uninstall sections to readme - Add uninstall scripts --- README.md | 43 +++++++++++++++++++++--- scripts/setup_service.sh | 30 ----------------- scripts/uninstall/undo_setup_gadgets.sh | 39 +++++++++++++++++++++ scripts/uninstall/undo_setup_usb_host.sh | 7 ++++ 4 files changed, 85 insertions(+), 34 deletions(-) delete mode 100755 scripts/setup_service.sh create mode 100644 scripts/uninstall/undo_setup_gadgets.sh create mode 100644 scripts/uninstall/undo_setup_usb_host.sh diff --git a/README.md b/README.md index 0f7fd92..dab4cf9 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,26 @@ Before building and running the project, ensure you have the following installed ``` > Note: You may need to add $(go env GOPATH)/bin to your PATH environment variable with the second command. + +## ⚠️ Caution + +**Please read before proceeding:** + +This project is currently in an experimental state and has only been tested on a limited number of devices. While it works well for my use case, please be aware that: + +- The scripts modify system-level configurations and USB settings +- Incorrect USB gadget configuration could potentially require a fresh OS installation to recover +- The project has only been tested on a small number of devices and configurations +- This is a personal project, not production-ready software + +**Before running this project, you should:** +- Only use it on devices where you can easily reinstall the OS if needed +- Carefully review all scripts and code before execution +- Have a backup plan in case something goes wrong +- Be comfortable with Linux system administration and USB configurations + +I cannot guarantee this will work on all devices or configurations. Proceed at your own risk. + ## Setup 1. Log in to your Raspberry Pi Zero. @@ -68,10 +88,10 @@ Before building and running the project, ensure you have the following installed 3. Run the setup scripts in the following order: ```bash - sudo ./scripts/setup_usb_host.sh + sudo ./scripts/setup_usb_host.sh # enable the USB host and load the necessary modules sudo reboot - sudo ./scripts/setup_bluetooth.sh - sudo ./scripts/setup_gadgets.sh + sudo ./scripts/setup_bluetooth.sh # enable and start the bluetooth service + sudo ./scripts/setup_gadgets.sh # create the gadget and configure the USB strings ``` 5. Pair your Bluetooth devices manually or using the script: @@ -113,7 +133,7 @@ This project uses Task runner for common operations: ## Diagnostic Tools -### IO Diagnostic +### I/O Doctor This tool will check for connected Bluetooth devices and display all incoming events from your Bluetooth keyboard and mouse, helping you debug connection and input issues. @@ -133,6 +153,21 @@ This interactive tool allows you to: 2. Type a test message These simulations help verify that the USB HID device is working correctly on the host computer. +### Uninstall and remove gadget + +To uninstall the service: +```bash +task service:uninstall +``` + +To remove the gadget and restore the USB host configuration: +```bash +./scripts/uninstall/undo_setup_gadgets.sh +./scripts/uninstall/undo_setup_usb_host.sh +``` + + + ## Development This project can be used as is or as basis for other types of USB gadgets. It can also serve as a learning opportunity for: diff --git a/scripts/setup_service.sh b/scripts/setup_service.sh deleted file mode 100755 index 33b20dd..0000000 --- a/scripts/setup_service.sh +++ /dev/null @@ -1,30 +0,0 @@ -#!/bin/bash - -# Create a systemd service file -cat << EOF > /etc/systemd/system/bt-hid-relay.service -[Unit] -Description=Bluetooth HID Relay Service -After=network.target bluetooth.target - -[Service] -ExecStart=/usr/local/bin/bt-hid-relay -Restart=always -User=root - -[Install] -WantedBy=multi-user.target -EOF - -# Assuming the compiled Go binary is named 'bt-hid-relay' -# and is located in the project directory -cp bt-hid-relay /usr/local/bin/ - -# Set correct permissions -chmod 755 /usr/local/bin/bt-hid-relay - -# Reload systemd, enable and start the service -systemctl daemon-reload -systemctl enable bt-hid-relay.service -systemctl start bt-hid-relay.service - -echo "Bluetooth HID Relay service has been set up and started" \ No newline at end of file diff --git a/scripts/uninstall/undo_setup_gadgets.sh b/scripts/uninstall/undo_setup_gadgets.sh new file mode 100644 index 0000000..8c6cff3 --- /dev/null +++ b/scripts/uninstall/undo_setup_gadgets.sh @@ -0,0 +1,39 @@ +#!/bin/bash + + + # Clean up gadget directory if it exists + + cleanup_gadget() { + echo "Cleaning up existing USB configurations..." + + # Only unload modules if they exist + if [ $MODULES_LOADED -eq 1 ]; then + echo "Unloading existing USB modules..." + modprobe -r g_ether usb_f_rndis usb_f_ecm u_ether || true + fi + + # Clean up gadget directory if it exists + if [ $GADGET_EXISTS -eq 1 ]; then + echo "Removing existing HID gadget configuration..." + cd /sys/kernel/config/usb_gadget/hid_gadget + if [ -f UDC ]; then + echo "" > UDC + fi + + # Remove symbolic links + rm -f configs/c.1/hid.usb0 + rm -f configs/c.1/hid.usb1 + + # Remove directories + rm -rf functions/hid.usb0 + rm -rf functions/hid.usb1 + rm -rf configs/c.1/strings/0x409 + rm -rf configs/c.1 + rm -rf strings/0x409 + + cd .. + rmdir hid_gadget 2>/dev/null || true + fi +} + +cleanup_gadget \ No newline at end of file diff --git a/scripts/uninstall/undo_setup_usb_host.sh b/scripts/uninstall/undo_setup_usb_host.sh new file mode 100644 index 0000000..4f6e275 --- /dev/null +++ b/scripts/uninstall/undo_setup_usb_host.sh @@ -0,0 +1,7 @@ +#!/bin/bash + +# Restore config.txt +sudo cp /boot/config.txt.bak /boot/config.txt + +# Remove dwc2 driver +sudo sed -i '/dtoverlay=dwc2/d' /boot/config.txt \ No newline at end of file