From 370b22bb02ee1a4405b07c265a92523ad496367e Mon Sep 17 00:00:00 2001
From: Erik Brakkee <erik@brakkee.org>
Date: Wed, 27 May 2026 00:10:30 +0200
Subject: [PATCH] improving the docs.

---
 README.md | 154 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 136 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 03656fe..9e53e9c 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,21 @@
 Bridge an ANT+ cycling power trainer over Bluetooth Low Energy, allowing modern devices that don't support 
 ANT+ to receive power and cadence data.
 
+## Quick Start
+
+1. **Set up the USB dongle** — Follow the [Setup instructions](#setup) to prevent the `usbserial` driver from claiming it
+2. **Build:**
+   ```bash
+   make build
+   ```
+3. **Run** (requires root):
+   ```bash
+   sudo ./bin/bridge
+   ```
+4. **Connect** — On your computer or phone, scan for BLE devices and connect to `LinuxAntBtBridge`.
+
+That's it. Your trainer's power and cadence data should now be available over BLE.
+
 ## Why this exists
 
 Modern training apps and devices (phone apps, many power meter displays) support Bluetooth LE but lack ANT+ radios. 
@@ -13,18 +28,26 @@ service over BLE.
 
 ## How it works
 
-1. Opens a USB ANT+ dongle (vendor ID `0x0fcf`) and listens for broadcast messages from a specific trainer device number.
-2. Parses power (Watts) and cadence (RPM) from the trainer's ANT+ data pages.
-3. Exposes a Cycling Power Measurement BLE service via the system's Bluetooth adapter, updating values as new ANT+ messages arrive.
+1. Opens a USB ANT+ dongle and listens for broadcast messages from a specific trainer device number.
+2. Parses power (Watts) and cadence (RPM) from the trainer's ANT+ data.
+3. Exposes a standard Cycling Power Profile BLE service via the system's Bluetooth adapter, updating values as new 
+   ANT+ messages arrive.
 
 ## Requirements
 
-- Linux
-- D-Bus (for BlueZ Bluetooth management)
-- A Bluetooth adapter
-- An ANT+ USB dongle
+### Hardware
+
+- A Bluetooth adapter (built-in or USB)
+- An ANT+ USB dongle (tested: ANT USBStick2, vendor `0x0fcf`, product `0x1008`)
 - An ANT+ cycling power trainer
 
+### Software
+
+- Linux
+- BlueZ 5.50+ (for Bluetooth management)
+- D-Bus (for BlueZ communication)
+- `hciconfig` (usually part of the `bluez-utils` or `bluez-tools` package)
+
 **Note:** This program must be run as root to access the USB dongle.
 
 ## Tested hardware
@@ -33,7 +56,21 @@ service over BLE.
 
 ## Setup
 
-The Linux `usbserial` driver must be prevented from claiming the ANT+ dongle. Create the following udev rule:
+The Linux `usbserial` driver must be prevented from claiming the ANT+ dongle. 
+
+### Find your dongle's USB IDs
+
+If you're not using the tested dongle, find your dongle's vendor and product IDs:
+
+```bash
+lsusb
+```
+
+Look for a line with "ANT" in the description. Note the vendor ID (e.g., `0fcf`) and product ID (e.g., `1008`).
+
+### Create the udev rule
+
+Create the following udev rule to prevent `usbserial` from claiming the dongle:
 
 ```bash
 sudo tee /etc/udev/rules.d/99-ant-usb.rules > /dev/null <<EOF
@@ -41,9 +78,9 @@ SUBSYSTEM=="usb", ATTRS{idVendor}=="0fcf", ATTRS{idProduct}=="1008", ENV{MODALIA
 EOF
 ```
 
-The vendor id and product id above can be obtained from the `dmesg` output after inserting the USB dongle. 
+Replace `0fcf` and `1008` with your dongle's actual vendor and product IDs if different.
 
-Then reload the rules and reconnect the dongle:
+### Reload the rules
 
 ```bash
 sudo modprobe -r usb_serial_simple
@@ -51,19 +88,23 @@ sudo udevadm control --reload-rules
 sudo udevadm trigger
 ```
 
-Verify the dongle is no longer claimed by `usbserial`:
+### Verify
+
+Reconnect the dongle and check `dmesg`:
 
 ```bash
 dmesg | tail -5
 ```
 
-Expected output:
+Expected output (no `usbserial` messages):
 ```
 usb 3-1.2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
 usb 3-1.2.1: Product: ANT USBStick2
 usb 3-1.2.1: Manufacturer: Dynastream Innovations
 ```
 
+If you see a line like `usb_serial converter now attached to ttyUSB0`, the udev rule did not apply.
+
 ## Installation
 
 ```bash
@@ -76,13 +117,13 @@ The binary is built to `bin/bridge`.
 
 ```bash
 # Use defaults (device 3001)
-./bin/bridge
+sudo ./bin/bridge
 
 # Custom trainer device
-./bin/bridge --device 0xbb9
+sudo ./bin/bridge --device 0xbb9
 
 # Custom vendor/product IDs
-./bin/bridge --vendor 0x0fcf --product 0x1008 --device 3001
+sudo ./bin/bridge --vendor 0x0fcf --product 0x1008 --device 3001
 ```
 
 ### CLI Flags
@@ -95,6 +136,42 @@ The binary is built to `bin/bridge`.
 | `--help` | | Show help |
 | `--version` | | Show version info |
 
+## Finding your trainer's ANT+ device number
+
+Most ANT+ cycling power trainers use device number `3001` (decimal) or `0xbb9` (hex). If that works, you can use the 
+bridge with default settings.
+
+If you're unsure of your trainer's device number, you can discover it using another ANT+ device (e.g., a Garmin Edge 
+head unit). Connect the Garmin to your trainer and look for the device number in the ANT+ sensor list.
+
+You can also try common device numbers for your trainer brand — most manufacturers use predictable numbers for their 
+devices.
+
+## Connecting
+
+The bridge exposes a standard [Cycling Power Profile](https://bluetooth.com/specifications/specs/cycling-power-service-1-0/) 
+service over BLE. Any app that supports this profile will work — no custom app required.
+
+Tested with:
+- Zwift
+
+May also work with other Cycling Power Profile apps:
+- TrainingPeaks
+- Wahoo SYSTM
+- TrainerRoad
+- Rouvy
+- Kinomap
+- GoldenCheetah
+
+### Steps to connect
+
+1. Run the bridge: `sudo ./bin/bridge`
+2. On your computer or phone, scan for BLE devices
+3. Connect to the device named `LinuxAntBtBridge`
+4. Start training in your app
+
+Your trainer's power and cadence data should now be available in the app.
+
 ## Output
 
 ```
@@ -103,9 +180,19 @@ The binary is built to `bin/bridge`.
 2026-05-26 11:00:34 product: 0x1008/4104
 2026-05-26 11:00:34 device: 0xbb9/3001
 2026-05-26 11:00:34 BLE advertising...
-2026-05-26 11:00:34 bt: watts: 150  rpm: 80  completedRevs: 1234  lastRevTime: 4890 processingTime: 250us
+2026-05-26 11:00:34 bt: watts: 150  rpm: 80  completedRevs: 1234  lastRevTime: 4890
 ```
 
+The bridge logs a lot of output during normal operation — this is expected and helpful for debugging during this early 
+stage of development.
+
+Key log lines:
+- `ANT Bridge ...` — Startup message with version and build time
+- `vendor: ...` / `product: ...` / `device: ...` — Configuration being used
+- `BLE advertising...` — BLE service is ready and visible to other devices
+- `bt: watts: ...` — Power and cadence data being broadcast
+- `hciconfig ... failed` — Bluetooth adapter reset warnings (usually harmless)
+
 ## Development
 
 ```bash
@@ -115,5 +202,36 @@ make clean    # Remove build artifacts
 
 ## Known issues
 
-It has been observed that during use the wattage sometimes drops briefly to 0 but then quickly recovers.
-Logging will hopefully pinpoint the issue should it occur again. 
+- **Verbose logging:** The bridge produces a lot of log output during normal operation. This is expected and helpful 
+  for debugging during this early stage of development.
+- **Wattage drops:** The wattage sometimes drops briefly to 0 but then quickly recovers. If this happens frequently, 
+  please report it with your log output.
+
+## Troubleshooting
+
+### No BLE devices found
+
+- Check that the Bluetooth adapter is enabled: `rfkill list bluetooth`
+- Check that the bridge is advertising: look for `BLE advertising...` in the log output
+- Make sure no other app is using the Bluetooth adapter
+
+### ANT+ dongle not found
+
+- Check that the dongle is plugged in: `lsusb | grep 0fcf`
+- Check that the `usbserial` driver is not claiming the dongle: `lsmod | grep usb_serial_simple`
+- Verify the udev rule was applied (see [Setup](#setup))
+- Make sure you're running with `sudo`
+
+### No data from trainer
+
+- Make sure the trainer is turned on and broadcasting
+- Make sure the dongle is close enough to the trainer (within 1-2 meters)
+- Verify the device number is correct (try `--device 3001`)
+- Check the log output for the `listening...` message
+- Try a different device number if available
+
+### BLE connection drops
+
+- Make sure the bridge is within range of the receiving device (within 5-10 meters)
+- Check for Bluetooth interference (other BLE devices, Wi-Fi, etc.)
+- Check the log output for `failed to write power characteristic` messages