hcitool

Configure and manage Bluetooth connections

TLDR

Scan for Bluetooth devices

$ hcitool scan

Output the name of a device, returning its MAC address

$ hcitool name [bdaddr]

Fetch information about a remote Bluetooth device

$ hcitool info [bdaddr]

Check the link quality to a Bluetooth device

$ hcitool lq [bdaddr]

Modify the transmit power level

$ hcitool tpl [bdaddr] [0|1]

Display the link policy

$ hcitool lp

Request authentication with a specific device

$ hcitool auth [bdaddr]

Display local devices

$ hcitool dev

dev
    Select device to use.

inq
    Inquire remote devices.

scan
    Scan for remote devices.

name
    Get name from remote device.

info
    Get information from remote device.

spinq
    Start periodic inquiry.

cmd [parameters]
    Send command to device.

con
    Create ACL connection.

dc
    Disconnect from device.

sr
    Switch role.

auth
    Authenticate device.

enc
    Enable encryption.

key
    Change connection key.

clock
    Get clock offset.

cclock
    Get corrected clock offset.

rssi
    Get signal strength.

lq
    Get link quality.

tpl
    Get transmit power level.

afh
    Get AFH channel map.

vers
    Get version information.

features
    Get features.

version
    Show version.

help
    Show help text.

DESCRIPTION

The hcitool command is a command-line utility used in Linux systems to configure Bluetooth connections.

It is a part of the bluez package, the official Linux Bluetooth protocol stack.

hcitool allows users to scan for Bluetooth devices, inquire about device information, establish connections, and perform other low-level Bluetooth operations.

It's useful for debugging Bluetooth issues, testing Bluetooth hardware, or automating Bluetooth tasks.

It interacts directly with the Bluetooth HCI (Host Controller Interface) layer. The command requires root privileges for most operations, reflecting the system-level control it provides over Bluetooth hardware.

CAVEATS

Requires root privileges for most operations.

Bluetooth device must be present and active.

RETURN VALUES

Returns 0 on success and 1 on failure.

HISTORY

hcitool has been a long-standing utility within the BlueZ Bluetooth stack for Linux. It predates the bluetoothctl utility.

Initially, it served as the primary tool for managing Bluetooth devices from the command line, offering low-level control over HCI operations.

Over time, as BlueZ evolved, more user-friendly tools like bluetoothctl emerged, providing a higher-level interface. However, hcitool remains valuable for advanced users and developers who need direct access to the HCI layer.