6.2 ROS Subscriber Factory

ros_subscriber_factory is used to create a subscriber handle. The constraints on the message type from publishers also apply to subscribers, but the read method returns a struct corresponding to the message type, blocking until one is available.

Subscriber must have compatible Quality of Service (QoS) parameters.

6.1.1. Command

ros_subscriber_factory(topic, type, history="default", depth=1, reliability="default", durability="default", deadline=0, lifespan=0, liveliness="default", lease_duration=0)

6.1.2. Parameters

(deafult parameters will fall back on the ROS backends defaults)

  1. topic : The name of the topic.

  2. type : The type of the messages on the topic. A dynamic library corresponding to the type must be present on the robot, e.g libstd_msgs__rosidl_typesupport_introspection_c.so for std_msgs/String.

  3. history : How many messages to store in the history. Options are “default”, “keep_last” and “keep_all”.

  4. depth : The size of the queue of old messages. It requires history to be “keep_last” to take effect.

  5. reliability : How reliable the topic should be. Options are “default”, “reliable”, and “best_effort”.

  6. durability : Options are “default”, “transient_local”, and “volatile”.

  7. deadline: A contract for how much time is allowed between messages.

  8. lifespan : The amount of time a message will be considered valid. 0 will mean lifespan is disabled.

  9. liveliness : Specifies for how long the subscriber is considered alive. Options are “default”, “automatic”, and “manual”.

  10. lease_duration: The period of time a subscriber has to indicate that it is alive before it is considered to have lost liveliness.

6.1.3. Methods on Handle

  1. read() : Returns the last published message on the topic. It will block until one is available.

  2. read_history() : Returns the saved published message on the topic. It has one parameter which the number of items to be returned.

Warning

Do not overload the read_history with a large number since this will give you a runtime too much behind exception.

  1. wait(timeout) : Returns a boolean indicating when a message is available on the topic. It will block for at most “timeout” seconds.

  2. close() : Indicates that the subscriber is done, and releases memory. The method should be used to actively close handles created in the local scope.

6.1.4. Example Command

ros_subscriber_factory("test", "std_msgs/String")

In the above example, it subscribes from the topic “test” with a message type from ROS2 standard messages (std_msgs) with the specific type String.

In order to use a message type, the corresponding dynamic library (in this case libstd_msgs__rosidl_typesupport_introspection_c.so) must be present on the robot, where it will be dynamically loaded when needed.

The std_msgs/String message type must have a single member named data of the type string.

Example:

reply = handle.read()
textmsg(reply.data)

6.1.5. Limitations

Please notice, that the subscriber can completely release the resources only when the program stops, or close is called on the object. Keep the number of subscribers as minimum as possible to avoid potential out-of-memory issues.