LCM-gen Tutorial

Defining a data type - example_t

When exchanging messages between two applications, you may have many different types of data. LCM allows you to define these types as language-independent data structures. You can have multiple fields, each with its own type and name. Some of these fields may be structs themselves, or arrays. LCM supports multiple languages and, types are defined in a language-neutral specification that looks very similar to C.

Let’s define an example type called example_t. Create a file called example_t.lcm with the following contents.

package exlcm;

struct example_t
{
    int64_t  timestamp;
    double   position[3];
    double   orientation[4]; 
    int32_t  num_ranges;
    int16_t  ranges[num_ranges];
    string   name;
    boolean  enabled;
}

The file is fairly straightforward, and consists of two parts: a package name, and a structure definition. The package defines a namespace for the data strucure, and gets mapped to the appropriate language construct (e.g., namespace in C++, package in Java and Python, etc.).

The structure definition is a list of data fields, each with a name and a type. A number of primitive types are available for use, some of which are shown above. The LCM type specification has a complete listing of primitive types.

The lcm-gen tool, distributed with LCM, converts message type definitions into code for supported programming languages, and maps message types into language-specific data structures or classes. Each data field is in turn mapped into a native data structure. In C, for example, boolean corresponds to the C type int8_t and string corresponds to a NULL-terminated char *. Note that unsigned types are not defined, since there is no equivalent in Java.

Additionally, you can define fixed-size or variable-length arrays. In this example, position is a double array of length 3, and ranges is a variable-length int16_t array. The length of ranges is specified by the num_ranges field.

Although not shown in this example, you can build up more complex types by referring to any other LCM types in the definition of your struct. The examples/ directory in the LCM source distribution contains more example type definitions. This feature, and others are all described in more detail in the LCM type specification.

Generating language-specific bindings

Run lcm-gen with the arguments listed in a row from the following table to generate bindings for the programming language of your choice.

Language	lcm-gen usage
C	lcm-gen -c example_t.lcm
C++	lcm-gen -x example_t.lcm
Java	lcm-gen -j example_t.lcm
Lua	lcm-gen -l example_t.lcm
Python	lcm-gen -p example_t.lcm
C#	lcm-gen –csharp example_t.lcm
MATLAB	Generate Java code
Go	lcm-gen -g example_t.lcm

You can pass additional arguments to lcm-gen to adjust its behavior for each programming language. Run lcm-gen -h to get a full list of its available options.