hciconfig

hciconfig [-a] [hciX] [command ...]

hciX
    Specifies the Bluetooth device to configure (e.g., hci0, hci1). If omitted, hciconfig typically operates on the first available device or lists all devices if no command is given.

-a
    When used without a command, displays all available information for all configured Bluetooth devices, including extended statistics.

up
    Activates the specified Bluetooth device, making it ready for connections and scans.

down
    Deactivates the specified Bluetooth device, taking it offline and preventing connections.

reset
    Resets the specified Bluetooth device to its default state, often used to resolve communication issues.

rstat
    Displays run-time statistics for the specified Bluetooth device, such as transmitted and received packets, and error counts.

nstat
    Resets the run-time statistics for the specified Bluetooth device to zero.

pscan
    Enables page scan mode, allowing the device to be discoverable and connectable by other Bluetooth devices.

iscan
    Enables inquiry scan mode, allowing the device to respond to inquiries from other Bluetooth devices, making it discoverable.

noscan
    Disables both page and inquiry scan modes, making the device undetectable and unconnectable by other Bluetooth devices (unless already paired).

lm [mode]
    Sets or displays the link mode. Common modes include auth (authentication), encrypt (encryption), sauth (secure authentication), sencrypt (secure encryption).

lp [policy]
    Sets or displays the link policy. Policies include master/slave switch, hold, sniff, and park modes for power management and connection efficiency.

name [name]
    Sets or displays the local human-readable name of the Bluetooth device. If name is omitted, the current name is displayed.

class [class]
    Sets or displays the Class of Device (CoD) for the Bluetooth adapter. CoD is a 24-bit value that describes the primary service class, major device class, and minor device class.

auth
    Enables authentication for new connections, requiring pairing or passkey exchange.

noauth
    Disables authentication, allowing connections without pairing requirements (less secure).

encrypt
    Enables encryption for new connections, securing data transfer.

noencrypt
    Disables encryption for new connections (less secure).

leadv [type]
    Configures LE (Low Energy) advertising type for the device.

leadvdata [data]
    Sets LE advertising data, which is broadcasted to other LE devices.

lescan
    Enables LE (Low Energy) scanning mode, allowing the device to discover other LE devices.

nolescan
    Disables LE (Low Energy) scanning mode.

hciconfig is a command-line utility used to configure Bluetooth High-Level Interface (HCI) devices on Linux systems. It allows administrators to manage various aspects of Bluetooth adapters, including bringing them up or down, changing local device addresses, setting scan modes (inquiry and page scan), enabling or disabling authentication and encryption, and managing device class settings. It provides direct control over the HCI layer, making it invaluable for advanced Bluetooth configurations, scripting automated tasks, and debugging Bluetooth connectivity issues. While newer tools like bluetoothctl offer more user-friendly interaction for common tasks, hciconfig remains a powerful tool for low-level device management and detailed status retrieval.

Many hciconfig commands that modify device parameters require root privileges (or execution via sudo).

While powerful, hciconfig operates at a low-level HCI interface and might not be the most straightforward tool for common user tasks. For general Bluetooth management and pairing, bluetoothctl is often preferred due to its interactive and user-friendly interface.

Some modern Bluetooth features or device-specific settings might not be fully controllable via hciconfig, depending on the kernel and BlueZ version.

To modify the settings of a Bluetooth device using hciconfig, you must have root privileges. Running commands like hciconfig hci0 up will require sudo. However, checking the status of devices (e.g., hciconfig or hciconfig -a) typically does not require elevated privileges.

Bluetooth devices on Linux are typically named hci0, hci1, and so forth, similar to network interfaces (eth0, wlan0). The first detected Bluetooth adapter is usually hci0. You can see a list of available devices by simply running hciconfig without any arguments.

hciconfig has been a fundamental part of the BlueZ Bluetooth protocol stack for Linux since its early development. It was one of the primary tools for system administrators to interact with and configure Bluetooth hardware before more advanced and user-friendly interfaces like bluetoothctl became prevalent. Its design reflects a direct interface to the HCI (Host Controller Interface) layer, providing fine-grained control over Bluetooth adapters. Although its direct usage by end-users has decreased in favor of higher-level tools, it remains crucial for scripting, debugging, and managing low-level Bluetooth device properties on Linux.

bluetoothctl(1), hcitool(1), rfkill(8), hcidump(1)