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.
Installing SIAM on the host requires the following steps:
Building SIAM on a host and installing on the target requires the following steps:
SIAM depends on a number of open-source third-party software packages.
The following table describes the packages and shows where to obtain them.
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|
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 is a native library (using JNO) providing serial and parallel communication for the Java Software Development Toolkit (JSDK) for Linux, Win32 and Mac OS
| 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.
log4j enables selective debug logging, that enables debug output to be prioritized and set at run time without modifying source code.
The log4 JAR file resides with other 3rd party JARS in SIAM_HOME/jars.
See the following pages for installation notes for these packages:
The following table describes optional software packages for SIAM
|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 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:
Support and more information may be found at Palta Software: http://www.paltasoftware.com/rdv/
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.
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/
|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|
|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|
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).
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
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.
There are several environment variables that must be set correctly in order to build SIAM.
These are outlined in the table below:
|SIAM_HOME||Path to the SIAM installation directory||
|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.
note the Cygwin-style mixed DOS/unix path separators
|JAVA_HOME||Path to Java developers kit (containing javac, java, jre extensions etc.)||
|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.*).
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:
|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:
|default||Builds all SIAM Java classes|
Build deployed system binary package (in ipkg format), configured for MOOS Mooring Controller (MMC), but may be modified for other platforms.
SIAM shore side distribution, typically used for portal installation (for MOOS). Includes shoreUtils, portal, documentation, etc.
Builds a SIAM JAR file (siam.jar) with core SIAM classes.
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)
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:
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.
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.