hciemu

hciemu [OPTION...]

-i, --index=
    Specifies the device index for the emulated controller (default: 0).

-c, --class=
    Sets the Class of Device (CoD) for the emulated controller, typically a 24-bit hexadecimal value (default: 0x000000).

-s, --speed=
    Defines the baud rate for the serial port communication used by the emulator. Relevant when not using a pseudo-terminal.

-p, --pty
    Instructs hciemu to use a pseudo-terminal (pty) for communication. When enabled, the path to the pseudo-terminal device (e.g., /dev/pts/X) is printed to standard output, which can then be used by the Bluetooth daemon (bluetoothd) or other applications as the serial port connection to the emulated device. This is the most common and flexible way to use hciemu.

-P, --pidfile=
    Writes the process ID (PID) of the hciemu instance to the specified FILE.

-u, --uuids=
    Specifies a comma-separated list of supported service UUIDs that the emulated device should advertise. These are typically 16-bit UUIDs.

-n, --nodisc
    Prevents the emulator from disconnecting upon the client closing its connection. This keeps the emulated device active.

-S, --sniff=
    Dumps all HCI traffic (commands, events, ACL data, SCO data) to the specified FILE for later analysis or debugging.

-h, --help
    Displays a help message and exits.

-v, --version
    Prints the version information of hciemu and exits.

hciemu is a utility from the BlueZ project designed to emulate a Bluetooth Host Controller Interface (HCI) device. This tool is primarily used for development and testing purposes, allowing Bluetooth host stacks (like the Linux kernel's Bluetooth stack or the bluetoothd daemon) to interact with a virtual Bluetooth controller without requiring physical Bluetooth hardware. It simulates the low-level HCI protocol communication, often via a pseudo-terminal (pty) or a specified serial device. This enables developers to test various Bluetooth functionalities, discover protocol issues, and debug applications in a controlled and reproducible environment, making it an invaluable asset for Bluetooth software engineers.

hciemu requires appropriate permissions, often root privileges or the CAP_NET_ADMIN capability, to create and manage virtual network interfaces and pseudo-terminals.
It is primarily a development tool and not intended for general user use or production environments. Misuse can lead to conflicts with actual Bluetooth hardware or system instability if not properly isolated. The emulation fidelity depends on the version and may not perfectly replicate all real-world hardware behaviors or quirks.

The most common way to use hciemu is with the --pty option. This creates a pseudo-terminal, and its path (e.g., /dev/pts/3) is printed to standard output. This path can then be passed to the bluetoothd daemon (e.g., bluetoothd -E -C -p /dev/pts/3) or other applications to connect to the emulated device. This allows for isolated testing environments where the emulated device can be started and stopped without affecting other Bluetooth interfaces.

hciemu is invaluable for debugging Bluetooth applications and protocol interactions. By using the --sniff option, developers can capture all HCI commands, events, and data packets exchanged between the host and the emulated controller. This captured data can then be analyzed with tools like Wireshark (which understands HCI logging formats) to identify protocol errors or unexpected behavior.

hciemu is an integral part of the BlueZ project, the official Linux Bluetooth protocol stack. BlueZ development began in the early 2000s, with hciemu being developed alongside the core stack to facilitate robust testing and debugging. Its primary purpose has always been to provide a controlled, software-based environment for testing kernel modules, drivers, and user-space applications related to Bluetooth without the need for diverse or specific physical hardware. This has been crucial for continuous integration and automated testing of the BlueZ stack over the years.

bluetoothd(8), hciconfig(8), hcitool(1), btmgmt(1), gatttool(1)