From df699d2612c0215a764f07bedc62372794b450a2 Mon Sep 17 00:00:00 2001 From: Klaus Reimer Date: Sun, 21 Oct 2018 12:22:03 +0200 Subject: [PATCH] Improve documentation --- src/site/apt/configuration.apt.vm | 25 +++++++---- src/site/apt/faq.apt.vm | 39 +++++++++-------- src/site/apt/nativelibs.apt.vm | 69 +++++++++++++++++-------------- src/site/apt/quickstart/index.apt | 23 +++++------ src/site/xdoc/index.xml.vm | 40 +++++++++--------- 5 files changed, 104 insertions(+), 92 deletions(-) diff --git a/src/site/apt/configuration.apt.vm b/src/site/apt/configuration.apt.vm index ea46ed9..7d6ef54 100644 --- a/src/site/apt/configuration.apt.vm +++ b/src/site/apt/configuration.apt.vm @@ -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 file which must be located in the root of your classpath: - + +----+ javax.usb.services = org.usb4java.javax.Services -+----+ ++----+ can be configured by adding more properties to this file as described in the following sections. - + * Communication timeout The default USB communication timeout of 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(); +----+ - \ No newline at end of file + + +* 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. diff --git a/src/site/apt/faq.apt.vm b/src/site/apt/faq.apt.vm index 581bfff..5bd958e 100644 --- a/src/site/apt/faq.apt.vm +++ b/src/site/apt/faq.apt.vm @@ -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 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 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 and . - + To activate this new configuration you may need to re-attach the USB device or run the command <<>>. * 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! - \ No newline at end of file + 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! diff --git a/src/site/apt/nativelibs.apt.vm b/src/site/apt/nativelibs.apt.vm index d8399b3..862aa7c 100644 --- a/src/site/apt/nativelibs.apt.vm +++ b/src/site/apt/nativelibs.apt.vm @@ -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 or environment variables like or . - + 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 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= +----+ @@ -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 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 . The file name depends on your operating system. Make sure you rename it to (Or whatever file extension - your platform uses) and copy this file into the directory + your platform uses) and copy this file into the directory in your classpath where is the name of your operating system and 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 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}}. - \ No newline at end of file diff --git a/src/site/apt/quickstart/index.apt b/src/site/apt/quickstart/index.apt index f6a36cc..302293a 100644 --- a/src/site/apt/quickstart/index.apt +++ b/src/site/apt/quickstart/index.apt @@ -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. - - - \ No newline at end of file + 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. diff --git a/src/site/xdoc/index.xml.vm b/src/site/xdoc/index.xml.vm index 090da5c..d266755 100644 --- a/src/site/xdoc/index.xml.vm +++ b/src/site/xdoc/index.xml.vm @@ -14,34 +14,34 @@ through the usb4java-javax extension.

- Supported platforms are Linux (x86 32/64 bit, ARM 32 bit), - OS X (x86 32/64 bit) and + Supported platforms are Linux (x86 32/64 bit, ARM 32/64 bit), + OS X (x86 64 bit) and Windows (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.

- +

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

<-- For using just usb4java without javax-usb -->
@@ -62,13 +62,13 @@
   </dependency>
 </dependencies>
- +

- Copyright (C) 2011 Klaus Reimer, k@ailis.de
+ Copyright (C) 2011 Klaus Reimer, k@ailis.de
Copyright (C) 2013 Luca Longinotti, l@longi.li

- +

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.

- +

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

- +

- For questions and discussions please use the - usb4java mailing list + For questions and discussions please use the + usb4java mailing list (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 usb4java+subscribe@googlegroups.com.

-

+

If you have found a bug in the software or this web site (even if it's just a typo) then please create - an issue on GitHub. + an issue on GitHub.