Metadata-Version: 2.4
Name: ble-message-bridge
Version: 0.1.1
Summary: A small BLE GATT transport for framed JSON and binary messages between Python desktops and Android devices.
Project-URL: Homepage, https://github.com/MN-company/ble-message-bridge
Project-URL: Documentation, https://github.com/MN-company/ble-message-bridge#readme
Project-URL: Repository, https://github.com/MN-company/ble-message-bridge
Project-URL: Issues, https://github.com/MN-company/ble-message-bridge/issues
Author: MN-company
License-Expression: MIT
License-File: LICENSE
Keywords: android,ble,bleak,bluetooth,framing,gatt,transport
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: bleak<4.0,>=1.1.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# BLE Message Bridge

BLE Message Bridge is a small transport layer for sending framed JSON and binary payloads over Bluetooth Low Energy GATT.

It is useful when you want a desktop Python app to talk to an Android device over BLE without rewriting the same plumbing every time:

- split large payloads into BLE-sized packets;
- reassemble packets on the other side;
- gzip larger JSON/text payloads;
- send compact binary ping/pong heartbeats;
- reconnect with jittered backoff;
- use one write characteristic and one notify characteristic for duplex messages.

This library started as the reusable BLE transport extracted from a desktop-to-Android app. The public package is intentionally app-agnostic: it does not know about chat, AI models, prompts, screenshots, or any product-specific message schema.

## Install

```bash
pip install ble-message-bridge
```

## Quick Start

```python
import asyncio

from ble_message_bridge import BleBridgeClient


def on_event(event: dict) -> None:
    print(event)


async def main() -> None:
    async with BleBridgeClient(event_sink=on_event) as client:
        devices = await client.scan()
        if not devices:
            raise SystemExit("No bridge devices found")

        await client.connect(devices[0].address)
        await client.send_json({"type": "hello", "text": "ciao"})
        await asyncio.sleep(3)


asyncio.run(main())
```

## Custom UUIDs

The defaults are stable UUIDs from the reference Android bridge. For your own app, create your own service and characteristic UUIDs:

```python
from ble_message_bridge import BleBridgeClient, BleBridgeConfig

config = BleBridgeConfig(
    service_uuid="00000000-0000-0000-0000-000000000001",
    write_char_uuid="00000000-0000-0000-0000-000000000002",
    notify_char_uuid="00000000-0000-0000-0000-000000000003",
)

client = BleBridgeClient(config=config)
```

## Events

`BleBridgeClient` reports everything through an optional event sink:

```python
def on_event(event: dict) -> None:
    match event["type"]:
        case "json":
            print("message", event["message"])
        case "payload":
            print("bytes", event["payload"])
        case "link_quality":
            print("rtt", event.get("rtt_ms"))
```

Common event types:

- `scan_result`
- `connected`
- `disconnected`
- `sent`
- `transfer_progress`
- `json`
- `payload`
- `bundle`
- `link_quality`
- `link_status`
- `error`

## Android

This repo includes reference Kotlin sources in [`android/`](android/) for an Android BLE peripheral/server that speaks the same framing protocol.

The Android side is not published to Maven yet. For now, copy the small reference classes into your app module, or use them as the basis for your own BLE service.

See [`docs/android.md`](docs/android.md).

## Protocol

The packet format is intentionally small:

```text
[version:1][transport_id:2][chunk_index:2][chunk_total:2][payload:n]
```

All integers are big-endian. Payloads larger than one BLE write/notification are split into multiple frames with the same `transport_id`.

See [`docs/protocol.md`](docs/protocol.md).

## Status

`0.1.x` is alpha. The framing format is simple and tested, but the public API may still evolve while real projects try it.

## License

MIT

