NAME
bluetooth —
Bluetooth Protocol
Family
SYNOPSIS
#include <netbt/bluetooth.h>
#include <netbt/hci.h>
#include <netbt/l2cap.h>
#include <netbt/rfcomm.h>
DESCRIPTION
The Bluetooth Protocol Family
ADDRESSING
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).
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
Specification. Any user may open an HCI socket but there are limitations
on what unprivileged users can send and receive. The local address
specified 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 delivered to
the specified device, otherwise
sendto(2) should be used.
The bt_psm and bt_channel fields
in the sockaddr_bt structure are ignored 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, Command_Complete and Command_Status events only
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, Event packets only 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/Sevice
Multiplexer to specify when making connections. If the special value of
L2CAP_PSM_ANY
is bound when the
listen(2) call is made, the
next available PSM from the dynamic range above 0x1001 will be selected
and may be discovered using the
getsockname(2) call.
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 already
established, EINPROGRESS
may be returned, and
it is not possible 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
connection and make use of the bt_psm, and
bt_channel fields in the
sockaddr_bt structure. The channel number must be
between 1 and 30 inclusive except that if the special value
RFCOMM_CHANNEL_ANY
is bound, when the
listen(2) call is made, the
first unused channel for the relevant bdaddr will be allocated and may be
discovered using the
getsockname(2) call. 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 RFCOMM
connection establishment. If the RFCOMM connection is already
established, EINPROGRESS
may be returned, and
it is not possible 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. Currently, 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.
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 */
uint16_t btri_max_acl; /* max ACL buffers */
uint16_t btri_max_sco; /* max SCO buffers */
} btri;
struct {
uint8_t btrf_page0[HCI_FEATURES_SIZE]; /* basic */
uint8_t btrf_page1[HCI_FEATURES_SIZE]; /* extended page 1 */
uint8_t btrf_page2[HCI_FEATURES_SIZE]; /* extended page 2 */
} btrf;
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_max_acl btru.btri.btri_max_acl
#define btr_max_sco btru.btri.btri_max_sco
#define btr_features0 btru.btrf.btrf_page0
#define btr_features1 btru.btrf.btrf_page1
#define btr_features2 btru.btrf.btrf_page2
#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 */
#define BTF_NOOP_ON_RESET (1<<8) /* wait for No-op on reset */
#define BTF_INIT_COMMANDS (1<<9) /* waiting for supported commands */
#define BTF_MASTER (1<<10) /* request Master role */
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 name field is empty, the
first device will be returned. Otherwise, the next device will be returned
until no more devices are found when the call will fail, with error
ENXIO
. Thus, you can cycle through all devices in
the system.
-
-
SIOCSBTFLAGS
- Set Bluetooth device Flags. Not all flags are
settable.
-
-
SIOCGBTFEAT
- Get Bluetooth device Features. This returns the cached
basic (page 0) and extended (page 1 & 2) features.
-
-
SIOCSBTPOLICY
- Set Bluetooth device Link Policy. Link Policy bits are
defined in <netbt/hci.h>, though
you can only set bits that the device supports.
-
-
SIOCSBTPTYPE
- Set Bluetooth device Packet Types. You can only set packet
types that the device supports.
-
-
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),
bluetooth(3),
bcsp(4),
bt3c(4),
btbc(4),
btuart(4),
options(4),
ubt(4)
HISTORY
The Bluetooth Protocol Stack was written for
NetBSD 4.0
by
Iain Hibbert under the sponsorship of Itronix,
Inc.