rusefi
/
usb4java
mirror of https://github.com/rusefi/usb4java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added some documentation to the site.

This commit is contained in:
Klaus Reimer 2011-02-06 00:46:52 +01:00 committed by k
parent 82e64dcfa9
commit cf711435ec
3 changed files with 177 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
src/site/apt/index.apt.vm
View File

@ -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
is not well tested at the moment.
the {{{http://www.javax-usb.org/}javax.usb standard (JSR-80)}}.
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.
[]

176
src/site/apt/manual.apt.vm
View File

@ -2,6 +2,178 @@
Manual
-----------------------------------------------------------------------------
Manual
Installation
{{{./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.
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}}
[]
TODO

1
src/site/site.xml
View File

@ -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>