1.\" $NetBSD: bluetooth.4,v 1.13 2009/05/04 20:42:00 wiz 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 December 28, 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. 74The local address specified by 75.Xr bind 2 76may be used to select the device that the socket will receive packets from. 77If 78.Dv BDADDR_ANY 79is specified then the socket will receive packets from all 80devices on the system. 81.Xr connect 2 82may be used to create connections such that packets sent with 83.Xr send 2 84will be delivered to the specified device, otherwise 85.Xr sendto 2 86should be used. 87.Pp 88The 89.Ar bt_psm 90and 91.Ar bt_channel 92fields in the sockaddr_bt structure are ignored by HCI protocol code 93and should be set to zero. 94.Pp 95HCI socket options: 96.Bl -tag -width XX 97.It Dv SO_HCI_EVT_FILTER Op Ar struct hci_filter 98This filter controls which events will be received at the socket. 99See 100.In netbt/hci.h 101for available events. 102By default, Command_Complete and Command_Status 103events only are enabled. 104.It Dv SO_HCI_PKT_FILTER Op Ar struct hci_filter 105This filter controls the type of packets that will be received at the 106socket. 107By default, Event packets only are enabled. 108.It Dv SO_HCI_DIRECTION Op Ar int 109When set, this enables control messages on packets received at the socket 110indicating the direction of travel of the packet. 111.El 112.Pp 113HCI 114.Xr sysctl 8 115controls: 116.Bl -tag -width XXX 117.It Dv net.bluetooth.hci.sendspace 118Default send buffer size for HCI sockets. 119.It Dv net.bluetooth.hci.recvspace 120Default receive buffer size for HCI sockets 121.It Dv net.bluetooth.hci.acl_expiry 122If set, this is the time in seconds after which unused ACL data connections 123will be expired. 124If zero, connections will not be closed. 125.It Dv net.bluetooth.hci.memo_expiry 126Time, in seconds, that the system will keep records of Bluetooth devices 127in the vicinity after an Inquiry Response packet has been received. 128This information is used for routing purposes. 129.It Dv net.bluetooth.hci.eventq_max 130The maximum number of packets on the low level Event queue. 131.It Dv net.bluetooth.hci.aclrxq_max 132The maximum number of packets on the low level ACL queue. 133.It Dv net.bluetooth.hci.scorxq_max 134The maximum number of packets on the low level SCO queue. 135.El 136.It Cm BTPROTO_L2CAP 137L2CAP sockets give sequential packet access over channels to other Bluetooth 138devices and make use of the 139.Ar bt_psm 140field in the 141.Ar sockaddr_bt 142structure to select the Protocol/Sevice Multiplexer to specify when making 143connections. 144.Pp 145L2CAP socket options: 146.Bl -tag -width XXX 147.It Dv SO_L2CAP_IMTU Op Ar uint16_t 148Incoming MTU 149.It Dv SO_L2CAP_OMTU Op Ar uint16_t 150Outgoing MTU (read-only) 151.It Dv SO_L2CAP_LM Op Ar int 152Link Mode. 153The following bits may be set: 154.Pp 155.Bl -tag -compact -width ".Dv L2CAP_LM_ENCRYPT" 156.It Dv L2CAP_LM_AUTH 157Request authentication 158.Pq pairing . 159.It Dv L2CAP_LM_ENCRYPT 160Request encryption 161.Pq includes auth . 162.It Dv L2CAP_LM_SECURE 163Request secured link 164.Pq encryption, plus change link key . 165.El 166.Pp 167Link mode settings will be applied to the baseband link during L2CAP 168connection establishment. 169If the L2CAP connection is already established, 170.Dv EINPROGRESS 171may be returned, and it is not possible to guarantee that data already queued 172.Pq from either end 173will not be delivered. 174If the mode change fails, the L2CAP connection will be aborted. 175.El 176.Pp 177L2CAP 178.Xr sysctl 8 179controls: 180.Bl -tag -width XXX 181.It Dv net.bluetooth.l2cap.sendspace 182Default send buffer size for L2CAP sockets. 183.It Dv net.bluetooth.l2cap.recvspace 184Default receive buffer size for L2CAP sockets. 185.It Dv net.bluetooth.l2cap.rtx 186Response Timeout eXpiry for L2CAP signals. 187.It Dv net.bluetooth.l2cap.ertx 188Extended Response Timeout eXpiry for L2CAP signals. 189.El 190.It Cm BTPROTO_RFCOMM 191RFCOMM sockets provide streamed data over Bluetooth connection and make use of the 192.Ar bt_psm , 193and 194.Ar bt_channel 195fields in the 196.Ar sockaddr_bt 197structure. 198The channel number must be between 1 and 30 inclusive except that if the 199special value 200.Dv RFCOMM_CHANNEL_ANY 201is bound, when the 202.Xr listen 2 203call is made, the first unused channel for the relevant bdaddr will be 204allocated and may be discovered using the 205.Xr getsockname 2 206call. 207If no PSM is specified, a default value of 208.Dv L2CAP_PSM_RFCOMM 209(0x0003) will be used. 210.Pp 211RFCOMM socket options: 212.Bl -tag -width XXX 213.It Dv SO_RFCOMM_MTU Op Ar uint16_t 214Maximum Frame Size to use for this link. 215.It Dv SO_RFCOMM_LM Op Ar int 216Link Mode. 217The following bits may be set at any time: 218.Pp 219.Bl -tag -compact -width ".Dv RFCOMM_LM_ENCRYPT" 220.It Dv RFCOMM_LM_AUTH 221Request authentication 222.Pq pairing . 223.It Dv RFCOMM_LM_ENCRYPT 224Request encryption 225.Pq includes auth . 226.It Dv RFCOMM_LM_SECURE 227Request secured link 228.Pq encryption, plus change link key . 229.El 230.Pp 231Link mode settings will be applied to the baseband link during RFCOMM 232connection establishment. 233If the RFCOMM connection is already established, 234.Dv EINPROGRESS 235may be returned, and it is not possible to guarantee that data already queued 236.Pq from either end 237will not be delivered. 238If the mode change fails, the RFCOMM connection will be aborted. 239.El 240.Pp 241RFCOMM 242.Xr sysctl 8 243controls: 244.Bl -tag -width XXX 245.It Dv net.bluetooth.rfcomm.sendspace 246Default send buffer size for RFCOMM sockets. 247.It Dv net.bluetooth.rfcomm.recvspace 248Default receive buffer size for RFCOMM sockets. 249.It Dv net.bluetooth.rfcomm.default_mtu 250Maximum Frame Size (N1) 251.It Dv net.bluetooth.ack_timeout 252Acknowledgement Timer (T1) 253.It Dv net.bluetooth.mcc_timeout 254Response Timer for Multiplexer Control Channel (T2) 255.El 256.It Cm BTPROTO_SCO 257SCO sockets provide sequential packet access to time sensitive data 258channels over Bluetooth connections, typically used for audio data. 259.Pp 260SCO socket options: 261.Bl -tag -width XXX 262.It Dv SO_SCO_MTU Op Ar uint16_t 263Maximum packet size for use on this link. 264This is read-only and will be set by the protocol code when a connection is made. 265Currently, due to limitations in the 266.Xr ubt 4 267driver, the SCO protocol code will only accept packets with 268exactly this size. 269.It Dv SO_SCO_HANDLE Op Ar uint16_t 270Connection handle for this link. 271This is read-only and provided for informational purposes only. 272.El 273.Pp 274SCO 275.Xr sysctl 8 276controls: 277.Bl -tag -width XXX 278.It Dv net.bluetooth.sco.sendspace 279Default send buffer size for SCO sockets. 280.It Dv net.bluetooth.sco.recvspace 281Default receive buffer size for SCO sockets. 282.El 283.El 284.Sh INFORMATION 285The following 286.Xr ioctl 2 287calls may be used to manipulate Bluetooth devices. 288The 289.Xr ioctl 2 290must be made on 291.Cm BTPROTO_HCI 292sockets. 293All of the requests take a 294.Ar btreq 295structure defined as follows as their parameter and unless otherwise 296specified, use the 297.Ar btr_name 298field to identify the device. 299.Bd -literal 300struct btreq { 301 char btr_name[HCI_DEVNAME_SIZE]; /* device name */ 302 303 union { 304 struct { 305 bdaddr_t btri_bdaddr; /* device bdaddr */ 306 uint16_t btri_flags; /* flags */ 307 uint16_t btri_num_cmd; /* # of free cmd buffers */ 308 uint16_t btri_num_acl; /* # of free ACL buffers */ 309 uint16_t btri_num_sco; /* # of free SCO buffers */ 310 uint16_t btri_acl_mtu; /* ACL mtu */ 311 uint16_t btri_sco_mtu; /* SCO mtu */ 312 uint16_t btri_link_policy; /* Link Policy */ 313 uint16_t btri_packet_type; /* Packet Type */ 314 } btri; 315 struct bt_stats btrs; /* unit stats */ 316 } btru; 317}; 318 319#define btr_flags btru.btri.btri_flags 320#define btr_bdaddr btru.btri.btri_bdaddr 321#define btr_num_cmd btru.btri.btri_num_cmd 322#define btr_num_acl btru.btri.btri_num_acl 323#define btr_num_sco btru.btri.btri_num_sco 324#define btr_acl_mtu btru.btri.btri_acl_mtu 325#define btr_sco_mtu btru.btri.btri_sco_mtu 326#define btr_link_policy btru.btri.btri_link_policy 327#define btr_packet_type btru.btri.btri_packet_type 328#define btr_stats btru.btrs 329 330/* btr_flags */ 331#define BTF_UP (1\*[Lt]\*[Lt]0) /* unit is up */ 332#define BTF_RUNNING (1\*[Lt]\*[Lt]1) /* unit is running */ 333#define BTF_XMIT_CMD (1\*[Lt]\*[Lt]2) /* transmitting CMD packets */ 334#define BTF_XMIT_ACL (1\*[Lt]\*[Lt]3) /* transmitting ACL packets */ 335#define BTF_XMIT_SCO (1\*[Lt]\*[Lt]4) /* transmitting SCO packets */ 336#define BTF_INIT_BDADDR (1\*[Lt]\*[Lt]5) /* waiting for bdaddr */ 337#define BTF_INIT_BUFFER_SIZE (1\*[Lt]\*[Lt]6) /* waiting for buffer size */ 338#define BTF_INIT_FEATURES (1\*[Lt]\*[Lt]7) /* waiting for features */ 339#define BTF_NOOP_ON_RESET (1\*[Lt]\*[Lt]8) /* wait for No-op on reset */ 340#define BTF_INIT_COMMANDS (1\*[Lt]\*[Lt]9) /* waiting for supported commands */ 341 342struct bt_stats { 343 uint32_t err_tx; 344 uint32_t err_rx; 345 uint32_t cmd_tx; 346 uint32_t evt_rx; 347 uint32_t acl_tx; 348 uint32_t acl_rx; 349 uint32_t sco_tx; 350 uint32_t sco_rx; 351 uint32_t byte_tx; 352 uint32_t byte_rx; 353}; 354 355.Ed 356.Bl -tag -width SIOCGBTPOLICY 357.It Dv SIOCGBTINFO 358Get Bluetooth device Info. 359Given the device name, fill in the 360btreq structure including the address field for use with socket addressing 361as above. 362.It Dv SIOCGBTINFOA 363Get Bluetooth device Info from Address. 364Given the device address, fill in the 365btreq structure including the name field. 366.It Dv SIOCNBTINFO 367Next Bluetooth device Info. 368If name field is empty, the first device will be returned. 369Otherwise, the next device will be returned. 370Thus, you can cycle through all devices in the system. 371.It Dv SIOCSBTFLAGS 372Set Bluetooth device Flags. 373Not all flags are settable. 374.It Dv SIOCSBTPOLICY 375Set Bluetooth device Link Policy. 376Link Policy bits are defined in 377.In netbt/hci.h , 378though you can only set bits that the device supports. 379.It Dv SIOCSBTPTYPE 380Set Bluetooth device Packet Types. 381You can only set packet types that the device supports. 382.It Dv SIOCGBTSTATS 383Read device statistics. 384.It Dv SIOCZBTSTATS 385Read device statistics, and zero them. 386.El 387.Pp 388Only the super-user may change device configurations. 389.Sh SEE ALSO 390.Xr bind 2 , 391.Xr getsockname 2 , 392.Xr bluetooth 3 , 393.Xr bcsp 4 , 394.Xr bt3c 4 , 395.Xr btbc 4 , 396.Xr btuart 4 , 397.Xr options 4 , 398.Xr ubt 4 399.Sh HISTORY 400The Bluetooth Protocol Stack was written for 401.Nx 4.0 402by 403.An Iain Hibbert 404under the sponsorship of Itronix, Inc. 405