LinuxCommandLibrary

hcitool

Configure and manage Bluetooth connections

TLDR

Scan for Bluetooth devices

$ hcitool scan
copy

Output the name of a device, returning its MAC address
$ hcitool name [bdaddr]
copy

Fetch information about a remote Bluetooth device
$ hcitool info [bdaddr]
copy

Check the link quality to a Bluetooth device
$ hcitool lq [bdaddr]
copy

Modify the transmit power level
$ hcitool tpl [bdaddr] [0|1]
copy

Display the link policy
$ hcitool lp
copy

Request authentication with a specific device
$ hcitool auth [bdaddr]
copy

Display local devices
$ hcitool dev
copy

SYNOPSIS

hcitool [options]

PARAMETERS

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.

SEE ALSO

Copied to clipboard