Universal Bluetooth SDK

A Go daemon and CLI for Bluetooth experiments, with AI and MCP integrations.

Build against one local API. Try it without a radio, send RFCOMM payloads on Linux,
and help build the missing foundations for nearby chat and local AI assistants.

Quick start · Build chat apps · Contribute · Roadmap

Experimental, not production-ready. The Go implementation supports a simulated
driver and Linux RFCOMM sending. It does not implement BLE GATT, bidirectional
chat, mesh routing, end-to-end encryption, or Bitchat interoperability.
“Universal” describes the project direction, not current platform coverage.

What can you build?

The useful shared layer is radio access and messaging primitives. Your app owns
its UI, identity, conversation history, model runtime, and user consent.

Quick start without Bluetooth hardware

Requires Go 1.24+. These POSIX-shell commands target Linux/macOS; Windows
runtime behavior has not been validated. The first build downloads dependencies.
No API key, model download, pairing, or root access is needed for the stub demo.

git clone https://github.com/sraodev/universal-bluetooth-sdk.git
cd universal-bluetooth-sdk
go build -o bin/ubtd ./cli/ubtd
go build -o bin/ubtctl ./cli/ubtctl

Terminal 1 — keep this running; stop with Ctrl-C:

mkdir -p "$HOME/.local/run/ubtd"
chmod 700 "$HOME/.local/run/ubtd"
./bin/ubtd --socket "$HOME/.local/run/ubtd/daemon.sock" --driver stub

Terminal 2:

export UBTD_SOCKET="$HOME/.local/run/ubtd/daemon.sock"
./bin/ubtctl ping
./bin/ubtctl status
./bin/ubtctl discover --scan-timeout 3
./bin/ubtctl send --address AA:BB:CC:DD:EE:01 --data 'hello'

Discovery returns the synthetic stub-pi and stub-esp32 peers. Sending reports
sent 5 bytes in 1234 µs: a simulation, not radio delivery or a benchmark.
For an automated check that starts and cleans up its own daemon:

python3 scripts/smoke.py

Real Bluetooth on Linux

The linuxrfcomm driver uses BlueZ's bluetoothctl devices to list already
known devices, not to perform a live scan. It opens a native RFCOMM socket for
sending. Configure pairing, adapter permissions, and a receiver separately.

On Debian/Raspberry Pi OS, install BlueZ with sudo apt install bluez. Then stop
the stub daemon and start ubtd --driver linuxrfcomm using the same private
socket path. Send using the receiver's actual address and RFCOMM channel (1–30):

./bin/ubtctl send --address AA:BB:CC:DD:EE:FF --port 1 --data 'hello'

The address is a placeholder. A successful write does not prove the remote app
processed the message. Do not assume raw Go payloads speak the legacy Python
SDK's length/acknowledgement/pickle protocol. Do not run the daemon as root by
default. See hardware validation and security.

AI, MCP, and replay

• Local AI: draft a short message with Ollama, review
  the saved text, then explicitly invoke ubtctl send. No automatic radio access.
• Cloud planner: ubtctl ask --dry-run "check daemon status" requires
  ANTHROPIC_API_KEY. It sends the goal and tool results to Anthropic and can incur
  charges. --dry-run suppresses sends; it does not make this an offline command.
• MCP: ubtctl mcp --socket "$UBTD_SOCKET" exposes daemon tools over stdio to
  a compatible client. The current server includes a send tool; use only trusted
  clients and their approval controls, preferably against the stub driver.
• Replay: ubtctl plan run --dry-run plan.json previews a saved trace without
  the daemon or an LLM. Executing mutating tools requires --yes before the path.

The cloud planner's ask command currently has no --yes confirmation flag:
without --dry-run, its tool calls can send. Do not confuse that with replay's
--yes gate. CLI details and configuration.

Architecture and current scope

CLI / Claude planner / MCP / saved plans
                  |
       length-prefixed JSON over local Unix socket
                  |
                 ubtd
                  |
           transport.Driver
             /         \
          stub       Linux RFCOMM
        simulated    one-shot send

The Go module still uses the historical import path
github.com/sraodev/bluetooth-service-rfcomm-python. Clone the current repository
URL above; module migration is tracked separately to avoid breaking consumers.
The JSON Go types are implemented in sdk/go/pkg/protocol;
v1.proto is a design counterpart, not generated bindings.

Help build the next milestone

We especially need Linux/Raspberry Pi testers, Go contributors, BLE engineers,
and developers building chat apps. Start with the
good first issues
or help wanted backlog.
BLE, cryptography, and protocol work are not beginner tasks.

Read CONTRIBUTING.md for setup and a small first PR.
ROADMAP.md gives acceptance gates, not promised dates.
If this is useful, star it to bookmark the project; a reproducible bug report,
hardware result, or example app helps even more.

Documentation · Security · Code of conduct · MIT license