---
title: Device Pairing
description: 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

<Tabs>
  <TabItem label="Interactive (default)">
```
bt_pair adapter="hci0" address="..." pairing_mode="interactive"
```

Returns immediately with status. If confirmation needed, use `bt_pair_confirm` to respond.
  </TabItem>
  <TabItem label="Auto">
```
bt_pair adapter="hci0" address="..." pairing_mode="auto"
```

Automatically accepts all pairing requests. Use only in trusted environments.
  </TabItem>
  <TabItem label="Elicit">
```
bt_pair adapter="hci0" address="..." pairing_mode="elicit"
```

Uses MCP elicitation to prompt the user directly (if the MCP client supports it).
  </TabItem>
</Tabs>

## 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"
```

<Aside type="note">
Disconnecting preserves the pairing. The device can reconnect later.
</Aside>

## 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:
```json
{
  "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`