sok-ble 0.1.0__py3-none-any.whl

sok_ble/const.py

@@ -0,0 +1,33 @@
+"""Constants and helpers for interacting with SOK BLE batteries."""
+
+from __future__ import annotations
+
+UUID_RX = "0000ffe1-0000-1000-8000-00805f9b34fb"
+UUID_TX = "0000ffe2-0000-1000-8000-00805f9b34fb"
+
+# Command byte templates extracted from the reference addon
+CMD_NAME = [0xEE, 0xC0, 0x00, 0x00, 0x00]
+CMD_INFO = [0xEE, 0xC1, 0x00, 0x00, 0x00]
+CMD_DETAIL = [0xEE, 0xC2, 0x00, 0x00, 0x00]
+CMD_SETTING = [0xEE, 0xC3, 0x00, 0x00, 0x00]
+CMD_PROTECTION = [0xEE, 0xC4, 0x00, 0x00, 0x00]
+CMD_BREAK = [0xDD, 0xC0, 0x00, 0x00, 0x00]
+
+
+def minicrc(data: list[int] | bytes) -> int:
+    """Compute CRC-8 used by the SOK protocol."""
+
+    crc = 0
+    for byte in data:
+        crc ^= byte & 0xFF
+        for _ in range(8):
+            crc = (crc >> 1) ^ 0x8C if (crc & 1) else crc >> 1
+    return crc
+
+
+def _sok_command(cmd: int) -> bytes:
+    """Return a command frame with CRC for the given command byte."""
+
+    data = [0xEE, cmd, 0x00, 0x00, 0x00]
+    crc = minicrc(data)
+    return bytes(data + [crc])

sok_ble/exceptions.py

@@ -0,0 +1,11 @@
+class SokError(Exception):
+    """Base for SOK library errors."""
+
+
+class BLEConnectionError(SokError):
+    """Raised when BLE communication fails."""
+
+
+class InvalidResponseError(SokError):
+    """Raised when an invalid response is received."""
+

sok_ble/sok_bluetooth_device.py

@@ -0,0 +1,160 @@
+"""BLE device abstraction for SOK batteries."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import AsyncIterator, Optional
+import logging
+import statistics
+
+from bleak.backends.device import BLEDevice
+
+from sok_ble.const import UUID_RX, UUID_TX, _sok_command
+from sok_ble.sok_parser import SokParser
+
+logger = logging.getLogger(__name__)
+
+try:
+    from bleak_retry_connector import (
+        BleakClientWithServiceCache,
+        establish_connection,
+    )
+except Exception:  # pragma: no cover - optional dependency
+    from bleak import BleakClient as BleakClientWithServiceCache
+    establish_connection = None  # type: ignore[misc]
+
+
+class SokBluetoothDevice:
+    """Minimal BLE interface for a SOK battery."""
+
+    def __init__(self, ble_device: BLEDevice, adapter: Optional[str] | None = None) -> None:
+        self._ble_device = ble_device
+        self._adapter = adapter
+
+        self.voltage: float | None = None
+        self.current: float | None = None
+        self.soc: int | None = None
+        self.temperature: float | None = None
+        self.capacity: float | None = None
+        self.num_cycles: int | None = None
+        self.cell_voltages: list[float] | None = None
+
+        # Housekeeping
+        self.num_samples = 0
+
+    @asynccontextmanager
+    async def _connect(self) -> AsyncIterator[BleakClientWithServiceCache]:
+        """Connect to the device and yield a BLE client."""
+        logger.debug("Connecting to %s", self._ble_device.address)
+        if establish_connection:
+            client = await establish_connection(
+                BleakClientWithServiceCache,
+                self._ble_device,
+                self._ble_device.name or self._ble_device.address,
+                adapter=self._adapter,
+            )
+        else:
+            client = BleakClientWithServiceCache(
+                self._ble_device,
+                adapter=self._adapter,
+            )
+            await client.connect()
+        try:
+            yield client
+        finally:
+            await client.disconnect()
+            logger.debug("Disconnected from %s", self._ble_device.address)
+
+    async def async_update(self) -> None:
+        """Poll the device for all telemetry and update attributes."""
+        responses: dict[int, bytes] = {}
+        async with self._connect() as client:
+            logger.debug("Send C1")
+            await client.write_gatt_char(UUID_TX, _sok_command(0xC1))
+            data = bytes(await client.read_gatt_char(UUID_RX))
+            logger.debug("Recv 0xCCF0: %s", data.hex())
+            responses[0xCCF0] = data
+
+            logger.debug("Send C1")
+            await client.write_gatt_char(UUID_TX, _sok_command(0xC1))
+            data = bytes(await client.read_gatt_char(UUID_RX))
+            logger.debug("Recv 0xCCF2: %s", data.hex())
+            responses[0xCCF2] = data
+
+            logger.debug("Send C2")
+            await client.write_gatt_char(UUID_TX, _sok_command(0xC2))
+            data = bytes(await client.read_gatt_char(UUID_RX))
+            logger.debug("Recv 0xCCF3: %s", data.hex())
+            responses[0xCCF3] = data
+
+            logger.debug("Send C2")
+            await client.write_gatt_char(UUID_TX, _sok_command(0xC2))
+            data = bytes(await client.read_gatt_char(UUID_RX))
+            logger.debug("Recv 0xCCF4: %s", data.hex())
+            responses[0xCCF4] = data
+
+        parsed = SokParser.parse_all(responses)
+        logger.debug("Parsed update: %s", parsed)
+
+        self.voltage = parsed["voltage"]
+        self.current = parsed["current"]
+        self.soc = parsed["soc"]
+        self.temperature = parsed["temperature"]
+        self.capacity = parsed["capacity"]
+        self.num_cycles = parsed["num_cycles"]
+        self.cell_voltages = parsed["cell_voltages"]
+
+        self.num_samples += 1
+
+    # Derived metrics -----------------------------------------------------
+
+    @property
+    def power(self) -> float | None:
+        """Return instantaneous power in watts."""
+        if self.voltage is None or self.current is None:
+            return None
+        return self.voltage * self.current
+
+    @property
+    def cell_voltage_max(self) -> float | None:
+        cells = self.cell_voltages
+        return max(cells) if cells else None
+
+    @property
+    def cell_voltage_min(self) -> float | None:
+        cells = self.cell_voltages
+        return min(cells) if cells else None
+
+    @property
+    def cell_voltage_avg(self) -> float | None:
+        cells = self.cell_voltages
+        if not cells:
+            return None
+        return sum(cells) / len(cells)
+
+    @property
+    def cell_voltage_median(self) -> float | None:
+        cells = self.cell_voltages
+        if not cells:
+            return None
+        return statistics.median(cells)
+
+    @property
+    def cell_voltage_delta(self) -> float | None:
+        if self.cell_voltage_max is None or self.cell_voltage_min is None:
+            return None
+        return self.cell_voltage_max - self.cell_voltage_min
+
+    @property
+    def cell_index_max(self) -> int | None:
+        cells = self.cell_voltages
+        if not cells:
+            return None
+        return cells.index(max(cells))
+
+    @property
+    def cell_index_min(self) -> int | None:
+        cells = self.cell_voltages
+        if not cells:
+            return None
+        return cells.index(min(cells))

sok_ble/sok_parser.py

@@ -0,0 +1,135 @@
+"""Parsing utilities for SOK BLE responses."""
+
+from __future__ import annotations
+
+import logging
+import struct
+from typing import Dict, Sequence
+
+from sok_ble.exceptions import InvalidResponseError
+
+logger = logging.getLogger(__name__)
+
+
+# Endian helper functions copied from the reference addon
+
+def get_le_short(data: Sequence[int] | bytes | bytearray, offset: int) -> int:
+    """Read a little-endian signed short."""
+    return struct.unpack_from('<h', bytes(data), offset)[0]
+
+
+def get_le_ushort(data: Sequence[int] | bytes | bytearray, offset: int) -> int:
+    """Read a little-endian unsigned short."""
+    return struct.unpack_from('<H', bytes(data), offset)[0]
+
+
+def get_le_int3(data: Sequence[int] | bytes | bytearray, offset: int) -> int:
+    """Read a 3-byte little-endian signed integer."""
+    b0, b1, b2 = bytes(data)[offset:offset + 3]
+    val = b0 | (b1 << 8) | (b2 << 16)
+    if val & 0x800000:
+        val -= 0x1000000
+    return val
+
+
+def get_be_uint3(data: Sequence[int] | bytes | bytearray, offset: int) -> int:
+    """Read a 3-byte big-endian unsigned integer."""
+    b0, b1, b2 = bytes(data)[offset:offset + 3]
+    return (b0 << 16) | (b1 << 8) | b2
+
+
+class SokParser:
+    """Parse buffers returned from SOK batteries."""
+
+    @staticmethod
+    def parse_info(buf: bytes) -> Dict[str, float | int]:
+        """Parse the information frame for voltage, current and SOC."""
+        logger.debug("parse_info input: %s", buf.hex())
+        if len(buf) < 18:
+            raise InvalidResponseError("Info buffer too short")
+
+        cells = [
+            get_le_ushort(buf, 0),
+            get_le_ushort(buf, 2),
+            get_le_ushort(buf, 4),
+            get_le_ushort(buf, 6),
+        ]
+        voltage = (sum(cells) / len(cells) * 4) / 1000
+
+        current = get_le_int3(buf, 8) / 10
+
+        soc = struct.unpack_from('<H', buf, 16)[0]
+
+        result = {
+            "voltage": voltage,
+            "current": current,
+            "soc": soc,
+        }
+        logger.debug("parse_info result: %s", result)
+        return result
+
+    @staticmethod
+    def parse_temps(buf: bytes) -> float:
+        """Parse the temperature from the temperature frame."""
+        logger.debug("parse_temps input: %s", buf.hex())
+        if len(buf) < 7:
+            raise InvalidResponseError("Temp buffer too short")
+
+        temperature = get_le_short(buf, 5) / 10
+        logger.debug("parse_temps result: %s", temperature)
+        return temperature
+
+    @staticmethod
+    def parse_capacity_cycles(buf: bytes) -> Dict[str, float | int]:
+        """Parse rated capacity and cycle count."""
+        logger.debug("parse_capacity_cycles input: %s", buf.hex())
+        if len(buf) < 6:
+            raise InvalidResponseError("Capacity buffer too short")
+
+        capacity = get_le_ushort(buf, 0) / 100
+        num_cycles = get_le_ushort(buf, 4)
+
+        result = {
+            "capacity": capacity,
+            "num_cycles": num_cycles,
+        }
+        logger.debug("parse_capacity_cycles result: %s", result)
+        return result
+
+    @staticmethod
+    def parse_cells(buf: bytes) -> list[float]:
+        """Parse individual cell voltages."""
+        logger.debug("parse_cells input: %s", buf.hex())
+        if len(buf) < 8:
+            raise InvalidResponseError("Cells buffer too short")
+
+        cells = [
+            get_le_ushort(buf, 0) / 1000,
+            get_le_ushort(buf, 2) / 1000,
+            get_le_ushort(buf, 4) / 1000,
+            get_le_ushort(buf, 6) / 1000,
+        ]
+        logger.debug("parse_cells result: %s", cells)
+        return cells
+
+    @classmethod
+    def parse_all(cls, responses: Dict[int, bytes]) -> Dict[str, float | int | list[float]]:
+        """Parse all response buffers into a single dictionary."""
+        logger.debug("parse_all input keys: %s", list(responses))
+        required = {0xCCF0, 0xCCF2, 0xCCF3, 0xCCF4}
+        if not required.issubset(responses):
+            raise InvalidResponseError("Missing response buffers")
+
+        info = cls.parse_info(responses[0xCCF0])
+        temperature = cls.parse_temps(responses[0xCCF2])
+        capacity_info = cls.parse_capacity_cycles(responses[0xCCF3])
+        cells = cls.parse_cells(responses[0xCCF4])
+
+        result = {
+            **info,
+            "temperature": temperature,
+            **capacity_info,
+            "cell_voltages": cells,
+        }
+        logger.debug("parse_all result: %s", result)
+        return result

sok_ble-0.1.0.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: sok-ble
+Version: 0.1.0
+Summary: SOK BLE battery interface library
+Author-email: Mitchell Carlson <mitchell.carlson.pro@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/IAmTheMitchell/sok-ble
+Project-URL: Bug Tracker, https://github.com/IAmTheMitchell/sok-ble/issues
+Project-URL: Changelog, https://github.com/IAmTheMitchell/sok-ble/blob/main/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: bleak>=0.22.3
+Requires-Dist: bleak-retry-connector>=3.10.0
+
+# SOK BLE
+
+![CI](https://github.com/IAmTheMitchell/sok-ble/actions/workflows/ci.yml/badge.svg)
+
+Python library for interacting with SOK Bluetooth-enabled batteries.
+
+## Quick Start
+
+```python
+import asyncio
+from bleak import BleakScanner
+from sok_ble.sok_bluetooth_device import SokBluetoothDevice
+
+
+async def main() -> None:
+    device = await BleakScanner.find_device_by_address("AA:BB:CC:DD:EE:FF")
+    sok = SokBluetoothDevice(device)
+    await sok.async_update()
+    print("Voltage:", sok.voltage)
+
+
+asyncio.run(main())
+```

sok_ble-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+sok_ble/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sok_ble/const.py,sha256=mHtJTbWz_dG3v1lhZrLDzMf-QAG9v5QWlHU9ZKsyYdg,998
+sok_ble/exceptions.py,sha256=7H1yUqqnrKyi3LwxRCMF7RkuGp_rgdy9j35nrMOgz44,247
+sok_ble/sok_bluetooth_device.py,sha256=-dMuHzM0FtBh_fu2MURiriOVhOGaLDM2ZQIRk6zDC84,5384
+sok_ble/sok_parser.py,sha256=zyrZwjOc4yeFfQWo_1B3VFxEGXLJBX7UQPL9e5ag1jQ,4441
+sok_ble-0.1.0.dist-info/METADATA,sha256=u1fvysxad3Cg-N2ipnnuhB2V4N8iVQEzel4-INBRpnU,1233
+sok_ble-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sok_ble-0.1.0.dist-info/top_level.txt,sha256=WTVtlZ2sADYAxKEBkDJPUn4hFAH9NfIZ9Q2HP2RKpbw,8
+sok_ble-0.1.0.dist-info/RECORD,,

sok_ble-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sok_ble-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sok_ble