hciattach

hciattach [-n] [-p] [-b baud_rate] [-t timeout] [-l] [-r] [-s initial_speed] [-f] [-e] [-c channel] [-i] [-m] [-d] [-v] device type [speed] [flow_control]

device
    The serial port device file to be used (e.g., /dev/ttyS0, /dev/ttyUSB0).

type
    The type of Bluetooth chip. Common types include any (autodetect), broadcom, csr, texas, intel, marvell, atheros, st, cc256x.

speed
    The primary baud rate to set the serial port to (e.g., 115200). This is the communication speed after initialization.

flow_control
    An optional argument to specify flow control, typically flow for hardware flow control or noflow to disable it.

-n
    
No flow control. Disables RTS/CTS hardware flow control explicitly.

-p
    
Pick PTS baud rate. Selects a baud rate commonly used for PTS (Protocol Testing System) testing.

-b baud_rate
    
Reset baud rate. Specifies an alternative baud rate that is used during the device's reset sequence.

-t timeout
    
Initialization timeout. Sets a timeout in seconds for the device initialization process. If the device doesn't respond within this time, hciattach will abort.

-l
    
Log to syslog. Redirects all output and error messages from hciattach to the system log (syslog).

-r
    
Hardware reset. Attempts to perform a hardware reset on the device before beginning the initialization process.

-s initial_speed
    
Initial speed. Sets an initial baud rate for devices that require speed negotiation or a lower speed for initial communication.

-f
    
Force reset. Forces a reset attempt even if the device times out during initialization.

-e
    
Exit on error. The command will terminate immediately if any error occurs during operation.

-c channel
    
BCSP channel. Specifies the BCSP (Bluetooth Serial Protocol) channel number, typically used with CSR (Cambridge Silicon Radio) devices.

-i
    
Intel initialization. Activates specific initialization routines designed for Intel Bluetooth devices.

-m
    
Marvell initialization. Activates specific initialization routines designed for Marvell Bluetooth devices.

-d
    
Debug mode. Enables verbose debugging output to assist in troubleshooting.

-v
    
Version information. Displays the hciattach version and exits.

hciattach is a Linux command-line utility used to initialize and attach serial-port-based Bluetooth devices to the Linux Bluetooth subsystem (BlueZ). It configures the specified serial port (e.g., /dev/ttyUSB0 or /dev/ttyS0) to communicate with a Bluetooth host controller. This process typically involves setting the correct baud rate, applying flow control settings, and uploading necessary firmware or initialization scripts specific to the Bluetooth chip type (e.g., Broadcom, CSR, Texas Instruments, Intel). Once hciattach successfully completes, the serial device becomes a recognized HCI (Host Controller Interface) device, accessible via tools like hciconfig or hcitool, allowing Bluetooth communication to commence. It bridges the gap between the physical serial connection and the software Bluetooth stack.

hciattach typically requires root privileges to access serial ports and configure the Bluetooth stack. Selecting the incorrect type argument can prevent the device from initializing correctly, often due to a failure in uploading the proper firmware. For certain chipsets, the required firmware files must be present in specific system directories (e.g., /lib/firmware/brcm). Services like ModemManager might interfere with serial port access and may need to be disabled. Debugging usually involves checking serial port permissions, cable connections, and system logs (dmesg, syslog) for detailed error messages.

Many Bluetooth chipsets require specific firmware to be loaded onto them after power-on for proper operation. hciattach is frequently responsible for this task, reading firmware files (e.g., .hcd files for Broadcom devices) from system paths like /lib/firmware/brcm based on the specified chip type. If the correct firmware is not found or successfully loaded, the device may fail to appear as an HCI device or function erratically.

For automatic initialization of Bluetooth devices upon system boot, hciattach commands are typically integrated into system startup configurations. This can involve adding entries to files like /etc/rc.local (on older systems) or, more commonly in modern Linux distributions, creating custom systemd service units that execute the hciattach command during the boot process, ensuring the Bluetooth device is always ready for use.

hciattach is an integral part of the BlueZ project, which serves as the official Bluetooth protocol stack for Linux. Its development emerged from the necessity to standardize the setup of serial-based Bluetooth host controllers, commonly found in embedded systems, older hardware, or when using external USB-to-serial Bluetooth dongles. The command has evolved over time to support a wider array of Bluetooth chipsets, each often requiring unique initialization sequences and firmware uploads to integrate seamlessly with the Linux HCI stack.

hciconfig(8), hcitool(1), rfkill(8), dmesg(1), bluetoothd(8)