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