1.\" $NetBSD: bluetooth.4,v 1.7 2007/09/30 04:22:52 kiyohara Exp $ 2.\" 3.\" Copyright (c) 2006 Itronix Inc. 4.\" All rights reserved. 5.\" 6.\" Written by Iain Hibbert for Itronix Inc. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. The name of Itronix Inc. may not be used to endorse 17.\" or promote products derived from this software without specific 18.\" prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY ITRONIX INC. ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 22.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY 24.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 25.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 27.\" ON ANY THEORY OF LIABILITY, WHETHER IN 28.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 30.\" POSSIBILITY OF SUCH DAMAGE. 31.\" 32.\" 33.Dd September 20, 2007 34.Dt BLUETOOTH 4 35.Os 36.Sh NAME 37.Nm bluetooth 38.Nd Bluetooth Protocol Family 39.Sh SYNOPSIS 40.In netbt/bluetooth.h 41.In netbt/hci.h 42.In netbt/l2cap.h 43.In netbt/rfcomm.h 44.Sh DESCRIPTION 45The 46.Tn Bluetooth 47Protocol Family 48.Sh ADDRESSING 49Bluetooth Protocol Family sockets all use a 50.Ar sockaddr_bt 51structure which contains a Bluetooth Device Address (BDADDR). 52This consists of a six byte string in least significant byte 53first order. 54.Bd -literal -offset -indent 55struct sockaddr_bt { 56 uint8_t bt_len; 57 sa_family_t bt_family; 58 bdaddr_t bt_bdaddr; 59 uint16_t bt_psm; 60 uint8_t bt_channel; 61}; 62.Ed 63.Pp 64The local address used by the socket can be set with 65.Xr bind 2 . 66.Sh PROTOCOLS 67Protocols included are: 68.Bl -tag -width XX 69.It Cm BTPROTO_HCI 70This gives raw access to the Host Controller Interface of local devices 71using the HCI protocol as described in the Bluetooth Core Specification. 72Any user may open an HCI socket but there are limitations on what 73unprivileged users can send and receive. The local address specified by 74.Xr bind 2 75may be used to select the device that the socket will receive packets from. If 76.Dv BDADDR_ANY 77is specified then the socket will receive packets from all 78devices on the system. 79.Xr connect 2 80may be used to create connections such that packets sent with 81.Xr send 2 82will be delivered to the specified device, otherwise 83.Xr sendto 2 84should be used. 85.Pp 86The 87.Ar bt_psm 88and 89.Ar bt_channel 90fields in the sockaddr_bt structure are ignored by HCI protocol code 91and should be set to zero. 92.Pp 93HCI socket options: 94.Bl -tag -width XX 95.It Dv SO_HCI_EVT_FILTER Op Ar struct hci_filter 96This filter controls which events will be recieved at the socket. See 97.In netbt/hci.h 98for available events. By default, Command_Complete and Command_Status 99events only are enabled. 100.It Dv SO_HCI_PKT_FILTER Op Ar struct hci_filter 101This filter controls the type of packets that will be received at the 102socket. By default, Event packets only are enabled. 103.It Dv SO_HCI_DIRECTION Op Ar int 104When set, this enables control messages on packets received at the socket 105indicating the direction of travel of the packet. 106.El 107.Pp 108HCI 109.Xr sysctl 8 110controls: 111.Bl -tag -width XXX 112.It Dv net.bluetooth.hci.sendspace 113Default send buffer size for HCI sockets. 114.It Dv net.bluetooth.hci.recvspace 115Default receive buffer size for HCI sockets 116.It Dv net.bluetooth.hci.acl_expiry 117If set, this is the time in seconds after which unused ACL data connections 118will be expired. If zero, connections will not be closed. 119.It Dv net.bluetooth.hci.memo_expiry 120Time, in seconds, that the system will keep records of Bluetooth devices 121in the vicinity after an Inquiry Response packet has been recieved. This 122information is used for routing purposes. 123.It Dv net.bluetooth.hci.eventq_max 124The maximum number of packets on the low level Event queue. 125.It Dv net.bluetooth.hci.aclrxq_max 126The maximum number of packets on the low level ACL queue. 127.It Dv net.bluetooth.hci.scorxq_max 128The maximum number of packets on the low level SCO queue. 129.El 130.It Cm BTPROTO_L2CAP 131L2CAP sockets give sequential packet access over channels to other Bluetooth 132devices and make use of the 133.Ar bt_psm 134field in the 135.Ar sockaddr_bt 136structure to select the Protocol/Sevice Multiplexer to specify when making 137connections. 138.Pp 139L2CAP socket options: 140.Bl -tag -width XXX 141.It Dv SO_L2CAP_IMTU Op Ar uint16_t 142Incoming MTU 143.It Dv SO_L2CAP_OMTU Op Ar uint16_t 144Outgoing MTU (read-only) 145.It Dv SO_L2CAP_LM Op Ar int 146Link Mode. 147The following bits may be set: 148.Pp 149.Bl -tag -compact -width ".Dv L2CAP_LM_ENCRYPT" 150.It Dv L2CAP_LM_AUTH 151Request authentication 152.Pq pairing . 153.It Dv L2CAP_LM_ENCRYPT 154Request encryption 155.Pq includes auth . 156.It Dv L2CAP_LM_SECURE 157Request secured link 158.Pq encryption, plus change link key . 159.El 160.Pp 161Link mode settings will be applied to the baseband link during L2CAP 162connection establishment. 163If the L2CAP connection is already established, 164.Dv EINPROGRESS 165may be returned, and it is not possible to guarantee that data already queued 166.Pq from either end 167will not be delivered. 168If the mode change fails, the L2CAP connection will be aborted. 169.El 170.Pp 171L2CAP 172.Xr sysctl 8 173controls: 174.Bl -tag -width XXX 175.It Dv net.bluetooth.l2cap.sendspace 176Default send buffer size for L2CAP sockets. 177.It Dv net.bluetooth.l2cap.recvspace 178Default receive buffer size for L2CAP sockets. 179.It Dv net.bluetooth.l2cap.rtx 180Response Timeout eXpiry for L2CAP signals. 181.It Dv net.bluetooth.l2cap.ertx 182Extended Response Timeout eXpiry for L2CAP signals. 183.El 184.It Cm BTPROTO_RFCOMM 185RFCOMM sockets provide streamed data over Bluetooth connection and make use of the 186.Ar bt_psm , 187and 188.Ar bt_channel 189fields in the 190.Ar sockaddr_bt 191structure. 192The channel number must be between 1 and 30 inclusive. 193If no PSM is specified, a default value of 194.Dv L2CAP_PSM_RFCOMM 195(0x0003) will be used. 196.Pp 197RFCOMM socket options: 198.Bl -tag -width XXX 199.It Dv SO_RFCOMM_MTU Op Ar uint16_t 200Maximum Frame Size to use for this link. 201.It Dv SO_RFCOMM_LM Op Ar int 202Link Mode. 203The following bits may be set at any time: 204.Pp 205.Bl -tag -compact -width ".Dv RFCOMM_LM_ENCRYPT" 206.It Dv RFCOMM_LM_AUTH 207Request authentication 208.Pq pairing . 209.It Dv RFCOMM_LM_ENCRYPT 210Request encryption 211.Pq includes auth . 212.It Dv RFCOMM_LM_SECURE 213Request secured link 214.Pq encryption, plus change link key . 215.El 216.Pp 217Link mode settings will be applied to the baseband link during RFCOMM 218connection establishment. 219If the RFCOMM connection is already established, 220.Dv EINPROGRESS 221may be returned, and it is not possible to guarantee that data already queued 222.Pq from either end 223will not be delivered. 224If the mode change fails, the RFCOMM connection will be aborted. 225.El 226.Pp 227RFCOMM 228.Xr sysctl 8 229controls: 230.Bl -tag -width XXX 231.It Dv net.bluetooth.rfcomm.sendspace 232Default send buffer size for RFCOMM sockets. 233.It Dv net.bluetooth.rfcomm.recvspace 234Default receive buffer size for RFCOMM sockets. 235.It Dv net.bluetooth.rfcomm.default_mtu 236Maximum Frame Size (N1) 237.It Dv net.bluetooth.ack_timeout 238Acknowledgement Timer (T1) 239.It Dv net.bluetooth.mcc_timeout 240Response Timer for Multiplexer Control Channel (T2) 241.El 242.It Cm BTPROTO_SCO 243SCO sockets provide sequential packet access to time sensitive data 244channels over Bluetooth connections, typically used for audio data. 245.Pp 246SCO socket options: 247.Bl -tag -width XXX 248.It Dv SO_SCO_MTU Op Ar uint16_t 249Maximum packet size for use on this link. 250This is read-only and will be set by the protocol code when a connection is made. 251Currently, due to limitations in the 252.Xr ubt 4 253driver, the SCO protocol code will only accept packets with 254exactly this size. 255.It Dv SO_SCO_HANDLE Op Ar uint16_t 256Connection handle for this link. 257This is read-only and provided for informational purposes only. 258.El 259.Pp 260SCO 261.Xr sysctl 8 262controls: 263.Bl -tag -width XXX 264.It Dv net.bluetooth.sco.sendspace 265Default send buffer size for SCO sockets. 266.It Dv net.bluetooth.sco.recvspace 267Default receive buffer size for SCO sockets. 268.El 269.El 270.Sh INFORMATION 271The following 272.Xr ioctl 2 273calls may be used to manipulate Bluetooth devices. The 274.Xr ioctl 2 275must be made on 276.Cm BTPROTO_HCI 277sockets. All of the requests take a 278.Ar btreq 279structure defined as follows as their parameter and unless otherwise 280specified, use the 281.Ar btr_name 282field to identify the device. 283.Bd -literal -offset 284struct btreq { 285 char btr_name[HCI_DEVNAME_SIZE]; /* device name */ 286 287 union { 288 struct { 289 bdaddr_t btri_bdaddr; /* device bdaddr */ 290 uint16_t btri_flags; /* flags */ 291 uint16_t btri_num_cmd; /* # of free cmd buffers */ 292 uint16_t btri_num_acl; /* # of free ACL buffers */ 293 uint16_t btri_num_sco; /* # of free SCO buffers */ 294 uint16_t btri_acl_mtu; /* ACL mtu */ 295 uint16_t btri_sco_mtu; /* SCO mtu */ 296 uint16_t btri_link_policy; /* Link Policy */ 297 uint16_t btri_packet_type; /* Packet Type */ 298 } btri; 299 struct bt_stats btrs; /* unit stats */ 300 } btru; 301}; 302 303#define btr_flags btru.btri.btri_flags 304#define btr_bdaddr btru.btri.btri_bdaddr 305#define btr_num_cmd btru.btri.btri_num_cmd 306#define btr_num_acl btru.btri.btri_num_acl 307#define btr_num_sco btru.btri.btri_num_sco 308#define btr_acl_mtu btru.btri.btri_acl_mtu 309#define btr_sco_mtu btru.btri.btri_sco_mtu 310#define btr_link_policy btru.btri.btri_link_policy 311#define btr_packet_type btru.btri.btri_packet_type 312#define btr_stats btru.btrs 313 314/* btr_flags */ 315#define BTF_UP (1\*[Lt]\*[Lt]0) /* unit is up */ 316#define BTF_RUNNING (1\*[Lt]\*[Lt]1) /* unit is running */ 317#define BTF_XMIT_CMD (1\*[Lt]\*[Lt]2) /* transmitting CMD packets */ 318#define BTF_XMIT_ACL (1\*[Lt]\*[Lt]3) /* transmitting ACL packets */ 319#define BTF_XMIT_SCO (1\*[Lt]\*[Lt]4) /* transmitting SCO packets */ 320#define BTF_INIT_BDADDR (1\*[Lt]\*[Lt]5) /* waiting for bdaddr */ 321#define BTF_INIT_BUFFER_SIZE (1\*[Lt]\*[Lt]6) /* waiting for buffer size */ 322#define BTF_INIT_FEATURES (1\*[Lt]\*[Lt]7) /* waiting for features */ 323 324struct bt_stats { 325 uint32_t err_tx; 326 uint32_t err_rx; 327 uint32_t cmd_tx; 328 uint32_t evt_rx; 329 uint32_t acl_tx; 330 uint32_t acl_rx; 331 uint32_t sco_tx; 332 uint32_t sco_rx; 333 uint32_t byte_tx; 334 uint32_t byte_rx; 335}; 336 337.Ed 338.Bl -tag -width SIOCGBTPOLICY 339.It Dv SIOCGBTINFO 340Get Bluetooth device Info. Given the device name, fill in the 341btreq structure including the address field for use with socket addressing 342as above. 343.It Dv SIOCGBTINFOA 344Get Bluetooth device Info from Address. Given the device address, fill in the 345btreq structure including the name field. 346.It Dv SIOCNBTINFO 347Next Bluetooth device Info . If name field is empty, the first device 348will be returned. Otherwise, the next device will be returned. Thus, you 349can cycle through all devices in the system. 350.It Dv SIOCSBTFLAGS 351Set Bluetooth device Flags. Not all flags are settable. 352.It Dv SIOCSBTPOLICY 353Set Bluetooth device Link Policy. Link Policy bits are defined in 354.In netbt/hci.h , 355though you can only set bits that the device supports. 356.It Dv SIOCSBTPTYPE 357Set Bluetooth device Packet Types. You can only set packet types 358that the device supports. 359.It Dv SIOCGBTSTATS 360Read device statistics. 361.It Dv SIOCZBTSTATS 362Read device statistics, and zero them. 363.El 364.Pp 365Only the super-user may change device configurations. 366.Sh SEE ALSO 367.Xr bind 2 , 368.Xr getsockname 2 , 369.Xr bluetooth 3 , 370.Xr bcsp 4 , 371.Xr bt3c 4 , 372.Xr btbc 4 , 373.Xr btuart 4 , 374.Xr options 4 , 375.Xr ubt 4 376.Sh HISTORY 377The Bluetooth Protocol Stack was written for 378.Nx 4.0 379by 380.An Iain Hibbert 381under the sponsorship of Itronix, Inc. 382