NetBSD/usr.sbin/btconfig/btconfig.8

.\" $NetBSD: btconfig.8,v 1.18 2012/03/15 22:35:03 njoly Exp $
.\"
.\" Copyright (c) 2006 Itronix Inc.
.\" All rights reserved.
.\"
.\" Written by Iain Hibbert for Itronix Inc.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of Itronix Inc. may not be used to endorse
.\"    or promote products derived from this software without specific
.\"    prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY ITRONIX INC. ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd October 11, 2010
.Dt BTCONFIG 8
.Os
.Sh NAME
.Nm btconfig
.Nd configure bluetooth devices
.Sh SYNOPSIS
.Nm
.Op Fl svz
.Oo
.Ar device
.Op Ar parameters
.Oc
.Nm
.Op Fl l
.Sh DESCRIPTION
.Nm
is used to configure Bluetooth devices.
If the
.Ar device
is given, but no parameters, then
.Nm
will print information about the device.
If no
.Ar device
is given, a basic list of devices will be printed.
.Pp
When the
.Fl l
flag is used, just the device names will be printed.
.Sh COMMANDS
The following parameters may be specified with
.Nm :
.Bl -tag -width xxxxxxxxxxx
.It Cm up
Enable Bluetooth Device.
.It Cm down
Disable Bluetooth Device.
.It Cm pscan
Enable Page Scan.
This enables incoming connections to the device.
.It Cm -pscan
Disable Page Scan.
.It Cm iscan
Enable Inquiry Scan.
This puts the device in Discoverable mode.
.It Cm -iscan
Disable Inquiry Scan.
.It Cm encrypt
Enable encryption.
This will cause the device to request encryption on all baseband
connections, and will only work if authentication is also enabled.
.It Cm -encrypt
Disable encryption.
.It Cm auth
Enable authentication.
This will cause the device to request authentication
for all baseband connections.
.It Cm -auth
Disable authentication.
.It Cm switch
Enable Role Switching.
In a Bluetooth piconet there is one Master and up to seven Slaves, and
normally the device that initiates a connection will take the Master role.
Enabling this option allows remote devices to switch connection roles.
.It Cm -switch
Disable Role Switching.
.It Cm master
Request the Master role when accepting connections.
.It Cm -master
Do not request Master role.
.It Cm hold
Enable Hold Mode.
.It Cm -hold
Disable Hold Mode.
.It Cm sniff
Enable Sniff Mode.
.It Cm -sniff
Disable Sniff Mode.
.It Cm park
Enable Park Mode.
.It Cm -park
Disable Park Mode.
.It Cm name Ar name
Set human readable name of device.
.It Cm ptype Ar type
Set packet types.
.Ar type
is a 16 bit hex value specifying packet types that will be requested
by outgoing ACL connections.
By default, all packet types that the device supports are enabled,
see bluetooth specifications for more information if you want to change this.
.It Cm class Ar class
Set class of device.
.Ar class
is a 6 digit hex value the value of which declares the device capabilities.
See the
.Qq Assigned Numbers - Baseband
document at
.Lk http://www.bluetooth.com/
for details of constructing a Class of Device value.
As a starter, 0x020104 means Desktop Computer, with Networking
available.
.It Cm fixed
Set fixed pin type.
.It Cm variable
Set variable pin type.
.It Cm inquiry
Perform device Discovery from the specified device and print details.
.It Cm imode Ar type
Set inquiry mode type to control which event formats are generated during
a device inquiry.
The
.Ar type
can be:
.Bl -tag -width xxxxxx
.It std
Standard Inquiry Result Event format.
.It rssi
Enable Remote Signal Strength Indicator (RSSI) in inquiry results.
This will only work if the device features indicate
.Aq RSSI with inquiry result .
.It ext
Inquiry Result with RSSI format or Extended Inquiry Result fomat.
This will only work where the device features indicate
.Aq extended inquiry ,
and the Extended Inquiry Result will only occur when the remote device
provides the extended information.
.El
.It Cm reset
Perform a hard reset on the device and re-initialise system state.
.It Cm voice
Set Voice Setting.
[This should be 0x0060 for now]
.It Cm pto
Set Page Timeout value.
This is a decimal value in milliseconds, indicating how long the device
will attempt to page another device when opening baseband connections.
.It Cm scomtu
Change SCO mtu value.
This is a decimal value, see
.Xr ubt 4
for reasons why you may need to do this.
.El
.Pp
All parameters are parsed before any device operations take place.
Each time the
.Fl v
flag is given, verbosity levels will be increased.
.Pp
Super-user privileges are required to change device configurations.
.Sh DIAGNOSTICS
Messages indicating the specified device does not exist, the
requested address is unknown, or the user is not privileged and
tried to alter an device's configuration.
.Sh SEE ALSO
.Xr bcsp 4 ,
.Xr bluetooth 4 ,
.Xr bt3c 4 ,
.Xr btbc 4 ,
.Xr btuart 4 ,
.Xr sbt 4 ,
.Xr ubt 4
.Sh HISTORY
The
.Nm
command was written for
.Nx 4.0
by
.An Iain Hibbert
under the sponsorship of Itronix, Inc.
.Sh BUGS
The output is very messy.