From be357376c97dd463e100ca05af88ccb94bcb3e07 Mon Sep 17 00:00:00 2001 From: Jan Gutsche <34797331+jaagut@users.noreply.github.com> Date: Tue, 3 Oct 2023 17:28:11 +0200 Subject: [PATCH] Update readme (#82) * Readme: add overview of components Signed-off-by: Jan Gutsche * Readme: Update wiki.ros.org URL to https Signed-off-by: Jan Gutsche * Readme: specify shell language for commands Signed-off-by: Jan Gutsche * Readme: Consistent punctuation Signed-off-by: Jan Gutsche * Readme: Update parameter description Signed-off-by: Jan Gutsche * Readme: Clearify mux initial_topic param Signed-off-by: Jan Gutsche --------- Signed-off-by: Jan Gutsche Co-authored-by: Jan Gutsche (cherry picked from commit f73df4aed3e6c472b378f644e7cee9ba8f7d0048) --- README.md | 75 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 46 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 47f5421..15321c8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # topic_tools -This package is the ROS 2 port of http://wiki.ros.org/topic_tools +This package is the ROS 2 port of https://wiki.ros.org/topic_tools Tools for directing, throttling, selecting, and otherwise manipulating ROS 2 topics at a meta-level. These tools do not generally perform serialization on the streams being manipulated, instead acting on generic binary data using `rclcpp`'s `GenericPublisher` and `GenericSubscription`. @@ -8,13 +8,21 @@ The tools in this package are provided as composable ROS 2 component nodes, so t ## Components +- [Relay](#relay): Subscribes to a topic and republishes to another. +- [RelayField](#relayfield): Republishes data in a different message type. +- [Transform](#transform): Manipulates a topic or a field and outputs data on another topic. +- [Throttle](#throttle): Republishes data with bandwidth or rate limit. +- [Drop](#drop): Republishes by dropping X out of every Y incoming messages. +- [Mux](#mux): Multiplexes incoming topics to an output. +- [Delay](#delay): Delays and republishes incoming data. + ### Relay Relay is ROS 2 node that subscribes to a topic and republishes all incoming data to another topic. It can work with any message type. #### Usage -``` +```shell ros2 run topic_tools relay [outtopic] ``` @@ -24,7 +32,7 @@ Subscribe to `intopic` and republish to either E.g. rename `base_scan` to `my_base_scan`: -``` +```shell ros2 run topic_tools relay base_scan my_base_scan ``` @@ -39,11 +47,11 @@ ros2 run topic_tools relay base_scan my_base_scan ### RelayField -RelayField is a ROS 2 node that allows to republish data in a different message type +RelayField is a ROS 2 node that allows to republish data in a different message type. #### Usage -``` +```shell ros2 run topic_tools relay_field [] ``` @@ -51,17 +59,17 @@ Subscribe to `input topic` and republish one or many of its fields onto another E.g. publish the contents of the `data` field in a `std_msgs/msg/String` onto the `frame_id` field of a `std_msgs/msg/Header`: -``` +```shell ros2 run topic_tools relay_field /chatter /header std_msgs/Header "{stamp: {sec: 0, nanosec: 0}, frame_id: m.data}" ``` ### Transform -Transform is a ROS 2 node that allows to take a topic or one of it fields and output it on another topic +Transform is a ROS 2 node that allows to take a topic or one of it fields and output it on another topic. #### Usage -``` +```shell ros2 run topic_tools transform [] [--import ] [--field ] ``` @@ -70,7 +78,7 @@ Subscribe to `input topic` and convert topic content or its field into E.g. transform `imu` orientation to `norm`: -``` +```shell ros2 run topic_tools transform /imu --field orientation /norm std_msgs/Float64 'std_msgs.msg.Float64(data=numpy.sqrt(numpy.sum(numpy.array([m.x, m.y, m.z, m.w]))))' --import std_msgs numpy ``` @@ -82,35 +90,36 @@ Throttle is ROS 2 node that subscribes to a topic and republishes incoming data #### throttle message (rate) -``` +```shell ros2 run topic_tools throttle messages [outtopic] ``` Throttle messages on `intopic` to a particular rate. - `intopic`: Incoming topic to subscribe to -- `msgs_per_sec`: maximum messages per second to let through. +- `msgs_per_sec`: Maximum messages per second to let through. - `outtopic`: Outgoing topic to publish on (default: intopic_throttle) E.g. throttle bandwidth-hogging laser scans (base_scan) to 1Hz: -``` +```shell ros2 run topic_tools throttle messages base_scan 1.0 ``` #### throttle bytes (bandwidth) -``` +```shell ros2 run topic_tools throttle bytes [outtopic] ``` Throttle messages on `intopic` to a particular rate. - `intopic`: Incoming topic to subscribe to -- `msgs_per_sec`: maximum messages per second to let through. +- `bytes_per_sec`: Maximum bytes of messages per second to let through. +- `window`: Time window in seconds to consider - `outtopic`: Outgoing topic to publish on (default: intopic_throttle) E.g. throttle bandwidth-hogging laser scans (base_scan) to 1KBps: -``` +```shell ros2 run topic_tools throttle bytes base_scan 1024 1.0 ``` @@ -124,6 +133,14 @@ ros2 run topic_tools throttle bytes base_scan 1024 1.0 - If True, only subscribe to `input_topic` if there is at least one subscriber on the `output_topic` - `use_wall_clock` (bool, default=False) - If True, then perform all rate measurements against wall clock time, regardless of whether simulation / log time is in effect. +- `throttle_type` (string, either `messages` or `bytes`) + - Method how to throttle +- `msgs_per_sec` (double) + - Maximum messages per second to let through. +- `bytes_per_sec` (integer) + - Maximum bytes of messages per second to let through. +- `window` (double) + - Time window in seconds to consider ### Drop @@ -132,7 +149,7 @@ It's mainly useful for limiting bandwidth usage, e.g., over a wireless link. It #### Usage -``` +```shell ros2 run topic_tools drop [outtopic] ``` @@ -143,7 +160,7 @@ Subscribe to and drop every out of messages. E.g. drop every other message published to base_scan: -``` +```shell ros2 run topic_tools drop base_scan 1 2 ``` @@ -155,8 +172,8 @@ ros2 run topic_tools drop base_scan 1 2 - the same as if provided as a command line argument - `lazy` (bool, default=False) - If True, only subscribe to `input_topic` if there is at least one subscriber on the `output_topic` -- `X`, `Y` (int) - - drop X out of every Y incoming messages +- `X` (int), `Y` (int) + - Drop X out of every Y incoming messages ### Mux @@ -166,7 +183,7 @@ and to add and delete input topics. At startup, the first input topic on the com #### Usage -``` +```shell ros2 run topic_tools mux [intopic2...] ``` @@ -176,7 +193,7 @@ Subscribe to ...N and publish currently selected topic to outopic. mux E.g. mux two command streams (auto_cmdvel and joystick_cmdvel) into one (sel_cmdvel): -``` +```shell ros2 run topic_tools mux sel_cmdvel auto_cmdvel joystick_cmdvel ``` @@ -188,8 +205,8 @@ ros2 run topic_tools mux sel_cmdvel auto_cmdvel joystick_cmdvel - the same as if provided as a command line argument - `lazy` (bool, default=False) - If True, only subscribe to `input_topic` if there is at least one subscriber on the `output_topic` -- `initial_topic` (str) - - Input topic to select on startup. If __none, start with no input topic. If unset, default to first topic in arguments +- `initial_topic` (str, default="") + - Input topic to select on startup. If `__none`, start with no input topic. If unset, default to first topic in arguments ### Delay @@ -198,7 +215,7 @@ It's useful to simulate computational results with high latency. #### Usage -``` +```shell ros2 run topic_tools delay [outtopic] ``` @@ -209,7 +226,7 @@ Subscribe to and republish on delayed by . E.g. delay messages published to base_scan by 500ms: -``` +```shell ros2 run topic_tools delay base_scan 0.5 ``` @@ -219,7 +236,7 @@ ros2 run topic_tools delay base_scan 0.5 - the same as if provided as a command line argument - `output_topic` (string, default=`_delay`) - the same as if provided as a command line argument -- `lazy` (bool, default=False) - - If True, only subscribe to `input_topic` if there is at least one subscriber on the `output_topic` -- `delay` (double) - - delay in seconds \ No newline at end of file +- `delay` (double, default=0.0) + - delay in seconds +- `use_wall_clock` (bool, default=False) + - If True, then perform all rate measurements against wall clock time, regardless of whether simulation / log time is in effect.