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:

• Configure host
• Install 3rd party software
• Install SIAM source code
• Configure build environment
• Build SIAM Java sources
• Build SIAM native sources for host
• Configure SIAM
• Configure instrument service JAR files
• Build instrument service JAR files

Install on target

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

• Configure host
• Install 3rd party software
• Install SIAM source code
• Configure build environment
• Build SIAM Java sources
• Build SIAM native sources for target
• Configure instrument service JAR files
• Build instrument service JAR files
• Make SIAM binary distribution package
• Install SIAM binary distribution on target
• Configure target
• Configure SIAM on target

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

Installation Notes

See the following pages for installation notes for these packages:

• Java SDK
• Gnu Utilities
• RXTX
• Open Source Data Turbine

Optional Packages

The following table describes optional software packages for SIAM

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

• Create a user account that will be used for SIAM administration and operation (which we refer to as "ops")*
• Add a user group call also "ops"
• Add user ops to groups ops, uucp, lock, wheel (no need to create these if they don't exist)

*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 royalty-free license through collaborator agreements. To obtain a license, please contact the Director of Information and Technology Dissemination at MBARI.

SIAM is distributed as a tar.gz archive. As user ops, the distribution should be unpacked on the computer that will be used to build the source tree. This will create a directory named siam2.

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:

• SIAM application: main SIAM package for data collection, logging and telemetry
• Native: platform-specific native code
• PUCK: Instrument service JAR archives
• Utilities: Java and (platform-specific) C applications for SIAM operations, accompanied by wrapper scripts written mostly in bash and csh
• Portal: Shore side telemetry, logging and archiving (used for MOOS)
• Shore Utils: Java and (platform-specific) C applications for SIAM operations, accompanied by wrapper scripts written mostly in bash, csh and Perl

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:

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:

Build targets

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

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:

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