NUSB(4)NUSB(4)

NAME

audio, disk, ether, kb, serial, ptp, dump, usbd - Universal Serial Bus drivers

SYNOPSIS

nusb/audio devid

nusb/cam [ -d ] devid

nusb/disk [ -d ] devid

nusb/ether [ -dD ] [ -t ethertype ] [ -a addr ] devid

nusb/kb [ -d ] devid

nusb/joy [ -d ] [ -b deadband ] devid

nusb/serial [ -d ] devid

nusb/ptp [ -dD ] devid

nusb/dump devid

nusb/usbd [ -dD ]

DESCRIPTION

These programs drive USB devices of specific classes via usb(3). Usually they are started by nusbrc(8) upon attachment of the device to the bus. All drivers except usbd take the decimal usb devid of the device they should handle as their last argument. A driver’s instance handles only one device at a time.

Drivers that provide file systems make them available as shares under /shr (see shr(3)) or /shr/usb (which is bound after /dev by nusbrc(8)).

Options –d and –D trigger debug diagnostics and file system debugging diagnostics for most drivers. Repeating any one of these may increase verbosity.

Hubs

Usbd enumerates the tree of USB hubs and configures the device on attachment. It provides a filesystem with the files usbevent and usbhubctl (usually seen as /dev/usbevent and /dev/usbhubctl).

When the usbevent file is read, it returns a 6-column, space-separated line of text, one for each event. The columns are: attach or detach followed by addr vid did csp and hname. The addr is the decimal device address assigned. Vid and did are formatted as 4 digit hexadecimal. Csp is the device class, subclass, protocol identifier formatted as 6 digit hexadecimal. Usbd assigns a stable device identifier based on the device descriptor for hname. This information is read by nusbrc(8) and the addr and hname are passed to a suitable driver as devid in the form addr:hname.

The usbhubctl file provides per-port power switching control (PPPS) by writing the following 4-column command format: portpower or portindicator followed by hub, port and the state on or off where hub selects the hub device (using its device address addr or hname) and port is the decimal port number (counting from 1).

Keyboards and mice

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 /dev/kbin to let kbdfs(8) process them. Mouse events are sent to /dev/mousein in the same way. A file /dev/hidNctl supports setting keyboard repeat and delay setting, the unit is milliseconds.

Joysticks

Joy parses data packets from a given endpoint and prints back any changes in the device’s axes or buttons. Buttons are identified via an integer id.

Directional buttons are reported either as buttons or axes with 3 positions: 0, 128, and 255 for left (or up), center and right (or down) respectively. Messages are in the form axis id position.

A deadband in the range of [0.0,1.0] can be set with the –b option to filter out input below a threshold on all analog axes.

On/off buttons are reported as either down or up respectively. Messages are in the form down|up id.

Disks

Disk configures and manages USB mass storage devices. It provides a file system (usually seen under /dev) that includes one directory per storage device, named sdUN[.M] in correspondence with the USB device identifier and the storage unit number (or LUN). The LUN is omitted for single lun devices.

The storage device directory contains the usual files served by sd(3): data, raw, and ctl.

The ctl file supplies the device geometry and partitions when read. Ptp configures and exposes a camera’s (and often a mobile device’s) storage to allow transferring data via the Picture Transfer Protocol (PTP).

Ethernet

Ether handles USB ethernet devices. The file system provided is compatible with ether(3) and added to the share usbnet (see shr(3)) which is bound after /net by nusbrc(8) so the device will appear as /net/etherUN. Without specifying the -t option, the device is assumed to be a CDC compliant ethernet communication device. Other devices might require setting an explicit ethertype, such as rndis, smsc, url, lan78xx, aue, a88772, a88178, or a88179 (see nusbrc(8)). On devices that support it, the mac address can be set using the -a addr option.

Serial and JTAG ports

Serial provides a file system (usually seen under /dev) that includes one directory per USB serial port, named eiaUN or eiaUN[.M]. In this directory there are two files, eiaU, similar to eiaN in uart(3), and eiaUctl, which admits writes in the same format as eiaNctl in uart(3). Reading from eiaUctl gives the serial port’s settings in the same format as eiaNstatus in uart(3). Options are similar to those of disk.

JTAG ports are similar but the files are named jtag and jtagctl.

Audio devices

Audio configures and manages a USB audio device. It implements a file system (normally seen under /dev), exporting audioUN , volumeUN and other files that have the same semantics as audio(3)).

Camera devices

Cam configures and exposes a USB camera device’s capabilities, implementing a file system compatible with camv(1), under a directory named camN[.M]. It provides the following files: desc, showing all of the device’s internal descriptors and their values; format, listing admissible image resolutions and framerates; ctl, the picture settings control file; frame, which captures and outputs a single video frame as an image(6) file; and video, streaming video in a preset format, resolution and framerate. In particular, reading from the ctl file yields a space-separated list of parameter settings, where the second and third columns correspond to key-value pairs, and an optional fourth column corresponds to the range of possible numerical values (formatted as minimum/increment/maximum). The same pairs can be written to the file to configure the camera. Currently, only the YUY2 video format is supported.

Debugging

Dump prints information about any currently unused USB device, listing available interfaces, endpoints and descriptors.

SOURCE

/sys/src/cmd/nusb

SEE ALSO

camv(1), joy(1), audio(3), ether(3), mouse(3), sd(3), uart(3), usb(3), shr(3), image(6), nusbrc(8), kbdfs(8)

HISTORY

Joy first appeared in 9front (March, 2014).
Cam first appeared in 9front (March, 2018).
Dump first appeared in 9front (July, 2026).

BUGS

The various device drivers are generic USB drivers and may work only for certain devices of each class.

USB ATA storage devices are not supported.

The serial driver works only for the Prolific chip and Ftdi, and control of the dcd and dsr signals and some of the extra features are not implemented. For Ftdi, only the Sheevaplug and Guruplug have been tried. There is support for the EHCI debug port, but it loses bytes.

USB video format settings cannot be changed while camv(1) is running, and must be set manually by writing them to cam(4)’sctl file before starting the viewer.