litime-ble

Lightweight Python library and CLI to read Li-Time BLE battery statistics via Bluetooth Low Energy.

New in 0.2.0: Device discovery, enhanced logging, comprehensive examples, and CLI module support.

Install

This library is listed as a package on PyPi and can be installed using pip

pip install litime-ble

Or install from source:

pip install .

Quick start

Device Discovery

Find your Li-Time battery automatically:

from litime_ble import find_litime_batteries_sync

batteries = find_litime_batteries_sync(timeout=5.0)
if batteries:
    mac_address = batteries[0]['address']
    print(f"Found battery: {mac_address}")

Battery Reading

from litime_ble import BatteryClient

# Synchronous (simple)
with BatteryClient.sync(address="C8:47:80:15:5C:0F") as client:
    status = client.read_once()
    print(f"Battery: {status.voltage_v:.1f}V, {status.soc_percent:.0f}%")
    print(status.json())  # Full data as JSON

# Asynchronous (recommended)
import asyncio
from litime_ble import BatteryClient

async def read_battery():
    client = BatteryClient(address="C8:47:80:15:5C:0F")
    async with client.session():
        status = await client.read_once_async()
        return status

status = asyncio.run(read_battery())

CLI

# Discover batteries
python -m litime_ble discover --battery-only

# Read battery status
python -m litime_ble read --address C8:47:80:15:5C:0F --json

# Or use the installed command
litime-battery read --address C8:47:80:15:5C:0F --json

Documentation & Examples

• Documentation - Complete API docs and usage guide
• Examples - Ready-to-run example scripts with CLI options
• Developer Guide - Setup, testing, and contribution guidelines

Developer

Quick test:

# PowerShell
$env:PYTHONPATH = (Resolve-Path src).Path; python -m pytest -q

# macOS/Linux
PYTHONPATH=$(pwd)/src python -m pytest -q

Code quality:

ruff check src --fix

License

This project is licensed under the MIT License.
It follows the same license as the original codebase it was based on: litime-bluetooth-battery.

Copyright (c) 2025 Konnexio Inc.