tenways-ble 0.2.0__py3-none-any.whl

tenways_ble/__init__.py

@@ -0,0 +1,26 @@
+from .client import (
+    TenwaysBatteryError,
+    TenwaysBike,
+    TenwaysError,
+    TenwaysTimeoutError,
+    TenwaysUnsupportedError,
+    scan_tenways,
+)
+from .models import TenwaysAdvertisement, TenwaysInfo
+from .protocol import TenwaysDeviceInfo, TenwaysProtocolError, TenwaysStatus
+
+__all__ = [
+    "TenwaysAdvertisement",
+    "TenwaysBatteryError",
+    "TenwaysBike",
+    "TenwaysDeviceInfo",
+    "TenwaysError",
+    "TenwaysInfo",
+    "TenwaysProtocolError",
+    "TenwaysStatus",
+    "TenwaysTimeoutError",
+    "TenwaysUnsupportedError",
+    "scan_tenways",
+]
+
+__version__ = "0.2.0"

tenways_ble/cli.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+from datetime import datetime
+
+from .client import TenwaysBike, scan_tenways
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="tenways", description="TENWAYS BLE diagnostics")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    scan = sub.add_parser("scan", help="Scan for nearby TENWAYS BLE devices")
+    scan.add_argument("--timeout", type=float, default=5.0)
+
+    battery = sub.add_parser("battery", help="Read standard BLE battery level")
+    battery.add_argument("address")
+
+    info = sub.add_parser("info", help="Show device name, battery and services")
+    info.add_argument("address")
+
+    status = sub.add_parser("status", help="Read live telemetry (King Meter command 0x0B)")
+    status.add_argument("address")
+
+    device_info = sub.add_parser("device-info", help="Read firmware and serial number")
+    device_info.add_argument("address")
+
+    listen = sub.add_parser("listen", help="Subscribe to raw TENWAYS notifications")
+    listen.add_argument("address")
+
+    return parser
+
+
+async def _scan(timeout: float) -> int:
+    devices = await scan_tenways(timeout)
+    if not devices:
+        print("No TENWAYS BLE devices found.")
+        return 1
+    for device in devices:
+        rssi = f"{device.rssi} dBm" if device.rssi is not None else "RSSI n/a"
+        print(f"{device.address:<20} {device.name or '<unnamed>':<28} {rssi}")
+    return 0
+
+
+async def _battery(address: str) -> int:
+    async with TenwaysBike(address) as bike:
+        value = await bike.battery_level()
+    print(f"Battery: {value} %")
+    return 0
+
+
+async def _info(address: str) -> int:
+    async with TenwaysBike(address) as bike:
+        info = await bike.info()
+    print(f"Address: {info.address}")
+    print(f"Name: {info.name or '<unknown>'}")
+    print(f"Battery: {info.battery_level if info.battery_level is not None else '<unavailable>'}%")
+    print("Services:")
+    for uuid in info.services:
+        print(f"  {uuid}")
+    return 0
+
+
+async def _status(address: str) -> int:
+    async with TenwaysBike(address) as bike:
+        status = await bike.read_status()
+    print(f"Traction battery: {status.battery_percent} %")
+    print(f"Odometer: {status.odometer_km:.1f} km")
+    print(f"Trip: {status.trip_km:.1f} km")
+    print(f"Max speed: {status.max_speed_kmh:.1f} km/h")
+    print(f"Average speed: {status.average_speed_kmh:.1f} km/h")
+    print(f"Ride time: {status.ride_time_s} s")
+    print(f"Speed (unconfirmed): {status.speed_kmh}")
+    print(f"Unknown 0x0B/0x11/0x23/0x4F: {status.raw_0b} {status.raw_11} {status.raw_23} {status.raw_4f}")
+    return 0
+
+
+async def _device_info(address: str) -> int:
+    async with TenwaysBike(address) as bike:
+        info = await bike.read_device_info()
+    print(f"Firmware: {info.firmware or '<unknown>'}")
+    print(f"Serial: {info.serial or '<unknown>'}")
+    return 0
+
+
+async def _listen(address: str) -> int:
+    stop = asyncio.Event()
+
+    def on_packet(data: bytes) -> None:
+        now = datetime.now().astimezone().isoformat(timespec="milliseconds")
+        print(f"RX {now}  {data.hex(' ')}", flush=True)
+
+    async with TenwaysBike(address) as bike:
+        try:
+            battery = await bike.battery_level()
+            print(f"Battery: {battery} %")
+        except Exception as exc:
+            print(f"Battery read failed: {exc}")
+
+        await bike.start_raw_notifications(on_packet)
+        print("Subscribed to proprietary TENWAYS notifications.")
+        print("Waiting for packets; press Ctrl+C to stop.")
+
+        try:
+            await stop.wait()
+        except asyncio.CancelledError:
+            raise
+        finally:
+            try:
+                await bike.stop_raw_notifications()
+            except Exception:
+                pass
+    return 0
+
+
+async def _amain(args: argparse.Namespace) -> int:
+    if args.command == "scan":
+        return await _scan(args.timeout)
+    if args.command == "battery":
+        return await _battery(args.address)
+    if args.command == "info":
+        return await _info(args.address)
+    if args.command == "status":
+        return await _status(args.address)
+    if args.command == "device-info":
+        return await _device_info(args.address)
+    if args.command == "listen":
+        return await _listen(args.address)
+    raise RuntimeError("Unhandled command")
+
+
+def main() -> None:
+    parser = _parser()
+    args = parser.parse_args()
+    try:
+        code = asyncio.run(_amain(args))
+    except KeyboardInterrupt:
+        code = 130
+    raise SystemExit(code)
+
+
+if __name__ == "__main__":
+    main()

tenways_ble/client.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+import logging
+from typing import Any
+
+from bleak import BleakClient, BleakScanner
+from bleak.backends.device import BLEDevice
+from bleak.backends.scanner import AdvertisementData
+
+from .const import (
+    BATTERY_LEVEL_UUID,
+    TENWAYS_NAME_PREFIXES,
+    TENWAYS_NOTIFY_UUID,
+    TENWAYS_SERVICE_UUID,
+    TENWAYS_WRITE_UUID,
+)
+from .models import TenwaysAdvertisement, TenwaysInfo
+from .protocol import (
+    CMD_INFO,
+    CMD_STATUS,
+    INFO_REQUEST,
+    STATUS_REQUEST,
+    TYPE_READ,
+    FrameAssembler,
+    TenwaysDeviceInfo,
+    TenwaysProtocolError,
+    TenwaysStatus,
+    decode_device_info,
+    decode_status,
+    parse_frame,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+NotificationCallback = Callable[[bytes], None | Awaitable[None]]
+
+
+class TenwaysError(RuntimeError):
+    """Base exception for tenways-ble."""
+
+
+class TenwaysBatteryError(TenwaysError):
+    """Raised when the standard battery value cannot be decoded."""
+
+
+class TenwaysTimeoutError(TenwaysError, TimeoutError):
+    """Raised when the bike does not answer a request in time."""
+
+
+class TenwaysUnsupportedError(TenwaysError):
+    """Raised when the device lacks the King Meter service."""
+
+
+def _looks_like_tenways(device: BLEDevice, adv: AdvertisementData | None) -> bool:
+    names = [device.name]
+    if adv is not None:
+        names.append(adv.local_name)
+        if TENWAYS_SERVICE_UUID in (adv.service_uuids or []):
+            return True
+    return any(
+        name and name.lower().startswith(TENWAYS_NAME_PREFIXES) for name in names
+    )
+
+
+async def scan_tenways(timeout: float = 5.0) -> list[TenwaysAdvertisement]:
+    """Scan for nearby devices whose advertisement looks like TENWAYS."""
+
+    found = await BleakScanner.discover(timeout=timeout, return_adv=True)
+    result: list[TenwaysAdvertisement] = []
+
+    for _key, value in found.items():
+        device, adv = value
+        if not _looks_like_tenways(device, adv):
+            continue
+        result.append(
+            TenwaysAdvertisement(
+                address=device.address,
+                name=adv.local_name or device.name,
+                rssi=adv.rssi,
+            )
+        )
+
+    return sorted(result, key=lambda item: item.rssi if item.rssi is not None else -999, reverse=True)
+
+
+class TenwaysBike:
+    """BLE client for a TENWAYS bicycle.
+
+    Pass an address or ``BLEDevice`` to let this class manage the connection,
+    or an already connected ``BleakClient`` (e.g. from bleak-retry-connector)
+    to only speak the protocol over it; the caller then owns the connection.
+
+    Only read requests are sent. Write commands are not implemented.
+    """
+
+    def __init__(
+        self,
+        address_or_device: str | BLEDevice | BleakClient,
+        *,
+        timeout: float = 15.0,
+        response_timeout: float = 5.0,
+    ) -> None:
+        self.timeout = timeout
+        self.response_timeout = response_timeout
+        self._owns_client = not isinstance(address_or_device, BleakClient)
+        self.address_or_device = address_or_device
+        self._client: BleakClient | None = None if self._owns_client else address_or_device
+        self._lock = asyncio.Lock()
+        self._assembler = FrameAssembler()
+        self._pending: tuple[int, asyncio.Future[bytes]] | None = None
+        self._protocol_notify = False
+        self._raw_callback: NotificationCallback | None = None
+
+    @property
+    def client(self) -> BleakClient:
+        if self._client is None or not self._client.is_connected:
+            raise TenwaysError("Bike is not connected")
+        return self._client
+
+    async def connect(self) -> None:
+        if not self._owns_client:
+            return
+        if self._client is not None and self._client.is_connected:
+            return
+        self._client = BleakClient(
+            self.address_or_device,
+            timeout=self.timeout,
+            disconnected_callback=self._on_disconnect,
+        )
+        await self._client.connect()
+
+    async def disconnect(self) -> None:
+        self._protocol_notify = False
+        self._raw_callback = None
+        if not self._owns_client or self._client is None:
+            return
+        try:
+            if self._client.is_connected:
+                await self._client.disconnect()
+        finally:
+            self._client = None
+
+    async def __aenter__(self) -> "TenwaysBike":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self.disconnect()
+
+    def _on_disconnect(self, _client: BleakClient) -> None:
+        self._protocol_notify = False
+        if self._pending is not None and not self._pending[1].done():
+            self._pending[1].set_exception(TenwaysError("Bike disconnected"))
+
+    async def battery_level(self) -> int:
+        """Read the Bluetooth standard Battery Level characteristic.
+
+        This is not the traction battery; see :meth:`read_status`.
+        """
+
+        raw = bytes(await self.client.read_gatt_char(BATTERY_LEVEL_UUID))
+        if len(raw) != 1:
+            raise TenwaysBatteryError(f"Unexpected battery payload: {raw.hex(' ')}")
+        value = raw[0]
+        if not 0 <= value <= 100:
+            raise TenwaysBatteryError(f"Invalid battery value: {value}")
+        return value
+
+    async def info(self) -> TenwaysInfo:
+        name: str | None = None
+        try:
+            name = self.client.name
+        except Exception:
+            pass
+
+        try:
+            battery = await self.battery_level()
+        except Exception:
+            battery = None
+
+        services = tuple(str(service.uuid).lower() for service in self.client.services)
+        address = getattr(self.client, "address", str(self.address_or_device))
+        return TenwaysInfo(
+            address=address,
+            name=name,
+            battery_level=battery,
+            services=services,
+        )
+
+    def supports_protocol(self) -> bool:
+        services = self.client.services
+        return (
+            services.get_characteristic(TENWAYS_WRITE_UUID) is not None
+            and services.get_characteristic(TENWAYS_NOTIFY_UUID) is not None
+        )
+
+    async def read_status(self) -> TenwaysStatus:
+        """Request and decode live telemetry (command 0x0B)."""
+
+        return decode_status(await self._request(STATUS_REQUEST, CMD_STATUS))
+
+    async def read_device_info(self) -> TenwaysDeviceInfo:
+        """Request firmware and serial number (command 0x04)."""
+
+        return decode_device_info(await self._request(INFO_REQUEST, CMD_INFO))
+
+    async def _request(self, request: bytes, cmd: int) -> bytes:
+        async with self._lock:
+            client = self.client
+            if not self.supports_protocol():
+                raise TenwaysUnsupportedError("King Meter service not found")
+            if not self._protocol_notify:
+                self._assembler.reset()
+                await client.start_notify(TENWAYS_NOTIFY_UUID, self._on_notify)
+                self._protocol_notify = True
+            future: asyncio.Future[bytes] = asyncio.get_running_loop().create_future()
+            self._pending = (cmd, future)
+            try:
+                await client.write_gatt_char(TENWAYS_WRITE_UUID, request, response=False)
+                async with asyncio.timeout(self.response_timeout):
+                    return await future
+            except TimeoutError as exc:
+                raise TenwaysTimeoutError(f"No reply to command {cmd:#04x}") from exc
+            finally:
+                self._pending = None
+
+    def _on_notify(self, _sender: Any, data: bytearray) -> None:
+        payload = bytes(data)
+        if self._raw_callback is not None:
+            result = self._raw_callback(payload)
+            if asyncio.iscoroutine(result):
+                asyncio.create_task(result)
+        for raw in self._assembler.feed(payload):
+            try:
+                frame = parse_frame(raw)
+            except TenwaysProtocolError as exc:
+                _LOGGER.debug("Dropping invalid frame %s: %s", raw.hex(" "), exc)
+                continue
+            pending = self._pending
+            if (pending is not None and not pending[1].done()
+                    and frame.type == TYPE_READ and frame.cmd == pending[0]):
+                pending[1].set_result(raw)
+            else:
+                _LOGGER.debug("Unsolicited frame %s", raw.hex(" "))
+
+    async def start_raw_notifications(self, callback: NotificationCallback) -> None:
+        """Subscribe to the proprietary TENWAYS notification characteristic."""
+
+        self._raw_callback = callback
+        if not self._protocol_notify:
+            self._assembler.reset()
+            await self.client.start_notify(TENWAYS_NOTIFY_UUID, self._on_notify)
+            self._protocol_notify = True
+
+    async def stop_raw_notifications(self) -> None:
+        self._raw_callback = None
+        self._protocol_notify = False
+        await self.client.stop_notify(TENWAYS_NOTIFY_UUID)

tenways_ble/const.py

@@ -0,0 +1,13 @@
+"""UUID constants observed on TENWAYS BLE devices."""
+
+BATTERY_SERVICE_UUID = "0000180f-0000-1000-8000-00805f9b34fb"
+BATTERY_LEVEL_UUID = "00002a19-0000-1000-8000-00805f9b34fb"
+
+# "KING METER" in ASCII; the proprietary King Meter transport.
+TENWAYS_SERVICE_UUID = "43480001-f001-4b49-4e47-204d45544552"
+TENWAYS_WRITE_UUID = "43480002-f001-4b49-4e47-204d45544552"
+TENWAYS_NOTIFY_UUID = "43480003-f001-4b49-4e47-204d45544552"
+TENWAYS_READ_UUID = "43480004-f001-4b49-4e47-204d45544552"
+
+TENWAYS_NAME_PREFIX = "tenways-ble-"
+TENWAYS_NAME_PREFIXES = (TENWAYS_NAME_PREFIX, "longtail duo")

tenways_ble/models.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class TenwaysAdvertisement:
+    address: str
+    name: str | None
+    rssi: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class TenwaysInfo:
+    address: str
+    name: str | None
+    battery_level: int | None
+    services: tuple[str, ...]

tenways_ble/protocol.py

@@ -0,0 +1,240 @@
+"""King Meter frame protocol used by the TENWAYS Longtail Duo.
+
+Sans-I/O: this module only builds and parses bytes. Everything here was
+derived from an Android HCI capture of the official TENWAYS app.
+
+Frame layout (both directions)::
+
+    [type][0x00][len][cmd][payload ...][crc_hi][crc_lo][0x45]
+
+``type`` is 0x62 (read) or 0x63 (write), ``len`` counts cmd + payload, and
+``crc`` is CRC-16/MODBUS over type..payload, transmitted high byte first.
+A read request lists field keys; the reply carries TLV entries
+``[key][size][value]`` with big-endian values.
+
+Only read requests are built. Write commands (0x63) are parsed but never
+generated.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+TYPE_READ = 0x62
+TYPE_WRITE = 0x63
+FRAME_TYPES = (TYPE_READ, TYPE_WRITE)
+HEADER_BYTE = 0x00
+END_BYTE = 0x45
+OVERHEAD = 6  # type, 0x00, len, crc_hi, crc_lo, end
+MAX_FRAME = 0xFF + OVERHEAD
+
+CMD_INFO = 0x04
+CMD_STATUS = 0x0B
+
+INFO_KEYS = (0x04, 0x05, 0x4F, 0x70)
+STATUS_KEYS = (0x06, 0x07, 0x08, 0x09, 0x11, 0x0A, 0x0B, 0x0C, 0x0F, 0x23, 0x4F)
+
+# Fields confirmed against the TENWAYS app; a reply without them is rejected.
+STATUS_REQUIRED = {0x07: 2, 0x08: 2, 0x09: 4, 0x0A: 4, 0x0C: 4, 0x0F: 1}
+# Plausible or unknown fields; absent or malformed values become None.
+STATUS_OPTIONAL = {0x06: 2, 0x0B: 2, 0x11: 1, 0x23: 2, 0x4F: 1}
+
+
+class TenwaysProtocolError(ValueError):
+    """Raised for frames that fail validation."""
+
+
+def crc16_modbus(data: bytes) -> int:
+    crc = 0xFFFF
+    for value in data:
+        crc ^= value
+        for _ in range(8):
+            crc = (crc >> 1) ^ 0xA001 if crc & 1 else crc >> 1
+    return crc
+
+
+def build_frame(frame_type: int, cmd: int, payload: bytes = b"") -> bytes:
+    if frame_type not in FRAME_TYPES:
+        raise ValueError(f"invalid frame type {frame_type:#04x}")
+    if len(payload) + 1 > 0xFF:
+        raise ValueError("payload too long")
+    body = bytes((frame_type, HEADER_BYTE, len(payload) + 1, cmd)) + payload
+    return body + crc16_modbus(body).to_bytes(2, "big") + bytes((END_BYTE,))
+
+
+def build_read_request(cmd: int, keys: tuple[int, ...]) -> bytes:
+    return build_frame(TYPE_READ, cmd, bytes(keys))
+
+
+STATUS_REQUEST = build_read_request(CMD_STATUS, STATUS_KEYS)
+INFO_REQUEST = build_read_request(CMD_INFO, INFO_KEYS)
+
+
+@dataclass(frozen=True, slots=True)
+class Frame:
+    type: int
+    cmd: int
+    payload: bytes
+
+
+def parse_frame(raw: bytes) -> Frame:
+    """Validate one complete frame: header, length, CRC and end byte."""
+    if len(raw) < OVERHEAD + 1:
+        raise TenwaysProtocolError("frame too short")
+    if raw[0] not in FRAME_TYPES:
+        raise TenwaysProtocolError(f"invalid frame type {raw[0]:#04x}")
+    if raw[1] != HEADER_BYTE:
+        raise TenwaysProtocolError(f"invalid header byte {raw[1]:#04x}")
+    if raw[2] == 0 or len(raw) != raw[2] + OVERHEAD:
+        raise TenwaysProtocolError("frame length mismatch")
+    if raw[-1] != END_BYTE:
+        raise TenwaysProtocolError("missing end byte")
+    if crc16_modbus(raw[:-3]) != int.from_bytes(raw[-3:-1], "big"):
+        raise TenwaysProtocolError("CRC mismatch")
+    return Frame(raw[0], raw[3], bytes(raw[4:-3]))
+
+
+def parse_tlv(payload: bytes) -> dict[int, bytes]:
+    fields: dict[int, bytes] = {}
+    pos = 0
+    while pos < len(payload):
+        if pos + 2 > len(payload):
+            raise TenwaysProtocolError("truncated TLV header")
+        key, size = payload[pos], payload[pos + 1]
+        value = payload[pos + 2:pos + 2 + size]
+        if len(value) != size:
+            raise TenwaysProtocolError(f"truncated TLV field {key:#04x}")
+        if key in fields:
+            raise TenwaysProtocolError(f"duplicate TLV field {key:#04x}")
+        fields[key] = value
+        pos += 2 + size
+    return fields
+
+
+class FrameAssembler:
+    """Split a notification byte stream into candidate frames.
+
+    Handles frames spread over several notifications, several frames in one
+    notification and garbage between frames. Returned frames are delimited
+    by their length byte only; validate them with :func:`parse_frame`.
+    """
+
+    def __init__(self, max_buffer: int = 4 * MAX_FRAME) -> None:
+        self._buf = bytearray()
+        self._max_buffer = max_buffer
+
+    def reset(self) -> None:
+        self._buf.clear()
+
+    def feed(self, chunk: bytes) -> list[bytes]:
+        self._buf += chunk
+        frames: list[bytes] = []
+        while True:
+            self._resync()
+            if len(self._buf) < 3:
+                break
+            total = self._buf[2] + OVERHEAD
+            if len(self._buf) < total:
+                break
+            candidate = bytes(self._buf[:total])
+            if candidate[-1] != END_BYTE:
+                # Wrong length byte: drop this start byte and search again.
+                del self._buf[0]
+                continue
+            frames.append(candidate)
+            del self._buf[:total]
+        if len(self._buf) > self._max_buffer:
+            self._buf.clear()
+        return frames
+
+    def _resync(self) -> None:
+        start = 0
+        while start < len(self._buf):
+            if self._buf[start] in FRAME_TYPES and (
+                start + 1 >= len(self._buf) or self._buf[start + 1] == HEADER_BYTE
+            ):
+                break
+            start += 1
+        if start:
+            del self._buf[:start]
+
+
+@dataclass(frozen=True, slots=True)
+class TenwaysStatus:
+    """Telemetry from a status reply (command 0x0B)."""
+
+    battery_percent: int
+    max_speed_kmh: float
+    average_speed_kmh: float
+    odometer_km: float
+    ride_time_s: int
+    trip_km: float
+    # Plausible but not yet confirmed while riding.
+    speed_kmh: float | None = None
+    # Meaning unknown; exposed raw for further analysis.
+    raw_0b: int | None = None
+    raw_11: int | None = None
+    raw_23: int | None = None
+    raw_4f: int | None = None
+    fields: Mapping[int, bytes] = field(default_factory=dict, repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class TenwaysDeviceInfo:
+    """Device information reply (command 0x04)."""
+
+    firmware: str | None
+    serial: str | None
+    fields: Mapping[int, bytes] = field(default_factory=dict, repr=False)
+
+
+def _reply_fields(raw: bytes, cmd: int) -> dict[int, bytes]:
+    frame = parse_frame(raw)
+    if frame.type != TYPE_READ:
+        raise TenwaysProtocolError(f"unexpected frame type {frame.type:#04x}")
+    if frame.cmd != cmd:
+        raise TenwaysProtocolError(f"unexpected command {frame.cmd:#04x}")
+    return parse_tlv(frame.payload)
+
+
+def _number(fields: Mapping[int, bytes], key: int, size: int) -> int | None:
+    value = fields.get(key)
+    if value is None or len(value) != size:
+        return None
+    return int.from_bytes(value, "big")
+
+
+def decode_status(raw: bytes) -> TenwaysStatus:
+    fields = _reply_fields(raw, CMD_STATUS)
+    for key, size in STATUS_REQUIRED.items():
+        if len(fields.get(key, b"")) != size:
+            raise TenwaysProtocolError(f"missing or malformed status field {key:#04x}")
+    req = {key: int.from_bytes(fields[key], "big") for key in STATUS_REQUIRED}
+    if req[0x0F] > 100:
+        raise TenwaysProtocolError(f"battery out of range: {req[0x0F]}")
+    opt = {key: _number(fields, key, size) for key, size in STATUS_OPTIONAL.items()}
+    return TenwaysStatus(
+        battery_percent=req[0x0F],
+        max_speed_kmh=req[0x07] / 10,
+        average_speed_kmh=req[0x08] / 10,
+        odometer_km=req[0x09] / 10,
+        ride_time_s=req[0x0A],
+        trip_km=req[0x0C] / 10,
+        speed_kmh=opt[0x06] / 10 if opt[0x06] is not None else None,
+        raw_0b=opt[0x0B],
+        raw_11=opt[0x11],
+        raw_23=opt[0x23],
+        raw_4f=opt[0x4F],
+        fields=fields,
+    )
+
+
+def decode_device_info(raw: bytes) -> TenwaysDeviceInfo:
+    fields = _reply_fields(raw, CMD_INFO)
+    version = fields.get(0x04)
+    serial = fields.get(0x70, b"").rstrip(b"\0").decode("ascii", "replace")
+    return TenwaysDeviceInfo(
+        firmware=".".join(str(b) for b in version) if version and len(version) == 3 else None,
+        serial=serial or None,
+        fields=fields,
+    )

tenways_ble-0.2.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: tenways-ble
+Version: 0.2.0
+Summary: Read-only BLE client, King Meter protocol and diagnostic CLI for TENWAYS e-bikes
+Project-URL: Homepage, https://github.com/Styx85/tenways-ble
+Project-URL: Issues, https://github.com/Styx85/tenways-ble/issues
+Author: Christoph Berliner
+License: MIT
+License-File: LICENSE
+Keywords: ble,bluetooth,ebike,home-assistant,king-meter,tenways
+Requires-Python: >=3.11
+Requires-Dist: bleak>=0.22
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tenways-ble
+
+Small experimental Python library and CLI for local BLE access to TENWAYS e-bikes.
+
+Read-only by design:
+
+- discovers nearby TENWAYS BLE devices;
+- decodes the proprietary **King Meter** frame protocol (CRC-16/MODBUS, TLV fields) used by the TENWAYS Longtail Duo;
+- reads live telemetry: traction battery, odometer, trip, max/average speed, ride time;
+- reads firmware and serial number;
+- reads the standard Bluetooth Battery Level characteristic (`0x2A19`), which is **not** the traction battery;
+- does **not** send any write, lock, light or configuration commands.
+
+The protocol was reconstructed from an Android HCI capture of the official TENWAYS app; all test vectors are the original captured frames. Live operation against the bike is still being validated.
+
+## Library usage
+
+```python
+import asyncio
+from tenways_ble import TenwaysBike
+
+async def main():
+    async with TenwaysBike("E8:88:6C:31:B3:0D") as bike:
+        status = await bike.read_status()
+        print(status.battery_percent, status.odometer_km)
+
+asyncio.run(main())
+```
+
+`TenwaysBike` also accepts an already connected `BleakClient` (for example from `bleak-retry-connector` in Home Assistant). It then only speaks the protocol and leaves the connection to the caller.
+
+The sans-I/O protocol module `tenways_ble.protocol` builds and parses frames without any Bluetooth dependency.
+
+## Devices
+
+| Device | Advertised name | Notes |
+|---|---|---|
+| Longtail Duo drive | `Longtail Duo` | King Meter service, telemetry source. Standard battery reads ~1 %, not the traction battery. |
+| Separate BLE device | `Tenways-ble-XXXXXX` | HID service, standard battery 100 %, also exposes the King Meter service. Function unconfirmed (remote/control unit?). |
+
+## Known GATT layout
+
+Standard battery service:
+
+- Service: `0000180f-0000-1000-8000-00805f9b34fb`
+- Battery Level: `00002a19-0000-1000-8000-00805f9b34fb` (`READ`, `NOTIFY`)
+
+King Meter service (`43480001-…` contains `KING METER` in ASCII):
+
+- Service: `43480001-f001-4b49-4e47-204d45544552`
+- Write: `43480002-f001-4b49-4e47-204d45544552` (`WRITE WITHOUT RESPONSE`)
+- Notify: `43480003-f001-4b49-4e47-204d45544552` (`NOTIFY`)
+- Read: `43480004-f001-4b49-4e47-204d45544552` (`READ`, no useful content observed)
+
+## King Meter protocol
+
+```
+[TYPE] [00] [LEN] [CMD] [PAYLOAD…] [CRC_HI] [CRC_LO] [45]
+```
+
+| Element | Meaning |
+|---|---|
+| TYPE | `0x62` read, `0x63` write |
+| `00` | constant header byte |
+| LEN | length of CMD + PAYLOAD; frame length is LEN + 6 |
+| CRC | CRC-16/MODBUS (`0xA001` reflected, init `0xFFFF`) over TYPE…PAYLOAD, **high byte first** |
+| `45` | end marker |
+
+A read request lists field keys; the reply returns `[key][size][value]` entries, big endian. Replies (54 bytes for status) exceed the default 20-byte notification payload and are reassembled.
+
+Status request (`CMD 0x0B`), as sent by the app: `62 00 0c 0b 06 07 08 09 11 0a 0b 0c 0f 23 4f 84 91 45`
+
+| Key | Size | Meaning | Status |
+|---|---|---|---|
+| `0x06` | 2 | current speed, 0.1 km/h | plausible, 0 while parked |
+| `0x07` | 2 | max speed, 0.1 km/h | matches app |
+| `0x08` | 2 | average speed, 0.1 km/h | matches app |
+| `0x09` | 4 | odometer, 0.1 km | matches app |
+| `0x0A` | 4 | ride time, s | matches app |
+| `0x0B` | 2 | unknown (655 at 68 %; range in 0.1 km?) | open |
+| `0x0C` | 4 | trip, 0.1 km | matches app |
+| `0x0F` | 1 | traction battery, % | plausible |
+| `0x11` | 1 | unknown | open |
+| `0x23` | 2 | unknown | open |
+| `0x4F` | 1 | unknown | open |
+
+Device info request (`CMD 0x04`, keys `04 05 4f 70`): key `0x04` holds three version bytes (`2.20.16` observed; the app shows `1.4.0` elsewhere, so this may be another component), key `0x70` the ASCII serial number.
+
+The app also writes a clock sync (`TYPE 0x63`, `CMD 0x01`, key `0x3C`). This library deliberately does not implement it.
+
+## Install for development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+pip install -e '.[dev]'
+```
+
+On Linux, BlueZ and a working Bluetooth adapter are required.
+
+## CLI
+
+Scan for likely TENWAYS devices:
+
+```bash
+tenways scan
+```
+
+Read live telemetry (traction battery, odometer, …):
+
+```bash
+tenways status E8:88:6C:31:B3:0D
+```
+
+Read firmware and serial number:
+
+```bash
+tenways device-info E8:88:6C:31:B3:0D
+```
+
+Read the standard BLE battery percentage (not the traction battery):
+
+```bash
+tenways battery E8:88:6C:31:B3:0D
+```
+
+Show basic GATT information and battery level:
+
+```bash
+tenways info E8:88:6C:31:B3:0D
+```
+
+Subscribe to the proprietary notification characteristic:
+
+```bash
+tenways listen E8:88:6C:31:B3:0D
+```
+
+Stop with `Ctrl+C`.
+
+## Optional HCI trace on Linux
+
+For traffic generated by this library/CLI on the same Linux Bluetooth controller, BlueZ `btmon` is useful:
+
+```bash
+sudo btmon -i hci0 -w tenways.btsnoop
+```
+
+Then run the CLI in another shell. The resulting `tenways.btsnoop` file can be inspected with Wireshark.
+
+This does **not** passively capture a BLE connection between an Android phone and the bicycle. For the original TENWAYS app, use Android HCI snoop logging or a dedicated BLE sniffer.
+
+## Safety
+
+`tenways-ble` 0.1.0 never writes arbitrary data to the proprietary TENWAYS write characteristic. Reverse engineering should start from observed traffic rather than guessed commands.
+
+## License
+
+MIT
+
+Never publish a raw phone HCI log; it contains traffic and identifiers of other devices.
+
+## Releasing
+
+Releases are published to PyPI by GitHub Actions via trusted publishing when a `v*` tag is pushed. The tag must match `__version__`.
+
+## Acknowledgements / Credits
+
+Based on and inspired by [stein155/cgo600-bridge](https://github.com/stein155/cgo600-bridge), which provided valuable groundwork for understanding the proprietary TENWAYS telemetry protocol and its integration with Home Assistant.
+
+Many thanks to the original author and contributors.
+
+The Longtail Duo implementation was developed using independently captured Bluetooth HCI traffic from the official TENWAYS app. It uses the King Meter BLE transport rather than the Nordic UART Service used by the CGO600 bridge.

tenways_ble-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+tenways_ble/__init__.py,sha256=txOSNn1uzsKDTI_Gc4FDCDT7b2ETFhdR60W1gUfvU_s,590
+tenways_ble/cli.py,sha256=VoS-ODT8ires2xmFeDvz-jK0gyEpPh03ohUH_-w-Vo8,4642
+tenways_ble/client.py,sha256=U9jHeGFO6SqhStqG_mTWwspxlte2W6mFya6KTyckAmA,9044
+tenways_ble/const.py,sha256=8p2tobKei5b2kw1ZumxH4NZn5xniua_zZLf2_k9zyCw,583
+tenways_ble/models.py,sha256=zmgVn2weCKNFNNHAFy3BrEJUtBMeDnmXXCdf3c9Ig0w,350
+tenways_ble/protocol.py,sha256=anAK4YcjJx0YKFLe7SF_oLUvcsjVAsbec-7_G-iYyjc,8123
+tenways_ble-0.2.0.dist-info/METADATA,sha256=1QxcC6AMMdbV1OZOaTkk-skUI6GPRatllacax71BhqM,6717
+tenways_ble-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+tenways_ble-0.2.0.dist-info/entry_points.txt,sha256=FsiLrfFD-vxS37T52WvbJZdB747QYQxfXx0FHqklx8M,49
+tenways_ble-0.2.0.dist-info/licenses/LICENSE,sha256=tJTTqFaZJxTrpyBowRTJa2CwuouUqknt7h6HE3NCyCk,1075
+tenways_ble-0.2.0.dist-info/RECORD,,

tenways_ble-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

tenways_ble-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tenways = tenways_ble.cli:main

tenways_ble-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christoph Berliner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.