mirror of https://github.com/rusefi/usb4java.git
Improve documentation
This commit is contained in:
parent
5249c172f9
commit
df699d2612
|
@ -1,7 +1,7 @@
|
|||
-----------------------------------------------------------------------------
|
||||
Configuration
|
||||
-----------------------------------------------------------------------------
|
||||
|
||||
|
||||
Configuration
|
||||
|
||||
The configuration options explained here are only valid for the javax-usb
|
||||
|
@ -15,21 +15,21 @@ Configuration
|
|||
implementation you have to put the following property into the
|
||||
<javax.usb.properties> file which must be located in the root of
|
||||
your classpath:
|
||||
|
||||
|
||||
+----+
|
||||
javax.usb.services = org.usb4java.javax.Services
|
||||
+----+
|
||||
+----+
|
||||
|
||||
<usb4java> can be configured by adding more properties to this file as
|
||||
described in the following sections.
|
||||
|
||||
|
||||
|
||||
* Communication timeout
|
||||
|
||||
The default USB communication timeout of <usb4java> is 2500 milliseconds.
|
||||
To change this to 250 milliseconds for example add this to the properties
|
||||
file:
|
||||
|
||||
file:
|
||||
|
||||
+----+
|
||||
org.usb4java.javax.timeout = 250
|
||||
+----+
|
||||
|
@ -52,4 +52,15 @@ org.usb4java.javax.scanInterval = 1000
|
|||
+----+
|
||||
((org.usb4java.javax.Services) UsbHostManager.getUsbServices()).scan();
|
||||
+----+
|
||||
|
||||
|
||||
|
||||
* Use USBDK
|
||||
|
||||
If you want to use {{{https://github.com/daynix/UsbDk}USBDK}} on Windows
|
||||
then you have to enable the feature with the following entry:
|
||||
|
||||
+----+
|
||||
org.usb4java.javax.useUSBDK = true
|
||||
+----+
|
||||
|
||||
This setting is ignored on other platforms.
|
||||
|
|
|
@ -1,15 +1,15 @@
|
|||
-----------------------------------------------------------------------------
|
||||
FAQ
|
||||
-----------------------------------------------------------------------------
|
||||
|
||||
|
||||
Frequently asked questions
|
||||
|
||||
If you have a question which is not answered here please ask the
|
||||
{{{mailto:usb4java@googlegroups.com}usb4java mailing list}}
|
||||
({{{http://groups.google.com/group/usb4java}Google group}}).
|
||||
You can subscribe to it via email by sending a mail to
|
||||
You can subscribe to it via email by sending a mail to
|
||||
{{{mailto:usb4java+subscribe@googlegroups.com}usb4java+subscribe@googlegroups.com}}.
|
||||
|
||||
|
||||
* I can't open my USB device on Linux. Why?
|
||||
|
||||
On Linux you need write permissions on the device file of the USB device
|
||||
|
@ -20,49 +20,48 @@ Frequently asked questions
|
|||
</etc/udev/rules.d/99-userusbdevices.rules> with content like this:
|
||||
|
||||
----
|
||||
SUBSYSTEM=="usb",ATTR{idVendor}=="89ab",ATTR{idProduct}=="4567",MODE="0660",GROUP="wheel"
|
||||
SUBSYSTEM=="usb",ATTR{idVendor}=="89ab",ATTR{idProduct}=="4567",MODE="0660",GROUP="plugdev"
|
||||
----
|
||||
|
||||
This means that whenever a USB device with vendor id <0x89ab> and product id
|
||||
<0x4567> is attached then the group <wheel> is permitted to
|
||||
write to the device. So make sure your user is in that group (or use a
|
||||
different group).
|
||||
|
||||
|
||||
If your device uses a shared vendor/product id then you might want to
|
||||
filter for the manufacturer and product name. This can be done by checking
|
||||
the ATTR properties <manufacturer> and <product>.
|
||||
|
||||
|
||||
To activate this new configuration you may need to re-attach the USB device
|
||||
or run the command <<<udevadm trigger>>>.
|
||||
|
||||
* I can't open my USB device on Windows. Why?
|
||||
|
||||
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}}
|
||||
{{{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 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
|
||||
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
|
||||
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!
|
||||
|
||||
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!
|
||||
|
|
|
@ -1,41 +1,41 @@
|
|||
-----------------------------------------------------------------------------
|
||||
Native libraries
|
||||
-----------------------------------------------------------------------------
|
||||
|
||||
|
||||
Library loading
|
||||
|
||||
The native libraries for all supported platforms are provided as JAR files
|
||||
which you can simply reference in your classpath. usb4java automatically
|
||||
determines on startup which libraries are needed for the current platform
|
||||
and extracts them to a temporary directory and loads them from there.
|
||||
This makes it easy to use usb4java because you just need to put the JARs
|
||||
and extracts them to a temporary directory and loads them from there.
|
||||
This makes it easy to use usb4java because you just need to put the JARs
|
||||
into your classpath. No need to fiddle around with <java.library.path> or
|
||||
environment variables like <LD_LIBRARY_PATH> or <DYLD_LIBRARY_PATH>.
|
||||
|
||||
|
||||
usb4java only extracts the files into a temporary directory when they
|
||||
are inside a JAR file. So if you prefer direct loading without extracting
|
||||
to a temporary directory then you may want to distribute the files in
|
||||
extracted form. Just make sure your classpath includes the directory where
|
||||
you have extracted the JARs. Here is an example application layout for this
|
||||
scenario:
|
||||
|
||||
|
||||
+-----------------------------------------------------------------------------+
|
||||
natives/
|
||||
org/usb4java/
|
||||
linux-x86/libusb4java.so
|
||||
windows-x86/libusb4java.dll
|
||||
osx-x86/libusb4java.dylib
|
||||
linux-x86-64/libusb4java.so
|
||||
win32-x86-64/libusb4java.dll
|
||||
darwin-x86-64/libusb4java.dylib
|
||||
lib/
|
||||
usb4java.jar
|
||||
commons-lang3.jar
|
||||
myapp.jar
|
||||
myapp.sh
|
||||
+-----------------------------------------------------------------------------+
|
||||
+-----------------------------------------------------------------------------+
|
||||
|
||||
To make this work just make sure to put the <natives> folder into your
|
||||
classpath.
|
||||
classpath.
|
||||
|
||||
|
||||
|
||||
Unsupported platforms
|
||||
|
||||
When you use usb4java on a platform which is not directly supported by
|
||||
|
@ -46,7 +46,7 @@ Native library not found in classpath: /org/usb4java/freebsd-x86/libusb4java.so
|
|||
+----+
|
||||
|
||||
+----+
|
||||
Unable to determine the shared library file extension for operating system
|
||||
Unable to determine the shared library file extension for operating system
|
||||
'strangeos'. Please specify Java parameter -Dusb4java.libext.strangeos=<FILE-EXTENSION>
|
||||
+----+
|
||||
|
||||
|
@ -54,12 +54,12 @@ Unable to determine the shared library file extension for operating system
|
|||
is completely unknown to the usb4java authors and usb4java does not know the
|
||||
file extension of shared libraries on this platform. You can fix this by
|
||||
specifying a Java parameter like this (As explained in the exception):
|
||||
|
||||
|
||||
+----+
|
||||
-Dusb4java.libext.strangeos=so
|
||||
+----+
|
||||
|
||||
After this you will most likely get the other exception, which means that
|
||||
After this you will most likely get the other exception, which means that
|
||||
there is no native JNI wrapper present for this platform. Your only chance
|
||||
here is to compile this wrapper yourself. I can't predict how this works
|
||||
on really strange platforms but chances are high that your platform is
|
||||
|
@ -68,48 +68,53 @@ Unable to determine the shared library file extension for operating system
|
|||
1. Install a Java JDK ({{{http://openjdk.java.net/}OpenJDK}} for example).
|
||||
Make sure the environment variable <JAVA_HOME> is pointing to the
|
||||
directory where you have installed the JDK.
|
||||
|
||||
|
||||
2. Install the {{{http://libusb.info/}libusb}} development files.
|
||||
|
||||
|
||||
3. Install {{{http://git-scm.com/}Git}}.
|
||||
|
||||
|
||||
4. Clone the {{{https://github.com/usb4java/libusb4java/}libusb4java source code repository}} with Git:
|
||||
|
||||
|
||||
+----
|
||||
$ git clone git://github.com/usb4java/libusb4java.git
|
||||
+----
|
||||
|
||||
5. Enter the cloned libusb4java directory:
|
||||
|
||||
|
||||
+----
|
||||
$ cd libusb4java
|
||||
+----
|
||||
|
||||
6. Compile the native library:
|
||||
|
||||
+----
|
||||
$ ./autogen.sh
|
||||
$ ./configure --prefix=/
|
||||
$ make install-strip DESTDIR=/tmp
|
||||
+----
|
||||
6. Create a build output directory and enter it:
|
||||
|
||||
8. When compilation was successful then the native library can be found in
|
||||
+---
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
+---
|
||||
|
||||
7. Compile the native library:
|
||||
|
||||
+----
|
||||
$ cmake .. -DCMAKE_INSTALL_PREFIX=""
|
||||
$ make install/strip DESTDIR=/tmp
|
||||
+----
|
||||
|
||||
8. When compilation was successful then the native library can be found in
|
||||
the directory </tmp/lib>. The file name depends on your operating system.
|
||||
Make sure you rename it to <libusb4java.so> (Or whatever file extension
|
||||
your platform uses) and copy this file into the directory
|
||||
your platform uses) and copy this file into the directory
|
||||
</org/usb4java/OS-ARCH/> in your classpath where <OS> is the name
|
||||
of your operating system and <ARCH> is your CPU architecture (Both
|
||||
must match the names mentioned in the exception thrown by usb4java.)
|
||||
|
||||
If you can't use the GNU compiler or the autotools then you are on your own.
|
||||
|
||||
If you can't use the GNU compiler or cmake then you are on your own.
|
||||
If you have some experience with compiling JNI libraries then I guess this
|
||||
won't be hard for you. There are only a couple of source files in the <src>
|
||||
sub folder. You could write a new simple Makefile or whatever is needed on
|
||||
your platform.
|
||||
|
||||
If you have problems then please consult the
|
||||
If you have problems then please consult the
|
||||
{{{mailto:usb4java@googlegroups.com}usb4java mailing list}}
|
||||
({{{http://groups.google.com/group/usb4java}Google group}}).
|
||||
You can subscribe to it via email by sending a mail to
|
||||
{{{mailto:usb4java+subscribe@googlegroups.com}usb4java+subscribe@googlegroups.com}}.
|
||||
|
|
@ -7,14 +7,14 @@ Quick start
|
|||
* Choose an API
|
||||
|
||||
usb4java provides two different APIs you can choose from:
|
||||
|
||||
|
||||
* {{{./libusb.html}The low-level (libusb) API}}
|
||||
|
||||
|
||||
* {{{./javax-usb.html}The high-level (javax-usb) API}}
|
||||
|
||||
|
||||
[]
|
||||
|
||||
The low-level API closely follows the C API of the
|
||||
|
||||
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
|
||||
|
@ -22,16 +22,13 @@ Quick start
|
|||
Java. The disadvantage is that you will have a hard time changing
|
||||
your code when you later switch to a different Java USB library. And as a
|
||||
pure Java developer you may dislike the API because it is too low-level (For
|
||||
example most methods return error codes instead of throwing exceptions).
|
||||
example most methods return error codes instead of throwing exceptions).
|
||||
|
||||
The high-level API simply implements the
|
||||
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
|
||||
specification is pretty old and may lack support for some newer USB
|
||||
techniques provided by the low-level API.
|
||||
|
||||
|
||||
|
||||
easier to use for Java developers. The disadvantage is that the javax-usb
|
||||
specification is very old (maybe even abandoned) and may lack support for
|
||||
some newer USB techniques provided by the low-level API.
|
||||
|
|
|
@ -14,34 +14,34 @@
|
|||
through the <a href="usb4java-javax/">usb4java-javax extension</a>.
|
||||
</p>
|
||||
<p>
|
||||
Supported platforms are <strong>Linux</strong> (x86 32/64 bit, ARM 32 bit),
|
||||
<strong>OS X</strong> (x86 32/64 bit) and
|
||||
Supported platforms are <strong>Linux</strong> (x86 32/64 bit, ARM 32/64 bit),
|
||||
<strong>OS X</strong> (x86 64 bit) and
|
||||
<strong>Windows</strong> (x86 32/64 bit). But other platforms may work
|
||||
as well (as long as they have at least Java 6 and are supported by
|
||||
as well (as long as they have at least Java 6 and are supported by
|
||||
libusb) by compiling the JNI library manually.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
|
||||
<section name="Download">
|
||||
<ul class="download">
|
||||
<li>
|
||||
Main library:<br />
|
||||
<strong><a href="${artifactBaseUrl}.tar.bz2">${project.artifactId}-${project.version}.tar.bz2</a></strong><br />
|
||||
<strong><a href="${artifactBaseUrl}.tar.xz">${project.artifactId}-${project.version}.tar.xz</a></strong><br />
|
||||
<strong><a href="${artifactBaseUrl}.zip">${project.artifactId}-${project.version}.zip</a></strong><br />
|
||||
</li>
|
||||
<li>
|
||||
javax-usb extension:<br />
|
||||
<strong><a href="${javaxArtifactBaseUrl}.tar.bz2">${project.artifactId}-javax-${usb4javaJavaxVersion}.tar.bz2</a></strong><br />
|
||||
<strong><a href="${javaxArtifactBaseUrl}.tar.xz">${project.artifactId}-javax-${usb4javaJavaxVersion}.tar.xz</a></strong><br />
|
||||
<strong><a href="${javaxArtifactBaseUrl}.zip">${project.artifactId}-javax-${usb4javaJavaxVersion}.zip</a></strong><br />
|
||||
</li>
|
||||
<li><a href="${repoBaseUrl}/">Older versions and snapshots</a></li>
|
||||
<li>
|
||||
Source code repository:
|
||||
<a href="http://github.com/usb4java/">GitHub</a>
|
||||
<a href="http://github.com/usb4java/">GitHub</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
When you are using Maven then you can add the necessary dependencies
|
||||
When you are using Maven then you can add the necessary dependencies
|
||||
like this:
|
||||
</p>
|
||||
<div class="source"><pre><-- For using just usb4java without javax-usb -->
|
||||
|
@ -62,13 +62,13 @@
|
|||
</dependency>
|
||||
</dependencies></pre></div>
|
||||
</section>
|
||||
|
||||
|
||||
<section name="License">
|
||||
<p>
|
||||
Copyright (C) 2011 Klaus Reimer, k@ailis.de<br />
|
||||
Copyright (C) 2011 Klaus Reimer, k@ailis.de<br />
|
||||
Copyright (C) 2013 Luca Longinotti, l@longi.li
|
||||
</p>
|
||||
|
||||
|
||||
<p>
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
|
@ -91,30 +91,30 @@
|
|||
THE SOFTWARE.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
|
||||
<section name="Getting started">
|
||||
<p>
|
||||
Read the <a href="quickstart/index.html">quick start guide</a> and the
|
||||
Read the <a href="quickstart/index.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/">low-level (libusb) examples</a>
|
||||
and
|
||||
and
|
||||
<a href="https://github.com/usb4java/usb4java-javax-examples/">high-level (javax-usb) examples</a>
|
||||
available.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
|
||||
<section name="Support">
|
||||
<p>
|
||||
For questions and discussions please use the
|
||||
<a href="mailto:usb4java@googlegroups.com">usb4java mailing list</a>
|
||||
For questions and discussions please use the
|
||||
<a href="mailto:usb4java@googlegroups.com">usb4java mailing list</a>
|
||||
(<a href="http://groups.google.com/group/usb4java">Google group</a>).
|
||||
You can subscribe to it via email by sending a mail to
|
||||
You can subscribe to it via email by sending a mail to
|
||||
<a href="mailto:usb4java+subscribe@googlegroups.com">usb4java+subscribe@googlegroups.com</a>.
|
||||
</p>
|
||||
<p>
|
||||
<p>
|
||||
If you have found a bug in the software or this
|
||||
web site (even if it's just a typo) then please create
|
||||
an <a href="${project.issueManagement.url}">issue on GitHub</a>.
|
||||
an <a href="${project.issueManagement.url}">issue on GitHub</a>.
|
||||
</p>
|
||||
</section>
|
||||
</body>
|
||||
|
|
Loading…
Reference in New Issue