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:

HCI sysctl(8) controls:

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:

L2CAP sysctl(8) controls:

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:

RFCOMM sysctl(8) controls:

BTPROTO_SCO

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

SCO socket options:

SCO sysctl(8) controls:

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 */ 
	    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 */ 
	} 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_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; 
};

Only the super-user may change device configurations.

HISTORY

The Bluetooth Protocol Stack was written for NetBSD 4.0 by Iain Hibbert under the sponsorship of Itronix, Inc.