Bluetooth Classic (BR/EDR) — device-level discovery, pairing, and cross-profile session management.

Profile-specific operations live in submodules:

• MobBluetooth.Hfp — Hands-Free Profile (audio + vendor AT commands). Use this for headsets, PTT-equipped earpieces, etc.
• MobBluetooth.Spp — Serial Port Profile (RFCOMM byte streams). Use this for legacy serial-over-Bluetooth devices (Arduino HC-05, OBD-II readers, marine GPS, industrial sensors).

(HID is not supported on Android — receiving HID input requires input-method/HID-host privileges Android denies ordinary apps.)

API style

Same as the rest of Mob: callbacks return socket unchanged, results arrive in handle_info/2 as messages. There are two families, and they do not share a uniform arity:

Device-level events are tagged :bt and carry no session id:

{:bt, :discovery_started}                  # 2-tuple, no payload
{:bt, :discovery_finished}
{:bt, :discovery_cancelled}
{:bt, :discovered, device}                 # 3-tuple, device map
{:bt, :paired, device}
{:bt, :pair_failed, %{address: addr, reason: atom}}
{:bt, :unpaired, device}
{:bt, :paired_list, [device]}
{:bt, :error, payload}

Profile events are tagged by profile (:bt_hfp, :bt_spp) — not :bt. Once a session exists they carry its integer session_id as the third element; pre-session failures omit it:

{:bt_hfp, :connected, session_id, payload}     # 4-tuple, has session
{:bt_hfp, :connect_failed, %{address: addr, reason: atom}}  # 3-tuple, no session yet
{:bt_hfp, :disconnected, session_id, reason}

The profile submodules document their own event sets.

Permissions

Bluetooth requires runtime permissions on Android 12+ (API 31+):

• :bluetooth_scan — for start_discovery/1
• :bluetooth_connect — for pair/2, connect/*, disconnect/2

Request via Mob.Permissions.request/2 before calling MobBluetooth functions.

iOS

Bluetooth Classic on iOS requires Apple's MFi (Made for iPhone) certification — a paid, NDA-gated program — so the classic surface above (discovery, pairing, HFP, SPP) is Android-only: those functions return {:error, :unsupported} synchronously on iOS.

iOS does expose BLE through CoreBluetooth, a separate, parallel protocol (a classic headset won't appear in a BLE scan, and vice versa). The ble_* functions — ble_scan/1, ble_stop_scan/1, ble_advertise/2, ble_stop_advertise/1 — are iOS-only (they return {:error, :unsupported} on Android, which has no BLE surface in this plugin yet) and need a real radio, so they do nothing on the iOS Simulator.

Background BLE

For BLE to keep running while the app is backgrounded, two things are needed (both shipped here):

• The app's Info.plist must declare UIBackgroundModes bluetooth-central (scanning/connecting) and/or bluetooth-peripheral (advertising). This plugin's manifest contributes both; mob_dev >= 0.6.16 merges them into the host Info.plist (alongside any existing entry such as audio).
• Background scanning requires a :service_uuids filter — ble_scan(socket, service_uuids: ["180D"]). iOS silently drops an unfiltered scan once backgrounded, so a foreground-style ble_scan(socket) will not deliver in the background.

iOS heavily throttles background BLE: scans are coalesced and de-duplicated (no repeat advertisement callbacks, slower RSSI), and background advertising drops the local name and moves service UUIDs to an overflow area only other iOS devices scanning for them can see. This is normal CoreBluetooth behaviour, not a plugin limitation. (Do not reach for the mob_background audio keep-alive for BLE — the dedicated background modes above are the Apple-blessed, review-safe path.)

Pairing flow

Two pairing modes, auto-selected by whether :pin is given:

# System UI flow — Android shows a system pairing dialog
socket = MobBluetooth.pair(socket, device)

# Programmatic — PIN supplied via API, no UI
socket = MobBluetooth.pair(socket, device, pin: "0000")

If the programmatic PIN fails or the device requires UI confirmation (e.g. numeric comparison), Android falls back to the system UI automatically.

Disconnect

One canonical disconnect for any profile session:

MobBluetooth.disconnect(socket, session_id)

The framework looks up which profile owns the session_id and routes to the right profile-disconnect internally. Emits a profile-specific disconnect event ({:bt_hfp, :disconnected, session_id, reason} etc).