BLUETOOTH(4)              OpenBSD Programmer's Manual             BLUETOOTH(4)

NAME
     bluetooth - Bluetooth protocol family

SYNOPSIS
     #include <netbt/bluetooth.h>
     #include <netbt/hci.h>
     #include <netbt/l2cap.h>
     #include <netbt/rfcomm.h>

DESCRIPTION
     Bluetooth protocol family sockets all use a sockaddr_bt structure which
     contains a Bluetooth Device Address (BDADDR).  This consists of a six
     byte string in least significant byte first order.

           struct sockaddr_bt {
                   uint8_t         bt_len;
                   sa_family_t     bt_family;
                   bdaddr_t        bt_bdaddr;
                   uint16_t        bt_psm;
                   uint8_t         bt_channel;
           };

     The local address used by the socket can be set with bind(2).

     OpenBSD provides support for the following devices:

   Human Interface Devices
        btkbd(4)      Bluetooth keyboard support
        btms(4)       Bluetooth mouse support

PROTOCOLS
     Protocols included are:

     BTPROTO_HCI
       This gives raw access to the Host Controller Interface of local devices
       using the HCI protocol as described in the Bluetooth Core Specifica-
       tion.  Any user may open an HCI socket but there are limitations on
       what unprivileged users can send and receive.  The local address speci-
       fied by bind(2) may be used to select the device that the socket will
       receive packets from.  If BDADDR_ANY is specified then the socket will
       receive packets from all devices on the system.  connect(2) may be used
       to create connections such that packets sent with send(2) will be de-
       livered to the specified device, otherwise sendto(2) should be used.

       The bt_psm and bt_channel fields in the sockaddr_bt structure are ig-
       nored by HCI protocol code and should be set to zero.

       HCI socket options:

       SO_HCI_EVT_FILTER [struct hci_filter]
         This filter controls which events will be received at the socket.
         See <netbt/hci.h> for available events.  By default, only Com-
         mand_Complete and Command_Status events are enabled.

       SO_HCI_PKT_FILTER [struct hci_filter]
         This filter controls the type of packets that will be received at the
         socket.  By default, only Event packets are enabled.

       SO_HCI_DIRECTION [int]
         When set, this enables control messages on packets received at the
         socket indicating the direction of travel of the packet.

       HCI sysctl(8) controls:

       net.bluetooth.hci.sendspace
            Default send buffer size for HCI sockets.

       net.bluetooth.hci.recvspace
            Default receive buffer size for HCI sockets.

       net.bluetooth.hci.acl_expiry
            If set, this is the time in seconds after which unused ACL data
            connections will be expired.  If zero, connections will not be
            closed.

       net.bluetooth.hci.memo_expiry
            Time, in seconds, that the system will keep records of Bluetooth
            devices in the vicinity after an Inquiry Response packet has been
            received.  This information is used for routing purposes.

       net.bluetooth.hci.eventq_max
            The maximum number of packets on the low level Event queue.

       net.bluetooth.hci.aclrxq_max
            The maximum number of packets on the low level ACL queue.

       net.bluetooth.hci.scorxq_max
            The maximum number of packets on the low level SCO queue.

     BTPROTO_L2CAP
       L2CAP sockets give sequential packet access over channels to other
       Bluetooth devices and make use of the bt_psm field in the sockaddr_bt
       structure to select the Protocol/Service Multiplexer to specify when
       making connections.

       L2CAP socket options:

       SO_L2CAP_IMTU [uint16_t]
            Incoming MTU.

       SO_L2CAP_OMTU [uint16_t]
            Outgoing MTU (read-only).

       SO_L2CAP_LM [int]
            Link Mode.  The following bits may be set:

            L2CAP_LM_AUTH         Request authentication (pairing).
            L2CAP_LM_ENCRYPT      Request encryption (includes auth).
            L2CAP_LM_SECURE       Request secured link (encryption, plus
                                  change link key).

            Link mode settings will be applied to the baseband link during
            L2CAP connection establishment.  If the L2CAP connection is al-
            ready established, EINPROGRESS may be returned, and it is not pos-
            sible to guarantee that data already queued (from either end) will
            not be delivered.  If the mode change fails, the L2CAP connection
            will be aborted.

       L2CAP sysctl(8) controls:

       net.bluetooth.l2cap.sendspace
            Default send buffer size for L2CAP sockets.

       net.bluetooth.l2cap.recvspace
            Default receive buffer size for L2CAP sockets.

       net.bluetooth.l2cap.rtx
            Response Timeout eXpiry for L2CAP signals.

       net.bluetooth.l2cap.ertx
            Extended Response Timeout eXpiry for L2CAP signals.

     BTPROTO_RFCOMM
       RFCOMM sockets provide streamed data over Bluetooth connections and
       make use of the bt_psm and bt_channel fields in the sockaddr_bt struc-
       ture.  The channel number must be between 1 and 30 inclusive.  If no
       PSM is specified, a default value of L2CAP_PSM_RFCOMM (0x0003) will be
       used.

       RFCOMM socket options:

       SO_RFCOMM_MTU [uint16_t]
            Maximum Frame Size to use for this link.

       SO_RFCOMM_LM [int]
            Link Mode.  The following bits may be set at any time:

            RFCOMM_LM_AUTH         Request authentication (pairing).
            RFCOMM_LM_ENCRYPT      Request encryption (includes auth).
            RFCOMM_LM_SECURE       Request secured link (encryption, plus
                                   change link key).

            Link mode settings will be applied to the baseband link during RF-
            COMM connection establishment.  If the RFCOMM connection is al-
            ready established, EINPROGRESS may be returned, and it is not pos-
            sible to guarantee that data already queued (from either end) will
            not be delivered.  If the mode change fails, the RFCOMM connection
            will be aborted.

       RFCOMM sysctl(8) controls:

       net.bluetooth.rfcomm.sendspace
            Default send buffer size for RFCOMM sockets.

       net.bluetooth.rfcomm.recvspace
            Default receive buffer size for RFCOMM sockets.

       net.bluetooth.rfcomm.default_mtu
            Maximum Frame Size (N1).

       net.bluetooth.ack_timeout
            Acknowledgement Timer (T1).

       net.bluetooth.mcc_timeout
            Response Timer for Multiplexer Control Channel (T2).

     BTPROTO_SCO
       SCO sockets provide sequential packet access to time sensitive data
       channels over Bluetooth connections, typically used for audio data.

       SCO socket options:

       SO_SCO_MTU [uint16_t]
            Maximum packet size for use on this link.  This is read-only and
            will be set by the protocol code when a connection is made.  Cur-
            rently, due to limitations in the ubt(4) driver, the SCO protocol
            code will only accept packets with exactly this size.

       SO_SCO_HANDLE [uint16_t]
            Connection handle for this link.  This is read-only and provided
            for informational purposes only.

       SCO sysctl(8) controls:

       net.bluetooth.sco.sendspace
            Default send buffer size for SCO sockets.

       net.bluetooth.sco.recvspace
            Default receive buffer size for SCO sockets.

INFORMATION
     The following ioctl(2) calls may be used to manipulate Bluetooth devices.
     The ioctl(2) must be made on BTPROTO_HCI sockets.  All of the requests
     take a btreq structure defined as follows as their parameter and unless
     otherwise specified, use the btr_name field to identify the device.

     struct btreq {
         char btr_name[HCI_DEVNAME_SIZE];    /* device name */

         union {
             struct {
                 bdaddr_t btri_bdaddr;       /* device bdaddr */
                 uint16_t btri_flags;        /* flags */
                 uint16_t btri_num_cmd;      /* # of free cmd buffers */
                 uint16_t btri_num_acl;      /* # of free ACL buffers */
                 uint16_t btri_num_sco;      /* # of free SCO buffers */
                 uint16_t btri_acl_mtu;      /* ACL mtu */
                 uint16_t btri_sco_mtu;      /* SCO mtu */
                 uint16_t btri_link_policy;  /* Link Policy */
                 uint16_t btri_packet_type;  /* Packet Type */
             } btri;
             struct bt_stats btrs;   /* unit stats */
         } btru;
     };

     #define btr_flags       btru.btri.btri_flags
     #define btr_bdaddr      btru.btri.btri_bdaddr
     #define btr_num_cmd     btru.btri.btri_num_cmd
     #define btr_num_acl     btru.btri.btri_num_acl
     #define btr_num_sco     btru.btri.btri_num_sco
     #define btr_acl_mtu     btru.btri.btri_acl_mtu
     #define btr_sco_mtu     btru.btri.btri_sco_mtu
     #define btr_link_policy btru.btri.btri_link_policy
     #define btr_packet_type btru.btri.btri_packet_type
     #define btr_stats       btru.btrs

     /* btr_flags */
     #define BTF_UP                  (1<<0)  /* unit is up */
     #define BTF_RUNNING             (1<<1)  /* unit is running */
     #define BTF_XMIT_CMD            (1<<2)  /* transmitting CMD packets */
     #define BTF_XMIT_ACL            (1<<3)  /* transmitting ACL packets */
     #define BTF_XMIT_SCO            (1<<4)  /* transmitting SCO packets */
     #define BTF_INIT_BDADDR         (1<<5)  /* waiting for bdaddr */
     #define BTF_INIT_BUFFER_SIZE    (1<<6)  /* waiting for buffer size */
     #define BTF_INIT_FEATURES       (1<<7)  /* waiting for features */

     struct bt_stats {
             uint32_t        err_tx;
             uint32_t        err_rx;
             uint32_t        cmd_tx;
             uint32_t        evt_rx;
             uint32_t        acl_tx;
             uint32_t        acl_rx;
             uint32_t        sco_tx;
             uint32_t        sco_rx;
             uint32_t        byte_tx;
             uint32_t        byte_rx;
     };


     SIOCGBTINFO    Get Bluetooth device info.  Given the device name, fill in
                    the btreq structure including the address field for use
                    with socket addressing as above.

     SIOCGBTINFOA   Get Bluetooth device info from address.  Given the device
                    address, fill in the btreq structure including the name
                    field.

     SIOCNBTINFO    Next Bluetooth device info.  If the name field is empty,
                    the first device will be returned.  Otherwise, the next
                    device will be returned.  This can be used to cycle
                    through all devices in the system.

     SIOCSBTFLAGS   Set Bluetooth device flags.  Not all flags can be set.

     SIOCSBTPOLICY  Set Bluetooth device link policy.  Link policy bits are
                    defined in <netbt/hci.h>, though bits can only be set if
                    the device supports it.

     SIOCSBTPTYPE   Set Bluetooth device packet types.  Only packet types that
                    the device supports can be set.

     SIOCGBTSTATS   Read device statistics.

     SIOCZBTSTATS   Read device statistics, and zero them.

     Only the super-user may change device configurations.

SEE ALSO
     bind(2), getsockname(2), options(4), ubt(4)

HISTORY
     The Bluetooth protocol stack was written for NetBSD 4.0 by Iain Hibbert
     under the sponsorship of Itronix, Inc. and ported to OpenBSD 4.2 by Uwe
     Stuehler <uwe@openbsd.org>.

OpenBSD 4.7                    January 14, 2010                              5
