public/antplusbridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improving the docs.

Browse Source
This commit is contained in:
Erik Brakkee 2026-05-27 00:10:30 +02:00
parent 497913b97c
commit 370b22bb02
1 changed files with 136 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
README.md
View File

@ -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