.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Device::USB::FAQ 3pm"
.TH Device::USB::FAQ 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Device::USB::FAQ \- Frequently Asked Questions for Device::USB
.SH SYNOPSIS
.IX Header "SYNOPSIS"
perldoc Device::USB::FAQ
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This is an attempt to answer some of the frequently asked questions about
the Device::USB module
.SH QUESTIONS
.IX Header "QUESTIONS"
.SS "Which platforms does Device::USB support?"
.IX Subsection "Which platforms does Device::USB support?"
\&\f(CW\*(C`Device:USB\*(C'\fR supports any platform that \f(CW\*(C`libusb\*(C'\fR supports. This list
currently includes Linux, FreeBSD, NetBSD, OpenBSD, Darwin, and MacOS X.
.PP
There is a port of the \f(CW\*(C`libusb\*(C'\fR library to the Windows environment called
\&\f(CW\*(C`LibUsb\-Win32\*(C'\fR. Because I don't have a development environment for testing
this library, \f(CW\*(C`Device::USB\*(C'\fR does not yet support this library.
.SS "Do I have to use Device::USB as root?"
.IX Subsection "Do I have to use Device::USB as root?"
By default, access to the USB devices on a Unix-based system appear to be
limited to the root account. This usually causes access to most of the
\&\f(CW\*(C`libusb\*(C'\fR features to fail with a permission error.
.PP
Using the \f(CW\*(C`Device::USB\*(C'\fR module as root avoids this feature, but is not
very satisfying from a security standpoint. (See the next question for
more options.)
.SS "How do I enable use of Device::USB as a non-root user?"
.IX Subsection "How do I enable use of Device::USB as a non-root user?"
Some of the attributes of USB devices are available to non-root users, but
accessing many of the more interesting features require special privileges.
According to the libusb source, the \f(CWopen()\fR function requires either device
nodes to be present or the usbfs file system to be mounted in specific
locations. Those places in order are:
.IP 1) 4
.IX Item "1)"
\&\fI/dev/bus/usb\fR  \- pre\-2.6.11: via devfs / post\-2.6.11: via udev
.IP 2) 4
.IX Item "2)"
\&\fI/proc/bus/usb\fR \- usbfs
.PP
Look in both locations on your system for which of these two methods your
libusb will use.
.PP
No matter which method your system uses, you will probably want to create a
separate group to control access. Run this command to add a system group:
.PP
.Vb 1
\&  addgroup \-\-system usb
.Ve
.PP
or
.PP
.Vb 1
\&  groupadd \-\-system usb
.Ve
.PP
You can then add users to that group to allow access to your usb devices.
.PP
\fIDEVFS / HOTPLUG\fR
.IX Subsection "DEVFS / HOTPLUG"
.PP
TODO
.PP
\fIUDEV\fR
.IX Subsection "UDEV"
.PP
If you use Debian/Ubuntu, look in the \fI/etc/udev/permissions.rules\fR file.
If you want to allow global access to all usb devices, make this change:
.PP
Change this:
  SUBSYSTEM=="usb_device", MODE="0664"
.PP
To this:
  SUBSYSTEM=="usb_device", MODE="0664", GROUP="usb"
.PP
After you reboot, all usb devices will inherit the mode and group specified.
.PP
If you want to only change permissions for certain devices, you can add this
on one line and adjust the product and vendor IDs:
.PP
.Vb 2
\&  SUBSYSTEM=="usb_device", GROUP="usb", \e
\&    SYSFS{idVendor}=="1234", SYSFS{idProduct}=="1234"
.Ve
.PP
\fIUSBFS\fR
.IX Subsection "USBFS"
.PP
The usbfs defaults to root as the user and group. This can be changed in the
\&\fI/etc/fstab\fR by adding the following on one line:
.PP
.Vb 5
\&  none /proc/bus/usb usbfs noauto,\e
\&      listuid=0,listgid=118,listmode=0664,\e
\&      busuid=0,busgid=118,busmode=0775,\e
\&      devuid=0,devgid=118,devmode=0664\e
\&      0 0
.Ve
.PP
The value \f(CW118\fR in the above should be replaced with the group id of
your usb group (created above). The list* values are to allow listing
devices, the bus* is to control access to the bus directories and the
dev* values control access to the device files. This approach does not
allow the kind of granular permission that the udev approach gives, so
it is all or nothing unless permissions are changed programmatically.
.PP
If your \fI/etc/fstab\fR file already has a line for \fI/proc/bus/usb\fR, add the
options above to the line that is already there rather than adding the
new line. For example, you would change
.PP
.Vb 1
\&  usbfs   /proc/bus/usb   usbfs   noauto  0 0
.Ve
.PP
to
.PP
.Vb 5
\&  usbfs   /proc/bus/usb   usbfs  noauto,\e
\&      listuid=0,listgid=118,listmode=0664,\e
\&      busuid=0,busgid=118,busmode=0775,\e
\&      devuid=0,devgid=118,devmode=0664\e
\&      0 0
.Ve
.PP
Once again, this needs to be all on one line with the \f(CW\*(C`\e\*(C'\fR characters
removed.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Device::USB and the \f(CW\*(C`libusb\*(C'\fR library site at
<http://libusb.sourceforge.net/>.
.SH AUTHOR
.IX Header "AUTHOR"
G. Wade Johnson (gwadej at cpan dot org)
Paul Archer (paul at paularcher dot org)
.PP
Houston Perl Mongers Group
.SH ACKNOWLEDGEMENTS
.IX Header "ACKNOWLEDGEMENTS"
Thanks go to various users who submitted questions and answers for the
list. In particular, Anthony L. Awtrey who contributed the first FAQ answer.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2006\-2013 Houston Perl Mongers
.PP
This document is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.