# 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
```bash
pip install litime-ble
```
Or install from source:
```bash
pip install .
```
## Quick start
### Device Discovery
Find your Li-Time battery automatically:
```python
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
```python
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
```bash
# 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](https://konnexio-inc.github.io/litime-ble/)** - Complete API docs and usage guide
- **[Examples](examples/)** - Ready-to-run example scripts with CLI options
- **[Developer Guide](docs/developer.md)** - Setup, testing, and contribution guidelines
## Developer
**Quick test:**
```bash
# PowerShell
$env:PYTHONPATH = (Resolve-Path src).Path; python -m pytest -q
# macOS/Linux
PYTHONPATH=$(pwd)/src python -m pytest -q
```
**Code quality:**
```bash
ruff check src --fix
```
## License
This project is licensed under the [MIT License](./LICENSE).
It follows the same license as the original codebase it was based on: [litime-bluetooth-battery](https://github.com/chadj/litime-bluetooth-battery).
Copyright (c) 2025 Konnexio Inc.
Raw data
{
"_id": null,
"home_page": null,
"name": "litime-ble",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "bluetooth, ble, battery, litime, solar, power",
"author": "Cameron K. Brooks",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ce/5c/7fcd65c7c71d275e06556bb156dbbe915a634961d37e184be7b6e0e58d10/litime_ble-0.2.2.tar.gz",
"platform": null,
"description": "# litime-ble\n\nLightweight Python library and CLI to read Li-Time BLE battery statistics via Bluetooth Low Energy.\n\n**New in 0.2.0**: Device discovery, enhanced logging, comprehensive examples, and CLI module support.\n\n## Install\n\n```bash\npip install litime-ble\n```\n\nOr install from source:\n\n```bash\npip install .\n```\n\n## Quick start\n\n### Device Discovery\n\nFind your Li-Time battery automatically:\n\n```python\nfrom litime_ble import find_litime_batteries_sync\n\nbatteries = find_litime_batteries_sync(timeout=5.0)\nif batteries:\n mac_address = batteries[0]['address']\n print(f\"Found battery: {mac_address}\")\n```\n\n### Battery Reading\n\n```python\nfrom litime_ble import BatteryClient\n\n# Synchronous (simple)\nwith BatteryClient.sync(address=\"C8:47:80:15:5C:0F\") as client:\n status = client.read_once()\n print(f\"Battery: {status.voltage_v:.1f}V, {status.soc_percent:.0f}%\")\n print(status.json()) # Full data as JSON\n\n# Asynchronous (recommended)\nimport asyncio\nfrom litime_ble import BatteryClient\n\nasync def read_battery():\n client = BatteryClient(address=\"C8:47:80:15:5C:0F\")\n async with client.session():\n status = await client.read_once_async()\n return status\n\nstatus = asyncio.run(read_battery())\n```\n\n## CLI\n\n```bash\n# Discover batteries\npython -m litime_ble discover --battery-only\n\n# Read battery status\npython -m litime_ble read --address C8:47:80:15:5C:0F --json\n\n# Or use the installed command\nlitime-battery read --address C8:47:80:15:5C:0F --json\n```\n\n## Documentation & Examples\n\n- **[Documentation](https://konnexio-inc.github.io/litime-ble/)** - Complete API docs and usage guide\n- **[Examples](examples/)** - Ready-to-run example scripts with CLI options\n- **[Developer Guide](docs/developer.md)** - Setup, testing, and contribution guidelines\n\n## Developer\n\n**Quick test:**\n\n```bash\n# PowerShell\n$env:PYTHONPATH = (Resolve-Path src).Path; python -m pytest -q\n\n# macOS/Linux\nPYTHONPATH=$(pwd)/src python -m pytest -q\n```\n\n**Code quality:**\n\n```bash\nruff check src --fix\n```\n\n## License\n\nThis project is licensed under the [MIT License](./LICENSE). \nIt follows the same license as the original codebase it was based on: [litime-bluetooth-battery](https://github.com/chadj/litime-bluetooth-battery).\n\nCopyright (c) 2025 Konnexio Inc.\n",
"bugtrack_url": null,
"license": null,
"summary": "Li Time Bluetooth battery reader via BLE (Python, Bleak)",
"version": "0.2.2",
"project_urls": null,
"split_keywords": [
"bluetooth",
" ble",
" battery",
" litime",
" solar",
" power"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0b941ad22acda9495cc25ee59aeede7f28978deba733776c188291ca355a1933",
"md5": "99e7d96568db36f778e168e4cd6993f6",
"sha256": "813114429e3b24ce7eac58fcddd9a826aa8fcd6483ab9bbb46a0165894d44c61"
},
"downloads": -1,
"filename": "litime_ble-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "99e7d96568db36f778e168e4cd6993f6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13025,
"upload_time": "2025-09-12T19:23:17",
"upload_time_iso_8601": "2025-09-12T19:23:17.287192Z",
"url": "https://files.pythonhosted.org/packages/0b/94/1ad22acda9495cc25ee59aeede7f28978deba733776c188291ca355a1933/litime_ble-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ce5c7fcd65c7c71d275e06556bb156dbbe915a634961d37e184be7b6e0e58d10",
"md5": "8c6dcdd4d14e896dd9fae6ea041f7bff",
"sha256": "0dcb3ef634a13b68f9456a0f31aba344c4fec4b52e85b074ae3b3f43e6c77e33"
},
"downloads": -1,
"filename": "litime_ble-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "8c6dcdd4d14e896dd9fae6ea041f7bff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 26373,
"upload_time": "2025-09-12T19:23:19",
"upload_time_iso_8601": "2025-09-12T19:23:19.209117Z",
"url": "https://files.pythonhosted.org/packages/ce/5c/7fcd65c7c71d275e06556bb156dbbe915a634961d37e184be7b6e0e58d10/litime_ble-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 19:23:19",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "litime-ble"
}
JSON