A subscriber listens for messages on a given topic. If you only require a single message, you can check out Ros.waitForMessageAsync in the Ros singleton.

Simple example

First, let’s start with a simple example:

1Subscriber {
2  id: mySubscriber
3  topic: "/intval"

This creates a subscriber object that is now available and subscribed to /intval. Let’s assume the topic publishes an std_msgs/Int32 message.

The std_msgs/Int32 message is defined as follows:

int32 data

We can display the published value using a text field:

1Text {
2  text: "Published value was: " +

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 last received value.

Full example

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

1Subscriber {
2  id: mySubscriber
3  ns: "~" // Namespace
4  topic: "/intval"
5  throttleRate: 30 // Update rate of message property in Hz
6  queueSize: 10
7  running: true
8  onNewMessage: doStuff(message)

The namespace ns property enables you to set the namespace of the ros::NodeHandle that is created to subscribe to the given topic.

The queueSize property controls how many incoming messages are queued for processing before the oldest are dropped.

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 running property, the subscriber can be enabled and disabled. If the property is set to false, the subscriber is shut down until it is set to true again and subscribes to the topic again. For example, the state of a Subscriber can be toggled using a button:

 1Button {
 2  id: myButton
 3  state: "active"
 4  onClicked: {
 5    mySubscriber.running = !mySubscriber.running
 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  ]

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 usually the same, though.

Finally, there’s also the messageType property which holds the type of the last received message, e.g., std_msgs/Int32.


class Subscriber : public QObjectRos

Public Functions


The topic this subscriber subscribes to.

The maximum number of messages that are queued for processing. Default: 10 The namespace of the NodeHandle created for this subscriber. The last message that was received by this subscriber. The type of the last received message, e.g., geometry_msgs/Pose. Limits the frequency in which the notification for an updated message is emitted. Default: 20 Hz Controls whether or not the subscriber is currently running, i.e., able to receive messages. Default: true

unsigned int getNumPublishers()

The number of publishers this subscriber is connected to.


void topicChanged()

Emitted when the topic changed.

void queueSizeChanged()

Emitted when the queueSize changed.

void nsChanged()

Emitted when the namespace ns changed.

void throttleRateChanged()

Emitted when the throttle rate was changed.

void runningChanged()

Emitted if the running state of this subscriber changed.

void messageChanged()

Emitted whenever a new message was received.

void messageTypeChanged()

Emitted whenever the type of the last received message changed.

void newMessage(QVariant message)

Emitted whenever a new message was received.


message – The received message.