# 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, 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!).