Execution and Runtime Configuration

The Tekkotsu framework allows your behaviors to run on a desktop computer as well as onboard an embedded device.  Flexibility in runtime environment is important to allow a variety of usage cases:

Building:

The downloads page should provide links to specialized instructions for your platform. But to summarize:

Execution

The Tekkotsu executable will be named make tekkotsu-MODEL, where MODEL is the name of the target robot. It will be placed directly in your project directory. To run it:

./tekkotsu-MODEL

You can launch Tekkotsu without any command line arguments.  Passing --help will give you a list of the available options, such as overriding runtime configuration values or causing startup to be interrupted at various stages of initialization in order to debug startup problems.

Once Tekkotsu is running, you can type help to get a list of commands and their syntax.  Some commands, like set, can also give descriptions of their arguments, e.g. help set Vision.Sources would give more information on the Vision.Sources parameter. Commands available for 3.1 release include:

Once the RUNNING runlevel is reached, the StartupBehavior of the current project is called, and the framework is fully operational.  You should be able to connect a ControllerGUI and launch behaviors, inspect values, etc.  However, you may notice that there are no camera images or sensor updates being processed.  To connect to your harware devices, you will need to configure the HAL as described in the next section.

Configuration

There are a number of configuration settings to control the passage of time and the input of vision and sensor data.  These settings are loaded from hal-modelname.plist file in the project directory if it exists, and are otherwise given default values from defaults/hal-modelname.plist.  These values can be overridden by command line arguments given when launching Tekkotsu, or by the set command at the HAL command prompt.

The DeviceDriver class provides the interface to a piece of hardware.  DeviceDrivers often connect to their hardware via a CommPort interface. Your robot's default configuration should have already instantiated the appropriate drivers and ports for your model, although you may need to fill in host names or other such parameters.  You can type 'set Drivers' or 'set CommPorts' to see the current settings.

DeviceDriver
DeviceDriver Architecture

You can create new drivers and comm ports with the 'new' command, and delete them with 'delete'. (see command list in previous section)

The HAL runs two threads for loading data, Vision and Sensors, which can each be connected to one of the DataSources via their Sources list.  Typing 'help set Vision.Sources' should display a list of all available image sources. Similarly, 'help set Sensors.Sources' will show sensor sources.

Once you have the threads connected to DataSources, and the DataSources configured to connect to their hardware, your behaviors should start seeing the data flow into the Main and Motion processes.

There are two fundamental modes for handling data.  In realtime mode the simulator time will be linked to the hardware clock, and data may be dropped if too much processing is being done on each frame. In non-realtime mode, the simulator waits until processing is complete on each data chunk before advancing the "time" to the next input. Non-realtime mode only really makes sense when using something like logged data on disk. If your data source is itself realtime, you're not going to go any faster than its sampling frequency, and will still drop data if you're too slow.

In realtime mode, you can scale the clock via the Speed parameter. For instance, you can set Speed=0.5 so that time moves at half speed.  This can help you to artificially constrain or boost the host system's computational power as if the code was running on a more or less powerful platform.

Other notable settings include:

Tool Development

It is often useful to use portions of framework code in small executables which do not need the full simulator environment, such as unit tests or data manipulation utilities.  Tekkotsu's tools directory has a few examples: safemot and convertmot are used for converting motion sequences from the binary CMPack format to the text based MotionSequence format.  The tools/test directory has a few unit tests that were used in development of sections of the framework.

In order to facilitate the usage of segments of the framework, we provide a header file in local/minisim.h.  This header file will provide initialization routines of many of the global variables which sections of the framework rely on, but it will only initialize those which you explicitly request to be enabled.

"Mini-sim" currently provides support for:

Thus, to make use of minisim's initialization routines, you would do something like this:
helloworld.cc
// typically, this is all you need (and you may not even need it)
#define TK_ENABLE_SOUTSERR

// these five are only needed for specific applications
//#define TK_ENABLE_CONFIG
//#define TK_ENABLE_EROUTER
//#define TK_ENABLE_WIRELESS
//#define TK_ENABLE_KINEMATICS
//#define TK_ENABLE_THREADING

//define the sections to enable *before* including minisim
#include "local/minisim.h"

#include <iostream>
#include <string>

using namespace std;

int main(int argc, char** argv) {
    //call the minisim initialization function
    //to set up the sections you enabled
    minisim::initialize();
   
    cout << "Hello World!" << endl;
    sout->printf("sout says hi too!\n");
   
    //call the minisim teardown function to free up those globals 
    minisim::destruct();
    return 0;
}

In order to link against libtekkotsu, you will need to have previously compiled the framework.  Go to the Tekkotsu directory and type 'make' if you haven't already.

Then, to compile and link your executable, use the -I flag to the compiler to specify that TEKKOTSU_ROOT should be searched for header files, and pass libtekkotsu.a to the linker so that the executable can be produced:
$ g++ tk_hello.cc -I${TEKKOTSU_ROOT} \
  -L${TEKKOTSU_ROOT}/build/PLATFORM_LOCAL/TGT_ERS7 -ltekkotsu -o tk_hello
$ ./tk_hello
Hello World!
sout says hi too!

Alternatively, you may prefer to use a Makefile to automate the build process. We provide a convenient template Makefile for tools in tools/tool_makefile. It is set up to do everything automatically, with the assumption that each tool has its own separate directory.
~$ mkdir helloworld
~$ cd helloworld
~/helloworld$ cp $TEKKOTSU_ROOT/tools/tool_makefile Makefile
This is a Mac OS X command -- if you copy the above sample code to the clipboard (aka "pasteboard"), this command will then paste it into to a file named "main.cc"
~/helloworld$ pbpaste > main.cc
~/helloworld$ make
Generating main.d...
Compiling main.cc...
Linking helloworld-ERS7...
The name of the executable was automatically taken from the name of the enclosing directory
~/helloworld$ ./helloworld-ERS7
Hello World!
sout says hi too!
~/helloworld$