SubSim Manual

This manual is for advanced user. For instructions on getting started with SubSim refer to the Installation Guide and the Quick Start Guide.

World Simulation

The objective of SubSim is to realistically simulate an autonomous robot in an underwater environment.  The underwater environment will be referred to in this document as the World, and three-dimensional objects in the World are called WorldObjects, or simply Objects.
In order to realistically simulate the underwater world, the objects must act and interact, with their environment in a similar manner to the physical reactions of real objects. This includes motion and visual appearance. Virtual sensors must also act like their real counterparts, so that any processing unit using information from a virtual sensor would not be able to differentiate the simulated signal from the real signal.

Physical Model

In order to accurately model the motion of objects under the influence of forces and collisions, a 3rd party physics engine called Newton was used.  More information about Newton can be found at

Sensors, motor, and liquid effects are modeled using the Physics Abstraction Layer (PAL) library. More information about PAL can be found at

Graphical Model

OpenGL along with a custom high-level interface is used to render the objects on the computer screen.  SubSim currently only supports Milkshape 3D models.

Controller Simulation

A requirement for the SubSim project is to simulate the execution of compiled code on an embedded system. For SubSim, the embedded controller is used to autonomously control a unmanned underwater vehicle. This requires that the SubSim application accept compiled code from source that has little or no changes from that for the actual embedded system.

Eyebot Controller

The EyeBot controller is developed to be a very versatile robot controller, suitable to build lots of different applications in the context of autonomous mobile robots. It is a 32-bit microcontroller with a variety of I/O capabilities. The Eyebot high-level API is implemented as one plugin. This provides a high-level interface to the sensors on the submarine, as well as driving commands. More information about the Eyebot microcontroller can be found at The Eyebot API is documented here.

Customizing SubSim

Because of settingsfiles and plugins SubSim can be easly customized and extended.

Creating a Custom AUV

This section covers how to create a custom autonomous underwater vehicle that can be simulated with SubSim.

  1. Create a directory to hold all the information about your AUV.
  2. Create the XML configuration file.  The configuration file determines everything about your AUV.  The configuration file should be stored in the custom AUV directory you created.
    The XML specifications are described in the Physics XML Guide
  3. Create the graphical model.  Use Milkshape 3D to create a visual representation of your AUV.  The graphical model should also be stored in the custom AUV directory you created.
  4. Write your program (or use an existing sample program). You can use either the:
  5. Try it out!  Write an Simulation File as described in the Simulation File Guide and experiment with your AUV.

Extending SubSim

SubSim was designed to be extendable through the use of Plugins.  See the Plugins HOWTO for more information on writing and compiling your own Plugin.

A low-level API interface that can be used to implement other microcontroller APIs is available. 
See the Low-level HOWTO for more information on using the low-level API.

Command Line Interface

This section discusses using the command prompt for starting SubSim. By default, the program can be started by typing the following

   > subsimD.exe

To see a complete list of command line parameters, use the -h or -help input switch.

   > subsimD.exe -h
   > subsimD.exe -help

If no parameters are passed in, SubSim will load the world from defaultworld.xml. You can specify a simulation file as parameter ans SubSim will load the simulation with all specifications. See the Subsim User Howto for more information about Simulationfiles

  > subsimD.exe mySimulation.sub