Python API

class lcm.Event(eventnum, timestamp, channel, data)

Data structure representing a single event in an LCM EventLog

channel

Channel on which message was received

data

Binary string containing raw message data

eventnum

Event number

timestamp

00 Jan 1, 1970 UTC marking the time at which the message was originally received

Type:

Microseconds since 00

Type:

00

class lcm.EventLog(path: str | PathLike, mode='r', overwrite=False)

EventLog is a class for reading and writing LCM log files in Python.

An EventLog opened for reading supports the iterator protocol, with each call to next() returning the next L{Event<lcm.Event>} in the log.

@undocumented: __iter__

close()

Closes the log file. After an EventLog is closed, it is essentially useless

@return: None

next()

@rtype: L{Event<lcm.Event>}

read_next_event()

@return: the next L{Event<lcm.Event>} in the log file. @rtype: L{Event<lcm.Event>}

seek(filepos)

Positions the internal file pointer at the next event that starts at or is after byte offset filepos.

@param filepos: byte offset from start of log

@return: None

seek_to_timestamp(timestamp)

Seek (approximately) to a particular timestamp.

@param eventlog The log file object @param ts Timestamp of the target event in the log file.

@return: None

size()

@return: the total size of the log file, in bytes @rtype: int

tell()

@return: the current position of the internal file pointer, in bytes @rtype: int

write_event(utime, channel, data)

Writes an event to the log file. Log file must be openeed in write mode.

@param utime: Microseconds since 00:00:00 Jan 1, 1970 UTC @param channel: Channel name corresponding to the event @param data: data bytes

@return: None

class lcm.LCM

The LCM class provides a connection to an LCM network.

usage:

m = LCM ([provider])

provider is a string specifying the LCM network to join. Since the Python LCM bindings are a wrapper around the C implementation, consult the C API documentation on how provider should be formatted. provider may be None or the empty string, in which case a default network is chosen.

To subscribe to a channel:

def msg_handler(channel, data):
   # message handling code here.  For example:
   print("received %d byte message on %s" % (len(data), channel))

m.subscribe(channel, msg_handler)

To transmit a raw binary string:

m.publish("CHANNEL_NAME", data)

In general, LCM is used with python modules compiled by lcm-gen, each of which provides the instance method encode() and the static method decode(). Thus, if one had a compiled type named example_t, the following message handler would decode the message:

def msg_handler(channel, data):
   msg = example_t.decode(data)

and the following usage would publish a message:

msg = example_t()
# ... set member variables of msg
m.publish("CHANNEL_NAME", msg.encode())

@undocumented: __new__, __getattribute__

fileno() → int

Returns a file descriptor suitable for use with select, poll, etc.

handle() → None

waits for and dispatches the next incoming message

handle_timeout(timeout_millis) → int

New in LCM 1.1.0

waits for and dispatches the next incoming message, with a timeout.

Raises ValueError if @p timeout_millis is invalid, or IOError if another error occurs.

@param timeout_millis: the amount of time to wait, in milliseconds. @return 0 if the function timed out, >1 if a message was handled.

publish(channel, data) → None

Publishes a message to an LCM network

@param channel: specifies the channel to which the message should be published. @param data: binary string containing the message to publish

subscribe(channel, callback) → L{LCMSubscription<lcm.LCMSubscription>}

Registers a callback function to handle messages received on the specified channel.

Multiple handlers can be registered for the same channel

@param channel: LCM channel to subscribe to. Can also be a GLib/PCRE regular expression. Implicitly treated as the regex “^channel$” @param callback: Message handler, must accept two arguments. When a message is received, callback is invoked with two arguments corresponding to the actual channel on which the message was received, and a binary string containing the raw message bytes.

unsubscribe(subscription_object) → None

Unregisters a message handler so that it will no longer be invoked when a message on the specified channel is received

@param subscription_object: An LCMSubscription object, as returned by a call to subscribe()

class lcm.LCMSubscription

The LCMSubscription class represents a single subscription of a message handler to an LCM channel.

This class should never be instantiated by the programmer.

@undocumented: __new__, __getattribute__, __init__

set_queue_capacity(num_messages) → None

Sets the maximum number of received but unhandled messages to queue for this subscription. If messages start arriving faster than they are handled, then they will be discarded after more than this number start piling up.

@param num_messages: Maximum number of messages to queue for this subscription. A number less than or equal to zero indicates no limit (very dangerous!).