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:

  1. Simulation:
  2. Remote Processing: (todo)
  3. Remote Framework: (todo)
  4. Tool Development:

Building:

See the installation, configuration, and compilation sections of the downloads page to get Tekkotsu up and running.

Execution

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.

Startup will end with a text display which should be very similar regardless of the platform being used. The platform setting largely affects the hardware abstraction layer, leaving the user code in the project is none the wiser.

PLATFORM_APERIOS PLATFORM_LOCAL 
[Power button pressed]
[...]
START UP BEHAVIOR...StartupBehavior()
  Loaded 10 colors.
*** PAUSED ***
Press the "back" button to leave battery \
display
BATTERY REPORT:
       Power Remain:   100%
       Capacity:       2200
       Voltage:        8.344
       Current:        0
       Temperature:    29.51
       Flags:  BatteryConnect
ExternalPower PowerGood 
SoundManager::LoadBuffer() of 8888 bytes
SoundManager::LoadBuffer() of 2042 bytes
SoundManager::LoadBuffer() of 2308 bytes
SoundManager::LoadBuffer() of 56586 bytes
SoundManager::LoadBuffer() of 10754 bytes
CONTROLLER-INIT...
Loading: /ms/data/motion/walk.prm
Pre-version 2.2 walk parameter file
DONE
Root Control:
**0> Mode Switch
  1> Background Behaviors
  2> TekkotsuMon
  3> Status Reports
  4> File Access
  5> Vision Pipeline
  6> Shutdown?
  7. Help
SoundManager::LoadBuffer() of 45954 bytes
START UP BEHAVIOR-DONE
 
Tekkotsu/project$ ./tekkotsu-ERS7
[...]
StartupBehavior()
  Loaded 10 colors.
*** PAUSED ***
Press the "back" button to leave battery \
display
BATTERY REPORT:
       Power Remain:   0%
       Capacity:       0
       Voltage:        0
       Current:        0
       Temperature:    0
       Flags:
       
SoundManager::LoadBuffer() of 8888 bytes
SoundManager::LoadBuffer() of 2042 bytes
SoundManager::LoadBuffer() of 2308 bytes
SoundManager::LoadBuffer() of 56586 bytes
SoundManager::LoadBuffer() of 10754 bytes
CONTROLLER-INIT...
Loading: [...]/project/ms/data/motion/walk.prm
Pre-version 2.2 walk parameter file
DONE
Root Control:
**0> Mode Switch
  1> Background Behaviors
  2> TekkotsuMon
  3> Status Reports
  4> File Access
  5> Vision Pipeline
  6> Shutdown?
  7. Help
SoundManager::LoadBuffer() of 45954 bytes
HAL:ERS-7>

The main difference between these two situations is that PLATFORM_APERIOS is a fixed hardware configuration, whereas PLATFORM_LOCAL ends with a command prompt to allow you interact with Tekkotsu's hardware abstraction layer (HAL).  Usually this prompt will be buried within the startup output due to process race conditions.  Just hit return to refresh the prompt.

You can type help to get a list of commands and their syntax.  Some commands, like set, can also give feedback on their arguments, e.g. help set Vision.Source would give more information on the Vision.Source 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 Source parameter.  Typing 'help set Vision.Source' should display a list of all available image sources. Similarly, 'help set Sensors.Source' 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.a, 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$