SIAM Installation Guide

Types of installation

Depending on the capabilities of the target application hardware and software, SIAM may be installed and built directly on the target platform, or built on a host machine as a binary distribution and installed on the target.

It is recommended to build directly on the target platform if possible. However, many embedded platforms do not have compilers and other tools for the target environment; these would be candidates for host installations.

Regardless of which type of installation used, you may find it convenient to set up a special user account for system administration (e.g. "ops"), especially if there will be more than one system operator.

Install on host

Installing SIAM on the host requires the following steps:

Install on target

Building SIAM on a host and installing on the target requires the following steps:

3rd Party Packages

SIAM depends on a number of open-source third-party software packages.
The following table describes the packages and shows where to obtain them.

Required Packages

Package Description Source Notes
Java SDK SIAM runs using Java SE Virtual Machine v1.3 or higher.
To build SIAM, a Java Developer Kit version 1.3 or higher is required.
We have successfully used JDK 6.x, J2SE 1.3.1, J2SE 1.4.2, J2SE 5.0
http://www.oracle.com/technetwork/java All SIAM code maintains compatibility with Java 1.3 to support older embedded JVMs
Apache Ant

Ant is to build SIAM as an alternative to make. Also used to build PUCK classes.

http://ant.apache.org version 1.8 or higher is required
Gnu Utilities

The SIAM utilities use various shells and scripts, primarily bash, csh, Perl

http://www.gnu.org
RXTX Version 2.1-7r2
RXTX is a native library (using JNO) providing serial and parallel communication for the Java Software Development Toolkit (JSDK) for Linux, Win32 and Mac OS
http://rxtx.qbang.org
http://users.frii.com/jarvi/rxtx
A version of RXTXcomm.jar is currently in the SIAM repository, but a platform-specific binary library is also required.
We do not have a license to distribute RXTX, so it is necessary to obtain and install RXTX from the developers.
The RXTX website has been undergoing some changes and availability has been spotty
if the first URL is not working, try the listed alternatives
Open Source Data Turbine (OSDT)

Streaming data middleware system that lets you stream live data from experiments, labs, webcams, etc.
SIAM uses OSDT to provide a data stream pub/sub mechanism for other applications, including other SIAM services and visualization tools like RDV.

http://www.dataturbine.org
log4j Version 1.2
log4j enables selective debug logging, that enables debug output to be prioritized and set at run time without modifying source code.
http://logging.apache.org/log4j/1.2/
The log4 JAR file resides with other 3rd party JARS in SIAM_HOME/jars.

Installation Notes

See the following pages for installation notes for these packages:

Optional Packages

The following table describes optional software packages for SIAM

Package Description Source Notes
Cygwin Cygwin provides an environment similar to Unix/Linux for Win32, including ports for a wide range of Gnu software http://www.cygwin.com An editor capable of saving files in Unix format (no DOS line ends) is needed, e.g. vi, emacs, etc. several are available as optional Cygwin packages.
Real-time Data Viewer
(RDV)
RDV is a visualization environment for scientific and engineering data.
Built on top of the Data Turbine dynamic data server, it supports local and remote data sources and can visualize numeric, video, image, and audio data in a number of different ways.
Download from google code:
http://code.google.com/p/rdv

Support and more information may be found at Palta Software: http://www.paltasoftware.com/rdv/
-
Gnu Utilities SIAM may be built using the Gnu tool chain (make, gcc).
The SIAM utilities use various shells and scripts, primarily bash, csh, Perl
http://www.gnu.org GNU make 3.81 (version 3.80 for Cygwin)
gcc version 4.2.1
Other versions may work, but have not been tested
Cygwin can provide these for Windows users
(see optional packages below)

User Accounts and Groups

If you are installing SIAM for deployment, it is convenient to install and run SIAM from an administrative account.
This step is not strictly necessary if you are installing SIAM for development. Typically, this is done before installing SIAM; the following steps are used to set up an administrative account called "ops".

*You may also choose to use your own account as the operator account. In this case, use group "users" (Linux) (or "staff" (Mac OS)); no need to create an "ops" group. Make sure that you belong to the groups users, uucp, wheel and lock. To make things less confusing, we'll refer to this user as "ops" or "user ops" as well.

SIAM Source

The SIAM code is currently shared under an open source license. The code repository is hosted externally at this site.

SIAM is distributed as a mercurial archive. Obtain a local copy of the mbari-siam repository with this command:

hg clone https://code.google.com/p/mbari-siam/

Win32 note: do not install siam in a path whose name contains any whitespace (e.g. "My Documents"), as it will interfere with make and javac

The top-level directory structure under siam2 is described in the following table:
Directory Description
atp Automated test scripts to exercise a few key test scripts
autoScript Scripts and code related to store-and-forward scripting feature
bin Binary build output for platform-specific native C code
build Scripts that may be used modified and used to configure build environment
classes Binary build output for SIAM Java classes
docs SIAM documentation
images Documentation image files
jars 3rd Party JAR files
logs SIAM data and logfile
make SIAM build configuration
native Native platform-specific C sources
patch revision-controlled binary patches [deprecated]
ports Instrument service JAR files and service/PUCK content sandbox
properties SIAM configuration files
releases revision-controlled SIAM releases [deprecated]
rootsrv Platform-specific native C server that performs priviledged system operations
shoreUtils Scripts for SIAM utilities used on "shore" (i.e., not strictly needed on target platform]
src SIAM Java sources
test Test code
utils SIAM utilities

The top level siam directory will be referred to as SIAM_HOME. The directory containing SIAM_HOME will be referred to as INSTALL. Create a directory in the same directory that contains SIAM_HOME called "codebase" (referred to as CODEBASE).

Setting permissions

Once the SIAM sources are installed, it is important to ensure that ownership and access permissions are set correctly for the SIAM files. For the most part, files in the SIAM distribution TAR file should have permissions set correctly; there are some files for which permissions and ownership need to be set to or by root.
The following listing summarizes SIAM file permissions and ownership.


# "ops" is the SIAM operator/administrator user account
# "ROOT" is the system root directory ("/")
# "SIAM" is the SIAM_HOME directory
# "INSTALL" is the directory containing SIAM_HOME

$CHOWN ops:root $ROOT/home/ops/.bashrc
$CHMOD 775 $ROOT/home/ops/.bashrc

$CHOWN -R ops:root $SIAM
$CHMOD -R 775  $SIAM/utils
$CHMOD -R 775  $SIAM/bin
$CHMOD -R 775  $SIAM/properties
$CHMOD -R 775  $SIAM/atp
$CHMOD -R 775  $SIAM/ports
$CHMOD -R 664  $SIAM/src

$CHOWN -R ops:users $INSTALL/codebase
$CHMOD -R 775 $INSTALL/codebase

For typical host installations, the ownership and permissions for system files are correctly set. If you are installing to an embedded target (e.g. MMC), the distribution may include system files that override default versions in flash memory.

If this is the case, the permissions and ownership may be changed during the installation process; these must be correctly set for the system to function properly after the installation. Embedded targets may also require SIAM to run system executables, some with priviledged access. The following list (though not exact or comprehensive) includes some system files and ownership/permissions that may need to be set for embedded targets.

# Some system files
$CHOWN root:root $ETC/hosts
$CHMOD 664 $ETC/hosts
$CHOWN root:root $ETC/hostname
$CHMOD 664 $ETC/hostname
$CHOWN root:root $ETC/inittab
$CHMOD 664 $ETC/inittab
$CHOWN root:root $ETC/profile
$CHMOD 664 $ETC/profile
$CHOWN root:root $ETC/fstab
$CHMOD 664 $ETC/fstab
$CHOWN root:root $ETC/resolv.conf
$CHMOD 664 $ETC/resolv.conf
$CHMOD 775 $ETC/init.d/*
$CHOWN root:root $ETC/init.d/binRouting.sh
$CHOWN root:root $ETC/init.d/rc.local
$CHOWN -R root:root $ETC/network
$CHMOD 775 $ETC/network
$CHMOD 664 $ETC/network/interfaces

# SIAM files
$CHOWN root:root $ETC/init.d/siamapp
$CHOWN -R ops:root $ETC/siam
$CHOWN root:root $ETC/siam/siamEnv

# Serial ports and other devices
$CHOWN root:lock $ROOT/dev/ttySA*
$CHMOD 666 $ROOT/dev/ttySA*
$CHOWN root:lock $ROOT/dev/ttySX*
$CHMOD 666 $ROOT/dev/ttySX*
$CHOWN root:root $ROOT/dev/null
$CHMOD 666 $ROOT/dev/null

# Example: boa webserver (for MMC)
$CHOWN -R ops:root $ETC/boa
$CHMOD 775 $ETC/boa
$CHMOD 664 $ETC/boa/boa.conf

# SIAM telemetry scripts
$CHOWN root:root $ETC/auxTelem.sh
$CHMOD 775 $ETC/auxTelem.sh
$CHOWN -R root:root $ETC/*ShoreMsgService
$CHMOD 775 $ETC/*ShoreMsgService

# PPP configurations
$CHOWN root:root $ETC/ppp/pap-secrets
$CHMOD 664 $ETC/ppp/pap-secrets
$CHOWN ops:root $ETC/ppp/peers/globalstar
$CHMOD 664 $ETC/ppp/peers/globalstar
$CHOWN ops:root $ETC/ppp/peers/globalstarAux
$CHMOD 664 $ETC/ppp/peers/globalstarAux
$CHOWN ops:root $ETC/ppp/peers/longhaul
$CHMOD 664 $ETC/ppp/peers/longhaul
$CHOWN ops:root $ETC/ppp/peers/shorthaul
$CHMOD 664 $ETC/ppp/peers/shorthaul
$CHOWN ops:root $ETC/ppp/peers/downlink7
$CHMOD 664 $ETC/ppp/peers/downlink7
$CHOWN ops:root $ETC/ppp/peers/subnode*
$CHMOD 664 $ETC/ppp/peers/subnode*
$CHOWN ops:root $ETC/ppp/peers/topnode*
$CHMOD 664 $ETC/ppp/peers/topnode*
$CHOWN ops:root $ETC/ppp/peers/uplink
$CHMOD 664 $ETC/ppp/peers/uplink

Building SIAM

SIAM is comprised of several major components:

These are mostly built using Gnu make, and the procedure is managed through a system of Makefiles (developed by GeoSoft: http://geosoft.no/development/javamake.html). The build procedure outlined below describes key steps to building SIAM software: setting up the environment and building various make targets.

Environment

There are several environment variables that must be set correctly in order to build SIAM.
These are outlined in the table below:

Environment Variable Description Example
SIAM_HOME Path to the SIAM installation directory

Linux, MacOS
/Users/someUser/cvs/siam2

Win32/Cygwin
c:/foo/bAR/Baz/siam2
note the Cygwin-style mixed DOS/unix path separators

SIAM_CLASSPATH Classpath variable containing appropriate 3rd party jars and all classes needed to build and run SIAM
Note that siam.jar is created after compiling the SIAM sources, so is not included in the SIAM repository.

Linux, MacOS
$JUNIT_HOME/junit-4.5.jar:$SIAM_HOME/jars/rbnb-java1_3 .jar:$SIAM_HOME/jars/siam.jar:$SIAM_HOME/classes:$SIAM_HOME/jars/gnu-re gexp-1.1.4.jar:$SIAM_HOME/jars/RXTXcomm.jar:$SIAM_HOME/jars/jcommon.kh.jar :$SIAM_HOME/jars/javax.jar:$SIAM_HOME/jars/log4j-1.2.13.jar:$SIAM_HOME/ jars/ssds-client-pub-bob.jar:$SIAM_HOME/jars/commons-logging.jar:$SIAM_HOM E/jars/javax.servlet.jar:$SIAM_HOME/jars/org.mortbay.jetty-jdk1.2.jar:$SIA M_HOME/jars/jddac-common.jar:$SIAM_HOME/jars/jddac-probe-j2me.jar

Win32/Cygwin
$JUNIT_HOME/junit-4.5.jar;$SIAM_HOME/classes;$SIAM_HOME/jars/jakarta-regexp-1.5.jar ;$SIAM_HOME/jars/RXTXcomm.jar;$SIAM_HOME/jars/jcommon.kh.jar;$SIAM_HOME/jars/jav ax.jar;$SIAM_HOME/jars/log4j-1.2.13.jar;$SIAM_HOME/jars/ssds-client-pub-bob.jar; $SIAM_HOME/jars/commons-logging.jar;$SIAM_HOME/jars/javax.servlet.jar;$SIAM_HOME /jars/org.mortbay.jetty-jdk1.2.jar;$SIAM_HOME/jars/jddac-common.jar;$SIAM_HOME/j ars/jddac-probe-j2me.jar

note the Cygwin-style mixed DOS/unix path separators
JAVA_HOME Path to Java developers kit (containing javac, java, jre extensions etc.)

Linux, MacOS
/System/Library/Frameworks/JavaVM.framework/Versions/Current/Commands/java_home This may vary, depending on your intstallation

Win32/Cygwin
c:/j2sdk-1.4.2_5
note the Cygwin-style mixed DOS/unix path separators

JAVA_DEV_ROOT Path to directory containing top Java source (src) directory should be same as SIAM_HOME
IS_UNIX Set to 1 if system is Linux or MacOS, otherwise 0 -
SIAM_BIN Path to directory containing native SIAM binaries (e.g. rconsole, ipaddr, ethaddr, etc. ) typically SIAM_HOME/bin/<platform>, e.g. SIAM_HOME/bin/x86_win32

It is often convenient to set the environment during login initialization (using .bashrc) or through scripts that may be sourced prior to building. Example scripts are included in the SIAM source package (siam2/build/siam-env.*).

Ant Build Files

SIAM uses Apache ant to create SIAM JAR files and instrument PUCK JAR files. Ant requires that two files, build.properties and build.xml, be located at the top of the build directory. build.properties contains build environment variable definitions.
build.xml contains build target definitions (much like a Makefile).
Issuing the ant command will automatically build the default target (in this case, all of the SIAM files).

In addition to build.xml, the SIAM distribution contains a number of other build configurations for generating PUCK JAR files. These should also be located in the top level SIAM directory (SIAM_HOME).

Build targets

To make specific targets use
ant
To see a list of availble targets, use
ant help

Among the targets listed are additional topics to provide detailed help on specified targets and their sub-targets. The table below describes several common targets that may be built:

Build Target Description
default Builds all SIAM Java classes
siamjar

Builds a SIAM JAR file (siam.jar) with core SIAM classes.
Does not include instrument service classes (which are obtained dynamically from instrument services running on the SIAM node).

siamif

Builds SIAM interface JAR (SIAM class exports for use by 3rd party applications).

Instrument Service JAR (PUCK) targets Targets to build instrument service packages for deployment.
Instrument service JARs may be configured and built using Makefiles or shell scripts.
Depends on instrument service XML not included with SIAM; you may make your own using examples, or supply a placeholder document. (see below)
javadoc

Builds SIAM JavaDoc documentation.

install

Copies siam.jar to codebase directory

Building siamjar

If you plan to build and run SIAM on the target, you will need to build the default (build SIAM classes) and siamjar (archive SIAM classes into siam.jar) targets:

ant
ant siamjar

Make Instrument Service JAR files

Once the SIAM classes have been built, instrument service JAR files may be configured and built.
There are a couple of ways to do this: using make or a shell script.
The instrument service JAR files (PUCK JARs) are configured in ant build files, organized by deployment.
The ant build files use the mkpuck and mksiamjar utilities, passing in instrument service default configuration parameters, and generate instrument service JAR files in SIAM_HOME/ports.
The instrument service JARs used by MBARI include an XML file containing metadata describing the instrument and it's data stream.
This XML document that accompanies the instrument service may be extracted by the host and used to automatically configure the data handling system.
This metadata is typically maintained separately from the SIAM repository, since it is instrument-specific.

Sample ant build files are included in the documentation in the SIAM_HOME/docs/siam-site/content/examples directory. There are example PUCK metadata XML files containing only comments, which are used in the example Makefiles. An example of the MBARI XML schema is also included.

Here are sample command lines showing how to use the example ant build commands:

# show available ant targets
ant help

# show available example targets
ant example.help

# build example ctd and adcp dummy services
ant example.ctd example.adcp

SIAM builds may also be managed using the Gnu make utility. Makefile examples (which reference XML not found in the SIAM repository) are included in the SIAM_HOME/make/ directory, e.g. Makefile.2009FOCE, pucks.ALOHA2010 etc.

If you are targeting a SIAM application or Portal* build for another machine, you also need to build a distribution using the deployed or shore targets:
Build an ipkg SIAM distribution for MOOS mooring controller:

ant moos.deployed

Build SIAM tar distribution for a Portal:

ant moos.shore


* a Portal is a telemetry endpoint for a SIAM node that is not continuously connected, e.g., a mooring with satellite communications
A portal manages connections and telemetry for the mooring and services as the access point to the remote SIAM node.