hcitool

Scan for Bluetooth devices

$ hcitool scan

$ hcitool name [bdaddr]

$ hcitool info [bdaddr]

$ hcitool lq [bdaddr]

$ hcitool tpl [bdaddr] [0|1]

$ hcitool lp

$ hcitool auth [bdaddr]

$ hcitool dev

hcitool [--help] [--version]
hcitool [options] command [command_options]

--help
    Displays the help message and exits.

--version
    Displays the version information and exits.

dev
    Displays information about local Bluetooth devices (HCIs).

inq
    Performs a Bluetooth inquiry to discover nearby classic Bluetooth devices.

scan
    Scans for and lists visible classic Bluetooth devices along with their names.

cc
    Creates a classic Bluetooth connection to the specified device address (BD_ADDR).

dc
    Disconnects an existing classic Bluetooth connection from the specified device address.

cmd [parameters...]
    Sends an arbitrary HCI command to the controller. OGF (Opcode Group Field) and OCF (Opcode Command Field) define the command. Parameters are optional and specific to the command's requirements.

lecc [type]
    Creates a Bluetooth Low Energy (LE) connection to the specified device address. Type specifies the address type (public or random).

ledc
    Disconnects an existing Bluetooth Low Energy (LE) connection using its connection handle.

lescan [type]
    Starts or stops an LE scan. Optionally specifies the scan type (active or passive).

hcitool is a command-line utility that provides a way to interact with Bluetooth Host Controller Interface (HCI) devices. It is part of the BlueZ Bluetooth protocol stack for Linux. This tool allows users to perform various low-level Bluetooth operations, such as querying local Bluetooth devices, scanning for remote devices, establishing and terminating connections, and sending raw HCI commands. hcitool is particularly useful for diagnostics, debugging, and advanced configuration of Bluetooth hardware and connections, providing more granular control than higher-level tools.

While modern Linux distributions often recommend bluetoothctl for general Bluetooth management due to its more user-friendly interface, hcitool remains indispensable for specific tasks requiring direct interaction with the HCI layer, especially for Bluetooth Low Energy (LE) operations and sending custom commands.

hcitool typically requires root privileges (e.g., using sudo) to perform most of its operations, especially those that modify device configuration or establish connections.

Many of its functionalities, particularly for general Bluetooth management, have been largely superseded by the more user-friendly bluetoothctl command-line tool, which is part of the modern BlueZ suite. While hcitool offers granular control at the HCI layer, it may not support all the latest Bluetooth profiles or features as comprehensively as higher-level tools or daemon services.

The cmd subcommand in hcitool is exceptionally powerful, allowing users to send arbitrary HCI commands directly to the Bluetooth controller. This requires a deep understanding of the Bluetooth HCI specification (Bluetooth Core Specification), including Opcode Group Fields (OGF) and Opcode Command Fields (OCF), and the specific parameters required for each command. It's primarily used for advanced debugging, testing, and custom controller interactions.

hcitool provides a suite of commands prefixed with "le" (e.g., lescan, lecc) specifically for interacting with Bluetooth Low Energy devices. These commands are essential for developers and testers working with LE-enabled hardware and applications, offering granular control over LE scanning, advertising, and connection parameters.

hcitool has been a fundamental part of the BlueZ Bluetooth stack for Linux since its early days. It emerged as one of the primary command-line tools for direct interaction with Bluetooth Host Controller Interface devices. Before the advent of more abstract and user-friendly tools like bluetoothctl, hcitool (along with hciconfig) was the go-to utility for Bluetooth device management, diagnostics, and development. Its longevity attests to its utility in providing low-level access, even as high-level management shifted to other tools. While its direct interactive use for everyday tasks has diminished, it remains crucial for scripting, automated testing, and deep-dive troubleshooting at the HCI layer.

bluetoothctl(1) - Modern interactive Bluetooth control utility., hciconfig(8) - Configures Bluetooth HCI devices., rfkill(8) - Enables or disables wireless devices., sdptool(1) - Manages Bluetooth Service Discovery Protocol (SDP) records.