# libblebus

C++17 Bluetooth LE IPC library.

Broker-based broadcast bus with length-prefixed framing. Bytes in, bytes out.

**Author:** Are Bjørby <are.bjorby@langsyn.org>
No routing, parsing, or protocol logic.

Each bus runs one broker thread listening on **two** transports at once: a local
unix socket and a BLE L2CAP connection-oriented channel. A writer on either side
reaches every reader on both.

## Build

```bash
make              # Build libblebus.a + libblebus.so
make test         # Build and run all 15 tests
make install      # Install to /usr/local (sudo required)
make clean        # Remove build artifacts
```

Requires: `g++` with C++17 support, `libbluetooth-dev`, `libsystemd-dev`.
Linux only (BlueZ L2CAP and sd-bus).

## API

Single public header: `#include <blebus.hpp>`

```cpp
blebus::create("sensors");                // Start broker + BLE advertising
blebus::Bus bus("sensors");               // Connect (RAII, local socket)
bus.write(data, len);                     // Broadcast (framed)
bus.write(string_view);                   // Broadcast (string_view)
bus.read(buf, len);                       // Non-blocking read
bus.read_wait(buf, len, timeout_ms);      // Blocking read
// ~Bus() disconnects (RAII)
blebus::destroy("sensors");               // Stop broker, drop all clients
```

`Bus` is move-only. Errors are `std::system_error`.

## Design

- **Dual listener**: one broker thread serves a local unix socket *and* a BLE
  L2CAP CoC at `PSM = 0x0080`. Local clients connect over the socket; remote
  peers connect over the radio.
- **Broadcast**: all connected readers (including the sender) receive every
  write.
- **Lossy**: slow readers are dropped, never buffered.
- **Wire frame**: 4-byte length prefix (network byte order) + payload.
  Wire-compatible with `libsockbus`.
- **Advertising**: `create()` registers an `org.bluez.LEAdvertisement1` object
  over sd-bus, so the host process needs Bluetooth adapter permissions.
- **Bounds**: `MAX_MSG_SIZE` is 65532 bytes — the 64 KB default buffer minus the
  4-byte prefix — and `MAX_READERS` is 8 per bus, deliberately tighter than the
  TCP sibling's, because here a reader may be a radio link.

## Testing

`make test` runs 15 tests over the **local unix-socket transport only**. The BLE
L2CAP path needs a real adapter and is not covered — a green suite says nothing
about the radio side, and that is worth knowing before depending on it.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for coding standards and how to contribute.

## License

MIT License — see [LICENSE](LICENSE).