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