sparrowwallet/usb4java
sparrowwallet/usb4java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improved some documentation

Browse Source
This commit is contained in:
Klaus Reimer 2014-03-08 10:39:35 +01:00
parent b6198180ab
commit 1be9a336aa
5 changed files with 243 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
pom.xml
View File

@ -83,6 +83,10 @@
<url>https://ci.ailis.de/job/${project.artifactId}/</url>
</ciManagement>
<prerequisites>
<maven>3.0</maven>
</prerequisites>
<reporting>
<plugins>
<plugin>
@ -195,7 +199,7 @@
<!-- Build binary artifacts for Unix, Mac OS X and Windows -->
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>2.2.2</version>
<version>2.4</version>
<configuration>
<appendAssemblyId>false</appendAssemblyId>
<descriptors>

26
src/site/apt/faq.apt.vm
View File

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

206
src/site/apt/quickstart.apt Normal file
View File

@ -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 <libusb> are defined as static members of the class
{{{./apidocs/org/usb4java/LibUsb.html}org.usb4java.LibUsb}}.
All structures of <libusb> are defined in separate classes which are named
similar to the original struct names but without underscores, with upper
case names and with the <libusb> prefix removed. For example the struct
<libusb_device_handle> 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 <libusb 1.0 API> and
the <usb4java> API:
* <interface> in the configuration descriptor is named <iface> because
<interface> is a reserved word in Java.
* <MaxPower> in 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 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 <null> 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}}
[]

64
src/site/apt/quickstart.apt.vm
View File

@ -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 <libusb> are defined as static members of the class
{{{./apidocs/org/usb4java/LibUsb.html}org.usb4java.LibUsb}}.
All structures of <libusb> are defined in separate classes which are named
similar to the original struct names but without underscores, with upper
case names and with the <libusb> prefix removed. For example the struct
<libusb_device_handle> 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 <libusb 1.0 API> and
the <usb4java> API:
* <interface> in the configuration descriptor is named <iface> because
<interface> is a reserved word in Java.
* <MaxPower> in 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 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 <null> 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}}
[]

10
src/site/xdoc/index.xml.vm
View File

@ -30,7 +30,7 @@
<strong><a href="${artifactBaseUrl}.zip">${project.artifactId}-${project.version}.zip</a></strong><br />
</li>
<li>
javax-usb extension:<br />
javax.usb extension:<br />
<strong><a href="${artifactBaseUrl}.tar.bz2">${project.artifactId}-javax-${usb4javaJavaxVersion}.tar.bz2</a></strong><br />
<strong><a href="${artifactBaseUrl}.zip">${project.artifactId}-javax-${usb4javaJavaxVersion}.zip</a></strong><br />
</li>
@ -52,7 +52,7 @@
&lt;/repository&gt;
&lt;/repositories&gt;
&lt;-- For using just usb4java without javax-usb --&gt;
&lt;-- For using just usb4java without javax.usb --&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
@ -61,7 +61,7 @@
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;-- For using usb4java with javax-usb --&gt;
&lt;-- For using usb4java with javax.usb --&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
@ -91,7 +91,9 @@
<p>
Read the <a href="quickstart.html">quick start guide</a> and the
<a href="faq.html">FAQ</a>. There are also some
<a href="https://github.com/usb4java/usb4java-examples/">examples</a>
<a href="https://github.com/usb4java/usb4java-examples/">low-level (libusb) examples</a>
and
<a href="https://github.com/usb4java/usb4java-javax-examples/">high-level (javax.usb) examples</a>
available.
</p>
</section>