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

pip install ble-message-bridge

Quick Start

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:

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:

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

Protocol

The packet format is intentionally small:

[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.

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