== relay ==

`relay` is ROS node that subscribes to a topic and republishes all incoming data to another topic. It can work with any message type.

`relay` is part of the [[topic_tools]] package.

=== relay usage ===
`relay <intopic> [outtopic]`

   Subscribe to `<intopic>` and republish to another topic. 
    * `intopic`: Incoming topic to subscribe to
    * `outtopic`: Outgoing topic to publish on (default: `intopic_relay`)

   e.g. rename `base_scan` to `my_base_scan`:
   {{{
rosrun topic_tools relay base_scan my_base_scan
}}}

==== Stealth mode ====

<<Version(Lunar)>>

This is almost the same as a normal relay but it relays only if the topic specified by param `~monitor_topic` is being subscribed by any other nodes except itself.

When input topic of relay and monitor topic are pointing to the same topic (this is the default configuration), the `relay` node subscribes input topic only when other nodes also subscribe the input topic.
It looks like `relay` node subscribes without increment subscription count.

This feature is useful for publishing topics for visualization with lazy transport (e.g. `nodelet_lazy` in [[nodelet_topic_tools]] ).
For example, lazy-transport-enabled nodes don't subscribe input topics unless other nodes subscribe the output topics of the nodes, but some nodes are expected to always subscribe topics (e.g. `RViZ`) and this breaks "laziness" of the nodes.
Putting `relay` node with stealth mode between `RViZ` and the lazy node will solve this issue.

=== Parameters ===
{{{
#!clearsilver CS/NodeAPI
param {
  no_header=True
  0.name= ~unreliable
  0.default=False
  0.type= bool
  0.desc= If True, prefer to negotiate an unreliable connection for the inbound data. (New in ROS 1.1.11)
  1.name= ~lazy
  1.default=False
  1.type= bool
  1.desc= If True, don't subscribe to input topic unless there is at least one subscriber on the output topic. (New in `ros_comm 1.5.0`)
  2.name= ~stealth
  2.default=False
  2.type= bool
  2.desc= If True, relay messages only if the topic specified by `~monitor_topic` is subscribed by any other nodes.
  3.name= ~monitor_topic
  3.default=same as `intopic`
  3.type= string
  3.desc= In `~stealth` mode, this node relays messages if the topic specified by this parameter is subscribed by any other nodes except this node itself.
  4.name= ~monitor_rate
  4.default=1.0
  4.type=double
  4.desc= Polling rate for monitoring subscribers of `~monitor_topic` in `~stealth` mode.
}
}}}