Driver Usage Guide

Required Maven Dependencies

Add the following dependency to your pom.xml:

<dependency>
    <groupId>de.uniluebeck.itm</groupId>
    <artifactId>wsn-device-drivers-factories</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

As optional dependency you can add the itmutils:

<dependency>
    <groupId>de.uniluebeck.itm.itmutils</groupId>
    <artifactId>itmutils</artifactId>
    <version>0.4-SNAPSHOT</version>
</dependency>

These are needed when using the following classes:

• ForwardingScheduledExecutorService

Device Initialization

ScheduledExecutorService executor = Executors.newScheduledThreadPool(3);
DeviceFactory factory = new DeviceFactoryImpl();
Device device = factory.create(executor, DeviceType.ISENSE);

At first we need a ScheduledExecutorService with a minimum thread size of 3. Then we can initialize the DeviceFactory and create a iSense Device. All available DeviceTypes are:

• ISENSE
• ISENSE39
• ISENSE48
• TELOSB
• PACEMATE
• MOCK

Using an existing ExecutorService

When you want to use an already existing ExecutorService you can use the ForwardingScheduledExecutorService as follows:

// Replace this ExecutorService with your existing one
ExecutorService executorService = Executors.newCachedThreadPool();

ScheduledExecutorService scheduleService = Executors.newScheduledThreadPool(1);
ScheduledExecutorService executor = new ForwardingScheduledExecutorService(scheduleService, executorService);

The ForwardingScheduledExecutorService will forward all scheduled task to the given ExecutorService.

Connecting to the Device

device.connect("/dev/ttyUSB0");

Note: connect can throw an IOException when a problem occurred during the connecting process.

Disconnect from the Device

device.close();

This will close the connection to the device. Note that the ScheduledExecutorService is not shut down when the close method is called. This has to be done manually.

Async Operation Execution

All operations executed on the Device are asynchronous. For this purpose you need a OperationCallback. This callback is notified, when the operation finished, an exception occurred or a progress change happend. A simple callback implementation can look like this:

OperationCallback<Void> callback = new OperationCallback<Void>() {
    @Override
    public void onProgressChange(float fraction) {
        System.out.println("Progress: " + (fraction * 100));
    }

    @Override
    public void onSuccess(Void result) {
        System.out.println("Operation done!");
    }

    @Override
    public void onFailure(Throwable throwable) {
        System.err.println("Operation failed with Exception: " + throwable, throwable);
    }

    @Override
    public void onExecute() {
        System.out.println("Starting operation...");
    }

    @Override
    public void onCancel() {
        System.out.println("Operation was canceled!");
    }
};

The generic type defines the return type of the operation. In this case the operation returns Void.

The asynchronously execution of operations allows to execute multiple operations at once without to worry about threading and concurrency. This is all done by this framework. To prevent an infinite execution of an operation all operations have a timeout which can be given in milliseconds. When an operation reaches the timeout limit a TimeoutException is thrown which is returned by calling the onFailure method of the callback.

Following operations are available:

• getChipType(long timeout, OperationCallback<ChipType> callback)
• `program(byte[] image, long timeout, AsyncCallback callback)``
• eraseFlash(long timeout, OperationCallback<Void> callback)
• writeFlash(int address, byte[] data, int length, long timeout, OperationCallback<Void> callback)
• readFlash(int address, int length, long timeout, OperationCallback<byte[]> callback)
• readMac(long timeout, OperationCallback<MacAddress> callback)
• writeMac(MacAddress macAddress, long timeout, OperationCallback<Void> callback)
• reset(long timeout, OperationCallback<Void> callback)
• send(byte[] message, long timeout, OperationCallback<Void> callback)

An example how to use there methods is described below:

Programming the Device

byte[] image = ... // Your image as byte array
device.program(image, 600000, callback);

Async Operation Execution Control

All defined operations return an OperationFuture. This can be used for controlling the async execution. Following functionality is available:

Cancel the Operation

OperationFuture future = device.getChipTypeOperation(30000, callback);
future.cancel();

When the operation was canceled successfully the onCancel method of the callback is called.

Synchron Operation Execution

You can wait for the operation to finished in an synchronous way:

OperationFuture future = device.getChipTypeOperation(30000, callback);
ChipType chipType = future.get(); // Wait for the operation to finish

Communicate with the Device Program

For the communication with the device program you can use the InputStream and OutputStream. These can be get be the getInputStream and getOutputStream methods. They can be used in a concurrent way. The device handles all concurrency issues.

Note: These methods are also available in the Connection interface, but these should never be used by the application developer. They are only intended for the internal usage in the device.