Added some documentation to the site.

src/site/apt/index.apt.vm

@@ -8,8 +8,7 @@ What is usb4java?
   based on the native {{{http://www.libusb.org/}libusb 0.1}} shared library
   and reflects this API as complete as possible. Java NIO buffers are used
   for data exchange between libusb and Java. The high-level part implements
-  the {{{http://www.java-usb.org/}javax.usb standard (JSR-80)}} but this part
+  the {{{http://www.javax-usb.org/}javax.usb standard (JSR-80)}}.
-  is not well tested at the moment.
   
   Supported platforms are Linux (Intel 32/64 bit), Mac OS X (Intel 32/64 bit,
   PowerPC 32 bit) and Windows (Intel 32/64 bit). But other platforms may work
@@ -25,7 +24,7 @@ What is usb4java?
 
 News
 
-  * 2011/01/29 - Version 0.1.12-1 has been released.
+  * 2011/02/05 - Version 0.1.0 has been released.
 
   []
 

src/site/apt/manual.apt.vm

@@ -1,7 +1,179 @@
  -----------------------------------------------------------------------------
  Manual
  -----------------------------------------------------------------------------
+ 
+Installation
 
-Manual
+  {{{./download.html}Download}} the <usb4java.jar> and a binary JAR matching
+  your platform. Copy the <usb4java.jar> into your class path and extract
+  the binary JAR to a directory from which Java can load JNI shared libraries.
+  You may specify a custom directory with the java option
+  <-Djava.library.path=some/dir> when running your java programs.
+  
+  If you are using the high-level <javax.usb> API then you also need the
+  <jsr80.jar> which can be downloaded from the
+  {{{http://sourceforge.net/projects/javax-usb/files/}javax.usb project site}}.
+  This JAR must also be copied into your class path.
+  
 
-  TODO
+The low-level API
+
+  It is recommended to use the high-level javax.usb API but there are
+  situations where you might want to use the low-level API instead. 
+  For example if you are already familiar with libusb or if you
+  are porting a C program to Java then it might be easier to use the
+  low-level API which is based on libusb version 0.1.12.
+  
+  All global functions and constants of libusb are defined as static
+  members of the class
+  {{{./apidocs/de/ailis/usb4java/jni/USB.html}de.ailis.usb4java.jni.USB}}.
+  All structures of libusb are defined in separate classes which are named
+  similiar to the original struct names. For example the struct
+  <usb_device> is defined in the class
+  {{{./apidocs/de/ailis/usb4java/jni/USB_Device.html}USB_Device}}. Struct
+  members are represented by static methods in the corresponding class.
+   
+  The following differences exists between the <libusb 0.1 API> and
+  the low-level API of <usb4java>:
+    
+  * <interface> of the configuration descriptor is named <iface> because
+    <interface> is a reserved word in Java.
+    
+  * <MaxPower> of the configuration descriptor is named <bMaxPower> to
+    be compatible to the USB specification and because method names starting
+    with upper-case letters are quite unusual in Java.
+    
+  * Whenever libusb expects a byte pointer and a length you have to use
+    a Java NIO ByteBuffer instead.
+    
+  * The method <libusb_has_get_driver_np()> can be used to check if the
+    platform-dependent method <usb_get_driver_np()> is available. 
+
+  * The method <libusb_has_detach_kernel_driver_np()> can be used to check if
+    the platform-dependent method <usb_detach_kernel_driver_np()> is available.
+    
+  * All methods which are returning a string through a byte buffer which was
+    passed as argument have additional simplified overloaded method
+    equivalents which are returning a Java String directly.
+  
+  []
+  
+  It is recommended to use static imports to access the API. Here is a small
+  example which iterates over all USB devices and prints the vendor and
+  product IDs:
+  
++-----------------------------------------------------------------------------+
+import static de.ailis.usb4java.jni.USB.*;
+
+public class Dump
+{
+    public static void main(String[] args)
+    {
+        usb_init();
+        usb_find_busses();
+        usb_find_devices();
+        USB_Bus bus = usb_get_busses();
+        while (bus != null)
+        {
+            USB_Device device = bus.devices();
+            while (device != null)
+            {
+                USB_Device_Descriptor desc = device.descriptor();
+                System.out.format("%04x:%04x%n", desc.idVendor(), desc.idProduct());
+                device = device.next();
+            }
+            bus = bus.next();
+        }
+    }
+}
++-----------------------------------------------------------------------------+
+  
+* More information about the low-level API
+
+  * {{{./apidocs/de/ailis/usb4java/jni/package-summary.html}Low-level API documentation of usb4java}}
+  
+  * {{{http://libusb.sourceforge.net/doc/}API documentatiaon of libusb 0.1}}
+  
+  []
+  
+  
+The high-level API
+
+  The high-level API implements the
+  {{{http://www.javax-usb.org/}javax.usb (JSR-80)}} standard. It is
+  recommended to use this API because it is object-oriented, event-driven and
+  uses exceptions for error-handling instead of negative return values like
+  the low-level API. Another advantage is that you may switch to a
+  different <javax.usb> implementation later without changing your code.
+  For example instead of using <usb4java> you may try out the reference
+  implementation for Linux and Windows.
+  
+  
+* Configuration
+
+  To use the <usb4java> implementation you have to create a file named
+  <javax.usb.properties> in the root of your class path with the following
+  content:
+
++-----------------------------------------------------------------------------+
+javax.usb.services = de.ailis.usb4java.Services 
++-----------------------------------------------------------------------------+
+ 
+ 
+* Finding USB devices
+
+  USB devices are managed in a tree. The root of this tree is a virtual
+  USB hub to which all physical root hubs are connected. More hubs can be
+  connected to these root hubs and any hub can have a number of connected
+  USB devices. The following source shows how to iterate over all devices: 
+
++-----------------------------------------------------------------------------+
+public class Dump
+{
+    private static void dump(UsbDevice device)
+    {
+        UsbDeviceDescriptor desc = device.getUsbDeviceDescriptor();
+        System.out.format("%04x:%04x%n", desc.idVendor() & 0xffff, desc.idProduct() & 0xffff);
+        if (device.isUsbHub())
+        {
+            UsbHub hub = (UsbHub) device;
+            for (UsbDevice child : (List<UsbDevice>) hub.getAttachedUsbDevices())
+            {
+                dump(child);
+            }
+        }
+    }
+
+    public static void main(String[] args) throws UsbException
+    {
+        UsbServices services = UsbHostManager.getUsbServices();
+        UsbHub rootHub = services.getRootUsbHub();
+        dump(rootHub);
+    }
+}
++-----------------------------------------------------------------------------+
+
+  You may notice some annoyances here. First of all the <javax.usb> API doesn't
+  use generics so type casting is needed when some method returns a List.
+  The second annoyance is that all descriptors of <javax.usb> use signed
+  types where the USB specification defines unsigned types. So an unsigned
+  8 bit value is of type <byte> (which is signed 8 bit) and an unsigned 16
+  bit value is of type <short> (signed 16 bit). This means that in some
+  situations like the formatted output in the example above the values must
+  be converted to unsigned values by performing operations like <<& 0xff>>
+  for 8-bit values and <<& 0xffff>> for 16 bit values.
+  
+  By the way: If you execute this program and no USB device is found at all
+  (except the virtual root hub) then this simply means that you have no
+  permissions to use any USB device   on your machine. On Linux for example
+  write permissions are needed on the device files. So you have to fix the
+  permissions of the USB device file or execute your program as root.
+
+* More information about the high-level API
+
+  * {{{./apidocs/index.html}API documentation of usb4java}}
+  
+  * {{{http://www.javax-usb.org/}javax-usb website}}
+  
+  []
+  

src/site/site.xml

@@ -9,6 +9,7 @@
 
   <body>
     <links>
+      <item name="javax.usb" href="http://www.javax-usb.org/" />
       <item name="libusb" href="http://www.libusb.org/" />
       <item name="libusb-win32" href="http://sourceforge.net/apps/trac/libusb-win32/wiki" />
     </links>