Java Tutorial
Sending and receiving LCM messages with Java
Introduction
This tutorial will show you how to use all of the core functionality of LCM, and is intended for those who have a working knowledge of Java. For detailed information about LCM, please see the Java API reference.
The topics covered in this tutorial are:
Initialize LCM in your application.
Publish a message.
Subscribe to and receive a message.
This tutorial uses the example_t message type defined in the
type definition tutorial, and assumes that you have
generated the Java bindings for the example type by running
lcm-gen -j example_t.lcm
After running this command, you should have one file, exlcm/example_t.java. This file is the Java binding for the example message type. If you have the time, take a moment to open up the file and inspect the generated code.
You can then compile this into a .class file, and then create a .jar
archive. Assuming that lcm.jar is in the current directory (see the Java notes page), you
could then run (also from a command shell):
javac -cp lcm.jar exlcm/*.java
jar cf my_types.jar exlcm/*.class
You should then have a file my_types.jar, which is a Java archive containing
the Java bindings for the example message. In order to use LCM types, you must
include the jar file on your classpath.
Initializing LCM
You will need to make sure that lcm.jar is in your classpath, and your Java classes will need to include “import lcm.lcm.*”.
To initialize LCM, with default options, simply call:
LCM myLCM = LCM.getSingleton();
The default options are suitable for communicating with other LCM applications on the local computer. For communication across computers, or other usages such as reading data from an LCM logfile (e.g., to post-process or analyze previously collected data), see the Java API reference.
Publishing a message
We can instantiate and then publish some sample data as follows:
import java.io.*;
import lcm.lcm.*;
public class SendMessage
{
public static void main(String args[])
{
try {
LCM lcm = LCM.getSingleton();
exlcm.example_t msg = new exlcm.example_t();
msg.timestamp = System.nanoTime();
msg.position = new double[] { 1, 2, 3 };
msg.orientation = new double[] { 1, 0, 0, 0 };
msg.ranges = new short[] {
0, 1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
};
msg.num_ranges = msg.ranges.length;
msg.name = "example string";
msg.enabled = true;
lcm.publish("EXAMPLE", msg);
} catch (IOException ex) {
System.out.println("Exception: " + ex);
}
}
}
After initializing LCM, this application creates an instance of the example message, fills in some message fields, and then publishes the message.
The call to lcm.publish() serializes the data into a byte stream and
transmits the packet using LCM to any interested receivers. The string
”EXAMPLE” is the channel name, which is a string
transmitted with each packet that identifies the contents to receivers.
Receivers subscribe to different channels using this identifier, allowing
uninteresting data to be discarded quickly and efficiently.
Subscribing to messages
In order to receive messages, you must implement an LCMSubscriber and pass it to LCM.subscribe(). The subscriber will be provided with a LCMDataInputStream that can be read for the message contents. All LCM data types include a constructor that takes a DataInput (including instances of LCMDataInputStream) as an argument. First, let’s look at the subscriber:
public class MySubscriber implements LCMSubscriber
{
public void messageReceived(LCM lcm, String channel, LCMDataInputStream ins)
{
System.out.println("Received message on channel " + channel);
example_t msg;
try {
msg = new example_t(ins);
} catch (IOException ex) {
System.out.println("Error decoding message: " + ex);
return;
}
System.out.println(" timestamp = " + msg.timestamp);
// Could do something else with the message here.
}
}
Next, we can subscribe to the message with:
lcm.subscriber("EXAMPLE", new MySubscriber());
The LCM instance has a background thread that constantly listens for messages. When a message on channel ”EXAMPLE” arrives, the LCM thread will invoke the messageReceived() method.
Putting it all together
Here’s an example of a complete subscriber application:
import java.io.*;
import lcm.lcm.*;
import exlcm.*;
public class MySubscriber implements LCMSubscriber
{
LCM lcm;
public MySubscriber()
throws IOException
{
this.lcm = new LCM();
this.lcm.subscribe("EXAMPLE", this);
}
public void messageReceived(LCM lcm, String channel, LCMDataInputStream ins)
{
System.out.println("Received message on channel " + channel);
try {
if (channel.equals("EXAMPLE")) {
example_t msg = new example_t(ins);
System.out.println(" timestamp = " + msg.timestamp);
System.out.println(" position = [ " + msg.position[0] +
", " + msg.position[1] + ", " + msg.position[2] + " ]");
System.out.println(" orientation = [ " + msg.orientation[0] +
", " + msg.orientation[1] +
", " + msg.orientation[2] +
", " + msg.orientation[3] + " ]");
System.out.print(" ranges = [ ");
for (int i=0; i<msg.num_ranges; i++) {
System.out.print("" + msg.ranges[i]);
if (i < msg.num_ranges-1)
System.out.print (", ");
}
System.out.println (" ]");
System.out.println(" name = '" + msg.name + "'");
System.out.println(" enabled = '" + msg.enabled + "'");
}
} catch (IOException ex) {
System.out.println("Exception: " + ex);
}
}
public static void main(String args[])
{
try {
MySubscriber m = new MySubscriber();
while(true) {
Thread.sleep(1000);
}
} catch (IOException ex) {
System.out.println("Exception: " + ex);
} catch (InterruptedException ex) { }
}
}
The full example is included in the LCM source distribution, in the examples/java directory.
Compiling and running
To compile and run the examples, let’s assume that the lcm.jar file is in the
current directory, along with SendMessage.java,
MySubscriber.java, and example_t.lcm. We can run our programs by
executing the commands:
# 1. Create the Java implementation of temperature_t.lcm
lcm-gen -j example_t.lcm
# 2. Compile the demo applications and the LCM type created above.
javac -cp .:lcm.jar *.java exlcm/*.java
# 3. Run MySubscriber (in one terminal)
java -cp .:lcm.jar MySubscriber
# 4. Run SendMessage (in another terminal)
java -cp .:lcm.jar SendMessage
Additional notes
See the Java notes page for some additional information related to LCM development with Java.