Jul

Firmata : OSGi example

Introduction

Ubiquisense comes with Serial communication features which allows to easily connect to Arduino boards over USB.

The communication IO take the form of an Rx/Tx queues full duplex communication. All aspect of the communication gets blended behind a basic Java API in an OSGi/Plugin SDK.

On the other side, Arduino boards are shipped with a software called Firmata which intends to handle analog/digital pins IOs over USB. Firmata protocol is Midi based and so, comes with a very low footprint and minimum bandwidth consumption.

Communication between an Arduino board and an host PC is now made so easy. As easy as developing few lines of an Eclipse RCP plugin. A single class in your plugin and you just get access to an Arduino software instance continuously updated from Firmata midi messages.

Obviously, the OSGi nature of the framework could be of some detestation for few people. Anyway OSGi/Equinox brings so much modularity and flexibility to it !

Let's explore this interesting programming model, leveraging a lot of model driven development inside and getting usable with a simple Java API.

How does it works ?

Below is the minimum amount of code necessary to get a communication and syncronization with an Arduino :


package com.ubiquisense.firmatata.core;

import net.sf.smbt.firmata.handlers.FirmataQxEventHandler;
import net.sf.smbt.firmata.ubiquino.Ubiquino;
import net.sf.smbt.firmata.ubiquino.core.UbiquinoUtils;
import net.sf.smbt.firmata.utils.FirmataCmdUtils;
import net.sf.smbt.mdl.arduino.ARDUINO_BOARD_UID;
import net.sf.smbt.mdl.arduino.ARDUINO_FIRMWARE_MODE;
import net.sf.smbt.mdl.arduino.AnalogPort;
import net.sf.smbt.protocol.ezfirmata.FirmataProtocolVersionCmd;
import net.sf.smbt.quantic.warp.QuanticMojo;
import net.sf.xqz.engine.utils.ITTLJob;
import net.sf.xqz.engine.utils.TTL;
import net.sf.xqz.model.engine.CmdPipe;
import net.sf.xqz.model.engine.EVENT_KIND;

import org.eclipse.equinox.app.IApplication;
import org.eclipse.equinox.app.IApplicationContext;

public class FirmataApplication implements IApplication {
    private Ubiquino ubiquino;
    private CmdPipe arduinoPipe;
    
    @Override
    public Object start(IApplicationContext context) throws Exception {
        String addr = "/dev/tty.usbserial-A7006022";
        arduinoPipe = QuanticMojo.INSTANCE.openUsbPipe("firmata", addr, 57600);
        
        ubiquino = UbiquinoUtils.INSTANCE.createArduinoBoard(
                ARDUINO_BOARD_UID.DIECMILA_ATMEGA_168,
                ARDUINO_FIRMWARE_MODE.ARDUINO_FIRMATA_V23
        );
        if (arduinoPipe == null) {
            System.err.println("Arduino not connected on address " + addr + " !!!");
            return -1;
        }
        arduinoPipe.addQxEventHandler(
            new FirmataQxEventHandler() {
                public void handleQxEvent(net.sf.xqz.model.engine.Event event) {
                    if (event.getKind().equals(EVENT_KIND.RX_DONE)) {
                        if (event.getCmd() instanceof FirmataProtocolVersionCmd) { // version : end of initialization
                            FirmataProtocolVersionCmd verCmd = (FirmataProtocolVersionCmd) event.getCmd();
                            System.out.println("v"+verCmd.getByte1()+"."+verCmd.getByte2());
                            for (AnalogPort analogPort : ubiquino.getBoard().getAnalogPorts()) {
                                arduinoPipe.send(
                                    FirmataCmdUtils.INSTANCE.createReportAnalogPin(
                                        analogPort.getMap().getValue(), // the true pin number on the board
                                        1 // report set to ON
                                    )
                                );        
                            }

                        } 
                        UbiquinoUtils.INSTANCE.handleUbiquinoSysexCmdEvent(ubiquino.getBoard(), event.getCmd());
                    }
                    super.handleQxEvent(event);
                };
            }
        );

        ITTLJob job = TTL.INSTANCE.createTTLJob(60000); // 1 minute
        
        while(job.isRunning()) {
            // user must kill the running app 
            for (AnalogPort p : ubiquino.getBoard().getAnalogPorts()) {
                System.out.println(p.getMap().getName() + " : " + p.getValue());
            }
        }
        
        return new Object();
    }

    @Override
    public void stop() {}
}

Java2html

Starting with Firmata (SDK)

In order to get done with Eclipse and Firmata, you will need Ubiquisense to get installed from update site and create a new plugin. Because Ubiquisense is an OSGi based framework, it is mandatory to get this plugin and create an application. If you are comfortable with eclipse/RCP development, you can also inspire yourself from the code and get it integrated into a view or a console.

The following steps are describing various installations and manipulations needed to get the example running. At the end of the day, it will be a good Eclipse training and will open so many new horizons !

Let's start the fun part ;-)

Step 1

Install Ubiquisense from update site or Eclipse marketplace : http://ubiquisense.com/p/ubiquisense/updates/0.5.1/site.xml

Step 2

Get Arduino for your platform : http://arduino.cc/en/Main/Software

Step 3

Install Standard Firmata on your Arduino board using Arduino IDE (Files > examples > Firmata > Standard Firmata)

Step 4

Import firmata example code com.ubiquisense.firmata.example plugin with code

Step 5

Open plugin.xml in the manifest editor and go to the extensions tab. Select the org.eclipse.core.runtime.applications contribution and then click the green arrow icon at the top of the page.

Troubleshooting :

If getting following error while running application, just try to add a -d32 option in launch configuration program arguments tab.

java.lang.UnsatisfiedLinkError: /eclipse-4.2RC2/plugins/org.rxtx.macosx.x86_2.1.72.201206301655/lib/librxtxSerial.jnilib: no suitable image found. Did find: /eclipse-4.2RC2/plugins/org.rxtx.macosx.x86_2.1.72.201206301655/lib/librxtxSerial.jnilib: no matching architecture in universal wrapper