specialized-turbo

Python library for talking to Specialized Turbo e-bikes (Vado, Levo, Creo) over Bluetooth Low Energy. Reads speed, power, cadence, battery, motor temp, odometer, assist level, range. Can also write settings like assist level and acceleration.

Async, built on bleak. Includes a CLI. Protocol docs in docs/protocol.md.

Installation

pip install specialized-turbo

For automatic key retrieval on newer encrypted bikes:

pip install "specialized-turbo[cloud]"

Quick start

Stream telemetry

import asyncio
from specialized_turbo import SpecializedConnection, TelemetryMonitor


async def main():
    async with SpecializedConnection("DC:DD:BB:4A:D6:55") as conn:
        monitor = TelemetryMonitor(conn)
        await monitor.start()

        async for msg in monitor.stream():
            print(f"{msg.field_name} = {msg.converted_value} {msg.unit}")


asyncio.run(main())

Newer bikes advertise an HMI serial/hardware pair and require a wrapped key from Specialized's keystore API. Supply either a provider or a wrapped key:

from specialized_turbo import SpecializedConnection
from specialized_turbo.cloud import SpecializedCloudClient

async with SpecializedCloudClient() as cloud:
    await cloud.login("rider@example.com", password)
    async with SpecializedConnection(
        "DC:DD:BB:4A:D6:55",
        key_provider=cloud,
    ) as conn:
        ...

# Or avoid account authentication by supplying the 64-character wrapped key.
async with SpecializedConnection(address, wrapped_key=wrapped_key) as conn:
    ...

The password is not persisted by the library. Provider users control token storage; manual-key users can operate without cloud access after obtaining the per-bike wrapped key.

Read the snapshot

async with SpecializedConnection("DC:DD:BB:4A:D6:55") as conn:
    monitor = TelemetryMonitor(conn)
    await monitor.start()
    await asyncio.sleep(5)

    snap = monitor.snapshot
    print(f"Speed: {snap.motor.speed_kmh} km/h")
    print(f"Battery: {snap.battery.charge_pct}%")
    print(
        f"Power: {snap.motor.rider_power_w} W (rider) + {snap.motor.motor_power_w} W (motor)"
    )
    print(f"Cadence: {snap.motor.cadence_rpm} RPM")
    print(f"Assist: {snap.motor.assist_level}")

Query a single value

from specialized_turbo import SpecializedConnection, Sender, BatteryChannel

async with SpecializedConnection("DC:DD:BB:4A:D6:55") as conn:
    msg = await conn.request_value(Sender.BATTERY, BatteryChannel.CHARGE_PERCENT)
    print(f"Battery: {msg.converted_value}%")

Write commands

async with SpecializedConnection("DC:DD:BB:4A:D6:55") as conn:
    await conn.set_assist_level(2)  # TRAIL
    await conn.set_acceleration(50.0)  # 50%
    await conn.set_shuttle(25)
    await conn.set_assist_percentage(0, 35)  # ECO = 35%

CLI

Scan for bikes:

specialized-turbo scan
specialized-turbo scan --timeout 15

Retrieve the wrapped key required by a newer encrypted bike:

specialized-turbo fetch-key DC:DD:BB:4A:D6:55 \
  --email rider@example.com

The password is prompted without echo. By default, stdout contains only the 64-character wrapped key, ready for --wrapped-key or the Home Assistant manual-key flow. Use explicit HMI identifiers when the bike is not nearby:

specialized-turbo fetch-key \
  --hmi-hardware 3.2.1 \
  --hmi-serial 123456789 \
  --email rider@example.com \
  --json

fetch-key requires specialized-turbo[cloud]. It does not print the final unwrapped AES key.

Stream telemetry:

specialized-turbo telemetry DC:DD:BB:4A:D6:55 --email rider@example.com
specialized-turbo telemetry DC:DD:BB:4A:D6:55 --wrapped-key "$WRAPPED_KEY"
specialized-turbo telemetry DC:DD:BB:4A:D6:55 --format json
specialized-turbo telemetry DC:DD:BB:4A:D6:55 --duration 30

Read a single value:

specialized-turbo read list                                             # show available fields
specialized-turbo read battery_charge_percent DC:DD:BB:4A:D6:55
specialized-turbo read speed DC:DD:BB:4A:D6:55 --format json

Write a value:

specialized-turbo write list                                            # show writable fields
specialized-turbo write assist_level 2 DC:DD:BB:4A:D6:55  # set to TRAIL
specialized-turbo write acceleration 50 DC:DD:BB:4A:D6:55 # 50% sensitivity

Dump GATT services (debugging):

specialized-turbo services DC:DD:BB:4A:D6:55

Capture complete TCX writes and notifications for protocol debugging:

specialized-turbo capture DC:DD:BB:4A:D6:55 --duration 60 > tcx-capture.tsv

Available fields

TCX2+ bikes have additional fields (range, altitude, gradient, calories, system temperature, and more). See docs/protocol.md for the full list.

Protocol support

Five protocol variants exist:

TCX1 shares the TURBOHMI UUID family with TCX2/3/4 but uses legacy write-then-read queries. The connected service structure distinguishes it from TCX2+. The BLEProfile enum (TCU1 / TCX) controls which GATT UUID family to use.

For encrypted bikes, only packet bytes 2–17 are encrypted. The parameter ID and CRC remain clear. The wrapped per-bike key comes from Specialized's cloud, while SYSTEM_GET_NEW_VI supplies a fresh session IV at connection time.

See docs/protocol.md for the full spec.

Pairing

The connection requests authenticated pairing for bikes using the TURBOHMI UUID family. Passkey entry and numeric comparison are handled by the active Bluetooth backend or its pairing agent; Bleak cannot accept a passkey value directly.

If the backend cannot present or confirm the pairing prompt, pair through the operating system first and reconnect. The deprecated --pin and pin= arguments are accepted for compatibility but their values are ignored.

Development

uv sync --extra dev
uv run pytest

License

MIT