1.\" $NetBSD: bluetooth.4,v 1.1 2006/06/19 15:44:36 gdamore 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 March 6, 2006 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.El 146.Pp 147L2CAP 148.Xr sysctl 8 149controls: 150.Bl -tag -width XXX 151.It Dv net.bluetooth.l2cap.sendspace 152Default send buffer size for L2CAP sockets. 153.It Dv net.bluetooth.l2cap.recvspace 154Default receive buffer size for L2CAP sockets. 155.It Dv net.bluetooth.l2cap.rtx 156Response Timeout eXpiry for L2CAP signals. 157.It Dv net.bluetooth.l2cap.ertx 158Extended Response Timeout eXpiry for L2CAP signals. 159.El 160.It Cm BTPROTO_RFCOMM 161RFCOMM sockets provide streamed data over Bluetooth connection and make use of the 162.Ar bt_psm , 163and 164.Ar bt_channel 165fields in the 166.Ar sockaddr_bt 167structure. 168The channel number must be between 1 and 30 inclusive. 169If no PSM is specified, a default value of 170.Dv L2CAP_PSM_RFCOMM 171(0x0003) will be used. 172.Pp 173RFCOMM socket options: 174.Bl -tag -width XXX 175.It Dv SO_RFCOMM_MTU Op Ar uint16_t 176Maximum Frame Size to use for this link. 177.El 178.Pp 179RFCOMM 180.Xr sysctl 8 181controls: 182.Bl -tag -width XXX 183.It Dv net.bluetooth.rfcomm.sendspace 184Default send buffer size for RFCOMM sockets. 185.It Dv net.bluetooth.rfcomm.recvspace 186Default receive buffer size for RFCOMM sockets. 187.It Dv net.bluetooth.rfcomm.default_mtu 188Maximum Frame Size (N1) 189.It Dv net.bluetooth.ack_timeout 190Acknowledgement Timer (T1) 191.It Dv net.bluetooth.mcc_timeout 192Response Timer for Multiplexer Control Channel (T2) 193.El 194.It Cm BTPROTO_SCO 195SCO sockets provide packetised access to time sensitive data channels over 196Bluetooth connections, typically used for audio data. Note that SCO socket 197support is currently experimental and needs to be explicitly configured in 198your kernel configuration file with the BLUETOOTH_SCO option. 199.Pp 200SCO socket options: 201.Bl -tag -width XXX 202.It Dv SO_SCO_MTU Op Ar uint16_t 203Maximun packet size for use on this link. This is read only and will be set 204by the socket code when a connection is made. 205.It Dv SO_SCO_HANDLE Op Ar uint16_t 206Connection handle for this link. This is read only and provided for 207informational purposes only. 208.El 209.Pp 210SCO 211.Xr sysctl 8 212controls: 213.Bl -tag -width XXX 214.It Dv net.bluetooth.sco.sendspace 215Default send buffer size for SCO sockets. 216.It Dv net.bluetooth.sco.recvspace 217Default receive buffer size for SCO sockets. 218.El 219.El 220.Sh INFORMATION 221The following 222.Xr ioctl 2 223calls may be used to manipulate Bluetooth devices. The 224.Xr ioctl 2 225must be made on 226.Cm BTPROTO_HCI 227sockets. All of the requests take a 228.Ar btreq 229structure defined as follows as their parameter and unless otherwise 230specified, use the 231.Ar btr_name 232field to identify the device. 233.Bd -literal -offset 234struct btreq { 235 char btr_name[HCI_DEVNAME_SIZE]; /* device name */ 236 237 union { 238 struct { 239 bdaddr_t btri_bdaddr; /* device bdaddr */ 240 uint16_t btri_flags; /* flags */ 241 uint16_t btri_num_cmd; /* # of free cmd buffers */ 242 uint16_t btri_num_acl; /* # of free ACL buffers */ 243 uint16_t btri_num_sco; /* # of free SCO buffers */ 244 uint16_t btri_acl_mtu; /* ACL mtu */ 245 uint16_t btri_sco_mtu; /* SCO mtu */ 246 uint16_t btri_link_policy; /* Link Policy */ 247 uint16_t btri_packet_type; /* Packet Type */ 248 } btri; 249 struct bt_stats btrs; /* unit stats */ 250 } btru; 251}; 252 253#define btr_flags btru.btri.btri_flags 254#define btr_bdaddr btru.btri.btri_bdaddr 255#define btr_num_cmd btru.btri.btri_num_cmd 256#define btr_num_acl btru.btri.btri_num_acl 257#define btr_num_sco btru.btri.btri_num_sco 258#define btr_acl_mtu btru.btri.btri_acl_mtu 259#define btr_sco_mtu btru.btri.btri_sco_mtu 260#define btr_link_policy btru.btri.btri_link_policy 261#define btr_packet_type btru.btri.btri_packet_type 262#define btr_stats btru.btrs 263 264/* btr_flags */ 265#define BTF_UP (1<<0) /* unit is up */ 266#define BTF_RUNNING (1<<1) /* unit is running */ 267#define BTF_XMIT_CMD (1<<2) /* transmitting CMD packets */ 268#define BTF_XMIT_ACL (1<<3) /* transmitting ACL packets */ 269#define BTF_XMIT_SCO (1<<4) /* transmitting SCO packets */ 270#define BTF_INIT_BDADDR (1<<5) /* waiting for bdaddr */ 271#define BTF_INIT_BUFFER_SIZE (1<<6) /* waiting for buffer size */ 272#define BTF_INIT_FEATURES (1<<7) /* waiting for features */ 273 274struct bt_stats { 275 uint32_t err_tx; 276 uint32_t err_rx; 277 uint32_t cmd_tx; 278 uint32_t evt_rx; 279 uint32_t acl_tx; 280 uint32_t acl_rx; 281 uint32_t sco_tx; 282 uint32_t sco_rx; 283 uint32_t byte_tx; 284 uint32_t byte_rx; 285}; 286 287.Ed 288.Bl -tag -width SIOCGBTPOLICY 289.It Dv SIOCGBTINFO 290Get Bluetooth device Info. Given the device name, fill in the 291btreq structure including the address field for use with socket addressing 292as above. 293.It Dv SIOCGBTINFOA 294Get Bluetooth device Info from Address. Given the device address, fill in the 295btreq structure including the name field. 296.It Dv SIOCNBTINFO 297Next Bluetooth device Info . If name field is empty, the first device 298will be returned. Otherwise, the next device will be returned. Thus, you 299can cycle through all devices in the system. 300.It Dv SIOCSBTFLAGS 301Set Bluetooth device Flags. Not all flags are settable. 302.It Dv SIOCSBTPOLICY 303Set Bluetooth device Link Policy. Link Policy bits are defined in 304.In netbt/hci.h , 305though you can only set bits that the device supports. 306.It Dv SIOCSBTPTYPE 307Set Bluetooth device Packet Types. You can only set packet types 308that the device supports. 309.It Dv SIOCGBTSTATS 310Read device statistics. 311.It Dv SIOCZBTSTATS 312Read device statistics, and zero them. 313.El 314.Pp 315Only the super-user may change device configurations. 316.Sh SEE ALSO 317.Xr bluetooth 3 , 318.Xr bind 2 , 319.Xr getsockname 2 , 320.Xr options 4 , 321.Xr bt3c 4 , 322.Xr ubt 4 323.Sh HISTORY 324The Bluetooth Protocol Stack was written for 325.Nx 4.0 326by 327.An Iain Hibbert 328under the sponsorship of Itronix, Inc. 329