Using RobCoGen

For the impatient

unzip robcogen-0.5.2.zip
cd robcogen-0.5.2/exe/
./robcogen.sh ../sample/fancy/model/fancy.kindsl    # launches the program
# you may now input 1, 4, and 28 to exit
ls -l /tmp/gen/cpp/                                 # check the generated C++

Requirements

RobCoGen is a Java program shipped with the required libraries.

To actually run RobCoGen one needs:

A Java Runtime Environment (jre)
The symbolic computation engine Maxima

Nowadays, a jre is likely to be already installed in any machine. Maxima is available for a variety of platforms. In Linux distributions such as Ubuntu, both can be installed with the package manager.

So far, RobCoGen has been tested only in Ubuntu Linux, although it should be possible to use it on any platform supported by Java and Maxima.

Execution

RobCoGen is a command line program:

cd exe/
./robcogen.sh <robot description file> [<desired transforms file>]

Arguments:

<robot description file> : path of the .kindsl file that models your robot; mandatory. See here.
<desired transforms file> : path of the .dtdsl file with a list of desired coordinate transforms and geometric Jacobians; optional.

The folder sample/fancy/model of the RobCoGen distribution contains a sample of both arguments.

When the second argument is provided, the matrices it references will be generated along with the rest of the code. Otherwise, no Jacobians are generated; some coordinate transforms are generated in any case as they are required by the dynamics algorithms.

Frontend

RobCoGen has a simple textual interface, prompting the user for an integer input. Enter a code from the displayed list, to trigger the corresponding generator (the identifier in capital letters is just a short mnemonic name for the code).

The list of available generation targets

0 - CTDSL
The coordinate transforms description file (.ctdsl - a document of the Transforms-DSL)
This file contains an abstract description of all the transforms associated with a given robot. It is not required to generate other things, but this function is provided for debug and for the interested user.
1 - ALLMx
All the Maxima code. Note: Maxima code must be generated before generating any other implementation of transforms or Jacobians
2 - TMx
Maxima code for coordinate transforms
3 - JMx
Maxima code for geometric Jacobians
4 - ALLC++
All the C++ code. The C++ code is very fast, efficient and compatible with hard real-time constraints. For example, the inverse dynamics code can be safely used in the real-time loop executing the control of the actuators.
5 - CC++
C++ common code (required to compile the rest)
6 - TC++
C++ coordinate Transform
7 - JC++
C++ geometric Jacobians
8 - DC++
C++ common code for dynamics (required to compile the other files related to dynamics)
9 - IDC++
C++ Inverse-Dynamics implementation (Newton-Euler algorithm). It supports floating base robots. In this case the interface of the class will be different than for a fixed base robot. Also note that the basic formulation of inverse dynamics for a floating base robot is actually a hybrid dynamics algorithm, where the spatial acceleration of the base is an output value.
10 - FDC++
C++ Forward-Dynamics implementation (articulated-body algorithm). It supports the floating base case.
11 - JSIMC++
C++ Joint-Space-Inertia-Matrix calculation (composite-rigid-body algorithm). This code includes the L^T L factorization to efficiently compute the inverse. It supports the floating base case (though the computation of the inverse still only applies to the actuated-joints-space block).
12 - MKC++
CMake file to build the generated C++ code
13 - ALLMt
All the Matlab code
14 - TMt
Matlab coordinate transforms
15 - JMt
Matlab geometric Jacobians
16 - DMt
Matlab common code for dynamics. This is basically just a file with the inertia properties of the links, expressed in different reference frames.
17 - IDMt
Matlab Inverse-Dynamics implementation
18 - JSIMMt
Matlab algorithm for the Joint-Space-Inertia-Matrix
19 -
20 -
21 -
22 - RB
Other formats for the description of a kinematic tree
23 - RB_ROS
an equivalent XML URDF robot description file, as described in the ROS documentation
24 - RB_Feath
an equivalent robot model in Matlab format, as required by the rigid-body dynamics software for Matlab available on Roy Featherstone's web page
25 - RB_SDFAST
equivalent SD/FAST model description
26 - Test
Helper C++ code to use the Octave tests for the generated C++
27 - Reload
Reload the input files
28 - Quit

Configuration

There are three configuration files alongside the script to launch the program:

core.cfg for core configuration
cpp.cfg to tune the generated C++
log4j.cfg to configure logging

(formerly, these files were respectively framework.properties, cpp.properties and log4j.properties)

Default values should work. In the following paragraphs I describe the few options one might want to change. Customize the rest if you know what you are doing. Some documentation is included in the configuration files themselves.

Output paths

See properties generator.outdir... in the main configuration file.

The .base sub-property selects the root folder in the filesystem where to place the generated code.

Since version 0.5.1, the other sub-properties .<lang> are treated as subfolders of the base. Also, setting .robotsubdir to true will result in an additional subfolder named as the robot model; in this case the final path will be in the form <base>/<robot>/<lang>.

Constant folding

Since version 0.5.0.

Property generator.misc.constantfolding in the main configuration file. Defaults to false.

Constant folding means that the robot model constants will appear in the generated code as float literals, possibly multiple times, in different locations. When set to false, symbolic identifiers will be used instead; the details on how these identifiers are associated with the actual value depends on the target language.

Constants in the form of PI expressions (like PI, PI/2.0, etc.) are always folded through. If you do not want this to happen, please use a float literal instead (like 3.14159).

Testing

There are no specific tests for the code generator itself, but there are functions to test the generated code, both C++ and Octave.

The tests themselves are written in Octave, and perform simple numerical comparisons with another, reference implementation of dynamics algorithms.

For more information, please refer to the readme of the repository of the test functions.

The tests are also included in the binary distribution of RobCoGen, in the folder etc/octave-tests.

Starting from version 0.5.1, RobCoGen generates some C++ programs and scripts to help testing the generated C++. See option 26 of the user interface.

Using RobCoGen

Requirements
Execution
- Frontend
Configuration
- Output paths
- Constant folding
Testing