share/man/man4/ubt.4

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