xref: /netbsd-src/share/man/man4/bluetooth.4 (revision ce2c90c7c172d95d2402a5b3d96d8f8e6d138a21) 
1.\"	$NetBSD: bluetooth.4,v 1.4 2006/09/02 23:52:45 wiz 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 August 27, 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 sequential packet access to time sensitive data
196channels over Bluetooth connections, typically used for audio data.
197.Pp
198SCO socket options:
199.Bl -tag -width XXX
200.It Dv SO_SCO_MTU Op Ar uint16_t
201Maximum packet size for use on this link.
202This is read-only and will be set by the protocol code when a connection is made.
203Currently, due to limitations in the
204.Xr ubt 4
205driver, the SCO protocol code will only accept packets with
206exactly this size.
207.It Dv SO_SCO_HANDLE Op Ar uint16_t
208Connection handle for this link.
209This is read-only and provided for informational purposes only.
210.El
211.Pp
212SCO
213.Xr sysctl 8
214controls:
215.Bl -tag -width XXX
216.It Dv net.bluetooth.sco.sendspace
217Default send buffer size for SCO sockets.
218.It Dv net.bluetooth.sco.recvspace
219Default receive buffer size for SCO sockets.
220.El
221.El
222.Sh INFORMATION
223The following
224.Xr ioctl 2
225calls may be used to manipulate Bluetooth devices. The
226.Xr ioctl 2
227must be made on
228.Cm BTPROTO_HCI
229sockets. All of the requests take a
230.Ar btreq
231structure defined as follows as their parameter and unless otherwise
232specified, use the
233.Ar btr_name
234field to identify the device.
235.Bd -literal -offset
236struct btreq {
237    char btr_name[HCI_DEVNAME_SIZE];	/* device name */
238
239    union {
240	struct {
241	    bdaddr_t btri_bdaddr;	/* device bdaddr */
242	    uint16_t btri_flags;	/* flags */
243	    uint16_t btri_num_cmd;	/* # of free cmd buffers */
244	    uint16_t btri_num_acl;	/* # of free ACL buffers */
245	    uint16_t btri_num_sco;	/* # of free SCO buffers */
246	    uint16_t btri_acl_mtu;	/* ACL mtu */
247	    uint16_t btri_sco_mtu;	/* SCO mtu */
248	    uint16_t btri_link_policy;	/* Link Policy */
249	    uint16_t btri_packet_type;	/* Packet Type */
250	} btri;
251	struct bt_stats btrs;   /* unit stats */
252    } btru;
253};
254
255#define btr_flags	btru.btri.btri_flags
256#define btr_bdaddr	btru.btri.btri_bdaddr
257#define btr_num_cmd	btru.btri.btri_num_cmd
258#define btr_num_acl	btru.btri.btri_num_acl
259#define btr_num_sco	btru.btri.btri_num_sco
260#define btr_acl_mtu	btru.btri.btri_acl_mtu
261#define btr_sco_mtu	btru.btri.btri_sco_mtu
262#define btr_link_policy btru.btri.btri_link_policy
263#define btr_packet_type btru.btri.btri_packet_type
264#define btr_stats	btru.btrs
265
266/* btr_flags */
267#define BTF_UP			(1\*[Lt]\*[Lt]0)	/* unit is up */
268#define BTF_RUNNING		(1\*[Lt]\*[Lt]1)	/* unit is running */
269#define BTF_XMIT_CMD		(1\*[Lt]\*[Lt]2)	/* transmitting CMD packets */
270#define BTF_XMIT_ACL		(1\*[Lt]\*[Lt]3)	/* transmitting ACL packets */
271#define BTF_XMIT_SCO		(1\*[Lt]\*[Lt]4)	/* transmitting SCO packets */
272#define BTF_INIT_BDADDR		(1\*[Lt]\*[Lt]5)	/* waiting for bdaddr */
273#define BTF_INIT_BUFFER_SIZE	(1\*[Lt]\*[Lt]6)	/* waiting for buffer size */
274#define BTF_INIT_FEATURES	(1\*[Lt]\*[Lt]7)	/* waiting for features */
275
276struct bt_stats {
277	uint32_t	err_tx;
278	uint32_t	err_rx;
279	uint32_t	cmd_tx;
280	uint32_t	evt_rx;
281	uint32_t	acl_tx;
282	uint32_t	acl_rx;
283	uint32_t	sco_tx;
284	uint32_t	sco_rx;
285	uint32_t	byte_tx;
286	uint32_t	byte_rx;
287};
288
289.Ed
290.Bl -tag -width SIOCGBTPOLICY
291.It Dv SIOCGBTINFO
292Get Bluetooth device Info. Given the device name, fill in the
293btreq structure including the address field for use with socket addressing
294as above.
295.It Dv SIOCGBTINFOA
296Get Bluetooth device Info from Address. Given the device address, fill in the
297btreq structure including the name field.
298.It Dv SIOCNBTINFO
299Next Bluetooth device Info . If name field is empty, the first device
300will be returned. Otherwise, the next device will be returned. Thus, you
301can cycle through all devices in the system.
302.It Dv SIOCSBTFLAGS
303Set Bluetooth device Flags. Not all flags are settable.
304.It Dv SIOCSBTPOLICY
305Set Bluetooth device Link Policy. Link Policy bits are defined in
306.In netbt/hci.h ,
307though you can only set bits that the device supports.
308.It Dv SIOCSBTPTYPE
309Set Bluetooth device Packet Types. You can only set packet types
310that the device supports.
311.It Dv SIOCGBTSTATS
312Read device statistics.
313.It Dv SIOCZBTSTATS
314Read device statistics, and zero them.
315.El
316.Pp
317Only the super-user may change device configurations.
318.Sh SEE ALSO
319.Xr bind 2 ,
320.Xr getsockname 2 ,
321.Xr bluetooth 3 ,
322.Xr bt3c 4 ,
323.Xr options 4 ,
324.Xr ubt 4
325.Sh HISTORY
326The Bluetooth Protocol Stack was written for
327.Nx 4.0
328by
329.An Iain Hibbert
330under the sponsorship of Itronix, Inc.
331