$Id: HOWTO.libusb,v 1.1 2002/10/15 13:29:58 poeml Exp $

LIBUSB Howto,
How to use libusb in the CL20 driver (and other USB projects).

The gphoto2 USB IO library is based on libusb, a library which allows
userspace programs access to USB devices.


1. Required software
libusb: at http://libusb.sourceforge.net
Most likely though, you already have it (it is a dependancy for gphoto for
example). 
Note: I use 1.5.something (#FIXME)


1.1 Required kernel settings
In order to allow userspace access to USB devices (still carefully protected
through the hotplug manager), you need the following kernel options enabled:

# USB support
CONFIG_USB=y
CONFIG_USB_DEBUG=y
CONFIG_USB_DEVICEFS=y

And one of the following (depending on your hardware)
CONFIG_USB_UHCI_ALT=y
# CONFIG_USB_OHCI is not set

Then, mount the USB_FS like:
mount -t usbdevfs none /proc/bus/usb

You can add the information to /etc/fstab, but on my Gentoo box it is mounted
automagically without it :-)


1.2 Permissions
The /proc/bus/usb/... data (all directories and files inside it) need to have
both read and write permissions set to allow your program or user account
to use the USB device.
Either chmod it to 777 as root (for development purposes only :), run the
tests as root (during development only :) or figure out how to get hotplug
to set the permissions accordingly!

#TODO: section on setting up hotplug



2.0 Introduction to libusb
libusb is a cross-platform, very easy to use library allowing full access to
the USB subsystem on your computer. The documentation is a bit sparse, so I
have collected my experiences here.


2.1 Preparations
Add:
	#include <usb.h>
to your source file.
Compile with
	"-lusb"


2.2 Initialization
You can optionally call:
	void usb_set_debug( int )
to set the debugging level, try something large and you should get plenty of
information :-)

Then, the first call (after usb_set_debug if you want) is
	void usb_init()
It doesn't return anything, but it might show some debugging information
if you have called usb_set_debug() beforehand.

Next comes:
	int usb_find_busses()
The result code should be 0 for success, or < 0 for an error. 
Example use:
	int result;
	result = usb_find_busses();
	printf("usb_find_busses() returned %d (%s)\n", result, usb_strerror()));
NOTE: usb_strerror() returns as a char *, the result of the latest action.
Think of the good old #include <errno.h> perror() days :-)

Then:
	int usb_find_devices()
The funny part here is that the result code is always 0, but usb_strerror()
DOES return the right error (for example permission error).
So for this call you could use:
	int result;
	result = usb_find_devices();
	printf("usb_find_devices() returned %d (%s)\n", result, usb_strerror()));
	if (strncmp(usb_strerror(),"No error", 8) != 0)
		printf("Error condition!\n");

	
More information to follow, please look at the initial test program!