From 1be9a336aae902b7c4eca1f1aace8cb7d5e60585 Mon Sep 17 00:00:00 2001 From: Klaus Reimer Date: Sat, 8 Mar 2014 10:39:35 +0100 Subject: [PATCH] Improved some documentation --- pom.xml | 6 +- src/site/apt/faq.apt.vm | 26 +++++ src/site/apt/quickstart.apt | 206 +++++++++++++++++++++++++++++++++ src/site/apt/quickstart.apt.vm | 64 ---------- src/site/xdoc/index.xml.vm | 10 +- 5 files changed, 243 insertions(+), 69 deletions(-) create mode 100644 src/site/apt/quickstart.apt delete mode 100644 src/site/apt/quickstart.apt.vm diff --git a/pom.xml b/pom.xml index 2d44820..810e95a 100644 --- a/pom.xml +++ b/pom.xml @@ -83,6 +83,10 @@ https://ci.ailis.de/job/${project.artifactId}/ + + 3.0 + + @@ -195,7 +199,7 @@ maven-assembly-plugin - 2.2.2 + 2.4 false diff --git a/src/site/apt/faq.apt.vm b/src/site/apt/faq.apt.vm index 11c0af5..1517e7b 100644 --- a/src/site/apt/faq.apt.vm +++ b/src/site/apt/faq.apt.vm @@ -40,3 +40,29 @@ Frequently asked questions On Windows you need to create a driver for your USB device. Read the {{{https://github.com/libusb/libusb/wiki/Windows#wiki-How_to_use_libusb_on_Windows}How to use libusb on Windows}} article from the {{{http://libusb.info}libusb project}} for more information. + +* My program crashes. What can I do? + + If the program crashes with a Java stack trace then it is most likely a + problem in your own program. If you can't find it you may find some help on + the {{{./mail-lists.html}mailinglist}}. + + If the JVM crashes the hard way because of a segfault in the native code then + it is more likely a problem of usb4java or libusb and you should file a + {{{./issue-tracking.html}bugreport}} with as much information as possible + (Full stack trace, full crash log, example code how to reproduce the crash). + + If usb4java crashes on Windows then please first of all make sure you have + created a proper device driver as explained in the previous FAQ entry. Also + consider creating a new up-to-date device driver with the latest Zadig tool. + + If you have experience in C programming then it would be very helpful when + you could try to reproduce the problem in C by directly using libusb. If + this works but the same USB communication doesn't work with usb4java then it + would be nice if you could give us your C source and Java source so we can + track down the difference which causes the crash. If the C program also + crashes then your problem is located in libusb and not in usb4java and you + should consult the libusb mailinglist or bug tracker instead. Never report a + problem in the libusb bug tracker or the libusb mailing list if you + can't reproduce the problem with a native C program! + \ No newline at end of file diff --git a/src/site/apt/quickstart.apt b/src/site/apt/quickstart.apt new file mode 100644 index 0000000..7deb3c4 --- /dev/null +++ b/src/site/apt/quickstart.apt @@ -0,0 +1,206 @@ + ----------------------------------------------------------------------------- + Quick start + ----------------------------------------------------------------------------- + +Quick start + +* Choose an API + + usb4java provides two different APIs you can work with: + + * The low-level (libusb) API + + * The high-level (javax.usb) API + + [] + + The high-level API simply implements the + {{{http://javax-usb.sourceforge.net/}javax.usb (JSR80) API}}. One advantage + of this API is that it is implementation-independent. So it is easy to + switch to a different javax.usb implementation later without changing your + code. Another advantage is that this API is object oriented and is much + easier to use for Java developers. The disadvantage is that the javax.usb + project is pretty old and currently looks inactive, maybe even dead. + + The low-level API closely follows the C API of the + {{{http://libusb.info/}libusb}} project. This API has the advantage that it + provides the same functionality as libusb does. And if you know the C API of + libusb then you will most likely feel right at home when using this API + with usb4java. The disadvantage is that you will have a hard time changing + your code when you later switch to a different Java USB library. + +* The low-level (libusb) API + +** API design + + The low-level API of usb4java closely follows the C API of the + {{{http://libusb.info/}libusb}} project. All global functions and + constants of are defined as static members of the class + {{{./apidocs/org/usb4java/LibUsb.html}org.usb4java.LibUsb}}. + All structures of are defined in separate classes which are named + similar to the original struct names but without underscores, with upper + case names and with the prefix removed. For example the struct + is defined in the class + {{{./apidocs/org/usb4java/DeviceHandle.html}DeviceHandle}}. Struct + members are represented by static methods in the corresponding class. + + The following notable differences exists between the and + the API: + + * in the configuration descriptor is named because + is a reserved word in Java. + + * in the configuration descriptor is named 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 direct Java NIO ByteBuffer instead. + + * 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. + + [] + +** Initialization/deinitialization + + Before using any usb4java functionality you must initialize libusb: + +---- +final Context context = new Context(); +int result = LibUsb.init(context); +if (result < 0) throw new RuntimeException("Unable to initialize libusb. Result=" + result); +---- + + Specifiying a context is optional. If your application only needs a single + libusb context then you can specify as context. + + Before your application terminates you should deinitialize libusb: + +---- +LibUsb.exit(context); +---- + + +** Find your device + + Your program most likely wants to communicate with a specific device so first + of all you have to find it. You have to get a list of all connected USB + devices and then check the vendor/product ids. Here is a method which can + be used for this purpose: + +---- +public Device findDevice(short vendorId, short productId) +{ + // Read the USB device list + DeviceList list = new DeviceList(); + int result = LibUsb.getDeviceList(null, list); + if (result < 0) throw new LibUsbException("Unable to get device list", result); + + try + { + // Iterate over all devices and scan for the right one + for (Device device: list) + { + DeviceDescriptor descriptor = new DeviceDescriptor(); + result = LibUsb.getDeviceDescriptor(device, descriptor); + if (result < 0) throw new LibUsbException("Unable to read device descriptor", result); + if (descriptor.idVendor() == vendorId && descriptor.idProduct() == productId) return device; + } + } + finally + { + // Ensure the allocated device list is freed + LibUsb.freeDeviceList(list, true); + } + + // Device not found + return null; +} +---- + + In your application it might be a little bit more complicated. Maybe you + have more than one device of the same type so you may need a list of devices. + Or you have to identify your device by the product or vendor string + descriptor instead of just checking the ID (In case you are using a + shared vendor/product ID). But this example should bring you on the right + track. + +** Device handles + + For the real USB communication you must open a new device handle and you + must close it again when you are finished communicating with the device. + Example: + +---- +DeviceHandle handle = new DeviceHandle(); +int result = LibUsb.open(device, handle); +if (result != LibUsb.SUCCESS) throw new LibUsbException("Unable to open USB device", result); +try +{ + // Use device handle here +} +finally +{ + LibUsb.close(handle); +} +---- + +** Interfaces + + Usually you are communicating with an interface provided by the USB device and + you have to claim this interface before using it and you have to release it + when you are finished. Example: + +---- +int result = LibUsb.claimInterface(handle, interfaceNumber); +if (result != LibUsb.SUCCESS) throw new LibUsbException("Unable to claim interface", result); +try +{ + // Use interface here +} +finally +{ + result = LibUsb.releaseInterface(handle, interfaceNumber); + if (result != LibUsb.SUCCESS) throw new LibUsbException("Unable to release interface", result); +} +---- + +** Communication + + For the actual USB communication you usually have to create a direct + byte buffer for the data to send or receive. Here is an example which + sends 8 bytes to a claimed interface unsing a control transfer: + +---- +ByteBuffer buffer = ByteBuffer.allocateDirect(8); +buffer.put(new byte[] { 1, 2, 3, 4, 5, 6, 7, 8 }); +int transfered = LibUsb.controlTransfer(handle, + (byte) (LibUsb.REQUEST_TYPE_CLASS | LibUsb.RECIPIENT_INTERFACE), + (byte) 0x09, (short) 2, (short) 1, buffer, 2500); +if (transfered < 0) + throw new LibUsbException("Control transfer failed", transfered); +if (transfered != message.length) + throw new RuntimeException("Not all data was sent to device"); +---- + + You may also want to use + {{{./apidocs/org/usb4java/LibUsb.html##bulkTransfer(org.usb4java.DeviceHandle, byte, java.nio.ByteBuffer, java.nio.IntBuffer, long)}bulkTransfer}} or + {{{./apidocs/org/usb4java/LibUsb.html##interruptTransfer(org.usb4java.DeviceHandle, byte, java.nio.ByteBuffer, java.nio.IntBuffer, long)}interruptTransfer}} + instead of + {{{./apidocs/org/usb4java/LibUsb.html##controlTransfer(org.usb4java.DeviceHandle, byte, byte, short, short, java.nio.ByteBuffer, long)}controlTransfer}} + + The parameters needed for the transfer calls are completely + device dependent so you have to check the device documentation for details. + +* See also + + * {{{./apidocs/org/usb4java/package-summary.html}API documentation of usb4java}} + + * {{{http://javax-usb.sourceforge.net/jdoc/}javax.usb (JSR80) API documentation}} + + * {{{http://libusb.sourceforge.net/api-1.0/}API documentation of libusb}} + + [] + \ No newline at end of file diff --git a/src/site/apt/quickstart.apt.vm b/src/site/apt/quickstart.apt.vm deleted file mode 100644 index df136b4..0000000 --- a/src/site/apt/quickstart.apt.vm +++ /dev/null @@ -1,64 +0,0 @@ - ----------------------------------------------------------------------------- - Quick start - ----------------------------------------------------------------------------- - -API design - - The API of usb4java closely follows the C API of the - {{{http://libusb.info/}libusb}} project. All global functions and - constants of are defined as static members of the class - {{{./apidocs/org/usb4java/LibUsb.html}org.usb4java.LibUsb}}. - All structures of are defined in separate classes which are named - similar to the original struct names but without underscores, with upper - case names and with the prefix removed. For example the struct - is defined in the class - {{{./apidocs/org/usb4java/DeviceHandle.html}DeviceHandle}}. Struct - members are represented by static methods in the corresponding class. - - The following notable differences exists between the and - the API: - - * in the configuration descriptor is named because - is a reserved word in Java. - - * in the configuration descriptor is named 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 direct Java NIO ByteBuffer instead. - - * 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. - - [] - -* Initialization/deinitialization - - Before using any usb4java functionality you must initialize libusb: - ----- -final Context context = new Context(); -int result = LibUsb.init(context); -if (result < 0) throw new RuntimeException("Unable to initialize libusb. Result=" + result); ----- - - Specifiying a context is optional. If your application only needs a single - libusb context then you can specify as context. - - Before your application terminates you should deinitialize libusb: - ----- -LibUsb.exit(context); ----- - - -* See also - - * {{{./apidocs/org/usb4java/package-summary.html}API documentation of usb4java}} - - * {{{http://libusb.sourceforge.net/api-1.0/}API documentation of libusb}} - - [] - \ No newline at end of file diff --git a/src/site/xdoc/index.xml.vm b/src/site/xdoc/index.xml.vm index a8a935d..0be3084 100644 --- a/src/site/xdoc/index.xml.vm +++ b/src/site/xdoc/index.xml.vm @@ -30,7 +30,7 @@ ${project.artifactId}-${project.version}.zip
  • - javax-usb extension:
    + javax.usb extension:
    ${project.artifactId}-javax-${usb4javaJavaxVersion}.tar.bz2
    ${project.artifactId}-javax-${usb4javaJavaxVersion}.zip
    • @@ -52,7 +52,7 @@ </repository> </repositories> -<-- For using just usb4java without javax-usb --> +<-- For using just usb4java without javax.usb --> <dependencies> <dependency> <groupId>${project.groupId}</groupId> @@ -61,7 +61,7 @@ </dependency> </dependencies> -<-- For using usb4java with javax-usb --> +<-- For using usb4java with javax.usb --> <dependencies> <dependency> <groupId>${project.groupId}</groupId> @@ -91,7 +91,9 @@

    Read the quick start guide and the FAQ. There are also some - examples + low-level (libusb) examples + and + high-level (javax.usb) examples available.