NEESgrid logo

Background and Intro

As of release 3.0, the NEESGrid code internals changed significantly with the introduction of the Creare Data Turbine code to replace the NSDS. (That link has more information about how to get the turbine, how we're using it, CVS, etc) The data turbine is a flexible network ring buffer, useful to streaming, synchronization, aggregation, scalability and other data tasks.

As we've learned how to utilize the turbine, we've written a set of applications that utilize it. This page documents what they are and how to run them at your site.

Revision History

V1.0 August 24 2004 Initial posting.
V1.1 September 23 2004 - Notes on DataVideoGather
V1.2 November 19, 2004 - Small edits for post to it.nees.org

Changes and Implications: NSDS to Turbine

The Data Turbine is considerably more flexible and capable than the NSDS it replaces, meaning that its well worth reading the documentation included in the distribution. Things such as plugins, subscribe vs monitor, etc require study to use and understand.

On the minus side, we currently require that desktop users download the Creare distribution to use the client applications; we'still working on embedding the video or plot programs in a Java web applet. We do have a JNLP (Java WebStart) wrapper written that works pretty well, and Oregon State has written a web applet, so there's progress on this front.

Compiling versus Running the code

Depending on your needs, you may not need to compile the code; we certainly hope that most people will simply need to run the programs as distributed. If you just want to run them, please jump straight to those instructions and skip the next few sections.

Compiling from CVS

Please see this page for instruction on downloading and compiling the code from CVS.

Note that, as of 9/23/04, CVS is now at cvs.nees.org.

Note that the default Ant target post-3.0 is to generate a jarfile, so you can run 

 ant deploy
to copy turbine.jar into $OGSA_ROOT/lib. There's also an undeploy target to remove it.

Compiling from the NEES-POP distribution

While similar to compiling from CVS, this is complicated by the fact that the source and build directories are owned by root and therefore not writeable by other users. You'll need to copy the source code from 
 /usr/local/src/neesgrid-{version}/components/rbnb-nees/
to your home directory or other writeable location, and work from there.

Running the applications

As distributed in the 3.0 NEES-POP tarball, the compiled java applications are installed into 
 /usr/local/nees/opt/rbnb-nees/
and the data turbine goes into 
 /usr/local/nees/opt/rbnb/
This is (debateably) broken, and may change post-3.0. If you choose to work with the CVS code, note that I've changed the build.xml script to build a jarfile by default, and have added a 'deploy' target.

To run the code, you need to have a few environment variables set correctly. I'll show you how to do so for C shell; you Bash or Zsh fans can modify to suit.

Here's the section of my .cshrc from a NEES-POP; 

setenv NEES_HOME /usr/local/nees

source ${NEES_HOME}/etc/csh.cshrc
setenv OGSA_ROOT $NEES_HOME/opt/grid
setenv JMFHOME /usr/local/JMF-2.1.1e
setenv CLASSPATH $NEES_HOME/opt/rbnb-nees:$RBNB_HOME/lib/rbnb.jar:${JMFHOME}/lib/jmf.jar:.
To be honest, I doubt this is optimal/minimal; please email me if you have a better configuration.

The trailing dot, meaning 'current working directory', is to get the log4j.properties file that some programs use. I don't like the fact that classpath is being used to read a properties file, but such is the state of things.

Note for running from CVS: The version of the turbine in the distribution has its jarfiles in 

 $RBNB_HOME/lib
And the later Creare distributions put it in 
 $RBNB_HOME/bin
You'll have to edit the CLASSPATH accordingly. The Ant file looks into both when its compiling, and works with both. Annoying.

Now, you should be able to just run the fully-named application, and Java will find it via the classpath: 

[hubbard@cee-rszs ~]$ java org.nees.rbnb.DaqToRbnb -h                           Default time: Time Zone offset: 6.0
Defalut time: Daylight Savings Time offest (in hours): -1.0
Set new parameter (in DaqToRbnb) name = ServerHostName
Set new parameter (in DaqToRbnb) name = ServerPortNumber
Set new parameter (in DaqToRbnb) name = DAQServer
Set new parameter (in DaqToRbnb) name = DAQControlPort
Set new parameter (in DaqToRbnb) name = DAQDataPort
Set new parameter (in DaqToRbnb) name = SourceName
Set new parameter (in DaqToRbnb) name = CacheSize
DaqToRbnb: usage is...
DaqToRbnb 
[-s Server Hostname *localhost] 
[-p Server Port Number *3333] 
[-q DAQ Server *localhost] 
[-c DAQ Control Port *55055] 
[-d DAQ Data Port *55056] 
[-n RBNB Source Name *FromDAQ] 
[-z cache size *100]
[-o time offset, floating point, hours to GMT *5.0]
[-D flag (t/f) to debug print data time stamps *f]

Programs, most common first

Common arguments

All of the turbine programs have a few arguments in common; I'll put them here rather than repeat them for every program. Important note on command-line help. All of apps have a -h flag, as shown here, to print their arguments out. Concise help, very useful, and I highly recommend its use to you.

Common arguments are

  • -s {hostname} IP or hostname of the machine running the Data Turbine
  • -p {port} Port number of the data turbine
  • -h Command help; prints arguments and default values for each.

    • org.nees.rbnb.DaqToRbnb

    This program is the NSDS driver replacement. It speaks DAQ protocol to the DAQ, converts the timestamps from ISO8601 into Java times, subscribes to all data channels, and stuffs the data into the Turbine.

    Arguments are:

  • -q {hostname} IP or hostname of the DAQ system
  • -c {port} Port on DAQ for control channel
  • -d {port} Port on DAQ for data channel
  • -n {Name} RBNB source name. This will show up in the Admin and plot tools, so it's worth naming your DAQs by function or location, e.g. 'DaqFloor3NW'
  • -z {Integer} Cache size. This defines how much data will be kept in memory for this DAQ, int timesteps. I suggest a large number, e.g. 10000.
  • -o {Float} Time offset. Due to LabVIEW limitations, the DAQ timestamps do not include timezone information. DaqToRbnb knows how to convert from local to UTC time; by default it uses the local timezone. You only need to change this if the DAQ and turbine are in different timezones.
  • -D {0/1} Debug flag. -D 1 turns on a raft of printouts relating to timestamp conversion. Not generally useful.

    • org.nees.rbnb.AxisSource

    This generates a video feed from an Axis camera or source, e.g. 2401, 2420, 2400+, etc. By default, it feeds video at 320x240, 30 frames per second.

    Arguments are:

  • -A {hostname} IP or hostname of the Axis unit
  • -S {string} Source name. This is how they are named and retrieved, so as with the DAQ its useful to give them descriptive names. For example, 'NW2ndFloor'.
  • -C {string} Channel name. Default is video.jpg, and I'd advise leaving this at the default.
  • -z {integer} Cache size, in frames, default 30. Figure out what you need, but keep in mind that these are about 100kbytes per frame, so you may have to increase the memory allocation of the data turbine if you want a lot of buffering here.
  • -H This selects high resolution (new default), 704x480
  • -L This selects low resolution, 352x240
  • -f {integer} This selects frames per second to capture, default is 30

    • org.nees.rbnb.TpsSource

    Similar to AxisSource, this takes a FlexTPS video stream and puts it into the data turbine. The arguments are slightly different.

    Note that this class will change name post-3.0 At the Christopher's request, we've renamed the class to FlexTpsSource; in 3.0 it's TpsSource.

    Arguments for the 3.0 release are:

  • -A {hostname} Hostname of TPS source
  • -S {string} Source name. This is how they are named and retrieved, so as with the DAQ its useful to give them descriptive names. For example, 'NW2ndFloor'.
  • -C {string} Channel name. Default is video.jpg, and I'd advise leaving this at the default.
  • -z {integer} Cache size, in frames, default 30. Figure out what you need, but keep in mind that these are about 100kbytes per frame, so you may have to increase the memory allocation of the data turbine if you want a lot of buffering here.

    • Additional arguments for the post-3.0 code are:

  • -T {public|private} TPS feed type (required)
  • -N {stream} User defined TPS stream name (required)
  • -F {integer} Frames per second, times ten
  • -U {string} username. Required if you have a passworded TPS feed
  • -P {string} Password, ditto.

    • org.nees.rbnb.DataVideoGather

    This is one of the coolest of the new features; this class combines DAQ data and video to produce a quicktime movie where every frame is sychronized to a DAQ sample. See this page for some examples of the output.

    To use this, you need

    1. Synchonized clocks on all applicable machines. This is harder than it seems. I recommend a local NTP server, such as this local GPS clock with NTP server software and NTP clients on all machines.
    2. Video feed. Any source that dumps JPEGs into the turbine is fine. We usually use the AxisSource but jcamera works too.
    3. DAQ feed. This is the source of the sync; the code takes frames closest to the DAQ samples.
    Here are the arguments: 
    DataVideoGather: usage is...
DataVideoGather 
[-s Server Hostname *localhost] 
[-p Server Port Number *3333] 
[-k Sink Name *DataVideoGather ]
[-c Data Channels Path Pattern - pearl-like pattern to match] 
[-C Data Channels list - comma seperated lsit of Paths]
[-x Include Hidden channels (true|false) *false]
[-Z zero for missing data; otherzise last value repeats]
[-v Video Source path - no path for no movie]
[-d Archive directory root *.]
[-M Movie output file name *Movie.mov]
[-D Data output file name *Data.txt]
[-f Frame Rate of final movie *1.0]
[-i Items to skip in data for each movie frame *0]
[-w Wait Time in seconds; the time between cycles *1800]
[-W Collection time in seconds; defaults to Wait Time]
    Here's an example, as used at 13WCEE: 
      java org/nees/rbnb/DataVideoGather -c "FromDAQ/.*" -v "axis46/video.jpg" -w $steps -W $steps -d $directory -f 15
    And here's another one I wrote for a recent demo, as csh script: 
    #!/bin/tcsh

set interval = 600
set framerate = 5

echo Movie from Axis 1
java org.nees.rbnb.DataVideoGather -s cee-zzle.cee.uiuc.edu -c "MainDAQ/.*"  -v "axis1/video.jpg" -M axis1.mov -w $interval -W $interval -f $framerate

echo Movie from Axis 2
java org.nees.rbnb.DataVideoGather -s cee-zzle.cee.uiuc.edu -c "MainDAQ/.*"  -v "axis2/video.jpg" -M axis2.mov -w $interval -W $interval -f $framerate
    Here are additional instructions for usage: 

    -c is the perl-like pattern that matches all the channels that you want to
use... it synchronizes on the "first" channel in the list...
-v is the full BRNB path of the video
-w and -W are the interval (in seconds) that will be captured (one used to
be the interval between captures, but that is no longer meaningful, since it
is now written as a one-shot, I just forgot which is which, so I set them
both)
-d is the directory were everything gets written
-f is the frame rate of the final movie in FPS... how fast do you want the
animation to play in QuickTime

    org.nees.rbnb.FileToRbnb

    This is not included in the 3.0 distribution; it will be included in post-3.0. It's a program to take an DAQ-format ASCII file and upload it into the data turbine.

    Arguments are

  • -n {string} source name. As with all of these, a descriptive name helps.
  • -c {string} channel name.
  • -d {directory} Directory to find the data file
  • -D {filename} Data file name
  • -z Cache size. Choose a buffer large enough to hold all the data.

    • java.org.nees.rbnb.GrabDataMultipleSink

    This is the complement of FileToRbnb; it downloads all specified channels to local disk.

    Arguments are

  • -k {string} Sink name. Not sure why you need this.
  • -d {directory} Directory to write data into.
  • -x {true|false} Include hidden. No, I don't understand this either.
  • -a {time} start time
  • -z {time} end time
    • Times can either be yyyy-mm-dd;hh:mm:ss.nnn or an arbitrary floating point number.

    More classes to come

    There are more to document, but that'll wait for later.

    Increasing the amount of memory for the turbine

    By default, Java gives 256MB of memory to the virtual machine running the turbine. While more than enough for most java programs, its often useful to increase this to allow for more channels and longer time histories. To do so, edit 
     /usr/local/nees/etc/rc.d/init.d/rbnb
    and change 
      java -jar lib/rbnb.jar &
    to 
      java -Xmx1024M -jar lib/rbnb.jar &
    Or whatever you want; this example allocates 1024MB (1GB) to the Turbine. We've used up to 1500MB on a 2GB machine with no problems.

    You'll have to restart the turbine for the change to take effect.

    Code documentation

    I've started adding Doxygen to the source code, for internal documentation. This has a long way to go, but may be useful for those wanting to look more at the internals.

    The latest version is included with the code, and can be generated by running 

     
  ant doxygen
    I've uploaded a snapshot generated on Aug 24 2004 so you can see what it looks like.

    Navigation links

  • Back to NEESGrid at Argonne
  • Back to home page
    •

    Support

    This work was supported primarily by the George E. Brown, Jr. Network for Earthquake Engineering Simulation (NEES) Program of the National Science Foundation under Award Number CMS-0117853.