Skip to content

Commit f785c86

Browse files
scpetersscpeters
authored
Add tutorial for gz topic tool (#137)
How to use --list, --info, --echo, --hz, --bw, and --pub. Signed-off-by: Steve Peters <[email protected]>
1 parent b5e3816 commit f785c86

File tree

2 files changed

+260
-0
lines changed

2 files changed

+260
-0
lines changed

‎gz_topic/tutorial.md

+254
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# Overview
2+
3+
Gazebo provides the `gz` command-line interface which allows introspection
4+
and interaction with a running simulation.
5+
This tutorial describes the functionality of the `gz topic` tool which
6+
focuses on topics published using the `gazebo-transport` interface.
7+
To interact with topics published using `ignition-transport`,
8+
please see the [documentation for `ign topic`](https://github.com/ignitionrobotics/ign-transport/blob/ign-transport9/tutorials/10_logging.md#running-the-examples).
9+
10+
# `gz topic --list`
11+
12+
To list the topics currently being published in a gazebo simulation,
13+
use the `--list` or `-l` parameter.
14+
15+
With a `gzserver` running in one terminal (with the empty.world by default),
16+
run the following in another terminal:
17+
18+
~~~
19+
gz topic --list
20+
~~~
21+
22+
which produces the following output:
23+
24+
~~~
25+
/gazebo/default/atmosphere
26+
/gazebo/default/diagnostics
27+
/gazebo/default/factory
28+
/gazebo/default/factory/light
29+
/gazebo/default/gui
30+
/gazebo/default/joint
31+
/gazebo/default/light/modify
32+
/gazebo/default/log/control
33+
/gazebo/default/log/status
34+
/gazebo/default/model/info
35+
/gazebo/default/model/modify
36+
/gazebo/default/physics
37+
/gazebo/default/physics/contacts
38+
/gazebo/default/playback_control
39+
/gazebo/default/pose/info
40+
/gazebo/default/pose/local/info
41+
/gazebo/default/pose/modify
42+
/gazebo/default/request
43+
/gazebo/default/response
44+
/gazebo/default/undo_redo
45+
/gazebo/default/user_cmd
46+
/gazebo/default/user_cmd_stats
47+
/gazebo/default/visual
48+
/gazebo/default/wind
49+
/gazebo/default/world_control
50+
/gazebo/default/world_stats
51+
/gazebo/server/control
52+
/gazebo/world/modify
53+
~~~
54+
55+
# `gz topic --info`
56+
57+
To get more information about a particular gazebo-transport topic, use the
58+
`--info` or `-i` parameter.
59+
60+
~~~
61+
gz topic -i /gazebo/default/world_stats
62+
~~~
63+
64+
which prints the type of message published on the topic and information
65+
about publishers and subscribers of that topic.
66+
67+
~~~
68+
Type: gazebo.msgs.WorldStatistics
69+
70+
Publishers:
71+
192.168.0.197:38057
72+
73+
Subscribers:
74+
75+
~~~
76+
77+
# `gz topic --echo`
78+
79+
To view the contents of messages published on a particular gazebo-transport
80+
topic, use the `--echo` or `-e` parameter. To echo messages for a finite
81+
duration of time, use the `--duration` or `-d` parameter as well.
82+
83+
~~~
84+
gz topic --echo /gazebo/default/world_stats --duration 1
85+
~~~
86+
87+
~~~
88+
sim_time {
89+
sec: 656
90+
nsec: 31000000
91+
}
92+
pause_time {
93+
sec: 0
94+
nsec: 0
95+
}
96+
real_time {
97+
sec: 657
98+
nsec: 883386244
99+
}
100+
paused: false
101+
iterations: 656031
102+
103+
sim_time {
104+
sec: 656
105+
nsec: 230000000
106+
}
107+
pause_time {
108+
sec: 0
109+
nsec: 0
110+
}
111+
real_time {
112+
sec: 658
113+
nsec: 83766729
114+
}
115+
paused: false
116+
iterations: 656230
117+
~~~
118+
119+
# `gz topic --hz` and `gz topic --bw`
120+
121+
The `--echo` command can be quite verbose. If you want to see only the
122+
frequency with which messages are published on a topic, use the `--hz`
123+
or `-z` parameter. If you want to see the bandwidth used by the topic,
124+
use `--bw` or `-b`.
125+
126+
~~~
127+
gz topic --hz /gazebo/default/world_stats
128+
~~~
129+
130+
~~~
131+
Hz: 4.98
132+
Hz: 4.96
133+
Hz: 5.01
134+
Hz: 4.99
135+
Hz: 5.00
136+
Hz: 4.98
137+
Hz: 4.98
138+
Hz: 4.99
139+
~~~
140+
141+
~~~
142+
gz topic --bw /gazebo/default/world_stats
143+
~~~
144+
145+
~~~
146+
Total[182.85 B/s] Mean[33.36 B] Min[33 B] Max[34 B] Messages[11]
147+
Total[185.19 B/s] Mean[33.40 B] Min[33 B] Max[34 B] Messages[10]
148+
Total[185.08 B/s] Mean[33.40 B] Min[33 B] Max[34 B] Messages[10]
149+
Total[185.16 B/s] Mean[33.40 B] Min[33 B] Max[34 B] Messages[10]
150+
Total[185.02 B/s] Mean[33.40 B] Min[33 B] Max[34 B] Messages[10]
151+
~~~
152+
153+
# `gz topic --pub`
154+
155+
Added in `gazebo10` by [Bitbucket pull request 2951](https://osrf-migration.github.io/gazebo-gh-pages/#!/osrf/gazebo/pull-requests/2951/page/1),
156+
a message can be published from the command-line by using the `--pub`
157+
or `-p` parameter. This command requires encoding the message as a string
158+
argument to the `--msg` or `-m` parameter. An easy way to see the syntax
159+
for these messages is to use `gz topic --echo` to display a message of
160+
similar type. In general, fields with numeric or string values are placed
161+
on their own line of a multi-line string with as `name: value`, while
162+
container messages use curly braces `{}`. Recall the content of a
163+
[WorldStatics](http://osrf-distributions.s3.amazonaws.com/gazebo/msg-api/9.0.0/world__stats_8proto.html)
164+
message from the example for `gz topic --echo`:
165+
166+
~~~
167+
sim_time {
168+
sec: 656
169+
nsec: 31000000
170+
}
171+
pause_time {
172+
sec: 0
173+
nsec: 0
174+
}
175+
real_time {
176+
sec: 657
177+
nsec: 883386244
178+
}
179+
paused: false
180+
iterations: 656031
181+
~~~
182+
183+
The message type is automatically inferred from the topic, so a publisher
184+
or subscriber for that topic must already exist in order to use this command.
185+
186+
Example of using this command are given in the following subsections.
187+
188+
## Pause and unpause
189+
190+
As a simple example, we can replicate the functionality of `gz world --pause`
191+
by publishing to the `~/world_control` topic:
192+
193+
In terminal A: open `gz stats` to see whether the simulation is running
194+
or paused.
195+
196+
In terminal B: use `gz topic --echo /gazebo/default/world_control` to
197+
watch for published messages.
198+
199+
In terminal C: use `gz world --pause 1` to pause the simulation and confirm
200+
that `gz stats` pauses in terminal A. This should show the following in
201+
terminal B:
202+
203+
~~~
204+
pause: true
205+
~~~
206+
207+
In terminal D: use `gz topic --pub` to unpause the simulation by publishing
208+
the opposite message to `/gazebo/default/world_control`.
209+
210+
~~~
211+
gz topic --pub /gazebo/default/world_control --msg 'pause: false'
212+
~~~
213+
214+
## Spawn a model with orientation specified by a quaternion
215+
216+
~~~
217+
gz topic -p /gazebo/default/factory \
218+
-m 'sdf_filename: "model://double_pendulum_with_base"
219+
pose {
220+
position {
221+
x: 1.23
222+
y: 2.34
223+
z: 3.45
224+
}
225+
orientation {
226+
x: 0.5
227+
y: 0.5
228+
z: 0.5
229+
w: 0.5
230+
}
231+
}'
232+
~~~
233+
234+
## Change the gzclient user camera pose
235+
236+
~~~
237+
gz topic -p /gazebo/default/gui \
238+
-m 'camera {
239+
name: "this_is_required_but_not_parsed"
240+
pose {
241+
position {
242+
x: 1.23
243+
y: 2.34
244+
z: 3.45
245+
}
246+
orientation {
247+
x: 0.5
248+
y: 0.5
249+
z: 0.5
250+
w: 0.5
251+
}
252+
}
253+
}'
254+
~~~

‎manifest.xml

+6
Original file line numberDiff line numberDiff line change
@@ -348,6 +348,12 @@
348348
<skill>beginner</skill>
349349
</tutorial>
350350

351+
<tutorial title="Topics on the commandline with gz topic" ref='gz_topic'>
352+
<markdown version="10+">topics_subscribe/tutorial.md</markdown>
353+
<description>How to introspect and publish on gazebo-transport topics from the command-line.</description>
354+
<skill>beginner</skill>
355+
</tutorial>
356+
351357
<tutorial title="Custom messages" ref='custom_messages'>
352358
<markdown version="1.9-7">custom_messages/tutorial.md</markdown>
353359
<markdown version="8+">custom_messages/tutorial-8.0.md</markdown>

0 commit comments

Comments
 (0)