LCM

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.