1.\" $NetBSD: ubt.4,v 1.5 2006/09/02 23:54:23 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.Dd August 27, 2006 33.Dt UBT 4 34.Os 35.Sh NAME 36.Nm ubt 37.Nd USB Bluetooth driver 38.Sh SYNOPSIS 39To compile this driver into the kernel, 40place the following lines in your 41kernel configuration file: 42.Bd -ragged -offset indent 43.Cd "device ubt" 44.Ed 45.Pp 46Alternatively, to load the driver as a 47module at boot time, place the following line in 48.Xr loader.conf 5 : 49.Bd -literal -offset indent 50ubt_load="YES" 51.Ed 52.Sh DESCRIPTION 53The 54.Nm 55driver provides support for USB Bluetooth dongles 56to the Bluetooth protocol stack. 57.Pp 58USB Bluetooth dongles provide two interfaces, both of which the 59.Nm 60driver claims. 61The second interface is used for Isochronous data and will have 62several alternate configurations regarding bandwidth consumption, 63which can be set using the hw.ubtN.config 64.Xr sysctl 8 65variable. 66The number of alternate configurations is indicated by the value 67in the hw.ubtN.alt_config variable, and the isoc frame size for the current 68configuration is shown in the hw.ubtN.sco_rxsize and hw.ubtN.sco_txsize 69variables. 70.Pp 71By default, configuration 0 is selected, which means that no bandwidth 72is used on the Isochronous interface and no SCO data can be sent. 73Consult the Bluetooth USB specification at https://www.bluetooth.org/ 74for complete instructions on setting bandwidth consumption. 75The following extract may be 76useful as a general guidance though details may differ between manufacturers. 77.Pp 78.Bl -tag -compact -width XXX 79.It 0 80No active voice channels 81.It 1 82One voice channel with 8-bit encoding 83.It 2 84Two voice channels with 8-bit encoding, or one voice channel with 8516-bit encoding. 86.It 3 87Three voice channels with 8-bit encoding 88.It 4 89Two voice channels with 16-bit encoding 90.It 5 91Three voice channels with 16-bit encoding 92.El 93.Sh SEE ALSO 94.Xr bluetooth 4 , 95.\".Xr uhub 4 , 96.Xr sysctl 8 97.Sh HISTORY 98This 99.Nm 100device driver was originally a character device written by 101.An David Sainty 102and 103.An Lennart Augustsson . 104It was rewritten to support socket based Bluetooth access for 105.Nx 4.0 106by 107.An Iain Hibbert . 108The 109.Nm 110driver was imported into 111.Dx 1.11 . 112.Sh CAVEATS 113Isochronous data is seemingly not well supported over USB in the current 114system and to get SCO working, you may have to calculate the SCO packet 115size that the stack will use. 116This is the sco_mtu value reported by the 117.Xr btconfig 8 118command, and when combined with the SCO header (3 bytes) should 119fit exactly into an integer number of Isochronous data frames where 120the frame size is indicated by the 121.Sq hw.ubtN.sco_txsize 122sysctl variable. 123.Pp 124For example: I want one voice channel (which is all that is supported, 125for now) so am using configuration #2, with a frame length of 17 126bytes. 127This gives possible values of: 128.Pp 129.Dl "(17 * 1) - 3 = 14" 130.Dl "(17 * 2) - 3 = 31" 131.Dl "(17 * 3) - 3 = 48" 132.Dl "(17 * 4) - 3 = 65" 133.Dl "(17 * 5) - 3 = 82" 134.Dl "etc." 135.Pp 136.Xr btconfig 8 137shows the maximum SCO payload as 64 bytes, so I am using the next smaller 138size of 48, to minimize the overhead of the 3 header bytes. 139.Pp 140The SCO packet size can be changed using the 141.Sq scomtu 142option to 143.Xr btconfig 8 . 144.Pp 145The failure mode is that the USB Bluetooth dongle locks up though 146generally removal/reinsertion will clear the problem. 147.Sh BUGS 148The Isochronous configuration can only be changed when the device is not 149marked up. 150