share/man/man4/bluetooth.4

   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
  46 The
  47 .Tn Bluetooth
  48 Protocol Family
  49 .Sh ADDRESSING
  50 Bluetooth Protocol Family sockets all use a
  51 .Ar sockaddr_bt
  52 structure which contains a Bluetooth Device Address (BDADDR).
  53 This consists of a six byte string in least significant byte
  54 first order.
  55 .Bd -literal -offset indent
  56 struct 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
  65 The local address used by the socket can be set with
  66 .Xr bind 2 .
  67 .Sh PROTOCOLS
  68 Protocols included are:
  69 .Bl -tag -width XX
  70 .It Cm BTPROTO_HCI
  71 This gives raw access to the Host Controller Interface of local devices
  72 using the HCI protocol as described in the Bluetooth Core Specification.
  73 Any user may open an HCI socket but there are limitations on what
  74 unprivileged users can send and receive. The local address specified by
  75 .Xr bind 2
  76 may be used to select the device that the socket will receive packets from. If
  77 .Dv BDADDR_ANY
  78 is specified then the socket will receive packets from all
  79 devices on the system.
  80 .Xr connect 2
  81 may be used to create connections such that packets sent with
  82 .Xr send 2
  83 will be delivered to the specified device, otherwise
  84 .Xr sendto 2
  85 should be used.
  86 .Pp
  87 The
  88 .Ar bt_psm
  89 and
  90 .Ar bt_channel
  91 fields in the sockaddr_bt structure are ignored by HCI protocol code
  92 and should be set to zero.
  93 .Pp
  94 HCI socket options:
  95 .Bl -tag -width XX
  96 .It Dv SO_HCI_EVT_FILTER Op Ar struct hci_filter
  97 This filter controls which events will be received at the socket. See
  98 .In netbt/hci.h
  99 for available events. By default, Command_Complete and Command_Status
 100 events only are enabled.
 101 .It Dv SO_HCI_PKT_FILTER Op Ar struct hci_filter
 102 This filter controls the type of packets that will be received at the
 103 socket. By default, Event packets only are enabled.
 104 .It Dv SO_HCI_DIRECTION Op Ar int
 105 When set, this enables control messages on packets received at the socket
 106 indicating the direction of travel of the packet.
 107 .El
 108 .Pp
 109 HCI
 110 .Xr sysctl 8
 111 controls:
 112 .Bl -tag -width XXX
 113 .It Va net.bluetooth.hci.sendspace
 114 Default send buffer size for HCI sockets.
 115 .It Va net.bluetooth.hci.recvspace
 116 Default receive buffer size for HCI sockets
 117 .It Va net.bluetooth.hci.acl_expiry
 118 If set, this is the time in seconds after which unused ACL data connections
 119 will be expired. If zero, connections will not be closed.
 120 .It Va net.bluetooth.hci.memo_expiry
 121 Time, in seconds, that the system will keep records of Bluetooth devices
 122 in the vicinity after an Inquiry Response packet has been received. This
 123 information is used for routing purposes.
 124 .It Va net.bluetooth.hci.eventq_max
 125 The maximum number of packets on the low level Event queue.
 126 .It Va net.bluetooth.hci.aclrxq_max
 127 The maximum number of packets on the low level ACL queue.
 128 .It Va net.bluetooth.hci.scorxq_max
 129 The maximum number of packets on the low level SCO queue.
 130 .El
 131 .It Cm BTPROTO_L2CAP
 132 L2CAP sockets give sequential packet access over channels to other Bluetooth
 133 devices and make use of the
 134 .Ar bt_psm
 135 field in the
 136 .Ar sockaddr_bt
 137 structure to select the Protocol/Service Multiplexer to specify when making
 138 connections.
 139 .Pp
 140 L2CAP socket options:
 141 .Bl -tag -width XXX
 142 .It Dv SO_L2CAP_IMTU Op Ar uint16_t
 143 Incoming MTU
 144 .It Dv SO_L2CAP_OMTU Op Ar uint16_t
 145 Outgoing MTU (read-only)
 146 .It Dv SO_L2CAP_LM Op Ar int
 147 Link Mode.
 148 The following bits may be set:
 149 .Pp
 150 .Bl -tag -compact -width ".Dv L2CAP_LM_ENCRYPT"
 151 .It Dv L2CAP_LM_AUTH
 152 Request authentication
 153 .Pq pairing .
 154 .It Dv L2CAP_LM_ENCRYPT
 155 Request encryption
 156 .Pq includes auth .
 157 .It Dv L2CAP_LM_SECURE
 158 Request secured link
 159 .Pq encryption, plus change link key .
 160 .El
 161 .Pp
 162 Link mode settings will be applied to the baseband link during L2CAP
 163 connection establishment.
 164 If the L2CAP connection is already established,
 165 .Er EINPROGRESS
 166 may be returned, and it is not possible to guarantee that data already queued
 167 .Pq from either end
 168 will not be delivered.
 169 If the mode change fails, the L2CAP connection will be aborted.
 170 .El
 171 .Pp
 172 L2CAP
 173 .Xr sysctl 8
 174 controls:
 175 .Bl -tag -width XXX
 176 .It Va net.bluetooth.l2cap.sendspace
 177 Default send buffer size for L2CAP sockets.
 178 .It Va net.bluetooth.l2cap.recvspace
 179 Default receive buffer size for L2CAP sockets.
 180 .It Va net.bluetooth.l2cap.rtx
 181 Response Timeout eXpiry for L2CAP signals.
 182 .It Va net.bluetooth.l2cap.ertx
 183 Extended Response Timeout eXpiry for L2CAP signals.
 184 .El
 185 .It Cm BTPROTO_RFCOMM
 186 RFCOMM sockets provide streamed data over Bluetooth connection and make use of the
 187 .Ar bt_psm ,
 188 and
 189 .Ar bt_channel
 190 fields in the
 191 .Ar sockaddr_bt
 192 structure.
 193 The channel number must be between 1 and 30 inclusive except that if the
 194 special value
 195 .Dv RFCOMM_CHANNEL_ANY
 196 is bound, when the
 197 .Xr listen 2
 198 call is made, the first unused channel for the relevant bdaddr will be
 199 allocated and may be discovered using the
 200 .Xr getsockname 2
 201 call.
 202 If no PSM is specified, a default value of
 203 .Dv L2CAP_PSM_RFCOMM
 204 (0x0003) will be used.
 205 .Pp
 206 RFCOMM socket options:
 207 .Bl -tag -width XXX
 208 .It Dv SO_RFCOMM_MTU Op Ar uint16_t
 209 Maximum Frame Size to use for this link.
 210 .It Dv SO_RFCOMM_LM Op Ar int
 211 Link Mode.
 212 The 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
 216 Request authentication
 217 .Pq pairing .
 218 .It Dv RFCOMM_LM_ENCRYPT
 219 Request encryption
 220 .Pq includes auth .
 221 .It Dv RFCOMM_LM_SECURE
 222 Request secured link
 223 .Pq encryption, plus change link key .
 224 .El
 225 .Pp
 226 Link mode settings will be applied to the baseband link during RFCOMM
 227 connection establishment.
 228 If the RFCOMM connection is already established,
 229 .Er EINPROGRESS
 230 may be returned, and it is not possible to guarantee that data already queued
 231 .Pq from either end
 232 will not be delivered.
 233 If the mode change fails, the RFCOMM connection will be aborted.
 234 .El
 235 .Pp
 236 RFCOMM
 237 .Xr sysctl 8
 238 controls:
 239 .Bl -tag -width XXX
 240 .It Va net.bluetooth.rfcomm.sendspace
 241 Default send buffer size for RFCOMM sockets.
 242 .It Va net.bluetooth.rfcomm.recvspace
 243 Default receive buffer size for RFCOMM sockets.
 244 .It Va net.bluetooth.rfcomm.default_mtu
 245 Maximum Frame Size (N1)
 246 .It Va net.bluetooth.rfcomm.ack_timeout
 247 Acknowledgement Timer (T1)
 248 .It Va net.bluetooth.rfcomm.mcc_timeout
 249 Response Timer for Multiplexer Control Channel (T2)
 250 .El
 251 .It Cm BTPROTO_SCO
 252 SCO sockets provide sequential packet access to time sensitive data
 253 channels over Bluetooth connections, typically used for audio data.
 254 .Pp
 255 SCO socket options:
 256 .Bl -tag -width XXX
 257 .It Dv SO_SCO_MTU Op Ar uint16_t
 258 Maximum packet size for use on this link.
 259 This is read-only and will be set by the protocol code when a connection is made.
 260 Currently, due to limitations in the
 261 .Xr ubt 4
 262 driver, the SCO protocol code will only accept packets with
 263 exactly this size.
 264 .It Dv SO_SCO_HANDLE Op Ar uint16_t
 265 Connection handle for this link.
 266 This is read-only and provided for informational purposes only.
 267 .El
 268 .Pp
 269 SCO
 270 .Xr sysctl 8
 271 controls:
 272 .Bl -tag -width XXX
 273 .It Va net.bluetooth.sco.sendspace
 274 Default send buffer size for SCO sockets.
 275 .It Va net.bluetooth.sco.recvspace
 276 Default receive buffer size for SCO sockets.
 277 .El
 278 .El
 279 .Sh INFORMATION
 280 The following
 281 .Xr ioctl 2
 282 calls may be used to manipulate Bluetooth devices. The
 283 .Xr ioctl 2
 284 must be made on
 285 .Cm BTPROTO_HCI
 286 sockets. All of the requests take a
 287 .Ar btreq
 288 structure defined as follows as their parameter and unless otherwise
 289 specified, use the
 290 .Ar btr_name
 291 field to identify the device.
 292 .Bd -literal
 293 struct 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
 335 struct 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
 351 Get Bluetooth device Info. Given the device name, fill in the
 352 btreq structure including the address field for use with socket addressing
 353 as above.
 354 .It Dv SIOCGBTINFOA
 355 Get Bluetooth device Info from Address. Given the device address, fill in the
 356 btreq structure including the name field.
 357 .It Dv SIOCNBTINFO
 358 Next Bluetooth device Info . If name field is empty, the first device
 359 will be returned. Otherwise, the next device will be returned. Thus, you
 360 can cycle through all devices in the system.
 361 .It Dv SIOCSBTFLAGS
 362 Set Bluetooth device Flags. Not all flags are settable.
 363 .It Dv SIOCSBTPOLICY
 364 Set Bluetooth device Link Policy. Link Policy bits are defined in
 365 .In netbt/hci.h ,
 366 though you can only set bits that the device supports.
 367 .It Dv SIOCSBTPTYPE
 368 Set Bluetooth device Packet Types. You can only set packet types
 369 that the device supports.
 370 .It Dv SIOCGBTSTATS
 371 Read device statistics.
 372 .It Dv SIOCZBTSTATS
 373 Read device statistics, and zero them.
 374 .El
 375 .Pp
 376 Only 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
 387 The Bluetooth Protocol Stack was written for
 388 .Nx 4.0
 389 by
 390 .An Iain Hibbert
 391 under the sponsorship of Itronix, Inc and was imported into
 392 .Dx 1.11 .