DS1620 based USB Digital Thermometer
source: http://csx.jp/~fex/usbio/dk8-en.html

USB-IO driver class library

I wrote a small Java class library to use Morphy USB-IO devices. It is still under development, but it currently runs fine under some limited purposes.

 

Why I did it?

... because I write everything in Java these days. Recently, I'm so Java-biased, so I can't stand the fact I must free (or delete) allocalted objects (memory blocks) manually.

I had no choice than using Java to control Morphy USBIO.

Overview of the Class Library

Here is an overview of the class library, explained by an example.

An LED Flusher

This is an example to flush an LED connected to USBIO. The LED must be wired to bit 0 of Port #1. Refer to the following schematics.

The controlling program is as follows.

import xyzzy.hardware.UsbIo;

class Led
{
    public static void main ( String[] argv )
    {
	try {
	    final UsbIo.Device usbio = UsbIo.getDevice();
	    try {
		int bits = 0xFF;

		for ( int count = 25; count > 0; --count ) {
		    bits ^= 0x01;
		    usbio.invoke( UsbIo.WRITE1, bits );
		    Thread.sleep( 200 );
		}

	    } finally {

		usbio.invoke( UsbIo.WRITE1, 0xFF );
		usbio.close();
	    }

	} catch ( Throwable e ) {
	    /* Show any Error/Exception.  */
	    e.printStackTrace();
	}
    }
}

Let me explain what the parts of the program are doing.

Primary USBIO controlling class

The class xyzzy.hardware.UsbIo, imported at the top of the program, is the primary class in the USBIO class library. This class and its subclass UsbIo.Device cooperatively cover major rolls to control USBIO devices.

Obtaining a USBIO device object

The program first obtains an object representing a USBIO device. The USBIO device object is an instance of the class UsbIo.Device. (In fact, it is an instance of a non-public subclass of the UsbIo.Device class.) In this example, a static method UsbIo.getDevice() is called to obtain a USBIO device object.

UsbIo.getDevice() returns a null if there is no USBIO device attached. (A practical program should check for the case, although the above example doesn't.) Conversely, it chooses one USBIO device arbitrarily, if there are two or more USBIO devices are attached. The application program has no controll over which device is chosen. If your program is intended to handle two or more USBIO devices in its own way, you should use another method UsbIo.allDevices(), which returns an Enumeration of USBIO device objects.

Invokation of a command

Use UsbIo.Device.invoke(int cmd, int arg) method to send a command to a USBIO to control the I/O ports on the USBIO. cmd is the command code to be sent to the USBIO, and arg is the parameter to the command. In this example, the method is used to send WRITE PORT #1 commands several times, altering the output port wired to an LED to flush it.

Termination of the use of USBIO device objects

When application finishes the use of a USBIO device object, it must call UsbIo.Device.close() method to release assocaited internal resources. This release operation will never issued automatically, so if you program failed to call close, and the garbage collector reclaimed the object, the resource leaks. (I know this specification is a headache of programmers, but this is the Java way.) In the above example, a try-finally construct is used to ensure the call to the close method. Since many methods in USBIO class library throw several unchecked exceptions, use of try-finally construct is almost mondatory.

How to get and install the class library

Downloading

You can download the class library from Downloading page on this site. Also, you might find many other sites/pages if you searched the Internet, since redistribution is allowed. You can try it if you meet any trouble downloading from here.

NOTE: When this page was unreachable for a month, I received an email saying "I tried many Internet search engines to find a mirror download site, but I got none." It's my pleasure to know there is an active user, but I meant it as a joke. I guess nobody want to mirror such a tiny program unasked. I apology for confusing you.

Both binary and source forms of distribution is available here. Binary distribution is further divided into a platform independent class file archive (jar file) and optional platform-dependent native code libraries.

(Currently, there are no Java API to access USB functionality directly, so use of native code is mandatory.)

Installing binary distribution

Different combinations of OS and Java Environment different binary distribution files. List of supported platforms and their required files are shown on the following table. To run on other platforms, you should get source distribution and recompiling (after some modification if needed.)

OS	CPU	JavaVM	Required files
Windows	Any	Microsoft VM	usbio.jar
Windows	x86	Sun Microsystems' JDK Sun Microsystems' JRE other compatible VM	usbio.jar usbio.dll
FreeBSD	x86	FreeBSD ported JDK FreeBSD ported JRE	usbio.jar libusbio.so

In any case, the preferred installation is that prepare for a dedicated directory (on any location) and put all files in it. To start an application that uses USBIO class library, you should cd to the directory and issue the following command. (The following samples assume you are starting an application Led in usbapps.jar.)

Windows + Microsoft VM

jview /cp:p usbio.jar;usbapps.jar Led

Windows + Sun Microsystems' JDK/JRE (ver. 1.1.x)

jre -cp usbio.jar;usbapps.jar Led

Windows + Sun Microsystems' JDK/JRE (Java 2)

java -cp usbio.jar;usbapps.jar Led

FreeBSD + ported JDK/JRE (ver. 1.1.x)

jre -cp usbio.jar:usbapps.jar Led

Note that, on FreeBSD (and on other modern posix-compatible operating systems), you should set LD_LIBRARY_PATH environment variable so that it includes a ., allowing the dynamic linker to find the libusbio.so.

Compiling the source distribution

Source files are distributed as a .zip file that is compatible with jar. You should use jar or any compatible tools to extract sources from it, so that you can compile them.

The Makefile included in the source distribution assumes use of Cygwin tools on Windows. It uses jikes when compile Java source files. Most of the Java compiler should do the job, so you can use your favorit compiler, if you don't like jikes. Native code related parts, however, require special considerations as explained below.

• On Microsoft JVM, native code (Windows API calls) will be invoked through J/Direct, so the Makefile assumes use of jvc to compile Java sources. (jvc is originally a command line compiler included in Microsoft J++, but is distributed for free of charge as a part of Microsoft SDK for Java.) No ohter compiler will generate J/Direct compatible .class files, so you should use jvc, here.

• For Sun Microsystems' JVM, JNI is used to invoke native code library. In the case of Windows, the native code library is compiled with the gcc come with Cygwin, with options set for Mingw development. The source shold be compiled with any other Windows compilers, such as Visual C++.

• For FreeBSD, the C compiler (gcc) come with the os is used to compile the native code library.