Subscription

A subscription listens for messages on a given topic.

Simple example

First, let’s start with a simple example:

1Subscription {
2  id: mySubscription
3  topic: "/intval"
4}

This creates a subscription on the topic /intval. The message type will be determined when the subscription is established. Let’s assume the topic publishes an example_interfaces/msg/Int32 message.

The example_interfaces/msg/Int32 message is defined as follows:

int32 data

We can display the published value using a text field:

1Text {
2  text: "Published value was: " + mySubscription.message.data
3}

Whenever a new message is received on /intval the message property is updated and the change is propagated to the text field. Thus, the text field will always display the latest received value.

Full example

In most cases, the above Subscription is sufficient. However, the Subscription has more properties to give you more fine-grained control.

 1Subscription {
 2  id: mySubscription
 3  topic: "/intval"
 4  // Using messageType sets the type explicitly, will not connect to a
 5  //  publisher if the type does not match
 6  messageType: "example_interfaces/msg/Int32"
 7  throttleRate: 30 // Update rate of message property in Hz. Default: 20
 8  // QoS settings, defaults to best_effort, durability_volatile and history depth of 1
 9  qos: Ros2.QoS().reliable().transient_local().keep_last(10)
10  enabled: true // Can be used to pause/unpause the subscription
11  onNewMessage: doStuff(message)
12}

Note that due to the throttleRate, messages may be dropped even if the qos is changed to keep more than 1. To avoid this, if you want to process all received messages up to the keep_last history depth, set the throttleRate to 0.

The throttleRate limits the rate in which QML receives updates from the given topic. By default the Subscriber polls with 20 Hz on the UI thread and will notify of property changes with at most this rate. This is to reduce load and prevent race conditions that could otherwise update the message while QML is using it since the subscriber is receiving messages in a background thread by default.

Using the enabled property, the subscription can be enabled and disabled. If the property is set to false, the subscription is shut down until it is set to true again and subscribes to the topic again. For example, the state of a Subscription can be toggled using a button:

 1Button {
 2  id: myButton
 3  state: "active"
 4  onClicked: {
 5    mySubscription.enabled = !mySubscription.enabled
 6    state = state == "active" ? "paused" : "active"
 7  }
 8  states: [
 9    State {
10      name: "active"
11      PropertyChanges {
12        target: myButton
13        text: "Unsubscribe"
14      }
15    },
16    State {
17      name: "paused"
18      PropertyChanges {
19        target: myButton
20        text: "Subscribe"
21      }
22    }
23  ]
24}

Whenever a new message is received, the newMessage signal is emitted and the message is passed and can be accessed as message which technically refers to the received message and not the message property of the Subscriber. Untechnically, they are the same, though.

Finally, there’s also the messageType property which holds the type of the received message, e.g., example_interfaces/msg/Int32. If it isn’t set, the type is determined from the first available publisher, otherwise, the subscription will only connect to publishers with the correct message type.

API

class Subscription : public QObjectRos2

Public Functions

unsigned int getPublisherCount() const
Returns:

The number of publishers this subscriber is connected to.

Signals

void newMessage(QVariant message)

Emitted whenever a new message was received.

Parameters:

message – The received message.

Properties

QString topic

The topic this subscriber subscribes to.

quint32 queueSize

The maximum number of messages that are queued for processing. Default: 10.

qml_ros2_plugin::QoSWrapper qos

The QoS settings for this subscription. Use Ros2.QoS() to create QoS settings.

QVariant message

The last message that was received by this subscriber.

QString messageType

Set to a specific type to subscribe to that type, e.g., geometry_msgs/msg/Pose, otherwise the type is automatically detected and if the topic has multiple available types, one is arbitrarily selected.

int throttleRate

Limits the frequency in which the notification for an updated message is emitted. Set to 0 to disable throttling and receive all messages. Default: 20Hz

bool enabled

Controls whether or not the subscriber is currently enabled, i.e., able to receive messages. Default: true.

bool subscribed

Indicates whether a subscription is active or not.