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

One runtime request covers the whole plugin on Android:

Mob.Permissions.request(socket, :bluetooth_connect)

It asks for what the running Android version needs:

• Android 11 and below (API ≤ 30) — ACCESS_FINE_LOCATION. The legacy BLUETOOTH / BLUETOOTH_ADMIN permissions are install-time and already granted, but classic discovery returns nothing without location.
• Android 12+ (API 31+) — the "Nearby devices" group (BLUETOOTH_SCAN, BLUETOOTH_CONNECT, BLUETOOTH_ADVERTISE) plus ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION, because discovery still needs location unless the app's manifest declares BLUETOOTH_SCAN with android:usesPermissionFlags="neverForLocation". When it does, location is not requested on API 31+ (see the README for the manifest lines).

Discovery also needs precise location: if the user picks "Approximate" the request reports :denied and start_discovery/1 fails with :location_permission_required. Pairing, profiles and advertising don't use location.

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

Background BLE is opt-in per app — by default this plugin declares no background modes (foreground only), so apps that don't need it don't ship an unused background-mode declaration (Apple rejects those at review). To enable it, two things are needed:

• Declare the mode(s) you use in your app config. Each adds the matching UIBackgroundModes entry to the host Info.plist (array-merged by mob_dev >= 0.6.16, alongside any existing entry such as audio):

  config :mob_bluetooth, ble_background_modes: [:central]              # background scanning/connecting
  config :mob_bluetooth, ble_background_modes: [:peripheral]           # background advertising
  config :mob_bluetooth, ble_background_modes: [:central, :peripheral] # both

• 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).