path: root/usr/src/man/man1m/wusbadm.1m

'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH WUSBADM 1M "Apr 22, 2009"
.SH NAME
wusbadm \- administer wireless USB hosts and devices
.SH SYNOPSIS
.LP
.nf
\fBwusbadm\fR list [\fB-h\fR | \fB-d\fR] [\fB-o\fR \fIfield\fR[,...]]
.fi

.LP
.nf
\fBwusbadm\fR associate [\fB-h\fR \fIhost-id\fR] [[\fB-c\fR [\fB-f\fR]] | \fB-n\fR] [\fB-o\fR]
.fi

.LP
.nf
\fBwusbadm\fR remove-dev [[\fB-d\fR \fIdev-id\fR] | [\fB-h\fR \fIhost-id\fR]] [\fB-f\fR]
.fi

.LP
.nf
\fBwusbadm\fR remove-host [\fB-h\fR \fIhost-id\fR] [\fB-f\fR]
.fi

.LP
.nf
\fBwusbadm\fR enable-host [\fB-h\fR \fIhost-id\fR]
.fi

.LP
.nf
\fBwusbadm\fR disable-host [\fB-h\fR \fIhost-id\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBwusbadm\fR command provides a command line interface to administer
wireless USB hosts and devices, including listing hosts and devices
information, associating the host with the device, removing host or device
information from the system, and enabling or disabling hosts.
.sp
.LP
Before connecting a wireless USB device to a host for the first time, a user
needs to set up the association information between them by running the wusbadm
associate subcommand. Following this, the user can  connect or disconnect the
device by simply turning on or off the device radio (perhaps a button on the
device, depending on the manufacturer). The device radio's turning on and off
are analogous to the hotplugging of wired USB devices.
.sp
.LP
The association information created by the \fBassociate\fR subcommand is
maintained in the non-volatile memory of the device and the host. On the host,
it can be removed by the \fBremove-dev\fR or \fBremove-host\fR subcommands. On
the device, it can be overwritten by another association. For a device is
associated with multiple hosts, the way that the device prioritizes or updates
its multiple records of association depends on the manufacturer.
.sp
.LP
Each \fBwusbadm\fR subcommand operates on one of the following objects:
.sp
.ne 2
.na
\fB\fIhost-id\fR\fR
.ad
.sp .6
.RS 4n
A two-digit number (in the range from 01 to 99) that  uniquely identifies a
wireless USB host on a system. It is generated when the \fBwusb\fR service (see
\fBNOTES\fR section) is successfully enabled and finds the host instance for
the first time. The number is maintained until removed by \fBremove-host\fR
subcommand.
.RE

.sp
.ne 2
.na
\fB\fIdev-id\fR\fR
.ad
.sp .6
.RS 4n
A five-digit number that uniquely identifies a wireless USB device associated
with a wireless USB host. The first two digits are the host-id of the wireless
USB host with which the device is associated. The last three-digit number (in
the range from 001 to 999) is used to differentiate devices associated with the
same host. In the five-digit number, the first two digits and the last three
are separated by a dot.
.sp
\fIdev-id\fR is generated during the device association process. It is
maintained for the device until removed by the \fBremove-dev\fR subcommand or
until updated by another association between the same host and device.
.RE

.SH SUB-COMMANDS
.sp
.LP
The following subcommands are supported. Except for the \fBlist\fR subcommand,
each subcommand displays subcommand-specific usage information if you run it
without any options or operands.
.sp
.ne 2
.na
\fB\fBlist\fR [\fB-h\fR | \fB-d\fR] [\fB-o\fR \fIfield\fR[,...]]\fR
.ad
.sp .6
.RS 4n
List wireless USB hosts and devices on a system, displaying the ID, state, and
type for all hosts and devices. By default, \fBlist\fR will list all hosts and
devices and all fields. Each host and its devices will be displayed as a group.
This subcommand supports the following options.
.sp
.ne 2
.na
\fB\fB-o\fR \fIfield\fR[,...], \fB--output\fR=\fIfield\fR[,...]\fR
.ad
.sp .6
.RS 4n
A case-insensitive, comma-separated list of output fields to display. The field
name must be one of the fields listed below, or the special value \fBall\fR to
display all fields. By default (without \fB-o\fR), \fBlist\fR displays all
fields.
.sp
.ne 2
.na
\fB\fBID\fR\fR
.ad
.sp .6
.RS 4n
The \fIhost-id\fR or \fIdev-id\fR.
.RE

.sp
.ne 2
.na
\fB\fBTYPE\fR\fR
.ad
.sp .6
.RS 4n
The \fBhost\fR or \fBdevice\fR types.
.sp
For \fBhost\fR, the types include \fBwhci\fR (on-board host) and \fBhwa\fR
(hot-pluggable host).
.sp
For \fBdevice\fR, the types include \fBkbd\fR, \fBmouse\fR, \fBstorage\fR,
\fBprinter\fR, \fBdwa\fR (wireless USB hub), \fBaudio\fR, \fBvideo\fR, and so
forth.
.RE

.sp
.ne 2
.na
\fB\fBSTATE\fR\fR
.ad
.sp .6
.RS 4n
There are the following states for the host:
.sp
.ne 2
.na
\fB\fBenabled\fR\fR
.ad
.sp .6
.RS 4n
The host is ready to work or is already working, including performing
association, connecting devices, performing data communication, and so forth.
.RE

.sp
.ne 2
.na
\fB\fBdisabled\fR\fR
.ad
.sp .6
.RS 4n
The host is not ready to work with any devices and no devices are connected to
the host. It might be stopped by a \fBdisable-host\fR subcommand, or the host
might not be available because it is physically unplugged or because of a
driver detach.
.RE

.sp
.ne 2
.na
\fB\fBdisconnected\fR\fR
.ad
.sp .6
.RS 4n
The host is not attached to the system.  An \fBhwa\fR device is in this state
after it is unplugged from the USB port on the system.
.RE

There are the folllowing states for the device:
.sp
.ne 2
.na
\fB\fBconnected\fR\fR
.ad
.sp .6
.RS 4n
The device is connected with a host and ready to be opened, or it is already
opened and working. By default, the device tries to get into this state after
the association is complete and its radio is turned on.
.RE

.sp
.ne 2
.na
\fB\fBdisconnected\fR\fR
.ad
.sp .6
.RS 4n
The device is not connected to a host or not ready to be opened yet. The device
might be in this state because its radio is out of range, power is off,
hardware problems, and so forth.
.RE

.RE

.RE

.sp
.ne 2
.na
\fB\fB-h\fR, \fB--host\fR\fR
.ad
.sp .6
.RS 4n
List the wireless USB hosts only.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR, \fB--device\fR\fR
.ad
.sp .6
.RS 4n
List the wireless USB devices only.
.RE

.RE

.sp
.ne 2
.na
\fB\fBassociate\fR [\fB-h\fR \fIhost-id\fR] [[\fB-c\fR [\fB-f\fR]] | \fB-n\fR]
[\fB-o\fR]\fR
.ad
.sp .6
.RS 4n
Designate the host to start an association process. Association is the initial
step before a wireless USB device can be connected with a wireless USB host.
.sp
There are two association models:
.sp
.ne 2
.na
\fBCable association\fR
.ad
.sp .6
.RS 4n
A user connects the device and host with a USB cable first, and then run this
subcommand to designate the host to setup the association information with the
device. After the association is in effect, the cable is no longer needed in
the subsequent connections between the same host and the device.
.RE

.sp
.ne 2
.na
\fBNumeric association\fR
.ad
.sp .6
.RS 4n
A user turns on the device radio and runs this subcommand to designate the host
to talk to the device. A short number is then displayed on both host and
device. The user compares the values of the numbers and confirms on both the
host and the device.
.RE

Following a successful association, the associated USB host and device are able
to proceed with the wireless connection process. By default, the association
information will be kept both on the host and the device until it is removed or
overwritten.
.sp
If there are multiple devices available for association, this subcommand will
list all of them, enabling a user to choose among them. This subcommand has the
following options.
.sp
.ne 2
.na
\fB\fB-h\fR \fIhost-id\fR, \fB--host\fR \fIhost-id\fR\fR
.ad
.sp .6
.RS 4n
Specify the host for which the association will be done. If this option is not
specified, this subcommand lists all enabled hosts for users to choose.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR, \fB--cable\fR\fR
.ad
.sp .6
.RS 4n
Start the cable association process. A user plugs the wireless USB device to
the host and runs the associate subcommand with this option.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR, \fB--numeric\fR\fR
.ad
.sp .6
.RS 4n
Start the numeric association process. This subcommand prompts the user to
compare the number displayed on the host and the device.
.RE

If neither of the preceding two association model  options (\fB-n\fR or
\fB-c\fR) is specified, this subcommand prompts the user to specify one of the
following association model options.
.sp
.ne 2
.na
\fB\fB-f\fR, \fB--force\fR\fR
.ad
.sp .6
.RS 4n
Start the cable association process. A user plugs the wireless USB device to
the host and runs the associate subcommand with this option.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR, \fB--onetime\fR\fR
.ad
.sp .6
.RS 4n
Indicate that this association is for a one-time connection. That is, after the
association, if the device is connected and then disconnected, the association
information for this device will be removed from the host system. A user would
need to perform another association for the next connection.
.RE

.RE

.sp
.ne 2
.na
\fB\fBremove-dev\fR [[\fB-d\fR \fIdev-id\fR] | [\fB-h\fR
\fIhost-id\fR]][\fB-f\fR]\fR
.ad
.sp .6
.RS 4n
Remove the association information of the wireless USB device from the system.
After the removal, the device cannot be connected with the host until the user
runs the \fBassociate\fR subcommand again, for the host and device. This
subcommand has the following options.
.sp
.ne 2
.na
\fB\fB-d\fR, \fB--device\fR=\fIdev-id\fR\fR
.ad
.sp .6
.RS 4n
Remove the association information of the wireless USB device specified by
\fIdev-id\fR.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR \fIhost-id\fR, \fB--host\fR=\fIhost-id\fR\fR
.ad
.sp .6
.RS 4n
Remove the association information of all the wireless USB devices associated
with the host specified by \fIhost-id\fR.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR, \fB--force\fR\fR
.ad
.sp .6
.RS 4n
Perform the removal without asking for confirmation. If the device is being
connected with the host, then this subcommand will force it to disconnect.
.RE

.RE

.sp
.ne 2
.na
\fB\fBremove-host\fR [\fB-h\fR \fIhost-id\fR] [\fB-f\fR]\fR
.ad
.sp .6
.RS 4n
Remove the host information from the system, including \fIhost-id\fR and the
association information of all the devices associated with the host. This
subcommand is used most often for removing the temporarily used hot-pluggable
wireless USB host, for example, a \fBhwa\fR dongle. The host can be brought
back by being re-enumerated, for example, physically hot-plugging a \fBhwa\fR
dongle. The host-id will then be updated and no device association information
can be restored. It is not recommended to remove a on-board host. This
subcommand has the following options.
.sp
.ne 2
.na
\fB\fB-h\fR \fIhost-id\fR, \fB--host\fR=\fIhost-id\fR\fR
.ad
.sp .6
.RS 4n
Specifies the \fIhost-id\fR to be removed.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR, \fB--force\fR\fR
.ad
.sp .6
.RS 4n
Perform the removal without asking for confirmation. If there are one or more
devices connected with the host, then force them to disconnect.
.RE

.RE

.sp
.ne 2
.na
\fB\fBenable-host\fR [\fB-h\fR \fIhost-id\fR]\fR
.ad
.sp .6
.RS 4n
Take the host to the enabled state. By default, the host is in the enabled
state. This subcommand has the following option.
.sp
.ne 2
.na
\fB\fB-h\fR \fIhost-id\fR, \fB--host\fR=\fIhost-id\fR\fR
.ad
.sp .6
.RS 4n
Specifies the \fIhost-id\fR to be enabled.
.RE

.RE

.sp
.ne 2
.na
\fB\fBdisable-host\fR [\fB-h\fR \fIhost-id\fR] [\fB-f\fR]\fR
.ad
.sp .6
.RS 4n
Take the host to the disabled state. The \fIhost-id\fR and all the association
information of the host are maintained. Issuing an \fBenable-host\fR subcommand
brings the host back to the enabled state. This subcommand has the following
options.
.sp
.ne 2
.na
\fB\fB-h\fR \fIhost-id\fR, \fB--host\fR=\fIhost-id\fR\fR
.ad
.sp .6
.RS 4n
Specifies the \fIhost-id\fR to be disabled.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR, \fB--force\fR\fR
.ad
.sp .6
.RS 4n
Perform the disable operation without asking for confirmation. If there are one
or more devices connected with the host, this option forces them to disconnect.
.RE

.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRListing All Hosts and Devices
.sp
.LP
The following command lists all wireless USB hosts and devices.

.sp
.in +2
.nf
# \fBwusbadm list\fR
01      enabled         hwa
01.001  connected       mouse
01.002  connected       kbd
02      enabled         whci
02.001  connected       printer
02.002  disconnected    storage
03      disabled        hwa
03.001  disconnected    storage
03.002  disconnected    dwa
.fi
.in -2
.sp

.LP
\fBExample 2 \fRAssociating to a Device Using Cable
.sp
.LP
The following command associates a device to a specific host (host-id
\fB01\fR), using the cable association approach.

.sp
.in +2
.nf
# \fBwusbadm associate -h 01 -c\fR
Associate a device with host (01) via cable.
Continue (yes/no)?
.fi
.in -2
.sp

.LP
\fBExample 3 \fRRemoving a Device's Association
.sp
.LP
The  following command removes a device's association information from the host
system.

.sp
.in +2
.nf
# \fBwusbadm remove-dev -d 01.002\fR
Remove the information of device (01.002) from system.
This device can not be connected with the host until it is associated
again. Continue (yes/no)?
.fi
.in -2
.sp

.LP
\fBExample 4 \fRRemoving Associations for All Devices
.sp
.LP
The  following command removes the association information for all devices
associated with a specific host.

.sp
.in +2
.nf
# \fBwusbadm remove-dev -h 02\fR
Remove the information of all the devices associated with host (02)
from the system.
All the devices associated with the host cannot be connected with it
until they are associated again. Continue (yes/no)?
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
Successful operation.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.sp .6
.RS 4n
Error: the operation failed. For example, a device failed to associate with a
host.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.sp .6
.RS 4n
Usage error.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.LP
\fB/usr/sbin\fR
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBhwahc\fR(7D), \fBusba\fR(7D)
.SH NOTES
.sp
.LP
The \fBwusb\fR (wireless USB administration) service is managed by the service
management facility, \fBsmf\fR(5), under the service identifier:
.sp
.in +2
.nf
svc:/system/wusb:default
.fi
.in -2
.sp

.sp
.LP
Administrative actions on this service, such as enabling, disabling, or
requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
status can be queried using the \fBsvcs\fR(1) command.
.sp
.LP
The \fBwusb\fR service is implemented by the \fBwusbd\fR daemon, a private
interface. As with the \fBwusb\fR service, the daemon is started by the SMF.
Specify the daemon with the service instance:
.sp
.in +2
.nf
svc:/system/wusbd:default
.fi
.in -2
.sp

.sp
.LP
The \fBwusbd\fR daemon should not be invoked directly.