From c933a14afb8f062aed705d9d3e7241d4d14269d9 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 31 Jul 2026 00:11:03 +0000 Subject: [PATCH] docs: summarize library overview in DocC and README Replace the placeholder DocC overview and the one-line README description with a summary of what ReliaBLE is and provides, drawn from PRD.md: device-protocol-agnostic BLE Central core, device-centric API, reliability focus, scanning, multi-peripheral support, command protocol, logging, Swift 6 architecture, and test coverage. Notes the pre-1.0 development status. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01C2RxM9mm52hyiK5oMpmVT4 --- README.md | 41 +++++++++++++- .../Documentation.docc/Documentation.md | 56 ++++++++++++++++++- 2 files changed, 94 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8865794..1247ab2 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,46 @@ [![CI](https://github.com/Five3Apps/ReliaBLE/actions/workflows/ci.yml/badge.svg)](https://github.com/Five3Apps/ReliaBLE/actions/workflows/ci.yml) -Modern library for handling BLE connections, with a focus on reliability. +A reliable, modern, and easy-to-use Swift package for apps that talk to Bluetooth Low Energy (BLE) peripherals. + +## Overview + +ReliaBLE is a **device-protocol-agnostic BLE Central core** for iOS and macOS. The +library owns the hard, reliability-sensitive parts of talking to a peripheral — link +lifecycle, GATT service/characteristic discovery and readiness, and the machinery that +runs commands against it — while your app owns the domain-specific packet content +(framing, CRC, application semantics). This lets you build robust device integrations +without becoming a CoreBluetooth expert. + +It is built for apps that think in terms of **"my devices"** first — wearables, IoT +sensors, and smart-home accessories — so the public API is **device-centric**: you work +through a `Peripheral` handle rather than juggling a central manager for everyday tasks. +Generic "nearby scanner" experiences are supported too, but secondary. + +> **Note:** ReliaBLE is under active development toward its v1 release and is not yet +> intended for production use. The public API may change before 1.0. See +> [`PRD.md`](PRD.md) for the full v1 target and current status. + +### What it provides + +- **Reliable communication** — not just a "connected" bit, but a link that stays up, + discovery that reaches a *ready* state, and commands that run to completion, with a + two-tier (system + library-managed exponential backoff) automatic reconnect model. +- **A device-centric API** — `ReliaBLEManager` owns authorization, Bluetooth state, + scanning, and the peripheral registry; connection, discovery, and I/O live on + `Peripheral` handles. Live CoreBluetooth objects never cross the public boundary. +- **App-controlled authorization** — ReliaBLE never triggers the iOS permission prompt + on its own; you decide when it appears. +- **Scanning with rich advertisement data** — filter by service UUID, consume results as + strongly-typed `AsyncStream`s, with background scanning and state restoration. +- **Multiple simultaneous peripherals** — connect to and manage many devices at once. +- **A command-style I/O protocol** — a flexible, app-defined protocol for read/write/ + notify, gated on discovery readiness *(v1 target)*. +- **Flexible, low-overhead logging** — enable/disable and route output as you choose. +- **Modern Swift 6 architecture** — builds under complete concurrency checking, isolating + all CoreBluetooth usage in a single internal isolation domain. +- **High test coverage** — CoreBluetooth is mocked in tests, so behavior is verified in + CI without physical hardware. ## Installation diff --git a/Sources/ReliaBLE/Documentation.docc/Documentation.md b/Sources/ReliaBLE/Documentation.docc/Documentation.md index 9ed8a15..bd36a56 100644 --- a/Sources/ReliaBLE/Documentation.docc/Documentation.md +++ b/Sources/ReliaBLE/Documentation.docc/Documentation.md @@ -1,10 +1,62 @@ # ``ReliaBLE`` -Modern library for handling BLE connections, with a focus on reliability. +A reliable, modern, and easy-to-use Swift interface for apps that talk to Bluetooth Low Energy (BLE) peripherals. ## Overview -This is a temporary overview. +ReliaBLE is a **device-protocol-agnostic BLE Central core** for iOS and macOS. The +library owns the hard, reliability-sensitive parts of talking to a peripheral — +link lifecycle, GATT service/characteristic discovery and readiness, and the +machinery that runs commands against it — while your app owns the domain-specific +packet content (framing, CRC, application semantics). This separation lets you +build robust device integrations without becoming a CoreBluetooth expert. + +It is built for apps that think in terms of **"my devices"** first: wearables, +IoT sensors, and smart-home accessories. Generic "nearby scanner" experiences are +supported too, but the design is optimized for connecting to and reliably +communicating with the specific devices your users own. To keep that model clean, +the public API is **device-centric** — you work through a ``Peripheral`` handle +rather than juggling a central manager for day-to-day tasks. + +> Note: ReliaBLE is under active development toward its v1 release and is not yet +> intended for production use. The public API — particularly the `Peripheral` +> control-handle model — may change before 1.0. See the project `PRD.md` for the +> full v1 target and current status. + +### What it provides + +- **Reliable communication.** The focus is end-to-end reliability, not just a TCP-style + "connected" bit: a link that stays up, discovery that reaches a *ready* state, and + commands that run to completion. Automatic reconnection uses a two-tier model that + combines the iOS system-managed reconnect with a configurable library-managed + exponential-backoff ladder. +- **A device-centric public API.** ``ReliaBLEManager`` owns process-wide concerns — + authorization, Bluetooth state, scanning, and the peripheral registry — while + connection, discovery, and I/O are expressed against ``Peripheral`` handles. Live + `CBPeripheral`, `CBService`, and `CBCharacteristic` objects never cross the public + boundary. +- **App-controlled authorization.** ReliaBLE never triggers the iOS permission prompt + on its own; you decide exactly when ``ReliaBLEManager/authorizeBluetooth()`` presents it. +- **Scanning with rich advertisement data.** Scan for all peripherals or filter by + service UUID, and consume results as strongly-typed ``AdvertisementData`` snapshots + through `AsyncStream`s — either per-advertisement (``PeripheralDiscoveryEvent``) or as a + de-duplicated list of ``Peripheral`` values. Background scanning and state restoration + are supported. +- **Multiple simultaneous peripherals.** Maintain connections to many devices at once, + each with its own connection state and (in the v1 target) its own command queue. +- **A command-style I/O protocol.** A flexible, app-defined command protocol for + reading, writing, and subscribing to characteristics, gated on discovery readiness so + I/O never races ahead of the GATT table *(v1 target)*. +- **Flexible, low-overhead logging.** Enable or disable logging through the public API + and direct output wherever you choose; when disabled it stays out of the hot path. +- **Modern Swift 6 architecture.** The library builds under complete concurrency + checking and isolates all CoreBluetooth usage in a single internal isolation domain, + so the public façade is safe to call without forcing `@MainActor` on your app. +- **High test coverage.** CoreBluetooth is mockable in tests (via Nordic's + CoreBluetoothMock), so behavior is verified in CI without physical hardware. + +See to install ReliaBLE, authorize Bluetooth, scan for devices, +and open your first connection. ## Topics