Adapter Management

import { Aside } from ‘@astrojs/starlight/components’;

Bluetooth adapters are the hardware interfaces that enable wireless communication. mcbluetooth provides full control over adapter configuration.

List Adapters

bt_list_adapters

Returns all Bluetooth adapters with their current state:

[
  {
    "name": "hci0",
    "address": "AA:BB:CC:DD:EE:FF",
    "alias": "My Laptop",
    "powered": true,
    "discoverable": false,
    "discoverable_timeout": 180,
    "pairable": true,
    "pairable_timeout": 0,
    "discovering": false
  }
]

Get Adapter Details

bt_adapter_info adapter="hci0"

Returns detailed information including supported features and UUIDs.

Power Control

Turn Bluetooth On

bt_adapter_power adapter="hci0" on=true

Turn Bluetooth Off

bt_adapter_power adapter="hci0" on=false

Discovery Settings

Make Discoverable

Allow other devices to see your computer:

bt_adapter_discoverable adapter="hci0" on=true timeout=180

timeout=0 means discoverable forever (use carefully)
timeout=180 means 3 minutes (default)

Stop Being Discoverable

bt_adapter_discoverable adapter="hci0" on=false

Pairing Acceptance

Enable Pairing

Allow devices to pair with your computer:

bt_adapter_pairable adapter="hci0" on=true timeout=0

Disable Pairing

bt_adapter_pairable adapter="hci0" on=false

Set Adapter Name

Change the friendly name other devices see:

bt_adapter_set_alias adapter="hci0" alias="Ryan's Desktop"

Common Workflows

Prepare for Incoming Connection

When you want another device to find and connect to your computer:

# Make discoverable and pairable
bt_adapter_discoverable adapter="hci0" on=true timeout=300
bt_adapter_pairable adapter="hci0" on=true timeout=300

This opens a 5-minute window for pairing.

Secure Configuration

For everyday use with known devices:

# Hidden but accepting connections from paired devices
bt_adapter_discoverable adapter="hci0" on=false
bt_adapter_pairable adapter="hci0" on=false

Adapter Properties Reference

Property	Description
`name`	System name (e.g., `hci0`)
`address`	MAC address
`alias`	Friendly name
`powered`	On/off state
`discoverable`	Visible to other devices
`discoverable_timeout`	Seconds until auto-hidden (0=forever)
`pairable`	Accepting new pairings
`pairable_timeout`	Seconds until auto-disable (0=forever)
`discovering`	Currently scanning
`uuids`	Supported Bluetooth profiles
`modalias`	Hardware identifier

Multiple Adapters

If you have multiple Bluetooth adapters (e.g., built-in + USB dongle):

# List all adapters
bt_list_adapters

# Configure each separately
bt_adapter_power adapter="hci0" on=true
bt_adapter_power adapter="hci1" on=false

Troubleshooting

Adapter Not Found

Check if the kernel sees your hardware:

# List USB Bluetooth devices
lsusb | grep -i bluetooth

# Check kernel messages
dmesg | grep -i bluetooth

# Verify btusb module is loaded
lsmod | grep btusb

Adapter Won’t Power On

BlueZ might be blocked by rfkill:

# Check rfkill status
rfkill list bluetooth

# Unblock if blocked
rfkill unblock bluetooth

Discovery Stops Unexpectedly

Discovery has a default timeout. For continuous scanning:

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

The bt_scan tool handles starting and stopping discovery automatically.