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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
UHIDD(8)		FreeBSD	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
     receive data through the shared interrupt endpoint	and pass it to the
     right class driver	instance. The class driver then	process	the data as

     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 cuse4bsd(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
		 requires that cuse4bsd(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
		 device	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
		 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 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
     active 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
     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 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), cuse4bsd(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.

FreeBSD	11.0			 March 6, 2010			  FreeBSD 11.0


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

home | help