How to use the command 'bluetoothctl' (with examples)

The bluetoothctl command is a powerful tool used to manage Bluetooth devices directly from the command line. This utility provides a convenient shell-like interface that allows users to handle various Bluetooth tasks without the need for a graphical interface. Whether you are pairing new devices, connecting or disconnecting peripherals, or simply managing known devices, bluetoothctl simplifies these processes significantly. It’s especially useful in environments where a graphical interface is unavailable or inconvenient to use.

Use case 1: Enter the bluetoothctl shell

Code:

bluetoothctl

Motivation:

Entering the bluetoothctl shell is the first step for users who want to interactively manage Bluetooth devices. This shell-like interface offers a comprehensive environment for executing Bluetooth commands and managing devices in real time, all from within a single dedicated session.

Explanation:

• bluetoothctl: The command itself launches the interactive shell where users can execute further Bluetooth management commands. It functions similarly to a terminal, allowing multiple commands to be executed in sequence without returning to the main shell environment.

Example Output:

[bluetooth]#

Upon entering the shell, the prompt changes to [bluetooth]#, indicating that the user is now in the Bluetooth control environment and ready to issue further commands.

Use case 2: List all known devices

Code:

bluetoothctl devices

Motivation:

Listing all known devices helps users quickly identify which devices have been previously paired with the system. This is particularly useful in confirming connections, troubleshooting device issues, or managing a list of trusted devices.

Explanation:

• bluetoothctl: Launches the Bluetooth command-line tool.
• devices: A sub-command used within bluetoothctl to list all previously known Bluetooth devices along with their MAC addresses and friendly names.

Example Output:

Device 00:1A:7D:DA:71:13 Headset
Device 00:21:54:AA:C1:2B Keyboard

The output provides a list of known devices, showing each device’s MAC address followed by its name, helping users identify them easily.

Use case 3: Power the Bluetooth controller on or off

Code:

bluetoothctl power on
# or
bluetoothctl power off

Motivation:

Controlling the power state of the Bluetooth controller is essential for conserving battery life in portable devices or managing security settings by preventing unauthorized Bluetooth connections. Toggling the controller’s power is a primary step in initializing or terminating Bluetooth activities.

Explanation:

• bluetoothctl: The main tool for executing Bluetooth commands.
• power: The command to alter the power state of the Bluetooth controller.
• on|off: The desired power state. on will turn the Bluetooth controller’s power on, enabling Bluetooth functionalities, while off will disable it, preventing any Bluetooth activity.

Example Output:

Changing power on succeeded

This output acknowledges the successful execution of the command, indicating the Bluetooth controller is either powered on or off depending on the given argument.

Use case 4: Pair with a device

Code:

bluetoothctl pair 00:1A:7D:DA:71:13

Motivation:

Pairing with a device is a fundamental step to establish a secure and trusted connection between the host system and the Bluetooth device. Without pairing, interactions with many Bluetooth devices would not be possible due to security protocols that require authentication before connection.

Explanation:

• bluetoothctl: Opens the command-line utility for managing Bluetooth devices.
• pair: Initiates the process to pair the device with the specified MAC address.
• 00:1A:7D:DA:71:13: The MAC address of the Bluetooth device to be paired. This address uniquely identifies the device within the Bluetooth network.

Example Output:

Attempting to pair with 00:1A:7D:DA:71:13
Pairing successful

Upon successful pairing, the user receives confirmation that the process completed without errors, establishing a trusted connection between the devices.

Use case 5: Remove a device

Code:

bluetoothctl remove 00:1A:7D:DA:71:13

Motivation:

Removing a device is necessary when cleaning up a list of known devices, particularly for devices that are no longer in use or trusted. This action also enhances security by minimizing the number of devices with which the host can inadvertently connect.

Explanation:

• bluetoothctl: Begins the Bluetooth command-line interface.
• remove: Specifies the command to remove a device from the list of known devices.
• 00:1A:7D:DA:71:13: The MAC address of the device intended for removal from the known devices list.

Example Output:

Removing device 00:1A:7D:DA:71:13
Device has been removed

This signifies that the specified device was successfully removed and will no longer be recognized as a known device by the Bluetooth controller.

Use case 6: Connect to a paired device

Code:

bluetoothctl connect 00:1A:7D:DA:71:13

Motivation:

Connecting to a paired device is often necessary for interaction or communication, such as streaming audio to a headset or transferring files to a Bluetooth-enabled device. Establishing a connection facilitates data exchange between the host and the paired device.

Explanation:

• bluetoothctl: Initiates the tool for executing Bluetooth commands.
• connect: Instructs the Bluetooth controller to establish a connection with the paired device.
• 00:1A:7D:DA:71:13: The MAC address of the previously-paired device that you wish to connect to.

Example Output:

Connection successful

This message indicates that the connection was made successfully, and the device is ready for interaction as needed.

Use case 7: Disconnect from a paired device

Code:

bluetoothctl disconnect 00:1A:7D:DA:71:13

Motivation:

Disconnecting from a device is required when you wish to terminate the interaction, either to switch to a different device or to conserve resources such as battery life. This helps in managing active connections and maintaining optimal performance of the Bluetooth subsystem.

Explanation:

• bluetoothctl: Calls the command-line utility for managing Bluetooth operations.
• disconnect: Orders the Bluetooth controller to sever the ongoing connection with the device.
• 00:1A:7D:DA:71:13: The unique MAC address of the device that is currently connected and needs to be disconnected.

Example Output:

Successful disconnected

This output denotes that the device was successfully disconnected, halting any ongoing communication between the two devices.

Use case 8: Display help

Code:

bluetoothctl help

Motivation:

Displaying help information is useful for new users or anyone needing a refresher on the available commands in bluetoothctl. It provides guidance and useful details about the various operations that can be performed, which is especially helpful when managing complex device interactions without a graphical user interface.

Explanation:

• bluetoothctl: Starts the command-line utility for Bluetooth.
• help: A command to display a list of all possible commands and their descriptions within the tool, serving as documentation for reference.

Example Output:

Available commands:
  list                       List available controllers
  show [ctrl]                Controller information
  devices                    List available devices
  pairable [on/off]          Set controller pairable mode
  discoverable [on/off]      Set controller discoverable mode
  ...

The output consists of a comprehensive list of commands, providing users with insights into functionalities available through bluetoothctl.

Conclusion:

Understanding how to use the bluetoothctl command with these examples equips users with the capability to efficiently manage Bluetooth devices via the command line. With the capability to pair, connect, disconnect, and execute various other operations, handling Bluetooth peripherals has never been simpler or more effective for users operating in non-graphical environments. These use cases offer a fundamental understanding, enabling users to leverage this utility for both basic and advanced Bluetooth functionalities.