Renamed manual to quickstart.

Added more quickstart information.
Added FAQ page.
Added warning to index page.

src/site/apt/faq.apt.vm

@@ -0,0 +1,17 @@
+ -----------------------------------------------------------------------------
+ FAQ
+ -----------------------------------------------------------------------------
+ 
+Frequently asked questions
+
+  If you have a question which is not answered here please drop me a mail
+  at {{{mailto:k@ailis.de}k@ailis.de}}.
+
+* Why are there no frequently asked questions here?
+
+  Because no one asked one so far. <usb4java> is pretty new and if you are
+  reading this you may be the first person who is interested in it. Please give
+  it a try and give me feedback.
+
+
+

src/site/apt/index.apt.vm

@@ -21,6 +21,13 @@ What is usb4java?
   want to use with usb4java (Instructions can be found on the libusb-win32
   website).
   
+  <<Warning! usb4java is a brand-new project and is not well tested.
+  The low-level API will most likely work as expected because it simply
+  wraps a stable native API but the javax.usb based high-level API is
+  a complicated piece of software and may contain many bugs. But
+  to squish them I need testers so please give it a try and give me feedback
+  or send me patches: {{{mailto:k@ailis.de}k@ailis.de}}>>     
+  
 
 News
 
@@ -45,7 +52,7 @@ License
 Getting started
 
   {{{./download.html}Download}} the latest usb4java and then 
-  read the {{{./manual.html}manual}} for some basic instructions how to use it.
+  read the {{{./quickstart.html}quick start guide}} and the {{{./faq.html}FAQ}}.
 
 
 Report problems

src/site/apt/quickstart.apt.vm

@@ -1,5 +1,5 @@
  -----------------------------------------------------------------------------
- Manual
+ Quick start
  -----------------------------------------------------------------------------
  
 Installation
@@ -125,7 +125,9 @@ javax.usb.services = de.ailis.usb4java.Services
   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: 
+  USB devices.
+  
+  The following source shows how to iterate over all devices: 
 
 +-----------------------------------------------------------------------------+
 public class Dump
@@ -153,21 +155,47 @@ public class Dump
 }
 +-----------------------------------------------------------------------------+
 
-  You may notice some annoyances here. First of all the <javax.usb> API doesn't
+  Often you need to search for a specific device before working with it. Here
-  use generics so type casting is needed when some method returns a List.
+  is an example how to scan the device tree for the first device with a
-  The second annoyance is that all descriptors of <javax.usb> use signed
+  specific vendor and product id. It can be easily expanded to check for
-  types where the USB specification defines unsigned types. So an unsigned
+  specific device classes or whatever:
-  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
+public UsbDevice findDevice(UsbHub hub, short vendorId, short productId)
-  be converted to unsigned values by performing operations like <<& 0xff>>
+{
-  for 8-bit values and <<& 0xffff>> for 16 bit values.
+    for (UsbDevice device : (List<UsbDevice>) hub.getAttachedUsbDevices())
+    {
+        UsbDeviceDescriptor desc = device.getUsbDeviceDescriptor();
+        if (desc.idVendor() == vendorId && desc.idProduct() == productId) return device;
+        if (device.isUsbHub())
+        {
+            device = findDevice((UsbHub) device, vendorId, productId);
+            if (device != null) return device;
+        }
+    }
+    return null;
+}
++-----------------------------------------------------------------------------+
+  
+
+* Communicate via the Default Control Pipe 
+
+  This example reads the current configuration number from a device:
+  
++-----------------------------------------------------------------------------+
+UsbControlIrp irp = device.createUsbControlIrp(
+    (byte) (UsbConst.REQUESTTYPE_DIRECTION_IN
+          | UsbConst.REQUESTTYPE_TYPE_STANDARD
+          | UsbConst.REQUESTTYPE_RECIPIENT_DEVICE),
+    UsbConst.REQUEST_GET_CONFIGURATION,
+    (short) 0,
+    (short) 0
+    );
+irp.setData(new byte[1]);
+device.syncSubmit(irp);
+System.out.println(irp.getData()[0]);
++-----------------------------------------------------------------------------+
   
-  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
 

src/site/site.xml

@@ -21,7 +21,8 @@
     <menu name="usb4java">
       <item name="About" href="./index.html" />
       <item name="Download" href="./download.html" />
-      <item name="Manual" href="./manual.html" />
+      <item name="Quick start" href="./quickstart.html" />
+      <item name="FAQ" href="./faq.html" />
     </menu>
     
     <menu ref="reports" />