Document desktop app setup

README.md

@@ -58,20 +58,75 @@ This repo includes a small Python GUI client that can scan for BullTron-style
 BLE devices, connect, poll telemetry, and display the decoded values locally on
 a PC.
 
-Install:
+### Debian
 
 ```sh
+sudo apt update
+sudo apt install python3 python3-venv python3-pip python3-tk bluez
+
 python3 -m venv .venv
 . .venv/bin/activate
 python3 -m pip install -r requirements.txt
 ```
 
-Run:
+Run the GUI:
 
 ```sh
 python3 bulltron_gui.py
 ```
 
+If scanning finds no devices, check that Bluetooth is powered and unblocked:
+
+```sh
+rfkill list bluetooth
+bluetoothctl power on
+bluetoothctl scan on
+```
+
+On some Debian installs, normal users cannot access BlueZ D-Bus discovery
+properly. If the GUI cannot scan/connect, first try logging out and back in
+after making sure your user is in the bluetooth group:
+
+```sh
+sudo usermod -aG bluetooth "$USER"
+```
+
+If that still fails, run once with elevated privileges to confirm it is a local
+permission issue rather than a protocol issue:
+
+```sh
+sudo .venv/bin/python bulltron_gui.py
+```
+
+### Windows 11
+
+Install Python 3.11 or newer from <https://www.python.org/downloads/windows/>
+or from the Microsoft Store. During the python.org install, enable `Add
+python.exe to PATH`.
+
+Open PowerShell in this repository and run:
+
+```powershell
+py -3 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python bulltron_gui.py
+```
+
+If PowerShell blocks venv activation, allow scripts for your user and retry:
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+.\.venv\Scripts\Activate.ps1
+```
+
+Windows 11 uses the native WinRT Bluetooth stack through `bleak`, so no BlueZ or
+extra Bluetooth driver package is needed. Make sure Bluetooth is enabled in
+Windows Settings and that the BullTron battery is nearby and not already held by
+the Android app. Pairing in Windows should not be required for normal telemetry;
+the original Android flow also reads telemetry without bonding.
+
 The GUI shows:
 
 - live pack voltage, current, discharge watts, SOC, remaining Ah, cell max/min,
@@ -190,7 +245,8 @@ if register 0x002F == 2:
 
 ## Caveats
 
-These findings are derived from the decompiled Android app, not from a live BLE
-capture. A capture is still useful to confirm firmware-specific behavior, current
-sign conventions, correction edge cases, and whether a specific battery requires
-link-layer encryption despite the app not initiating pairing itself.
+These findings are derived from the decompiled Android app and confirmed against
+one real Android HCI snoop capture. More captures are still useful to confirm
+firmware-specific behavior, current sign conventions, correction edge cases, and
+whether a specific battery requires link-layer encryption despite the app not
+initiating pairing itself.