harvey/sys/man/4/usb

.TH USB 4
.SH NAME
usbmouse,
kb,
usbaudio,
print
\- Universal Serial Bus user-level device drivers
.SH SYNOPSIS
.B usb/usbmouse
[
.B -fsv
] [
.B -a
.I accel
] [
.I ctrlno
.I n
]
.PP
.B usb/kb
[
.B -dkmn
] [
.B -a
.I n
] [
.I ctlrno
.I n
]
.PP
.B usb/usbaudio
[
.B -pV
] [
.B -m
.I mountpoint
] [
.B -s
.I srvname
] [
.B -v
.I volume
] [
.I ctrlno
.I n
]
.PP
.B usb/print
.SH DESCRIPTION
These programs implement support for specific USB device classes.
They should be run after
.IR usbd (4)
has had a chance to locate the devices in question and provide
them with device addresses and minimal configuration.
Dynamic handling of device insertion and removal is currently not supported.
.SS Mice
.I Usbmouse
sends mouse events from a USB mouse to
.B /dev/mousein
where the Plan 9 kernel processes them like other mice, but see
.I kb
below.
.PP
Without arguments, it scans the USB status files to find a mouse
and uses the first one it finds.  A pair of numeric arguments overrides this search
with a specific USB controller and device.  The options are
.TF "-a ac"
.TP
.BI -a " accel"
Accelerate mouse movements.
.TP
.BI -f
Run usbmouse in foreground.
.TP
.BI -s
Use the scrollwheel.
.TP
.BI -v
Verbose mode.
.SS Keyboards and mice
.I Kb
supports USB keyboards and mice either as separate USB devices
or as a single combined USB device. Scan codes from the keyboard
are sent to
.B /dev/kbin
to let the kernel process them.
Mouse events are sent to
.B /dev/mousein
in the same way.
.PP
Without arguments it handles the keyboard and mouse devices found
on the bus.
Otherwise it uses the one attached to controller
.I ctrlno
with device number
.IR n .
The following options are understood:
.TF -k
.TP
.B \-a
Accelerate the mouse to level
.I n
(similar to the kernel mouse driver acceleration).
.TP
.B \-d
Activate debug diagnostics. Repeating the flag one or more times
increases the verbosity.
.TP
.B \-k
Serve just the keyboard (and not the mouse).
.TP
.B \-m
Serve just the mouse (and not the keyboard).
.TP
.B \-n
Dry run. Do not send any events to the kernel for processing.
.SS Printers
.I Print
is a script that mounts a USB printer on
.BR /dev/lp .
.SS Audio devices
.I Usbaudio
configures and manages a USB audio device.  It implements a file system,
normally mounted on
.BI /dev ,
but this can be changed with the
.B \-m
option, with files
.BR volume ,
.BR audioctl ,
.BR audio ,
and
.BR audioin .
The names
.B volume
and
.B audio
maintain backward compatibility with the soundblaster driver.
.PP
The
.B \-V
option (verbose) causes usbaudio to print information about the device on startup.
The
.B \-s
option specifies a name for a file descriptor to be posted in
.BR /srv .
The
.B \-v
options sets initial
.IR volume .
.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
.I out
may be omitted.  Settings are given as percentages of the range,
except for speed which is in Hz.
.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 data format is little endian, 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.
.SH EXAMPLE
To use a USB mouse and audio device, 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/print
}
.EE
.PP
Alternatively, just put
.B usbstart
in your profile.
.SH SOURCE
.B /sys/src/cmd/usb
.SH "SEE ALSO"
.IR usb (3),
.IR usbd (4),
.IR usbdisk (4)
.SH BUGS
.I Usbaudio
only works for certain audio devices.
This is the list of devices known to work with
.IR usbaudio :
.IP "" 3
.RS
.TF "Edirol U"
.TP
Xitel AN1
Output only.
Marginally enough to drive headphones.
Has mute, volume, bass, treble controls.
.TP
Philips USB speakers, model DSS 370/17
.I 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
(haven't tested recording, but I believe it'll work).
.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