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.
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.
To develop & compile your controller program you can either use Microsoft Visual Studio 7.1 or your favorite texteditor with MinGW as compiler.
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.
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.
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 https://www.mingw.org.
For program development jEdit is recommended https://www.jedit.org. as text editor.
Togehter with the jEdit Console Plugin it is very handy to compile your program.
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)
#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;
}
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.