tenways-ble 0.2.0__tar.gz

tenways_ble-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e '.[dev]' build
+      - run: pytest
+      - name: Check tag matches version
+        run: test "v$(python -c 'import tenways_ble; print(tenways_ble.__version__)')" = "$GITHUB_REF_NAME"
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

tenways_ble-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,19 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[dev]'
+      - run: pytest

tenways_ble-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+*.btsnoop

tenways_ble-0.2.0/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.

tenways_ble-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,174 @@
+# 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/docs/RESEARCH.md

@@ -0,0 +1,86 @@
+# Research leads
+
+Leads for decoding more of the Longtail Duo. **Nothing here is confirmed for
+the King Meter BLE interface (`43480001-…`)**; only frames captured from the
+official TENWAYS app count as evidence. Never derive write commands from these
+sources.
+
+## Hardware chain (hypothesis)
+
+```
+TENWAYS app / Home Assistant
+        │  King Meter BLE (43480001-…) — confirmed by HCI capture
+Display / BLE module  — possibly DigiTech BC351
+        │  internal bus, probably CAN
+Bafang M410 drive (250 W, 80 Nm, integrated controller) — confirmed by TENWAYS
+```
+
+The display may forward only a subset of motor data over BLE, or may answer
+further, not yet captured BLE field keys. CAN frames cannot be assumed to pass
+through the BLE channel.
+
+## King Meter display protocols (serial, not BLE)
+
+- [stancecoke/BMSBattery_S_controllers_firmware `display_kingmeter.c`](https://github.com/stancecoke/BMSBattery_S_controllers_firmware/blob/Master/display_kingmeter.c)
+  — C implementation of the 901U/KM5S display protocol, including a handshake
+  and OEM-specific handshake tables.
+- [EBiCS/EBiCS_Firmware](https://github.com/EBiCS/EBiCS_Firmware) — separate
+  implementations for KINGMETER_618U, KINGMETER_901U, Bafang LCD and TFT.
+- [King Meter J-LCD5S protocol (PDF)](https://www.emubikes.com/wp-content/uploads/2020/12/J-LCD5S-protocol-From-KING-METER_1589857045208.pdf)
+  — speed, battery, assist levels, error codes, lights. Useful for guessing
+  which data exists, not for BLE field keys.
+
+No public source found that documents the King Meter BLE UUID or the
+`62 00 … CRC 45` framing.
+
+## Bafang CAN (different transport)
+
+- [speedysheep/ebike-protocols `BAFANG_CAN_PROTOCOL.md`](https://github.com/speedysheep/ebike-protocols/blob/main/bafang/BAFANG_CAN_PROTOCOL.md)
+  — reverse-engineered Bafang CAN codes, e.g. `0x32/0x00` (state of charge,
+  cadence, torque, remaining range), `0x32/0x01` (speed, motor current, battery
+  voltage, controller and motor temperature; 16-bit little endian, temperatures
+  offset −40 °C), `0x63/0x00` (assist level, mode, light bits), `0x64/0x02–05`
+  (cell voltages, mV).
+- [andrey-pr/OpenBafangTool](https://github.com/andrey-pr/OpenBafangTool) —
+  diagnosis and configuration for Bafang UART and CAN.
+- [Kaspars Dambis: Bafang CAN bus programming](https://kaspars.net/blog/bafang-canbus)
+  — CAN adapter, HIGO connectors, 250 kbit/s, SocketCAN; comments mention a
+  TENWAYS AGO-X with M410.
+
+A direct CAN capture would be a later, separate option and needs opening the
+bike's wiring. Not planned for now.
+
+## Display: DigiTech BC351 (unconfirmed)
+
+A dealer lists the Longtail Duo display as DigiTech BC351 with Bluetooth. Not
+an official TENWAYS statement for every hardware revision.
+
+- 3.5" colour display, UART or CAN, optional Bluetooth 4.2 and GPS, vendor app
+  "Bikewise Pro".
+- [DigiTech B-COCKPiT BC351 manual](https://www.manualslib.com/manual/3148608/Digitech-B-Cockpit-Bc351.html)
+  (documents Bluetooth pairing via QR code)
+- [HEPHA BC351 manual](https://www.manualslib.de/manual/1351570/Hepha-Bc351.html)
+  — OEM display on the same base.
+
+Do not treat DigiTech and King Meter as the same manufacturer without evidence.
+If Bikewise Pro talks to the bike, an HCI capture of that app could reveal more
+BLE commands.
+
+## Open status fields and tests
+
+| Field | Captured | Next test |
+|---|---|---|
+| `0x0B` | 655 | Compare with range shown on display; does it fall while riding? |
+| `0x11` | 0 | Change assist level on the parked bike, read again |
+| `0x23` | 0 | Toggle lights, read again |
+| `0x4F` | 1 | Correlate with display/power states |
+| `0x06` | 0 | Capture while riding (safely, supervised) to confirm current speed |
+
+These are hypotheses. A key number matching a Bafang CAN code does not imply
+the same meaning in the BLE protocol.
+
+## Capture procedure
+
+Android HCI snoop log (`mSnoopLogSettingAtEnable = full`), retrieved via bug
+report from `FS/data/misc/bluetooth/logs/btsnoop_hci.log`. Trigger exactly one
+action in the app per capture and note the time. Never publish a raw capture.

tenways_ble-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tenways-ble"
+version = "0.2.0"
+description = "Read-only BLE client, King Meter protocol and diagnostic CLI for TENWAYS e-bikes"
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["tenways", "ebike", "bluetooth", "ble", "king-meter", "home-assistant"]
+license = { text = "MIT" }
+authors = [
+  { name = "Christoph Berliner" }
+]
+dependencies = [
+  "bleak>=0.22",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/Styx85/tenways-ble"
+Issues = "https://github.com/Styx85/tenways-ble/issues"
+
+[project.scripts]
+tenways = "tenways_ble.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tenways_ble"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+asyncio_mode = "auto"
+pythonpath = ["src"]

tenways_ble-0.2.0/src/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"