Blob: hci.rst

Blob id: f2868465584202a1780516cd5c8f158efd8e4e07

Size: 3.3 KB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
===
hci
===

----------------------
Bluetooth HCI protocol
----------------------

:Version: BlueZ
:Copyright: Free use of this software is granted under the terms of the GNU
            Lesser General Public Licenses (LGPL).
:Date: October 2024
:Manual section: 7
:Manual group: Linux System Administration

SYNOPSIS
========

.. code-block::

    #include <sys/socket.h>
    #include <bluetooth/bluetooth.h>
    #include <bluetooth/hci.h>

    hci_socket = socket(PF_BLUETOOTH, SOCK_RAW, BTPROTO_HCI);

DESCRIPTION
===========

Bluetooth Host Controller Interface (HCI) is the standard protocol to
communicate with Bluetooth adapters. HCI protocol provides a uniform command
method for the Host to access Controller capabilities and to control connections
to other Controllers.

SOCKET ADDRESS
==============

.. code-block::

    struct sockaddr_hci {
        sa_family_t    hci_family;
        unsigned short hci_dev;
        unsigned short hci_channel;
    };

Possible values for hci_channel:

.. csv-table::
    :header: "Define", "Value", "Description"
    :widths: auto

    **HCI_CHANNEL_RAW**, 0x00, Raw channel - Used for raw HCI communication
    **HCI_CHANNEL_USER**, 0x01, User channel - Used for userspace HCI communication (disables kernel processing)
    **HCI_CHANNEL_MONITOR**, 0x02, Monitor channel - Used for monitoring HCI traffic (btmon(1))
    **HCI_CHANNEL_CONTROL**, 0x03, Control channel - Used to manage local adapters (bluetoothd(7))
    **HCI_CHANNEL_LOGGING**, 0x04, Logging channel - Used to inject logging messages (bluetoothd(7))

Example:

.. code-block::

    struct sockaddr_hci addr;

    memset(&addr, 0, sizeof(addr));
    addr.hci_family = AF_BLUETOOTH;
    addr.hci_dev = HCI_DEV_NONE;
    addr.hci_channel = HCI_CHANNEL_CONTROL;

SOCKET OPTIONS
==============

The socket options listed below can be set by using **setsockopt(2)** and read
with **getsockopt(2)** with the socket level set to SOL_BLUETOOTH or SOL_HCI
(HCI_FILTER).

HCI_FILTER (since Linux 2.6)
----------------------------

Filter by HCI events, requires hci_channel to be set to HCI_CHANNEL_RAW,
possible values:

.. code-block::

    struct hci_filter {
        uint32_t type_mask;
        uint32_t event_mask[2];
        uint16_t opcode;
    };

Example:

.. code-block::

    struct hci_filter flt;

    memset(&flt, 0, sizeof(flt));
    flt.type_mask = 1 << BT_H4_EVT_PKT;
    flt.event_mask[0] = 0xffffffff;
    flt.event_mask[1] = 0xffffffff;

    setsockopt(fd, SOL_HCI, HCI_FILTER, &flt, sizeof(flt));

BT_SNDBUF (since Linux 5.16)
----------------------------

Set send buffer size, requires hci_channel to be set to HCI_CHANNEL_MONITOR,
HCI_CHANNEL_CONTROL or HCI_CHANNEL_LOGGING.

Default value is 1028.

Example:

.. code-block::

    uint16_t mtu = UINT16_MAX;
    int err;

    err = setsockopt(fd, SOL_BLUETOOTH, BT_SNDMTU, &mtu, sizeof(mtu));

BT_RCVBUF (since Linux 5.16)
----------------------------

Set receive buffer size, requires hci_channel to be set to HCI_CHANNEL_MONITOR,
HCI_CHANNEL_CONTROL or HCI_CHANNEL_LOGGING.

Default value is 1028.

Example:

.. code-block::

    uint16_t mtu;
    socklen_t len;
    int err;

    len = sizeof(mtu);
    err = getsockopt(sock, SOL_BLUETOOTH, BT_RCVMTU, mtu, &len);

RESOURCES
=========

http://www.bluez.org

REPORTING BUGS
==============

linux-bluetooth@vger.kernel.org

SEE ALSO
========

socket(7)