Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
UHIDD(8)		  BSD System Manager's Manual		      UHIDD(8)

     uhidd -- USB HID daemon

     uhidd [-c file] [-DdhkmosuVv] /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 log-
     ical 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 re-
     ceive data	through	the shared interrupt endpoint and pass it to the right
     class driver instance. The	class driver then process the data as approri-

     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 collec-
     tion 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

     The Consumer Control class	driver is basically a special keyboard driver
     that handles multimedia keys found	on USB keyboard. It translates con-
     sumer page	usage (USB multimedia keys) to unassigned or rarely used key-
     codes. 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 configu-
     ration 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 cre-
     ates 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:

     -c	file	 Specify the path to the configuration file. The default path
		 is /usr/local/etc/uhidd.conf.

     -D		 Dump HID device report	descriptor in human readable form.
		 This option implies -d.

     -d		 Do not	detach from the	controlling terminal, i.e., run	in
		 foreground. This option is intended for debugging the daemon.

     -h		 Attach	the Virtual Generic HID	class driver.  This option re-
		 quires	that cuse(4) driver loaded as a	kernel module.

     -H		 Specify the name of the virtual HID device created by the
		 virtual generic HID driver. The default name used for the de-
		 vice is "uvhid".

     -k		 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.

     -m		 Attach	Mouse class driver.

     -o		 Attach	Consumer Control class driver.

     -s		 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.

     -u		 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 at-
		 taching 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 han-
		 dling the device.

     -V		 Output	the version of uhidd daemon to stderr and exit.

     -v		 Output	additional information for debugging purpose. Multiple
		 -v specified in the command line will increase	the level of
		 the verbosity.	This option implies -d.

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

     The uhidd daemon can coexist with the kernel USB HID drivers for key-
     board, mouse etc.	When the daemon	starts,	if it detects there is an ac-
     tive kernel driver	already	attached to the	device,	it will	abort grace-
     fully. 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 de-
     vice 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 rel-
     evant USB HID kernel modules should be removed.

     /usr/local/etc/uhidd.conf		      the default name of the configu-
					      ration file
     /var/run/	      process id of the	currently run-
					      ning 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:

     The uhidd daemon was written by Kai Wang <>, based	on the
     work done by many others.

BSD				 March 6, 2010				   BSD


Want to link to this manual page? Use this URL:

home | help