1.\" $NetBSD: ubt.4,v 1.5 2006/09/02 23:54:23 wiz Exp $ 2.\" $DragonFly: src/share/man/man4/ubt.4,v 1.3 2008/02/03 06:33:00 hasso Exp $ 3.\" 4.\" Copyright (c) 2006 Itronix Inc. 5.\" All rights reserved. 6.\" 7.\" Written by Iain Hibbert for Itronix Inc. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. The name of Itronix Inc. may not be used to endorse 18.\" or promote products derived from this software without specific 19.\" prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY ITRONIX INC. ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 23.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 24.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY 25.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 26.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 28.\" ON ANY THEORY OF LIABILITY, WHETHER IN 29.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 30.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31.\" POSSIBILITY OF SUCH DAMAGE. 32.\" 33.Dd August 27, 2006 34.Dt UBT 4 35.Os 36.Sh NAME 37.Nm ubt 38.Nd USB Bluetooth driver 39.Sh SYNOPSIS 40To compile this driver into the kernel, 41place the following lines in your 42kernel configuration file: 43.Bd -ragged -offset indent 44.Cd "device ubt" 45.Ed 46.Pp 47Alternatively, to load the driver as a 48module at boot time, place the following line in 49.Xr loader.conf 5 : 50.Bd -literal -offset indent 51ubt_load="YES" 52.Ed 53.Sh DESCRIPTION 54The 55.Nm 56driver provides support for USB Bluetooth dongles 57to the Bluetooth protocol stack. 58.Pp 59USB Bluetooth dongles provide two interfaces, both of which the 60.Nm 61driver claims. 62The second interface is used for Isochronous data and will have 63several alternate configurations regarding bandwidth consumption, 64which can be set using the hw.ubtN.config 65.Xr sysctl 8 66variable. 67The number of alternate configurations is indicated by the value 68in the hw.ubtN.alt_config variable, and the isoc frame size for the current 69configuration is shown in the hw.ubtN.sco_rxsize and hw.ubtN.sco_txsize 70variables. 71.Pp 72By default, configuration 0 is selected, which means that no bandwidth 73is used on the Isochronous interface and no SCO data can be sent. 74Consult the Bluetooth USB specification at https://www.bluetooth.org/ 75for complete instructions on setting bandwidth consumption. 76The following extract may be 77useful as a general guidance though details may differ between manufacturers. 78.Pp 79.Bl -tag -compact -width XXX 80.It 0 81No active voice channels 82.It 1 83One voice channel with 8-bit encoding 84.It 2 85Two voice channels with 8-bit encoding, or one voice channel with 8616-bit encoding. 87.It 3 88Three voice channels with 8-bit encoding 89.It 4 90Two voice channels with 16-bit encoding 91.It 5 92Three voice channels with 16-bit encoding 93.El 94.Sh SEE ALSO 95.Xr bluetooth 4 96.\".Xr uhub 4 , 97.Xr sysctl 8 98.Sh HISTORY 99This 100.Nm 101device driver was originally a character device written by 102.An David Sainty 103and 104.An Lennart Augustsson . 105It was rewritten to support socket based Bluetooth access for 106.Nx 4.0 107by 108.An Iain Hibbert . 109The 110.Nm 111driver was imported into 112.Dx 1.11 . 113.Sh CAVEATS 114Isochronous data is seemingly not well supported over USB in the current 115system and to get SCO working, you may have to calculate the SCO packet 116size that the stack will use. 117This is the sco_mtu value reported by the 118.Xr btconfig 8 119command, and when combined with the SCO header (3 bytes) should 120fit exactly into an integer number of Isochronous data frames where 121the frame size is indicated by the 122.Sq hw.ubtN.sco_txsize 123sysctl variable. 124.Pp 125For example: I want one voice channel (which is all that is supported, 126for now) so am using configuration #2, with a frame length of 17 127bytes. 128This gives possible values of: 129.Pp 130.Dl "(17 * 1) - 3 = 14" 131.Dl "(17 * 2) - 3 = 31" 132.Dl "(17 * 3) - 3 = 48" 133.Dl "(17 * 4) - 3 = 65" 134.Dl "(17 * 5) - 3 = 82" 135.Dl "etc." 136.Pp 137.Xr btconfig 8 138shows the maximum SCO payload as 64 bytes, so I am using the next smaller 139size of 48, to minimize the overhead of the 3 header bytes. 140.Pp 141The SCO packet size can be changed using the 142.Sq scomtu 143option to 144.Xr btconfig 8 . 145.Pp 146The failure mode is that the USB Bluetooth dongle locks up though 147generally removal/reinsertion will clear the problem. 148.Sh BUGS 149The Isochronous configuration can only be changed when the device is not 150marked up. 151