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.
1Subscriber {
2 id: mySubscriber
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 queueSize: 10
9 enabled: true // Can be used to pause/unpause the subscription
10 onNewMessage: doStuff(message)
11}
The queueSize
property controls how many incoming messages are queued for
processing before the oldest are dropped.
Note that due to the throttleRate
messages may be dropped even if the queueSize
is large enough.
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()¶
- 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.
- 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. Default: 20 Hz.
- 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.
-
unsigned int getPublisherCount()¶