hciattach

hciattach [options] tty baudrate protocol [parameters]

-n, --nounit
    Do not use BlueZ kernel HCI device layer (debug only).

-s, --setbaud speed
    Set baudrate to speed after attachment.

-P, --protocol proto
    Use specific protocol proto (e.g., h4, bcsp).

-b, --baud
    Enable baudrate changing procedure.

-p, --param param
    Pass param to protocol initialization.

-l, --length len
    Set H4 packet header length to len.

-r, --rts-cts
    Enable RTS/CTS hardware flow control.

-m, --mode mode
    Set protocol mode (0=slave, 1=master).

-t, --timeout timeout
    Set initialization timeout in seconds.

-d, --debug
    Enable debug output.

-q, --quiet
    Suppress standard output.

-v, --verbose
    Increase verbosity.

-V, --version
    Print version and exit.

-h, --help
    Print help and exit.

The hciattach command is a utility from the BlueZ Bluetooth protocol stack for Linux. It attaches serial (UART) connected Bluetooth devices to the kernel's HCI (Host Controller Interface) layer, enabling them as standard /dev/hciX devices.

This is essential for initializing Bluetooth controllers on embedded systems, Raspberry Pi, or any setup where the Bluetooth chip communicates over a serial port. hciattach programs the serial port parameters, detects or sets the transport protocol (e.g., H4, BCSP), handles baud rate negotiation, and performs firmware loading or initialization sequences specific to the protocol.

Once attached, the device appears in hciconfig output and can be managed like any Bluetooth adapter. It supports common protocols like H4 (default UART), Three-wire (BCSP), and vendor-specific ones like Atheros ath3k. The command runs as root and detaches on exit unless specified otherwise.

Primarily used in headless or custom Bluetooth setups, it's less common on desktops where USB dongles or integrated controllers use built-in drivers.

Requires root privileges.
May conflict with ModemManager.
Deprecated for some modern chips; use kernel drivers or brltty alternatives where possible.
Detaches on SIGINT; use -n for persistent attachment.

h4 (standard UART), bcsp (3-wire), ath3k (Atheros), h5 (3-wire HDLC), ll (Linux Ldisc), ppp (PPP). Use any for auto-detect.

hciattach /dev/ttyUSB0 115200 any
Attaches USB-serial Bluetooth at 115200 baud with auto protocol.

Introduced in early BlueZ (Linux Bluetooth stack) around 2002 by Marcel Holtmann. Evolved with protocol support (H4 in v1, BCSP v2.x). Maintained in BlueZ 5.x but less central as kernel modules improved.

hciconfig(1), hcitool(1), bluetoothctl(1), rfkill(8), stty(1)