HOW TO Compile and Run a LowLevel Program for SubSim

This document explains how to compile a controler program with the SubSIm LowLevel API and HDT for the EyeBotPlugin in SubSim.

The low-level interface is inteneded for developers who wish to simulate thier own high level controller system. An example high-level control system (the Eyebot RoBios API), is provided with SubSim EyeBot Plugin, and is recommended for beginners as it provides a much simpler interface.

Internal API

The internal API consits of only five functions:

  SS_DID InitDevice( char* device_name );
  SS_ERROR ReleaseDevice( SS_DID device );
  SS_ERROR GetTime( SS_CLOCK *time );
  SS_ERROR SetData( SS_DID device, DeviceData* data );
  SS_ERROR GetData( SS_DID device, DeviceData* data );

The function InitDevice initializes the device given by its name and stores it in the internal registry. It returns a unique handle that can be used to further reference the device (e.g. sensors, motors). GetTime returns a time stamp holding the execution time of the submarines program in milliseconds. In case of failure an error code is returned.

The functions that are actually manipulating the sensors and actuators and therefore affect the interaction of the submarine with its environment are either the GetData or SetData function. While the first one retrieves the data (e.g. sensor readings), the later one changes the internal state of a device by passing control and/or information data to the device. Both return appropriate error codes if the operation fails.

Compiling the controler program

To develop & compile your controller program you can either use Microsoft Visual Studio 7.1 or your favorite texteditor with MinGW as compiler.

Using Microsoft Visual Studio 7.1

Create a new solution to hold your code projects. For each program you write, define int main(int,char**) and a HDT file in separate projects.

  1. Create a new Win32 project.
    In the Win32 Application Wizard Application Settings, set Application type to DLL and Additional options to Empty project.
  2. Set up the include and library paths.
    Select Project -> Properties, then select C/C++ and set the additional include directory to your subsim include path. (Normally: ../../subsim/include)
    Select Linker, and set the additional library directory to your subsim library path (Normally: ../../subsim/lib) Select Linker -> Input and add SubSim.lib (or SubSimD.lib for debug builds) to the Additional Dependencies.
  3. Set the runtime library (C/C++ -> Code Generation) to Multi-Threaded DLL

The project should now be set up, and ready for you to compile a new program.

Some configurations of Visual Studio will not define _WINDLL. This setting must be defined in order to export your programs main function. If the project has been correctly set up, you should see the message "Main is being automatically exported" when you compile.

Using MinGW

MinGW is a collection of freely available and freely distributable Windows specific header files and import libraries combined with GNU toolsets that allow one to produce native Windows programs that do not rely on any 3rd-party C runtime DLLs. It is a free package available under
For program development jEdit is recommended as text editor. Togehter with the jEdit Console Plugin it is very handy to compile your program.

  1. Create new directory in one of the subsim examlpe directories.
  2. Copy one of the makefiles from an highlevel example in your directory.
  3. Write your programm with the ending .cpp
  4. Run the command mingw32-make under a command-shell in your directory (make sure the MinGW path is set).

if you are tired of typing mingw32-make all the time. Create a make.bat file with mingw32-make %1in any dir which is in the path (e.g. the minGW bin dir)

Example Program:

#include "lowlevel.h" //include low-level api
#include <stdio.h> //for printf

int main ( int argc, char** argv )
	sim_api::SS_CLOCK time;
	sim_api::GetTime ( &time ); //get the time
	printf( "Time is %d\n",(long) time );
	return 0;

Executing a program in SubSim

To execute the program you have to add the program name in a .sub SimulationFile. And load the file in SubSim. Make sure the EyeBot plugin is loaded. See Manual and HOWTO SUBFILES for more details on that


More low-level example programs, including a VC71 workspace can be found in the examples/low-level directory.