1 '\" te 2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved 3 .\" 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. 4 .\" 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 5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 6 .TH WUSBADM 1M "Apr 22, 2009" 7 .SH NAME 8 wusbadm \- administer wireless USB hosts and devices 9 .SH SYNOPSIS 10 .LP 11 .nf 12 \fBwusbadm\fR list [\fB-h\fR | \fB-d\fR] [\fB-o\fR \fIfield\fR[,...]] 13 .fi 14 15 .LP 16 .nf 17 \fBwusbadm\fR associate [\fB-h\fR \fIhost-id\fR] [[\fB-c\fR [\fB-f\fR]] | \fB-n\fR] [\fB-o\fR] 18 .fi 19 20 .LP 21 .nf 22 \fBwusbadm\fR remove-dev [[\fB-d\fR \fIdev-id\fR] | [\fB-h\fR \fIhost-id\fR]] [\fB-f\fR] 23 .fi 24 25 .LP 26 .nf 27 \fBwusbadm\fR remove-host [\fB-h\fR \fIhost-id\fR] [\fB-f\fR] 28 .fi 29 30 .LP 31 .nf 32 \fBwusbadm\fR enable-host [\fB-h\fR \fIhost-id\fR] 33 .fi 34 35 .LP 36 .nf 37 \fBwusbadm\fR disable-host [\fB-h\fR \fIhost-id\fR] 38 .fi 39 40 .SH DESCRIPTION 41 .sp 42 .LP 43 The \fBwusbadm\fR command provides a command line interface to administer 44 wireless USB hosts and devices, including listing hosts and devices 45 information, associating the host with the device, removing host or device 46 information from the system, and enabling or disabling hosts. 47 .sp 48 .LP 49 Before connecting a wireless USB device to a host for the first time, a user 50 needs to set up the association information between them by running the wusbadm 51 associate subcommand. Following this, the user can connect or disconnect the 52 device by simply turning on or off the device radio (perhaps a button on the 53 device, depending on the manufacturer). The device radio's turning on and off 54 are analogous to the hotplugging of wired USB devices. 55 .sp 56 .LP 57 The association information created by the \fBassociate\fR subcommand is 58 maintained in the non-volatile memory of the device and the host. On the host, 59 it can be removed by the \fBremove-dev\fR or \fBremove-host\fR subcommands. On 60 the device, it can be overwritten by another association. For a device is 61 associated with multiple hosts, the way that the device prioritizes or updates 62 its multiple records of association depends on the manufacturer. 63 .sp 64 .LP 65 Each \fBwusbadm\fR subcommand operates on one of the following objects: 66 .sp 67 .ne 2 68 .na 69 \fB\fIhost-id\fR\fR 70 .ad 71 .sp .6 72 .RS 4n 73 A two-digit number (in the range from 01 to 99) that uniquely identifies a 74 wireless USB host on a system. It is generated when the \fBwusb\fR service (see 75 \fBNOTES\fR section) is successfully enabled and finds the host instance for 76 the first time. The number is maintained until removed by \fBremove-host\fR 77 subcommand. 78 .RE 79 80 .sp 81 .ne 2 82 .na 83 \fB\fIdev-id\fR\fR 84 .ad 85 .sp .6 86 .RS 4n 87 A five-digit number that uniquely identifies a wireless USB device associated 88 with a wireless USB host. The first two digits are the host-id of the wireless 89 USB host with which the device is associated. The last three-digit number (in 90 the range from 001 to 999) is used to differentiate devices associated with the 91 same host. In the five-digit number, the first two digits and the last three 92 are separated by a dot. 93 .sp 94 \fIdev-id\fR is generated during the device association process. It is 95 maintained for the device until removed by the \fBremove-dev\fR subcommand or 96 until updated by another association between the same host and device. 97 .RE 98 99 .SH SUB-COMMANDS 100 .sp 101 .LP 102 The following subcommands are supported. Except for the \fBlist\fR subcommand, 103 each subcommand displays subcommand-specific usage information if you run it 104 without any options or operands. 105 .sp 106 .ne 2 107 .na 108 \fB\fBlist\fR [\fB-h\fR | \fB-d\fR] [\fB-o\fR \fIfield\fR[,...]]\fR 109 .ad 110 .sp .6 111 .RS 4n 112 List wireless USB hosts and devices on a system, displaying the ID, state, and 113 type for all hosts and devices. By default, \fBlist\fR will list all hosts and 114 devices and all fields. Each host and its devices will be displayed as a group. 115 This subcommand supports the following options. 116 .sp 117 .ne 2 118 .na 119 \fB\fB-o\fR \fIfield\fR[,...], \fB--output\fR=\fIfield\fR[,...]\fR 120 .ad 121 .sp .6 122 .RS 4n 123 A case-insensitive, comma-separated list of output fields to display. The field 124 name must be one of the fields listed below, or the special value \fBall\fR to 125 display all fields. By default (without \fB-o\fR), \fBlist\fR displays all 126 fields. 127 .sp 128 .ne 2 129 .na 130 \fB\fBID\fR\fR 131 .ad 132 .sp .6 133 .RS 4n 134 The \fIhost-id\fR or \fIdev-id\fR. 135 .RE 136 137 .sp 138 .ne 2 139 .na 140 \fB\fBTYPE\fR\fR 141 .ad 142 .sp .6 143 .RS 4n 144 The \fBhost\fR or \fBdevice\fR types. 145 .sp 146 For \fBhost\fR, the types include \fBwhci\fR (on-board host) and \fBhwa\fR 147 (hot-pluggable host). 148 .sp 149 For \fBdevice\fR, the types include \fBkbd\fR, \fBmouse\fR, \fBstorage\fR, 150 \fBprinter\fR, \fBdwa\fR (wireless USB hub), \fBaudio\fR, \fBvideo\fR, and so 151 forth. 152 .RE 153 154 .sp 155 .ne 2 156 .na 157 \fB\fBSTATE\fR\fR 158 .ad 159 .sp .6 160 .RS 4n 161 There are the following states for the host: 162 .sp 163 .ne 2 164 .na 165 \fB\fBenabled\fR\fR 166 .ad 167 .sp .6 168 .RS 4n 169 The host is ready to work or is already working, including performing 170 association, connecting devices, performing data communication, and so forth. 171 .RE 172 173 .sp 174 .ne 2 175 .na 176 \fB\fBdisabled\fR\fR 177 .ad 178 .sp .6 179 .RS 4n 180 The host is not ready to work with any devices and no devices are connected to 181 the host. It might be stopped by a \fBdisable-host\fR subcommand, or the host 182 might not be available because it is physically unplugged or because of a 183 driver detach. 184 .RE 185 186 .sp 187 .ne 2 188 .na 189 \fB\fBdisconnected\fR\fR 190 .ad 191 .sp .6 192 .RS 4n 193 The host is not attached to the system. An \fBhwa\fR device is in this state 194 after it is unplugged from the USB port on the system. 195 .RE 196 197 There are the folllowing states for the device: 198 .sp 199 .ne 2 200 .na 201 \fB\fBconnected\fR\fR 202 .ad 203 .sp .6 204 .RS 4n 205 The device is connected with a host and ready to be opened, or it is already 206 opened and working. By default, the device tries to get into this state after 207 the association is complete and its radio is turned on. 208 .RE 209 210 .sp 211 .ne 2 212 .na 213 \fB\fBdisconnected\fR\fR 214 .ad 215 .sp .6 216 .RS 4n 217 The device is not connected to a host or not ready to be opened yet. The device 218 might be in this state because its radio is out of range, power is off, 219 hardware problems, and so forth. 220 .RE 221 222 .RE 223 224 .RE 225 226 .sp 227 .ne 2 228 .na 229 \fB\fB-h\fR, \fB--host\fR\fR 230 .ad 231 .sp .6 232 .RS 4n 233 List the wireless USB hosts only. 234 .RE 235 236 .sp 237 .ne 2 238 .na 239 \fB\fB-d\fR, \fB--device\fR\fR 240 .ad 241 .sp .6 242 .RS 4n 243 List the wireless USB devices only. 244 .RE 245 246 .RE 247 248 .sp 249 .ne 2 250 .na 251 \fB\fBassociate\fR [\fB-h\fR \fIhost-id\fR] [[\fB-c\fR [\fB-f\fR]] | \fB-n\fR] 252 [\fB-o\fR]\fR 253 .ad 254 .sp .6 255 .RS 4n 256 Designate the host to start an association process. Association is the initial 257 step before a wireless USB device can be connected with a wireless USB host. 258 .sp 259 There are two association models: 260 .sp 261 .ne 2 262 .na 263 \fBCable association\fR 264 .ad 265 .sp .6 266 .RS 4n 267 A user connects the device and host with a USB cable first, and then run this 268 subcommand to designate the host to setup the association information with the 269 device. After the association is in effect, the cable is no longer needed in 270 the subsequent connections between the same host and the device. 271 .RE 272 273 .sp 274 .ne 2 275 .na 276 \fBNumeric association\fR 277 .ad 278 .sp .6 279 .RS 4n 280 A user turns on the device radio and runs this subcommand to designate the host 281 to talk to the device. A short number is then displayed on both host and 282 device. The user compares the values of the numbers and confirms on both the 283 host and the device. 284 .RE 285 286 Following a successful association, the associated USB host and device are able 287 to proceed with the wireless connection process. By default, the association 288 information will be kept both on the host and the device until it is removed or 289 overwritten. 290 .sp 291 If there are multiple devices available for association, this subcommand will 292 list all of them, enabling a user to choose among them. This subcommand has the 293 following options. 294 .sp 295 .ne 2 296 .na 297 \fB\fB-h\fR \fIhost-id\fR, \fB--host\fR \fIhost-id\fR\fR 298 .ad 299 .sp .6 300 .RS 4n 301 Specify the host for which the association will be done. If this option is not 302 specified, this subcommand lists all enabled hosts for users to choose. 303 .RE 304 305 .sp 306 .ne 2 307 .na 308 \fB\fB-c\fR, \fB--cable\fR\fR 309 .ad 310 .sp .6 311 .RS 4n 312 Start the cable association process. A user plugs the wireless USB device to 313 the host and runs the associate subcommand with this option. 314 .RE 315 316 .sp 317 .ne 2 318 .na 319 \fB\fB-n\fR, \fB--numeric\fR\fR 320 .ad 321 .sp .6 322 .RS 4n 323 Start the numeric association process. This subcommand prompts the user to 324 compare the number displayed on the host and the device. 325 .RE 326 327 If neither of the preceding two association model options (\fB-n\fR or 328 \fB-c\fR) is specified, this subcommand prompts the user to specify one of the 329 following association model options. 330 .sp 331 .ne 2 332 .na 333 \fB\fB-f\fR, \fB--force\fR\fR 334 .ad 335 .sp .6 336 .RS 4n 337 Start the cable association process. A user plugs the wireless USB device to 338 the host and runs the associate subcommand with this option. 339 .RE 340 341 .sp 342 .ne 2 343 .na 344 \fB\fB-o\fR, \fB--onetime\fR\fR 345 .ad 346 .sp .6 347 .RS 4n 348 Indicate that this association is for a one-time connection. That is, after the 349 association, if the device is connected and then disconnected, the association 350 information for this device will be removed from the host system. A user would 351 need to perform another association for the next connection. 352 .RE 353 354 .RE 355 356 .sp 357 .ne 2 358 .na 359 \fB\fBremove-dev\fR [[\fB-d\fR \fIdev-id\fR] | [\fB-h\fR 360 \fIhost-id\fR]][\fB-f\fR]\fR 361 .ad 362 .sp .6 363 .RS 4n 364 Remove the association information of the wireless USB device from the system. 365 After the removal, the device cannot be connected with the host until the user 366 runs the \fBassociate\fR subcommand again, for the host and device. This 367 subcommand has the following options. 368 .sp 369 .ne 2 370 .na 371 \fB\fB-d\fR, \fB--device\fR=\fIdev-id\fR\fR 372 .ad 373 .sp .6 374 .RS 4n 375 Remove the association information of the wireless USB device specified by 376 \fIdev-id\fR. 377 .RE 378 379 .sp 380 .ne 2 381 .na 382 \fB\fB-h\fR \fIhost-id\fR, \fB--host\fR=\fIhost-id\fR\fR 383 .ad 384 .sp .6 385 .RS 4n 386 Remove the association information of all the wireless USB devices associated 387 with the host specified by \fIhost-id\fR. 388 .RE 389 390 .sp 391 .ne 2 392 .na 393 \fB\fB-f\fR, \fB--force\fR\fR 394 .ad 395 .sp .6 396 .RS 4n 397 Perform the removal without asking for confirmation. If the device is being 398 connected with the host, then this subcommand will force it to disconnect. 399 .RE 400 401 .RE 402 403 .sp 404 .ne 2 405 .na 406 \fB\fBremove-host\fR [\fB-h\fR \fIhost-id\fR] [\fB-f\fR]\fR 407 .ad 408 .sp .6 409 .RS 4n 410 Remove the host information from the system, including \fIhost-id\fR and the 411 association information of all the devices associated with the host. This 412 subcommand is used most often for removing the temporarily used hot-pluggable 413 wireless USB host, for example, a \fBhwa\fR dongle. The host can be brought 414 back by being re-enumerated, for example, physically hot-plugging a \fBhwa\fR 415 dongle. The host-id will then be updated and no device association information 416 can be restored. It is not recommended to remove a on-board host. This 417 subcommand has the following options. 418 .sp 419 .ne 2 420 .na 421 \fB\fB-h\fR \fIhost-id\fR, \fB--host\fR=\fIhost-id\fR\fR 422 .ad 423 .sp .6 424 .RS 4n 425 Specifies the \fIhost-id\fR to be removed. 426 .RE 427 428 .sp 429 .ne 2 430 .na 431 \fB\fB-f\fR, \fB--force\fR\fR 432 .ad 433 .sp .6 434 .RS 4n 435 Perform the removal without asking for confirmation. If there are one or more 436 devices connected with the host, then force them to disconnect. 437 .RE 438 439 .RE 440 441 .sp 442 .ne 2 443 .na 444 \fB\fBenable-host\fR [\fB-h\fR \fIhost-id\fR]\fR 445 .ad 446 .sp .6 447 .RS 4n 448 Take the host to the enabled state. By default, the host is in the enabled 449 state. This subcommand has the following option. 450 .sp 451 .ne 2 452 .na 453 \fB\fB-h\fR \fIhost-id\fR, \fB--host\fR=\fIhost-id\fR\fR 454 .ad 455 .sp .6 456 .RS 4n 457 Specifies the \fIhost-id\fR to be enabled. 458 .RE 459 460 .RE 461 462 .sp 463 .ne 2 464 .na 465 \fB\fBdisable-host\fR [\fB-h\fR \fIhost-id\fR] [\fB-f\fR]\fR 466 .ad 467 .sp .6 468 .RS 4n 469 Take the host to the disabled state. The \fIhost-id\fR and all the association 470 information of the host are maintained. Issuing an \fBenable-host\fR subcommand 471 brings the host back to the enabled state. This subcommand has the following 472 options. 473 .sp 474 .ne 2 475 .na 476 \fB\fB-h\fR \fIhost-id\fR, \fB--host\fR=\fIhost-id\fR\fR 477 .ad 478 .sp .6 479 .RS 4n 480 Specifies the \fIhost-id\fR to be disabled. 481 .RE 482 483 .sp 484 .ne 2 485 .na 486 \fB\fB-f\fR, \fB--force\fR\fR 487 .ad 488 .sp .6 489 .RS 4n 490 Perform the disable operation without asking for confirmation. If there are one 491 or more devices connected with the host, this option forces them to disconnect. 492 .RE 493 494 .RE 495 496 .SH EXAMPLES 497 .LP 498 \fBExample 1 \fRListing All Hosts and Devices 499 .sp 500 .LP 501 The following command lists all wireless USB hosts and devices. 502 503 .sp 504 .in +2 505 .nf 506 # \fBwusbadm list\fR 507 01 enabled hwa 508 01.001 connected mouse 509 01.002 connected kbd 510 02 enabled whci 511 02.001 connected printer 512 02.002 disconnected storage 513 03 disabled hwa 514 03.001 disconnected storage 515 03.002 disconnected dwa 516 .fi 517 .in -2 518 .sp 519 520 .LP 521 \fBExample 2 \fRAssociating to a Device Using Cable 522 .sp 523 .LP 524 The following command associates a device to a specific host (host-id 525 \fB01\fR), using the cable association approach. 526 527 .sp 528 .in +2 529 .nf 530 # \fBwusbadm associate -h 01 -c\fR 531 Associate a device with host (01) via cable. 532 Continue (yes/no)? 533 .fi 534 .in -2 535 .sp 536 537 .LP 538 \fBExample 3 \fRRemoving a Device's Association 539 .sp 540 .LP 541 The following command removes a device's association information from the host 542 system. 543 544 .sp 545 .in +2 546 .nf 547 # \fBwusbadm remove-dev -d 01.002\fR 548 Remove the information of device (01.002) from system. 549 This device can not be connected with the host until it is associated 550 again. Continue (yes/no)? 551 .fi 552 .in -2 553 .sp 554 555 .LP 556 \fBExample 4 \fRRemoving Associations for All Devices 557 .sp 558 .LP 559 The following command removes the association information for all devices 560 associated with a specific host. 561 562 .sp 563 .in +2 564 .nf 565 # \fBwusbadm remove-dev -h 02\fR 566 Remove the information of all the devices associated with host (02) 567 from the system. 568 All the devices associated with the host cannot be connected with it 569 until they are associated again. Continue (yes/no)? 570 .fi 571 .in -2 572 .sp 573 574 .SH EXIT STATUS 575 .sp 576 .LP 577 The following exit values are returned: 578 .sp 579 .ne 2 580 .na 581 \fB\fB0\fR\fR 582 .ad 583 .sp .6 584 .RS 4n 585 Successful operation. 586 .RE 587 588 .sp 589 .ne 2 590 .na 591 \fB\fB1\fR\fR 592 .ad 593 .sp .6 594 .RS 4n 595 Error: the operation failed. For example, a device failed to associate with a 596 host. 597 .RE 598 599 .sp 600 .ne 2 601 .na 602 \fB\fB2\fR\fR 603 .ad 604 .sp .6 605 .RS 4n 606 Usage error. 607 .RE 608 609 .SH ATTRIBUTES 610 .sp 611 .LP 612 See \fBattributes\fR(5) for descriptions of the following attributes: 613 .sp 614 .LP 615 \fB/usr/sbin\fR 616 .sp 617 618 .sp 619 .TS 620 box; 621 c | c 622 l | l . 623 ATTRIBUTE TYPE ATTRIBUTE VALUE 624 _ 625 Interface Stability Committed 626 .TE 627 628 .SH SEE ALSO 629 .sp 630 .LP 631 \fBattributes\fR(5), \fBhwahc\fR(7D), \fBusba\fR(7D) 632 .SH NOTES 633 .sp 634 .LP 635 The \fBwusb\fR (wireless USB administration) service is managed by the service 636 management facility, \fBsmf\fR(5), under the service identifier: 637 .sp 638 .in +2 639 .nf 640 svc:/system/wusb:default 641 .fi 642 .in -2 643 .sp 644 645 .sp 646 .LP 647 Administrative actions on this service, such as enabling, disabling, or 648 requesting restart, can be performed using \fBsvcadm\fR(1M). The service's 649 status can be queried using the \fBsvcs\fR(1) command. 650 .sp 651 .LP 652 The \fBwusb\fR service is implemented by the \fBwusbd\fR daemon, a private 653 interface. As with the \fBwusb\fR service, the daemon is started by the SMF. 654 Specify the daemon with the service instance: 655 .sp 656 .in +2 657 .nf 658 svc:/system/wusbd:default 659 .fi 660 .in -2 661 .sp 662 663 .sp 664 .LP 665 The \fBwusbd\fR daemon should not be invoked directly.