# bluez v0.1.0 - Table of Contents

> BlueZ-over-D-Bus client for Elixir: BLE scanning, GATT, pairing, and bluez-alsa audio

## Pages

- [Bluez](readme.md)

- Guides
  - [Architecture](architecture.md)
  - [Host integration](host_integration.md)
  - [Nerves system requirements](nerves_system.md)

## Modules

- Supervision
  - [Bluez](Bluez.md): Brings up the Linux BlueZ stack — `dbus-daemon`, `bluetoothd`, and
(optionally) bluez-alsa — under one supervisor, with Elixir clients for
BLE scanning (`Bluez.Client`), active GATT connections (`Bluez.Gatt`),
pairing (`Bluez.Agent`), and A2DP audio PCM discovery (`Bluez.BlueAlsa`).
  - [Bluez.BusReady](Bluez.BusReady.md): A supervised gate that blocks in `init/1` until the D-Bus system-bus socket
exists, so the next `:rest_for_one` sibling (`bluetoothd`) never starts
before `dbus-daemon` is listening. Stays alive afterwards as an idle
GenServer so `:rest_for_one` re-runs it whenever `dbus-daemon` restarts.

- Vendored D-Bus client
  - [Bluez.Rebus](Bluez.Rebus.md): An Elixir implementation of the D-Bus message protocol.
  - [Bluez.Rebus.Decoder](Bluez.Rebus.Decoder.md): D-Bus message decoder that unmarshals data according to D-Bus wire format.
  - [Bluez.Rebus.Encoder](Bluez.Rebus.Encoder.md): D-Bus message encoder that marshals data according to D-Bus wire format.
  - [Bluez.Rebus.Message](Bluez.Rebus.Message.md): D-Bus message protocol implementation.

- Scanning
  - [Bluez.Advert](Bluez.Advert.md): Reconstructs a BLE advertisement (the verbatim-ish AD byte structure plus
the fields an ESPHome-style scanner host needs) from BlueZ's *parsed* device
properties.
  - [Bluez.Client](Bluez.Client.md): Persistent `rebus` D-Bus client + service to `org.bluez`, driving BLE
scanning and turning device signals into advertisements, fanned out
through the `on_advertisement:` fun.
  - [Bluez.DeviceCache](Bluez.DeviceCache.md): Pure per-device advertisement cache with emit-gating and a bounded size.
No I/O — `Bluez.Client` owns the side effects (it emits the
adverts this module returns).

- GATT
  - [Bluez.Gatt](Bluez.Gatt.md): Active BLE connections + GATT client over BlueZ D-Bus — the engine an
ESPHome-proxy-style host puts behind its Bluetooth-proxy adapter.
  - [Bluez.Gatt.Characteristic](Bluez.Gatt.Characteristic.md): A GATT characteristic within a `Bluez.Gatt.Service`.
  - [Bluez.Gatt.Descriptor](Bluez.Gatt.Descriptor.md): A GATT descriptor within a `Bluez.Gatt.Characteristic`.
`handle` is the descriptor's own attribute handle.

  - [Bluez.Gatt.Service](Bluez.Gatt.Service.md): A GATT primary/secondary service discovered on a connected device —
the neutral shape `Bluez.GattTree` builds
and `Bluez.Gatt` emits in `{:gatt_service, address, service}`
events. Hosts translate it to their own wire shape in the `on_gatt_event:`
fun.
  - [Bluez.GattTree](Bluez.GattTree.md): Build a GATT tree from BlueZ's `GetManagedObjects` reply.

- Pairing
  - [Bluez.Agent](Bluez.Agent.md): The `org.bluez.Agent1` pairing agent backing `Bluez.Gatt`'s `pair/1`
(Phase 2 of the Bluetooth proxy).

- Audio
  - [Bluez.BlueAlsa](Bluez.BlueAlsa.md): Persistent `rebus` D-Bus client to `org.bluealsa` (the bluez-alsa
`bluealsad` daemon), used to learn which A2DP-playback PCMs are *ready to
open* right now. This is the control-plane half of the Bluetooth-headphone
audio path; the data plane is sendspin opening the ALSA PCM string directly.

- D-Bus plumbing
  - [Bluez.DBus](Bluez.DBus.md): Shared helpers for outbound D-Bus method calls to `org.bluez` over a
`rebus` connection, used by `Bluez.Client` (passive
scanning) and `Bluez.Gatt` (active connections).
  - [Bluez.DevicePath](Bluez.DevicePath.md): Convert between wire BLE addresses and BlueZ device object paths.
  - [Bluez.Variant](Bluez.Variant.md): Unwraps `org.bluez` D-Bus property maps (as decoded by `rebus`) into plain
Elixir maps for `Bluez.Advert`.