mcbluetooth/docs-site/src/content/docs/guides/pairing.md

title	description
Device Pairing	Pair Bluetooth devices with automatic PIN and passkey handling

import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';

Pairing establishes a trusted relationship between devices, enabling secure communication. mcbluetooth includes a smart pairing agent that handles all Bluetooth pairing methods.

Scanning for Devices

Before pairing, discover available devices:

bt_scan adapter="hci0" timeout=10 mode="both"

Scan modes:

• classic — Traditional Bluetooth (BR/EDR)
• ble — Bluetooth Low Energy only
• both — Both types (default)

Initiating Pairing

Basic Pairing

bt_pair adapter="hci0" address="AA:BB:CC:DD:EE:FF"

Pairing Modes

``` bt_pair adapter="hci0" address="..." pairing_mode="interactive" ```

Returns immediately with status. If confirmation needed, use bt_pair_confirm to respond.

bt_pair adapter="hci0" address="..." pairing_mode="auto"

Automatically accepts all pairing requests. Use only in trusted environments.

bt_pair adapter="hci0" address="..." pairing_mode="elicit"

Uses MCP elicitation to prompt the user directly (if the MCP client supports it).

Pairing Methods

Bluetooth uses different pairing methods based on device capabilities:

Method	Description	Agent Action
Just Works	No user interaction	Auto-accepted
Numeric Comparison	Confirm 6-digit code matches	Show code, await confirmation
Passkey Entry	Enter code shown on other device	Prompt for passkey
Legacy PIN	Enter 4-6 digit PIN	Prompt for PIN

Handling Confirmation Requests

When pairing requires confirmation:

# Check for pending requests
bt_pairing_status

# Confirm with passkey (if needed)
bt_pair_confirm adapter="hci0" address="..." passkey=123456 accept=true

# Or reject
bt_pair_confirm adapter="hci0" address="..." accept=false

Managing Paired Devices

List Paired Devices

bt_list_devices adapter="hci0" filter="paired"

Remove Pairing

bt_unpair adapter="hci0" address="AA:BB:CC:DD:EE:FF"

This removes the device from known devices and deletes all pairing information.

Connection Management

Connect to Paired Device

bt_connect adapter="hci0" address="AA:BB:CC:DD:EE:FF"

Disconnect

bt_disconnect adapter="hci0" address="AA:BB:CC:DD:EE:FF"

Disconnecting preserves the pairing. The device can reconnect later.

Trust and Security

Trust a Device

Trusted devices can connect automatically without explicit authorization:

bt_trust adapter="hci0" address="..." trusted=true

Untrust

bt_trust adapter="hci0" address="..." trusted=false

Block a Device

Prevent a device from connecting:

bt_block adapter="hci0" address="..." blocked=true

Unblock

bt_block adapter="hci0" address="..." blocked=false

Device Information

Get Device Details

bt_device_info adapter="hci0" address="AA:BB:CC:DD:EE:FF"

Returns:

{
  "address": "AA:BB:CC:DD:EE:FF",
  "name": "Bose NCH700",
  "alias": "My Headphones",
  "paired": true,
  "bonded": true,
  "trusted": true,
  "connected": true,
  "uuids": ["0000110b-...", "0000110e-..."],
  ...
}

Set Device Name

bt_device_set_alias adapter="hci0" address="..." alias="My Headphones"

Common Workflows

Pair New Headphones

# Put headphones in pairing mode first!

# Scan for them
bt_scan adapter="hci0" timeout=15

# Pair
bt_pair adapter="hci0" address="C8:7B:23:55:68:E8"

# Trust for auto-reconnect
bt_trust adapter="hci0" address="C8:7B:23:55:68:E8" trusted=true

# Connect
bt_connect adapter="hci0" address="C8:7B:23:55:68:E8"

Pair a Phone for OBEX

# Scan and pair
bt_scan adapter="hci0"
bt_pair adapter="hci0" address="AA:BB:CC:DD:EE:FF"

# Both devices may show confirmation prompts - accept on both

# After pairing, OBEX profiles become available
bt_obex_status

Troubleshooting

Pairing Fails Immediately

• Ensure the device is in pairing mode
• Check device isn't already paired (try bt_unpair first)
• Verify adapter is powered and pairable

"Authentication Rejected"

• Device may have reached its pairing limit
• Try resetting Bluetooth on the other device
• Delete the pairing on both sides and retry

Pairing Stuck

# Check for pending requests
bt_pairing_status

# Cancel if stuck
bt_pair_confirm adapter="hci0" address="..." accept=false

Device Connects Then Disconnects

• Profile incompatibility (e.g., device doesn't support expected audio profile)
• Check device UUIDs with bt_device_info
• Try connecting specific profile with bt_connect_profile