.TH USB 4
.SH NAME
usbmouse,
usbaudio,
usbprinter,
usbstart
\- Universal Serial Bus user\-level device drivers
.SH SYNOPSIS
.B usb/usbmouse
[
.B -fsv
] [
.B -a
.I accel
] [
.I m
.I n
]
.PP
.B usb/usbaudio
[
.B -V
] [
.B -v
.I volume
] [
.B -m
.I mountpoint
] [
.B -s
.I srvname
] [
.I m
.I n
]
.PP
.B usb/usbprinter
.PP
.B usbstart
.SH DESCRIPTION
These programs implement support for specific 
.SM USB
device classes.
With the exception of
.IR usbstart ,
they should be run after
.IR usbd (4)
has located available
.SM USB
devices and provided them with device addresses and minimal configuration.
Dynamic handling of device insertion and removal is currently not supported.
.SS Mice
Without arguments,
.I usbmouse
reads the
.SM USB
status files (see
.IR usb (3))
to find a mouse, writing events from the first one found to
.B /dev/mousein
(see
.IR mouse (3)).
Given an argument of 
.SM USB
hub number
.I m
and slot number
.IR n ,
.I usbmouse
looks for a mouse only at
.BI /dev/usb m / n /status .
The options are:
.TP
.BI -f
Run in foreground.
.TP
.BI -s
Enable the scrollwheel.
.TP
.BI -v
Produce verbose output on standard error. Often combined with
.BR -f .
.TP
.BI -a " accel"
Set the movement acceleration to the number
.IR accel .
.SS Audio devices
.I Usbaudio
configures and manages a 
.SM USB
audio device. With no arguments, it reads the
.SM USB
status files to find an audio device, and uses the first one found.
Given an argument of
.SM USB
hub number
.I m
and slot number
.IR n ,
.I usbaudio
looks for an audio device only at
.BI /dev/usb m / n /status .
.PP
.I Usbaudio
serves a one-level file system presenting the files
.BR audio ,
.BR audioctl ,
.BR audioin ,
and
.BR volume .
The names
.B audio
and
.B volume
maintain compatibility with the soundblaster driver (see
.IR audio (3)).
This filesystem is by default mounted on
.BI /dev ,
but a
.I mountpoint
can be specified with the
.B \-m
option.
The
.B \-s
option causes
.I usbaudio
to post its service as
.BI /srv/ srvname .
.PP
The
.B \-V
option produces verbose information about the audio device on standard error.
.PP
Reading
.B volume
or
.B audioctl
yields the device's settings.  The data format of
.B volume
is compatible with the soundblaster and
produces something like:
.IP
.EX
audio out 65
treb out 0
bass out 0
speed out 44100
.EE
.PP
This file can be written using the same syntax.
The keyword
.B out
may be omitted.
Settings are given as percentages of the range, except for speed which is in
.SM Hz.
The
.B -v
option sets the initial
.IR volume .
.PP
The file
.B audioctl
provides more information, using up to 6 columns of 12 characters each.
From left to right, the fields are:
.IR "control name" ,
.I in
or
.IR out ,
.IR "current value" ,
.IR "minimum value" ,
.IR maximum ,
and
.IR resolution .
There are 3, 5, or 6 columns present.
Maxima and resolution are omitted when they are not available or not applicable.
The resolution for
.I speed
is reported as 1 (one) if the sampling frequency is continuously variable.  It is absent
if it is settable at a fixed number of discrete values only.
.PP
When all values from
.B audioctl
have been read, a zero-sized buffer is returned (the usual end-of-file indication).
A new read will then block until one of the settings changes and then report its new value.
.PP
The file
.B audioctl
can be written like
.BR volume .
.PP
Audio data is written to
.B audio
and read from
.BR audioin .
The audio data is a sequence of little-endian integer samples ordered primarily by time and secondarily by channel.
Samples occupy the minimum integral number of bytes.
Read and write operations of arbitrary size are allowed.
.SS Printers
.I Usbprinter
is an
.IR rc (4)
script that reads the
.SM USB
status files and
.IR bind s
the
.B ep2data
file of the first printer device it finds to
.BR /n/lp ,
which can then be used as an
.B LPDEST
(see
.IR lp (1)).
.SS Convenience
The
.IR rc (1)
script
.I usbstart
starts
.IR usbd (4),
then uses
.I usbmouse
and
.I usbaudio
to configure and manage a mouse and an audio device.
.I Usbstart
is similar to the example below.
.SH EXAMPLE
.LP
To use a
.SM USB
mouse, audio device, and printer, put the following in your profile
(replace
.I x
with your favorite initial volume setting):
.IP
.EX
.ta 6n
if (test -r '#U'/usb0) {
	usb/usbd
	usb/usbmouse -a 2
	usb/usbaudio -v \fIx\fP
	usb/usbprinter
}
.EE
.PP
.SH FILES
.TF /dev/usb?/?/status
.TP
.B /dev/usb?/?/status
.SM USB
device status files
.TF /n/lp
.TP
.B /n/lp
.I usbprinter
.IR bind (1)
location for
.B ep2data
file
.SH SOURCE
.B /sys/src/cmd/usb
.br
.B /rc/bin/usbstart
.SH "SEE ALSO"
.IR usb (3),
.IR usbd (4),
.IR mouse (3),
.IR audio (3),
.IR lp (1)
.SH BUGS
.I Usbaudio
is only known to work with the list of devices below:
.IP
.RS
.TP
Xitel AN1
Output only.
Marginally enough to drive headphones.
Has mute, volume, bass, treble controls.
.TP
Philips DSS 370/17 USB speakers
Usbaudio acts on the volume
.L +
and
.L -
buttons.
.TP
Edirol UA-3
Playback and record.
Playback only at 44.1 KHz, record at 32, 44.1 or 48 KHz.
Playback volume control and mute control.
The device only has analog (slider controlled)
input volume control.
.TP
Edirol UA-1X
Playback and record.
Playback only at 32, 44.1 or 48 KHz, record at 8, 16, 22.05, 32, 44.1 or 48 KHz.
Playback volume control and mute control
(recording not tested).
.TP
Xitel Pro HiFi-Link
Playback only.
48 KHz only.
There is a volume control but it isn't connected to the output, so does nothing.
.TP
Onkyo WAVIO series MA-500U
Includes three optical digital interfaces, two analog, and an
amplifier (15W + 15W).
.TP
Turtle Beach Audio Advantage micro
Headset and S/Pdif out, volume and mute controls.
.RE