System Administration Commands wusbadm(1M) NAME wusbadm - Administer Wireless USB hosts and devices SYNOPSIS wusbadm 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 wusbadm provides a command line interface to administer wireless USB hosts and devices, including list hosts and devices information, associate the host with the device, remove host or device information from the system, and enable/disable hosts. Before connecting a wireless USB device with a host for the first time, user need to setup the association information between them by running wusbadm associate subcommand. And then, user can connect/disconnect the device by just turning on/off the device radio (maybe a button on the device, depends on manufacturer). The device radio's turning on/off are similar as the hotplugging of wired USB devices. The association information is then kept in the non-volatile memory of the device and host. On the host, it can be removed by remove-dev or remove-host subcommand. On the device, it can be overwritten by another association. If a device is associated with multiple hosts, the way that the device prioritize or update its multiple records of association information depends on the manufacturer. Each wusbadm subcommand operates on one of the following objects: host-id A two digits number (start from 01 to 99) to unique identify a wireless USB host on a system. It is generated when the host driver is successfully attached to the host controller at the first time. It is kept for the host until removed by "remove-host" subcommand. dev-id A four digits number to unique identify a wireless USB device associated with a wireless USB host on the system. The first two digits number is the host-id of the wireless USB host that the device is associated. The last two digits number (start from 01 to 99) is used to differentiate devices associated to the same host. The first two digits number and the last two are separated by a dot. dev-id is generated during the device association process. It is kept for the device until removed by "remove-dev" subcommand or updated by another association done between the same host and device. SUBCOMMANDS The following subcommands are supported: list [-h | -d] [-o field[,...]] List wireless USB hosts and devices on a system, displaying the host/device's ID, state, and type. By default, it will list all hosts/devices and all fields. Each host and its devices will be displayed as a group. -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 (hotpluggable host dongle). For device, the types include kbd, mouse, storage, printer, dwa (wireless USB hub), audio, video, etc. STATE There are two states for the host: enabled The host is ready to work or being working, including performing association, connecting devices, performing data communication, etc. disabled The host is not ready to work with any devices and no devices are being connected with host. It might be stopped by "disable-host" subcommand, or, the host might not be available due to physically unplugged or driver detach. There are two 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 done and its radio is turned on. disconnected The device is not connecting with a host or not ready to be opened yet. The device might be in this state due to the reasons such as radio out of range, power off, and hardware problems, etc. -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. User connect 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 done, the cable is no longer needed in the subsequent connections between the same host and the device. Numeric association. User turn on the device radio and run this subcommand to designate the host to talk to the device. A short number is then displayed on both host and device. User compare the values of the numbers and confirm on both host and device side. Upon a successful association, the associated USB host and device are then able to go ahead with 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 more than one devices available for association, this subcommand will list all of them for users to choose. -h host-id, --host=host-id Specify for which host the association process will be done. If this option is not specified, this subcommand will list all enabled hosts for users to choose. -c, --cable Start the cable association process. User plug the wireless USB device to the host and then run associate subcommand with this option. -n, --numeric Start the numeric association process. This subcommand will give a prompt message to ask user to compare the digit number displayed on the host and the device. If none of the above two association model options (-n and -c) is specified, this subcommand will firstly show a prompt message to ask for user's input for association model options. -f, --force Perform the association without ask for user's confirmation. This option applies for cable association only. -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, then the association information for this device will be removed from the host system. User need to perform another association for the next time connection. remove-dev [[-d dev-id] | [-h host-id]] [-f] Remove the association information of the wireless USB device from the system. After the remove, the device can not be connected with the host until user run associate subcommand again for the host and device. -d dev-id, --device=dev-id Remove the association information of the wireless USB device specified by the dev-id. -h host-id, --host=host-id Remove the association information of all the wireless USB devices associated with the host that is specified by the host-id. -f, --force Perform the remove 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 usually for removing the temporarily used hotpluggable wireless USB host, for example, a hwa dongle. The host can be brought back by being re-enumerated, for example, physically hotplugging 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. -h host-id, --host=host-id Specify the host by host-id. -f, --force Perform the remove without asking for confirmation. If there are some devices are being 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 enabled state. -h host-id, --host=host-id Specify the host by host-id. disable-host [-h host-id] [-f] Take the host to disabled state. The host-id and all the association information of the host are kept. Issuing an enable-host subcommand brings the host back to enabled state. -h host-id, --host=host-id Specify the host by host-id. -f, --force Perform the disable without asking for confirmation. If there are some devices connecting with the host, then this subcommand will force them to disconnect. EXAMPLES Example 1 List all wireless USB hosts and devices # wusbadm list ID STATE TYPE 01 enabled hwa 01.01 connected mouse 01.02 connected kbd 02 enabled whci 02.01 connected printer 02.02 disconnected storage 03 disabled hwa 03.01 disconnected storage 03.02 disconnected dwa Example 2 Associate a device with a specific host (host-id 01), using cable association approach. # wusbadm associate -h 01 -c Example 3 Remove a device's association information from the host system. # wusbadm remove-dev -d 01.02 Example 4 Remove the association information of all the devices associated with a specific host. # wusbadm remove-dev -h 02 EXIT STATUS The following exit values are returned: 0 Successful operation 1 Error: the operation failed. For example, a device failed to associate with a host. 2 Usage error. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: /usr/sbin ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWwusbadm | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| SEE ALSO attributes(5), wusbd(1M), usba(7D), hwahc(7D), whci(7D), dwa(7D) NOTES The wusb service is managed by the service 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.