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
Gnu Utilities SIAM is 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)
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
Apache Ant Ant may be used to build SIAM as an alternative to make. Also used to build PUCK classes. http://ant.apache.org -
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/
-

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 mbari-siam 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.*).

Makefiles

There is a system of Makefiles used to build SIAM. The Java classes for each package are built by Makefiles in the package directory. These are invoked by two top-level Makefiles that also define build targets and compilation options.
Another set of Makefiles for building instrument service JAR files are used to configure instrument service defaults; these are organized by deployment.
The native C code applications (many of which are application- or platform-specific) also have Makefiles associated with them.
All of these are summarized below:

Makefile Location Description
SIAM_HOME/Makefile top level Makefile - defines which packages are built
SIAM_HOME/make/Makefile Rules, build targets and compilation options are all defined here - invokes package-level Makefiles
SIAM_HOME/make/Makefile.[deployment] Makefiles for deployment-specific PUCK targets
SIAM_HOME/src/[package]/Makefile Each Java package has a Makefile - defines source files for javac and rmic compilation
SIAM_HOME/native/[platform]/src/[package]/Makefile Makefiles for building platform-specific native C applications

Although the name of the siam repository is "siam2" SIAM makefiles rely on the SIAM_HOME directory name being named "siam". Create a symbolic link to with this name to the siam2 directory as follows before building SIAM:

ln -s siam2 siam

Build targets

The table below defines various targets that may be built using the SIAM makefiles:
Build Target Description
default Builds all SIAM Java classes
deployed

Build deployed system binary package (in ipkg format), configured for MOOS Mooring Controller (MMC), but may be modified for other platforms.
Includes all core SIAM components needed to configure and run SIAM (on MMC).
Includes patches that overwrite system files in the (linux) root file system.
Does not include documentation, portal, shoreUtils, instrument service classes (which are provided by instrument service JARS) or other components not required by MMC.

shore

SIAM shore side distribution, typically used for portal installation (for MOOS). Includes shoreUtils, portal, documentation, etc.

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).

javadoc

Builds SIAM JavaDoc documentation.

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)

Make 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:

make
make 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 Makefiles/scripts organized by deployment.
The Makefiles 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.

Using Makefiles
The main makefile (SIAM_HOME/make/Makefile) contains lines that may be uncommented to include the instrument service Makefiles.
In these files, targets are defined for building related groups of instruments. The targets are given names prepended with the deployment name to prevent target naming conflicts.
For example a target named "2009FOCE.ctd" builds a set of CTD instrument service JAR files with different IDs and configurations.
There is generally a default target (e.g. focepucks) for building all of the instrument groups, or targets may be built individually.

Using shell scripts
Since there are not really any dependencies to be managed, using make is not strictly required.
The script to configure and build instrument service JAR files may be called by a shell script as well.
SIAM_HOME/docs/siam-site/examples/makeJars-example.sh is an example of one way to do this that allows groups of JAR files to be built.

Sample Makefiles and JAR-building scripts are included in the documentation in the SIAM_HOME/docs/siam-site/content/examples directory. There are example XML files containing only comments, which are used in the example Makefiles. An example of the MBARI XML schema is also included. Additional Makefile examples (that reference XML not found in the SIAM repository) are included in the SIAM_HOME/make/ directory, e.g. Makefile.2009FOCE, pucks.ALOHA2010 etc.

Here are sample command lines showing how to use the example Makefile and script (execute from SIAM_HOME after uncommenting the appropriate line in make/Makefile):

# show available example targets
make example.help

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

# show available example targets using script
makeJars-example.sh --help

# build example ctd and camera services using script
makeJars-example.sh ctd cam

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:

make deployed

Build SIAM tar distribution for a Portal:

make 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.