bluetoothctl-hci(1) Linux System Administration bluetoothctl-hci(1)

# [Name](#Name)

bluetoothctl-hci - HCI Submenu

# [SYNOPSIS](#SYNOPSIS)

**bluetoothctl** \[--options] \[hci.commands]

**Note:**

This submenu communicates directly with the Bluetooth controller via HCI socket, bypassing the BlueZ D-Bus API. Commands use the Host Controller Interface (HCI) protocol.

# [Commands](#Commands)

## [open](#open)

Open HCI channel.

[**Usage**](#Usage)

**> open <index> <chan=raw,user>**

[**index**](#index)

HCI controller index number (e.g., 0, 1, 2)

[**chan**](#chan)

Channel type (raw or user)

[**Example Open user channel (controller needs to be powered off first)**](#Example)

```
> power off
> hci.open 0 user
HCI index 0 user channel opened
```

[**Example Open user channel for HCI controller 0**](#Example~2)

```
> hci.open 0 user
```

[**Example Open user channel for HCI controller 1**](#Example~3)

```
> hci.open 1 user
```

[**Example Open user channel for HCI controller 2**](#Example~4)

```
> hci.open 2 user
```

[**Example Open raw channel for HCI controller 0**](#Example~5)

```
> hci.open 0 raw
```

[**Example Open raw channel for HCI controller 1**](#Example~6)

```
> hci.open 1 raw
```

## [cmd](#cmd)

Send HCI command.

[**Usage**](#Usage~2)

**> cmd <opcode> \[parameters...]**

[**opcode**](#opcode)

HCI command opcode in hexadecimal format (e.g., 0x0c03)

[**parameters**](#parameters)

Optional command parameters as hexadecimal bytes

[**Example Send HCI Reset command**](#Example~7)

```
> hci.cmd 0x0c03
HCI Command complete:
00
```

[**Example Send HCI Reset command (no parameters)**](#Example~8)

```
> hci.cmd 0x0c03
```

[**Example Send HCI Read Local Version Information**](#Example~9)

```
> hci.cmd 0x1003
```

[**Example Send HCI Read BD Address**](#Example~10)

```
> hci.cmd 0x1009
```

[**Example Send HCI Set Event Filter with parameter 0x01**](#Example~11)

```
> hci.cmd 0x0c01 0x01
```

[**Example Send LE Set Advertising Parameters with 2 parameters**](#Example~12)

```
> hci.cmd 0x200f 0x00 0x08
```

[**Example Send LE Set Advertising Data with length and data bytes**](#Example~13)

```
> hci.cmd 0x2008 0x20 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08
```

[**Example Send HCI Set Event Mask command**](#Example~14)

```
> hci.cmd 0x0c05 0x02
```

[**Example Send HCI Write Scan Enable**](#Example~15)

```
> hci.cmd 0x0c2a 0x01
```

[**Example Send HCI Write Class of Device**](#Example~16)

```
> hci.cmd 0x0c23 0x00 0x08
```

## [send](#send)

Send HCI data packet.

[**Usage**](#Usage~3)

**> send <type=acl,sco,iso> <handle> \[data...]**

[**type**](#type)

Packet type (acl, sco, or iso)

[**handle**](#handle)

Connection handle in hexadecimal format (e.g., 0x0000)

[**data**](#data)

Optional data bytes in hexadecimal format

[**Example Send ACL data packet to connection handle 0x0000**](#Example~17)

```
> hci.send acl 0x0000
```

[**Example Send empty ACL packet to handle 0x0000**](#Example~18)

```
> hci.send acl 0x0000
```

[**Example Send ACL packet with "Hello" data to handle 0x0001**](#Example~19)

```
> hci.send acl 0x0001 0x48 0x65 0x6c 0x6c 0x6f
```

[**Example Send ACL packet with custom data to handle 0x0010**](#Example~20)

```
> hci.send acl 0x0010 0x01 0x02 0x03 0x04
```

[**Example Send empty SCO packet to handle 0x0000**](#Example~21)

```
> hci.send sco 0x0000
```

[**Example Send SCO packet with audio data**](#Example~22)

```
> hci.send sco 0x0001 0xaa 0xbb 0xcc
```

[**Example Send SCO packet with sine wave pattern**](#Example~23)

```
> hci.send sco 0x0002 0x80 0x00 0x80 0x00
```

[**Example Send empty ISO packet to handle 0x0000**](#Example~24)

```
> hci.send iso 0x0000
```

[**Example Send ISO packet with sample data**](#Example~25)

```
> hci.send iso 0x0001 0x12 0x34 0x56 0x78
```

[**Example Send ISO packet for LE Audio stream**](#Example~26)

```
> hci.send iso 0x0020 0xa0 0xa1 0xa2 0xa3
```

## [register](#register)

Register HCI event handler.

[**Usage**](#Usage~4)

**> register <event>**

[**event**](#event)

HCI event code in hexadecimal format (e.g., 0x0e)

[**Example Register handler for Command Complete event**](#Example~27)

```
> register 0x0e
```

[**Example Register handler for Command Status event**](#Example~28)

```
> register 0x0f
```

[**Example Register handler for Connection Complete event**](#Example~29)

```
> register 0x03
```

[**Example Register handler for Disconnection Complete event**](#Example~30)

```
> register 0x05
```

[**Example Register handler for LE Meta events**](#Example~31)

```
> register 0x3e
```

[**Example Register handler for Inquiry Complete event**](#Example~32)

```
> register 0x02
```

[**Example Register handler for Role Change event**](#Example~33)

```
> register 0x22
```

## [unregister](#unregister)

Unregister HCI event handler.

[**Usage**](#Usage~5)

**> unregister <event>**

[**event**](#event~2)

HCI event code in hexadecimal format (e.g., 0x0e)

[**Example Unregister Command Complete event handler**](#Example~34)

```
> unregister 0x0e
```

[**Example Unregister Command Status event handler**](#Example~35)

```
> unregister 0x0f
```

[**Example Unregister Connection Complete event handler**](#Example~36)

```
> unregister 0x03
```

[**Example Unregister Disconnection Complete event handler**](#Example~37)

```
> unregister 0x05
```

[**Example Unregister LE Meta event handler**](#Example~38)

```
> unregister 0x3e
```

## [close](#close)

Close HCI channel.

Closes the currently open HCI channel.

[**Usage**](#Usage~6)

**> close**

[**Example Close the current HCI channel**](#Example~39)

```
> close
```

# [RESOURCES](#RESOURCES)

<http://www.bluez.org>

# [REPORTING BUGS](#REPORTING_BUGS)

<linux-bluetooth@vger.kernel.org>

# [Copyright](#Copyright)

Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL).

December 2024 BlueZ

---

Document: bluetoothctl-hci(1) from bluez 5.87-r1 (Chainguard OS)
Source: https://github.com/bluez/bluez