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|
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|
The SIAM utilities use various shells and scripts, primarily bash, csh, Perl
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.
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
|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/
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)
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 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.*).
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).
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:
|default||Builds all SIAM Java classes|
Builds a SIAM JAR file (siam.jar) with core SIAM classes.
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)
Builds SIAM JavaDoc documentation.
Copies siam.jar to codebase directory
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 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:
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:
* 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.