Robotics Service Bus

h1. RSB.m

{{>toc}}

We are currently exploring the best way to expose RSB in Matlab. The most straightforward way to do this is to use the Java implementation directly from within Matlab. However, as the Matlab Java interpreter is not able to handle Java's Generic types, we need to wrap around some parts of the RSBJava API which use generics.

For this, a very preliminary support library for Matlab is available here: https://code.cor-lab.org/git/rsb.git.matlab

It currently includes a simple example demonstrating the live plotting of rst.JointAngles data.

h2. Compililation and Installation

After cloning the repository, you need to curently build the library from source. Given the dependencies (Apache Ant + Java libraries for ProtoBuf, RSB and RST) are available, the command to build the library with ant is as follows (please adjust the paths to your environment):

<pre>

$ ant -Dpbuf.lib=/usr/local/share/java/protobuf-java-2.4.1.jar -Drsb.lib=../rsb-java/dist/lib/rsb-0.8.0.jar -Drst.lib=../../rst/proto/build/java/rst-0.9.0.jar -Drstsandbox.lib=../../rst/proto/build/java/rstsandbox-0.9.0.jar

</pre>

You may easily install the resulting Jar-file (@rsb-m-<version>.jar@) to the folder of your choice, e.g., @/usr/local/share/java@.

h2. Usage in Matalb

After installation of this library, the current steps in using RSB in Matlab are as follows:

h3. Loading the Java RSB libraries into Matlab

<pre>

javaaddpath /usr/share/java/RSBJava-0.5.0.jar

javaaddpath /usr/share/java/protobuf.jar

javaaddpath /usr/share/java/rstsandbox.jar

javaaddpath /usr/share/java/rst.jar

</pre>

For the Matlab bindings, please replace @${home}@ with the full path to your workspace in case you have a checked out version of RSB.m. Otherwise just change the path to an installed version of RSB.m.

<pre>

javaaddpath /public/amarsi_workshop/lib/rsb.m-0.5.0.jar

</pre>

<pre>

rsb.matlab.ConverterRegistration.register()

</pre>

The last call initializes the ProtocolBufferConverter instances with a few selected RST types. This mechanism will definitely be changed as it currently introduces an unwanted dependency (at this stage) to RST.

h3. Get queue object for domain-specific data

<pre>

%   Scope must map to a rst.kinematics.JointAngles type

angles = rsb.matlab.JointAnglesQueue;

</pre>

JointAnglesQueue is a class of the RSB.m library that maps the RSB domain type rst.JointAngles to a matlab vector with floats. Furthermore, it allows access to the underlying BlockingQueue that provides further methods for queue management. See the RSBJava API documentation for more information.

h3. Connect queue to RSB listener

<pre>

sub = rsb.Factory.getInstance().createListener('/oncilla');

sub.activate()

sub.addHandler(angles, true)

</pre>

Here the usual RSBJava API is used. After calling addHandler, the angles queue receives data. You can easily check this by calling: @angles.getQueue().isEmpty()@ Further information about the queue class attached to this callback "can be found here":http://download.oracle.com/javase/6/docs/api/java/util/concurrent/BlockingQueue.html

h3. Doing something useful, e.g., data visualization 

Having the queue, we can now operate directly on the returned floats. For instance, display them in a live plot:

<pre>

a = zeros(1,200)

while(1)

a(1:end - 1) = a(2:end);

% blocks until new data is available

a(end) = angles.take(1000);

angles.getQueue.clear;

plot(a);

getframe;

end

</pre>

To prevent memory leaks, the above code clears the queue after each (blocking) call to @take@.

h3. Unload the RSB Java libraries

<pre>

javarmpath ${home}/workspace/RSB.m/dist/lib/rsb.m-0.5.0.jar

javarmpath /usr/share/java/rst.jar

javarmpath /usr/share/java/rstsandbox.jar

javarmpath /usr/share/java/RSBJava-0.5.0.jar

javarmpath /usr/share/java/protobuf.jar

</pre>

This example code is available as Matlab functions in the RSB.m project here: https://code.cor-lab.org/projects/rsb/repository/show/trunk/matlab/matlab

h2. Older notes

Sending data from Matlab to RSB:

<pre>

>> javaaddpath /vol/cit/share/java/RSBJava-0.4.0.jar

>> javaaddpath /opt/local/share/java/protobuf.jar

>> f = rsb.Factory.getInstance()

f =

rsb.Factory@5c4e0c39

>> s = Scope('/example/informer')

s =

/example/informer/

>> i = f.createInformer(s)

No rsb.conf found in configuration directory '/Users/swrede/.config'

No rsb.conf found in working directory '/Users/swrede/Documents/MATLAB'

i =

rsb.Informer@75222b8e

>> i.activate

18.07.2011 18:21:22 rsb.Informer$InformerStateInactive activate

INFO: Informer activated: [Scope:/example/informer/,Type:String]

>> i.send('RSB')

ans =

Event[id=4145dcfd-aff7-45de-b00f-0c6c315f0ce7, scope=/example/informer/, type =String, metaData=MetaData[senderId = 4d619c1a-b516-4474-9eed-eb216546ff01, createTime = 1311006099963000, sendTime = 1311006099966000, receiveTime = 0, userTimes = {}, userInfos = {}]]

</pre>

h2. Helpers

*Catching Java exceptions*

<pre>

>> try

lhhipangles.take(12)

catch,

s = lasterror();

end

>> s

</pre>

*Working with the returned Java arrays*

Naive conversion to matrix type:

<pre>

function [ matrix ] = parseArray( array )

%PARSEARRAY Parse Java array into Matlab matrix

%   Not nice. We need to find a better solution.

matrix = zeros(8,1);

for i = 1:8

    matrix(i) = array(i);

end

end

</pre>

*Helpful Mathworks Documentation* 

* "Cells and matrices":http://www.mathworks.de/help/techdoc/ref/cell.html

* "Working with Java arrays":http://www.mathworks.de/help/techdoc/matlab_external/f15351.html