GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
UHIDD(8) FreeBSD System Manager's Manual UHIDD(8)

uhidd
USB HID daemon

uhidd [-c file] [-H devname] [-dDhkmosuUvV] /dev/ugen%u.%u

The uhidd daemon handles USB HID devices like mouse, keyboard etc. in userland using the libusb20 library.

The uhidd daemon is intended to handle USB HID devices with multiple logical devices sharing one endpoint, usually that is multiple application collections inside one interface. The daemon attaches interface driver to each HID interface of the ugen%u.%u device and attaches class drivers to application collections found inside that inteface. Interface driver receive data through the shared interrupt endpoint and pass it to the right class driver instance. The class driver then process the data as approriate.

There are currently 4 HID class driver available: Mouse driver, Keyboard driver, Consumer Control driver and Virutal Generic HID driver.

The Mouse driver extracts mouse input data from mouse application collection and pass the mouse event to the console driver to make it available to the text console and user programs.

The Keyboard driver creates a vkbd(4) virtual keyboard, extracts keyboard HID input report from keyboard application collection, translates the HID codes to key scancodes and passes the scancodes to the vkbd(4) control device.

The Consumer Control class driver is basically a special keyboard driver that handles multimedia keys found on USB keyboard. It translates consumer page usage (USB multimedia keys) to unassigned or rarely used keycodes. See uhidd.conf(5) for how to configure the keymap. If a multimedia keymap is not found in the configuration for a USB keyboard, The driver will create a in-memory keymap and assigns keycodes automatically when multimedia keys are pressed. This in-memory keymap will also be stored in /var/run/uhidd.ugen%u.%u/cc_keymap, and can be copy-pasted into configuration file so the driver can load the keymap directly next time.

All other HID application collections that don't have a specific driver can be attached by the Virtual Generic HID class driver. The driver creates a virtual USB HID device using the cuse(4) interface, so normal USB HID applications that deal with uhid(4), e.g. usbhidctl(1), could access the data through the virutal interface.

The uhidd daemon supports the following options:
file
Specify the path to the configuration file. The default path is /usr/local/etc/uhidd.conf.
Do not detach from the controlling terminal, i.e., run in foreground. This option is intended for debugging the daemon.
Dump HID device report descriptor in human readable form. This option implies -d.
Attach the Virtual Generic HID class driver. This option requires that cuse(4) driver loaded as a kernel module.
devname
Specify the name of the virtual HID device created by the virtual generic HID driver. The default name used for the device is “uvhid”.
Attach Keyboard class driver. This option requires that vkbd(4) compiled in the kernel or loaded as a kernel module, and that the keyboard multiplexer kbdmux(4) be enabled.
Attach Mouse class driver.
Attach Consumer Control class driver.
Instruct the Virtual Generic HID driver to strip the report ID byte from the hid report data. This is needed if the hid application is using usbhid(3) parser to parse the data read from the simulated uhid(4) interface.
When this option is specified, if there is an active kernel driver attached to the device interface, the uhidd daemon will try to detach the active kernel driver first, before attaching itself to the device. This option is easpecially useful when there is no easy way to unload the kernel USB HID device drivers. If this option is not present and the uhidd daemon finds out the device is already attached by a kernel driver, it will abort and let the kernel driver continue handling the device.
When this option is specified, the uhidd deamon will attach the device interface even if there is an active kernel driver attached to the device, or if the daemon fails to detach the kernel driver.
Output additional information for debugging purpose. Multiple -v specified in the command line will increase the level of the verbosity. This option implies -d.
Output the version of uhidd daemon to stderr and exit.

There are more options that can be configured through uhidd.conf(5).

The uhidd daemon can coexist with the kernel USB HID drivers for keyboard, mouse etc. When the daemon starts, if it detects there is an active kernel driver already attached to the device, it will abort gracefully. If the option -u is specified or the configuration option “detach_kernel_driver” is applicable for the device, it will attempt to detach the kernel driver first before attaching itself to the device.

However note that if the kernel USB HID drivers are compiled as kernel modules and are not yet loaded at the point when the device is attached to the system, the uhidd daemon will attach itself to the device first, and the kernel driver will be loaded and attached to the device after. As a result, both uhidd daemon and the kernel driver will attach to the device at the same time, which causes undefined behaviours. To overcome this problem, when the kernel drivers are compiled as modules, the devd(8) rules listed in the “/etc/devd/usb.conf” config file for the relevant USB HID kernel modules should be removed.

/usr/local/etc/uhidd.conf
the default name of the configuration file
/var/run/uhidd.ugen.%u.%u.pid
process id of the currently running uhidd daemon that attached to device ugen.%u.%u
/var/run/uhidd.ugen.%u.%u/cc_keymap
the in-memory multimedia keymap for device ugen.%u.%u

usbhidaction(1), usbhidctl(1), cuse(3), usb(3), usbhid(3), uhid(4), vkbd(4), uhidd.conf(5), bthidd(8), moused(8)

There are additional instructions and setup examples in the web page: http://wiki.FreeBSD.org/uhidd

The uhidd daemon was written by Kai Wang ⟨kaiw@FreeBSD.org⟩, based on the work done by many others.
October 23, 2012 FreeBSD 13.1-RELEASE

Search for    or go to Top of page |  Section 8 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.