bluetoothctl guide

bluetoothctl_guide.md

Guide to Connecting to a Bluetooth Device using bluetoothctl

This guide walks you through the process of connecting to a Bluetooth device on a Linux system using the bluetoothctl command-line tool. It covers initial setup, scanning, pairing, and connecting procedures, along with troubleshooting tips.

Prerequisites

• A Linux distribution with Bluetooth support (e.g., Arch Linux).
• The bluez package installed, which provides bluetoothctl and related utilities.
• A working Bluetooth adapter installed on your system.
• Sudo privileges to execute commands that require root access.

---

1. Verify Bluetooth Service and Hardware

First, ensure that the Bluetooth service is running and your system recognizes the Bluetooth adapter.

a. Check Bluetooth Service Status

sudo systemctl status bluetooth

• If the service isn’t active, start it:

  sudo systemctl start bluetooth

• Enable the service on boot:

  sudo systemctl enable bluetooth

b. List Available Bluetooth Controllers

sudo bluetoothctl list

• This command should list one or more controllers. For example:

  Controller 98:83:89:D8:70:52 archlinux [default]
  

• If no controller is listed, verify hardware connections, enable Bluetooth in BIOS/UEFI, and check for necessary drivers.

c. Check for Soft/Hard Blocks

rfkill list bluetooth

• If the output shows that Bluetooth is blocked, unblock it:

  sudo rfkill unblock bluetooth

---

2. Initialize bluetoothctl and Power On the Adapter

Start the Bluetooth control tool and prepare your adapter for scanning and pairing.

a. Launch bluetoothctl

sudo bluetoothctl

You will enter the interactive prompt [bluetooth]#.

b. Select and Power On Your Controller

1. List Controllers:

   [bluetooth]# list
   

2. Select the Default Controller (if not already selected):

   [bluetooth]# select <MAC-address>
   

   Replace <MAC-address> with your controller’s MAC address, e.g., 98:83:89:D8:70:52.
3. Power On the Controller:

   [bluetooth]# power on
   

   You should see a confirmation like Changing power on succeeded.

c. Set Up Agent and Make Discoverable (Optional)

To handle pairing requests:

[bluetooth]# agent on
[bluetooth]# default-agent

Optionally, make your device discoverable:

[bluetooth]# discoverable on

---

3. Scanning for Devices

Now that your adapter is powered on, start scanning for nearby Bluetooth devices.

a. Start Scanning

[bluetooth]# scan on

• The adapter will begin scanning, and you will see output lines for every device discovered:

  [NEW] Device 7D:2B:B5:6A:02:78 Device_Name
  

b. Stop Scanning (After Finding Devices)

When you have identified the device you want:

[bluetooth]# scan off

---

4. Pairing and Connecting to a Device

With the device discovered, proceed to pair, trust, and connect.

a. List Discovered Devices

[bluetooth]# devices

• This command lists all known devices with their MAC addresses and names.

b. Select a Device

Choose the device you want to interact with:

[bluetooth]# select <Device-MAC>

Replace <Device-MAC> with the MAC address of the target device.

c. Pair with the Device

[bluetooth]# pair <Device-MAC>

• Follow any on-screen prompts. Some devices may require a PIN confirmation or acceptance.

d. Trust the Device

To allow automatic reconnections in the future:

[bluetooth]# trust <Device-MAC>

e. Connect to the Device

[bluetooth]# connect <Device-MAC>

• The device should now connect. If it’s an audio device, additional configuration for audio services (like PulseAudio or BlueALSA) may be needed.

---

5. Additional Commands and Tips

a. Get Device Information

To view details about a connected or known device:

[bluetooth]# info <Device-MAC>

b. Remove a Device

If you want to remove a paired device from the list:

[bluetooth]# remove <Device-MAC>

c. Exiting bluetoothctl

When finished:

[bluetooth]# quit

---

6. Troubleshooting

If you encounter issues during the process:

a. Check Adapter Status

Within bluetoothctl, verify adapter details:

[bluetooth]# show

• Confirm Powered: yes and appropriate discoverability settings.

b. Use hciconfig for Additional Information

hciconfig -a

• Ensure the interface (e.g., hci0) is UP and RUNNING. If not, bring it up:

  sudo hciconfig hci0 up

c. Verify System Logs for Errors

dmesg | grep -i bluetooth

• Look for driver or hardware errors.

d. Ensure System and Drivers are Up-to-Date

On Arch Linux, update your system:

sudo pacman -Syu

• Check for updated drivers or firmware for your specific Bluetooth adapter.