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