WUSBADM(1M)WUSBADM(1M)NAMEwusbadm - administer wireless USB hosts and devices
SYNOPSISwusbadm list [-h | -d] [-o field[,...]]
wusbadm associate [-h host-id] [[-c [-f]] | -n] [-o]
wusbadm remove-dev [[-d dev-id] | [-h host-id]] [-f]
wusbadm remove-host [-h host-id] [-f]
wusbadm enable-host [-h host-id]
wusbadm disable-host [-h host-id]
DESCRIPTION
The wusbadm 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.
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 run‐
ning 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.
The association information created by the associate subcommand is
maintained in the non-volatile memory of the device and the host. On
the host, it can be removed by the remove-dev or remove-host subcom‐
mands. 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.
Each wusbadm subcommand operates on one of the following objects:
host-id
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 wusb service (see NOTES section) is successfully enabled and
finds the host instance for the first time. The number is main‐
tained until removed by remove-host subcommand.
dev-id
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 associ‐
ated. 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 sep‐
arated by a dot.
dev-id is generated during the device association process. It is
maintained for the device until removed by the remove-dev subcom‐
mand or until updated by another association between the same host
and device.
SUB-COMMANDS
The following subcommands are supported. Except for the list subcom‐
mand, each subcommand displays subcommand-specific usage information if
you run it without any options or operands.
list [-h | -d] [-o field[,...]]
List wireless USB hosts and devices on a system, displaying the ID,
state, and type for all hosts and devices. By default, list 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.
-o field[,...], --output=field[,...]
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 all to display all fields. By default
(without -o), list displays all fields.
ID
The host-id or dev-id.
TYPE
The host or device types.
For host, the types include whci (on-board host) and hwa
(hot-pluggable host).
For device, the types include kbd, mouse, storage, printer,
dwa (wireless USB hub), audio, video, and so forth.
STATE
There are the following states for the host:
enabled
The host is ready to work or is already working,
including performing association, connecting devices,
performing data communication, and so forth.
disabled
The host is not ready to work with any devices and no
devices are connected to the host. It might be stopped
by a disable-host subcommand, or the host might not be
available because it is physically unplugged or because
of a driver detach.
disconnected
The host is not attached to the system. An hwa device
is in this state after it is unplugged from the USB
port on the system.
There are the folllowing states for the device:
connected
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.
disconnected
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, hard‐
ware problems, and so forth.
-h, --host
List the wireless USB hosts only.
-d, --device
List the wireless USB devices only.
associate [-h host-id] [[-c [-f]] | -n] [-o]
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.
There are two association models:
Cable association
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.
Numeric association
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.
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.
If there are multiple devices available for association, this sub‐
command will list all of them, enabling a user to choose among
them. This subcommand has the following options.
-h host-id, --host host-id
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.
-c, --cable
Start the cable association process. A user plugs the wireless
USB device to the host and runs the associate subcommand with
this option.
-n, --numeric
Start the numeric association process. This subcommand prompts
the user to compare the number displayed on the host and the
device.
If neither of the preceding two association model options (-n or
-c) is specified, this subcommand prompts the user to specify one
of the following association model options.
-f, --force
Start the cable association process. A user plugs the wireless
USB device to the host and runs the associate subcommand with
this option.
-o, --onetime
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 per‐
form another association for the next connection.
remove-dev [[-d dev-id] | [-h host-id]][-f]
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 associate subcommand again, for
the host and device. This subcommand has the following options.
-d, --device=dev-id
Remove the association information of the wireless USB device
specified by dev-id.
-h host-id, --host=host-id
Remove the association information of all the wireless USB
devices associated with the host specified by host-id.
-f, --force
Perform the removal without asking for confirmation. If the
device is being connected with the host, then this subcommand
will force it to disconnect.
remove-host [-h host-id] [-f]
Remove the host information from the system, including host-id and
the association information of all the devices associated with the
host. This subcommand is used most often for removing the temporar‐
ily used hot-pluggable wireless USB host, for example, a hwa don‐
gle. The host can be brought back by being re-enumerated, for exam‐
ple, physically hot-plugging a hwa 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.
-h host-id, --host=host-id
Specifies the host-id to be removed.
-f, --force
Perform the removal without asking for confirmation. If there
are one or more devices connected with the host, then force
them to disconnect.
enable-host [-h host-id]
Take the host to the enabled state. By default, the host is in the
enabled state. This subcommand has the following option.
-h host-id, --host=host-id
Specifies the host-id to be enabled.
disable-host [-h host-id] [-f]
Take the host to the disabled state. The host-id and all the asso‐
ciation information of the host are maintained. Issuing an enable-
host subcommand brings the host back to the enabled state. This
subcommand has the following options.
-h host-id, --host=host-id
Specifies the host-id to be disabled.
-f, --force
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.
EXAMPLES
Example 1 Listing All Hosts and Devices
The following command lists all wireless USB hosts and devices.
# wusbadm list
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
Example 2 Associating to a Device Using Cable
The following command associates a device to a specific host (host-id
01), using the cable association approach.
# wusbadm associate -h 01 -c
Associate a device with host (01) via cable.
Continue (yes/no)?
Example 3 Removing a Device's Association
The following command removes a device's association information from
the host system.
# wusbadm remove-dev -d 01.002
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)?
Example 4 Removing Associations for All Devices
The following command removes the association information for all
devices associated with a specific host.
# wusbadm remove-dev -h 02
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)?
EXIT STATUS
The following exit values are returned:
0
Successful operation.
1
Error: the operation failed. For example, a device failed to asso‐
ciate with a host.
2
Usage error.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
/usr/sbin
┌────────────────────┬─────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼─────────────────┤
│Interface Stability │ Committed │
└────────────────────┴─────────────────┘
SEE ALSOattributes(5), hwahc(7D), usba(7D)NOTES
The wusb (wireless USB administration) service is managed by the ser‐
vice management facility, smf(5), under the service identifier:
svc:/system/wusb:default
Administrative actions on this service, such as enabling, disabling, or
requesting restart, can be performed using svcadm(1M). The service's
status can be queried using the svcs(1) command.
The wusb service is implemented by the wusbd daemon, a private inter‐
face. As with the wusb service, the daemon is started by the SMF.
Specify the daemon with the service instance:
svc:/system/wusbd:default
The wusbd daemon should not be invoked directly.
Apr 22, 2009 WUSBADM(1M)
