diff --git a/pom.xml b/pom.xml index cf2326b..2d44820 100644 --- a/pom.xml +++ b/pom.xml @@ -60,10 +60,11 @@ UTF-8 - http://nexus.ailis.de/content/groups/public/de/ailis/${project.artifactId}/${project.artifactId} - + http://nexus.ailis.de/content/groups/public/org/usb4java + ${repoBaseUrl}/${project.version}/${project.artifactId}-${project.version} 1.2.0-SNAPSHOT + 1.2.0-SNAPSHOT @@ -191,6 +192,33 @@ + + + maven-assembly-plugin + 2.2.2 + + false + + src/main/assembly/tarball.xml + src/main/assembly/zip.xml + + + + 420 + 493 + 493 + + + + + package-assembly + package + + attached + + + + diff --git a/src/main/assembly/AUTHORS.txt b/src/main/assembly/AUTHORS.txt new file mode 100644 index 0000000..6cbe9c1 --- /dev/null +++ b/src/main/assembly/AUTHORS.txt @@ -0,0 +1,6 @@ +Developers +---------- + +Klaus Reimer +Luca Longinotti + diff --git a/src/main/assembly/README.txt b/src/main/assembly/README.txt new file mode 100644 index 0000000..62f3f9b --- /dev/null +++ b/src/main/assembly/README.txt @@ -0,0 +1,16 @@ +${project.artifactId} ${project.version} +${project.url} +Copyright 2014 usb4java Team +See LICENSE.md for licensing information. +------------------------------------------------------------------------------ + +The lib directory contains the following JAR files: + +usb4java-*.jar (The main usb4java library) +libusb4java-*.jar (The native libraries for the various platforms) +commons-lang3-*.jar (Apache Commons Lang library needed by usb4java) + +If you don't want usb4java to extract the native libraries into a temporary +directoy on each program start then you might want to distribute them in +extracted form with your application. Just make sure your classpath points +to the directory where you extracted the JARs. diff --git a/src/main/assembly/tarball.xml b/src/main/assembly/tarball.xml new file mode 100644 index 0000000..a37a02d --- /dev/null +++ b/src/main/assembly/tarball.xml @@ -0,0 +1,38 @@ + + + tarball + + tar.bz2 + + + + + / + + LICENSE.md + + 0644 + unix + + + src/main/assembly + / + + README.txt + AUTHORS.txt + + 0644 + unix + true + + + + + lib + false + runtime + + + diff --git a/src/main/assembly/zip.xml b/src/main/assembly/zip.xml new file mode 100644 index 0000000..7d043c1 --- /dev/null +++ b/src/main/assembly/zip.xml @@ -0,0 +1,38 @@ + + + zip + + zip + + + + + / + + LICENSE.md + + 0644 + dos + + + src/main/assembly + / + + README.txt + AUTHORS.txt + + 0644 + dos + true + + + + + lib + false + runtime + + + diff --git a/src/site/apt/configuration.apt.vm b/src/site/apt/configuration.apt.vm index fb6cca3..7e2e317 100644 --- a/src/site/apt/configuration.apt.vm +++ b/src/site/apt/configuration.apt.vm @@ -4,20 +4,24 @@ Configuration + The configuration options explained here are only valid for the javax-usb + extension of usb4java. If you access your USB devices with the native + libusb API then no configuration is needed. + + +* Selecting usb4java as javax-usb implementation + To tell the USB Host Manager of to use the implementation you have to put the following property into the file which must be located in the root of your classpath: +----+ -javax.usb.services = de.ailis.usb4java.Services +javax.usb.services = org.usb4java.javax.Services +----+ can be configured by adding more properties to this file as - described in the following sections. All these properties only affect - the high-level API of . The low-level API just wraps - the native library so no configuration is available (or needed) for - it. + described in the following sections. * Communication timeout @@ -27,7 +31,7 @@ javax.usb.services = de.ailis.usb4java.Services file: +----+ -de.ailis.usb4java.timeout = 250 +org.usb4java.javax.timeout = 250 +----+ @@ -37,7 +41,7 @@ de.ailis.usb4java.timeout = 250 change this to 1000 milliseconds for example add this to the properties file: +----+ -de.ailis.usb4java.scanInterval = 1000 +org.usb4java.javax.scanInterval = 1000 +----+ When you set this interval to 0 then only scans once during @@ -46,6 +50,6 @@ de.ailis.usb4java.scanInterval = 1000 to the implementation, because this is not a javax.usb feature: +----+ -((de.ailis.usb4java.Services) UsbHostManager.getUsbServices()).scan(); +((org.usb4java.javax.Services) UsbHostManager.getUsbServices()).scan(); +----+ \ No newline at end of file diff --git a/src/site/apt/faq.apt.vm b/src/site/apt/faq.apt.vm index 5ac6115..68a6c6f 100644 --- a/src/site/apt/faq.apt.vm +++ b/src/site/apt/faq.apt.vm @@ -4,8 +4,11 @@ Frequently asked questions - If you have a question which is not answered here please create an - {{{${project.issueManagement.url}}issue on GitHub}}. + 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 + {{{mailto:usb4java+subscribe@googlegroups.com}usb4java+subscribe@googlegroups.com}}. * I can't open my USB device on Linux. Why? @@ -14,28 +17,25 @@ Frequently asked questions running your program as root. If this works then it is recommended to configure to give your user write permissions when the device is attached. You can do this by creating a file like - with content like this: + with content like this: ---- - SUBSYSTEM=="usb",ATTR{idVendor}=="89ab",ATTR{idProduct}=="4567",MODE="0660",GROUP="plugdev" + SUBSYSTEM=="usb",ATTR{idVendor}=="89ab",ATTR{idProduct}=="4567",MODE="0660",GROUP="wheel" ---- This means that whenever a USB device with vendor id <0x89ab> and product id - <0x4567> is attached then the group is permitted to + <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 <{idProduct}>. + the ATTR properties and . - To activate this new configuration you may have to restart your udev daemon - (<<>>) and then re-attach the USB device. + To activate this new configuration you may need to re-attach the USB device. * I can't open my USB device on Windows. Why? - On Windows you need to create a driver for your USB device. - Don't worry, this isn't that complicated but still too complicated to - explain here. The - {{{https://github.com/libusbx/libusbx/wiki/Windows-Backend#wiki-How_to_use_libusbx_on_Windows}libusbx project}} - explains how to do it. + 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. diff --git a/src/site/apt/nativelibs.apt.vm b/src/site/apt/nativelibs.apt.vm index ed7280a..d8399b3 100644 --- a/src/site/apt/nativelibs.apt.vm +++ b/src/site/apt/nativelibs.apt.vm @@ -4,38 +4,37 @@ Library loading - The native libraries for all supported platforms are included in the - standard usb4java JAR file (But there is also one without the native - libs if you want to package them in your own way). usb4java 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 JAR in your classpath. No need to - fiddle around with or environment variables like - or . + 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 + 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 use the - file instead and ship the native libraries with - your application in extracted form. Here is an example application layout: + 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/ - de/ailis/usb4java/libusb/ + org/usb4java/ linux-x86/libusb4java.so windows-x86/libusb4java.dll osx-x86/libusb4java.dylib lib/ - usb4java-no-natives.jar + usb4java.jar commons-lang3.jar - usb.jar + myapp.jar myapp.sh +-----------------------------------------------------------------------------+ To make this work just make sure to put the folder into your - classpath. The native libraries itself can be found in the - or the file. - + classpath. + Unsupported platforms @@ -43,7 +42,7 @@ Unsupported platforms usb4java then you might get one of the following two exceptions: +----+ -Native library not found in classpath: /de/ailis/usb4java/libusb/freebsd-x86/libusb4java.so +Native library not found in classpath: /org/usb4java/freebsd-x86/libusb4java.so +----+ +----+ @@ -52,7 +51,7 @@ Unable to determine the shared library file extension for operating system +----+ If you get the second one then this simply means that your operating system - is completely unknown to the usb4java author and usb4java does not know the + 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): @@ -70,23 +69,23 @@ Unable to determine the shared library file extension for operating system Make sure the environment variable is pointing to the directory where you have installed the JDK. - 2. Install the {{{http://www.libusb.org/}libusb}} development files. + 2. Install the {{{http://libusb.info/}libusb}} development files. 3. Install {{{http://git-scm.com/}Git}}. - 4. Clone the {{{https://github.com/kayahr/usb4java/}usb4java source code repository}} with Git: + 4. Clone the {{{https://github.com/usb4java/libusb4java/}libusb4java source code repository}} with Git: +---- -$ git clone git://github.com/kayahr/usb4java.git +$ git clone git://github.com/usb4java/libusb4java.git +---- - 5. Go to the directory containing the C sources of the JNI wrapper: + 5. Enter the cloned libusb4java directory: +---- -$ cd usb4java/src/main/c +$ cd libusb4java +---- - 6. Compile the wrapper: + 6. Compile the native library: +---- $ ./autogen.sh @@ -98,7 +97,7 @@ $ make install-strip DESTDIR=/tmp 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 - in your classpath where is the name + 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.) @@ -109,6 +108,8 @@ $ make install-strip DESTDIR=/tmp your platform. If you have problems then please consult the - {{{http://groups.google.com/group/usb4java}usb4java Google Group}}. - Someone may be able to help. + {{{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.apt.vm b/src/site/apt/quickstart.apt.vm index 5e2cac0..df136b4 100644 --- a/src/site/apt/quickstart.apt.vm +++ b/src/site/apt/quickstart.apt.vm @@ -1,152 +1,22 @@ ----------------------------------------------------------------------------- Quick start ----------------------------------------------------------------------------- - -Installation - Download the latest and put it into your class path. Since - version 0.5.0 you no longer need to care about the native libraries. They - are included in the JAR file and will be used from there. - - If you are using the high-level API then you also need the - which can be downloaded from the - {{{http://javax-usb.sourceforge.net/}javax.usb project site}}. - This JAR (Which is also included in the usb4java distribution tarball/zip - as ) must also be copied into your class path. - - Another dependency needed since version 1.0.0 is - {{{http://commons.apache.org/proper/commons-lang/}commons-lang v3}}. +API design - -The high-level API - - The high-level API implements the - {{{http://javax-usb.sourceforge.net/}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 implementation later without changing your code. - For example instead of using you may try out the reference - implementation for Linux and Windows. - - -* Configuration - - To use the implementation you have to create a file named - <{{{./configuration.html}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) hub.getAttachedUsbDevices()) - { - dump(child); - } - } - } - - public static void main(String[] args) throws UsbException - { - UsbServices services = UsbHostManager.getUsbServices(); - UsbHub rootHub = services.getRootUsbHub(); - dump(rootHub); - } -} -+-----------------------------------------------------------------------------+ - - Often you need to search for a specific device before working with it. Here - is an example how to scan the device tree for the first device with a - specific vendor and product id. It can be easily expanded to check for - specific device classes or whatever: - -+-----------------------------------------------------------------------------+ -public UsbDevice findDevice(UsbHub hub, short vendorId, short productId) -{ - for (UsbDevice device : (List) hub.getAttachedUsbDevices()) - { - UsbDeviceDescriptor desc = device.getUsbDeviceDescriptor(); - if (desc.idVendor() == vendorId && desc.idProduct() == productId) return device; - if (device.isUsbHub()) - { - device = findDevice((UsbHub) device, vendorId, productId); - if (device != null) return device; - } - } - return null; -} -+-----------------------------------------------------------------------------+ - - -* Communicate via the Default Control Pipe - - This example reads the current configuration number from a device: - -+-----------------------------------------------------------------------------+ -UsbControlIrp irp = device.createUsbControlIrp( - (byte) (UsbConst.REQUESTTYPE_DIRECTION_IN - | UsbConst.REQUESTTYPE_TYPE_STANDARD - | UsbConst.REQUESTTYPE_RECIPIENT_DEVICE), - UsbConst.REQUEST_GET_CONFIGURATION, - (short) 0, - (short) 0 - ); -irp.setData(new byte[1]); -device.syncSubmit(irp); -System.out.println(irp.getData()[0]); -+-----------------------------------------------------------------------------+ - - -* More information about the high-level API - - * {{{./apidocs/index.html}API documentation of usb4java}} - - * {{{http://javax-usb.sourceforge.net/}javax-usb website}} - - [] - - -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 1.0. - - All global functions and constants of libusb are defined as static - members of the class - {{{./apidocs/de/ailis/usb4java/libusb/LibUsb.html}de.ailis.usb4java.libusb.LibUsb}}. - All structures of libusb are defined in separate classes which are named + The API of usb4java closely follows the C API of the + {{{http://libusb.info/}libusb}} project. All global functions and + constants of are defined as static members of the class + {{{./apidocs/org/usb4java/LibUsb.html}org.usb4java.LibUsb}}. + All structures of 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 + case names and with the prefix removed. For example the struct is defined in the class - {{{./apidocs/de/ailis/usb4java/libusb/DeviceHandle.html}DeviceHandle}}. Struct + {{{./apidocs/org/usb4java/DeviceHandle.html}DeviceHandle}}. Struct members are represented by static methods in the corresponding class. The following notable differences exists between the and - the low-level API of : + the API: * in the configuration descriptor is named because is a reserved word in Java. @@ -162,18 +32,33 @@ The low-level API passed as argument have additional simplified overloaded method equivalents which are returning a Java String directly. - * Currently the asynchronous functions of libusb are not wrapped by usb4java. - This may change in the future (Some help here is highly appreciated). So - currently asynchronous communication is only possible with the high-level - API which uses the synchronous libusb functions in Java threads. - [] - -* More information about the low-level API - * {{{./apidocs/de/ailis/usb4java/libusb/package-summary.html}Low-level API documentation of usb4java}} +* Initialization/deinitialization + + Before using any usb4java functionality you must initialize libusb: - * {{{http://libusb.sourceforge.net/api-1.0/}API documentatiaon of 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 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}} [] \ No newline at end of file diff --git a/src/site/site.xml b/src/site/site.xml index 3bfaaa2..a735e46 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -6,7 +6,7 @@ usb4java images/logo.png - http://kayahr.github.com/${project.artifactId}/ + http://usb4java.org/ @@ -22,9 +22,13 @@ - + + + + + @@ -40,7 +44,7 @@ - usb4java/usb4java + usb4java right red diff --git a/src/site/xdoc/index.xml.vm b/src/site/xdoc/index.xml.vm index 06471ca..a8a935d 100644 --- a/src/site/xdoc/index.xml.vm +++ b/src/site/xdoc/index.xml.vm @@ -1,17 +1,17 @@ - usb4java + About

- usb4java is a Java library to access USB devices. The low-level - part is based on the native - libusb 1.0 library. Java NIO - buffers are used for data exchange between libusb and Java. The - high-level part implements the - javax.usb standard (JSR-80). + usb4java is a Java library to access USB devices. It is based on + the native libusb 1.0 library + and uses Java NIO buffers for data exchange between libusb and Java. + usb4java also supports the + javax.usb standard (JSR-80) + through the usb4java-javax extension.

Supported platforms are Linux (x86 32/64 bit, ARM 32 bit), @@ -25,14 +25,19 @@

@@ -47,12 +52,22 @@ </repository> </repositories> +<-- For using just usb4java without javax-usb --> <dependencies> <dependency> <groupId>${project.groupId}</groupId> <artifactId>${project.artifactId}</artifactId> <version>${project.version}</version> </dependency> +</dependencies> + +<-- For using usb4java with javax-usb --> +<dependencies> + <dependency> + <groupId>${project.groupId}</groupId> + <artifactId>${project.artifactId}-javax</artifactId> + <version>${usb4javaJavaxVersion}</version> + </dependency> </dependencies>

@@ -74,38 +89,18 @@

- Download - the latest usb4java and then read the - quick start guide and the + Read the quick start guide and the FAQ. There are also some examples available.

- -

For questions and discussions please use the - usb4java Google Group. + usb4java mailing list + (Google group). You can subscribe to it via email by sending a mail to usb4java+subscribe@googlegroups.com.