This is a guide written for new users of SubSim. By following the steps below, you will install SubSim, start the program, and run a simple client program.
To install SubSim, simply double-click on the installation file, and an installation
wizard will guide you trough the installation process.
After the installation process completes, there should be a "Subsim SDK"
folder in your
windows program folder.
Clicking the SubsimMain entry will start the SubSim application with the defaultworld.
You also have the possibility to start SubSim from the command prompt or the
SubsimConsole shell. See the section on running SubSim
from the command line.
If you would like to see SubSim in action just choose one of our example programmes
in
one of the example directories under /subsim/examples. Just doubleclick on one
of the
simulation files with the SubSim icon and SubSim should start, loading and running
the
chosen program.
You may wish to try the SubSim Beginners Tutorial. This will teach you how to load and run different programs on a Submarine.
SubSim uses a set of configuration files to set up the default simulation world. These files are in XML format, so they are relatively easy to read, understand, and modify if necessary. (Remember, it is a good idea to make a back-up copy before editing the XML files.)
Here is a list of the default XML files and a description of their usage:
SubSim uses many plugins to extend the GUI interface and provide useful functions to the user. There are a set of core plugins that are required to run SubSim. These are
The term client program refers to C or C++ code which has been compiled into a .dll. This .dll can be loaded at run-time by SubSim and the program executed. The code within the .dll appears to the user like a ordinary program (i.e. int main (int argc, char* argv[]) must be defined ). See the User HOWTO for more information on compiling your own source code for SubSim. To execute a client program, start SubSim and find the Client Manager GUI (this should be shown automatically). Select File->Run from the Client Manager menu. You will be prompted for a program file. Select the program you wish to run. After selecting the program, it will be started automatically.
The SubSim user interface is based around a single central simulation window, henceforth referred to as the main window.
In the 3D simulated world, the user's viewpoint is controlled by a virtual camera which is taking continuous pictures of the scene. The position and orientation of the camera can be controlled either by the mouse by the keyboard or by the GUI (recommended).
Zoom Slider: Get closer to the object with the camera
Strafe Y: Move the camera in Y-direction (up and down)
Rotate Y: Rotate the scene around the Y-axis
Strafe X: Move the camera in X-direction (left and right)
Rotate X: Rotate the scene around the X-axis
To move the camera with the mouse, move the mouse pointer inside the main window, press and hold the left mouse button, then drag the mouse pointer across the screen. The motion of the camera approximates a "trackball", meaning the view changes as if there was a large ball that you were spinning by clicking and dragging it. The following table lists the keys and their affect on the view. UP, DOWN, LEFT, and RIGHT refer to the arrow keys. A plus sign means that keys must be depressed at the same time
| UP | Pan camera up |
| DOWN | Pan camera down |
| LEFT | Pan camera to left |
| RIGHT | Pan camera to right |
| CTRL + UP | Move camera forward |
| CTRL + DOWN | Move camera backward |
| CTRL + LEFT | Rotate camera to left |
| CTRL + RIGHT | Rotate camera to right |
| SHIFT + CTRL + UP | Rotate camera up |
| SHIFT + CTRL + DOWN | Rotate camera down |
The main window status bar (along the bottom of the main window) gives useful information about the status of the simulation. The status bar is divided into fields. The left-most field is for generic text and application messages. The field after "Threads" denotes the number of user programs currently running. The next field to the right shows the simulation status. This field will read either STOPPED, PAUSED, or RUNNING depending on the simulator state. The next field to the right shows the simulation time in seconds. The right-most field shows the frames-per-second render rate.
The Client Manager plugin displays information about the currently loaded user programs and allows you to load and unload programs. To open the Client Manager window, choose "Client Manager" from the main window's "Tools" menu. In order to execute a program, you must first load it so that it appears in the program list. To load a program, select File => Load from the Client Manager menu. Any program in the programs list can be executed. To execute a program, first select it in the table so that a bold blue line appears around the desired program (in the above image, the second program from the top is selected). After selecting the program, select File => Run from the Client Manager menu.
The World Manager plugin displays information about the simulated world and objects contained in that world. For each object in the world, the name, position, and local coordinate frame axes are displayed.
The Eyebot LCD plugin simulates the physical interface of the Eyebot microcontroller. The Eyebot API LCD functions print to the LCD screen. The four white buttons at the bottom of the Eyebot LCD can be clicked on with the mouse to simulate Eyebot key input.
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