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

Improve documentation

This commit is contained in:
Klaus Reimer 2018-10-21 12:22:03 +02:00
parent 5249c172f9
commit df699d2612
5 changed files with 104 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
src/site/apt/configuration.apt.vm
View File

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

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

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

69
src/site/apt/nativelibs.apt.vm
View File

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

23
src/site/apt/quickstart/index.apt
View File

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

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

@ -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>&lt;-- For using just usb4java without javax-usb --&gt;
@ -62,13 +62,13 @@
&lt;/dependency&gt;
&lt;/dependencies&gt;</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>