diff --git a/source/Concepts/Basic.rst b/source/Concepts/Basic.rst index b6cd5a7c3af..a65588add58 100644 --- a/source/Concepts/Basic.rst +++ b/source/Concepts/Basic.rst @@ -11,12 +11,9 @@ These are the concepts that will help you get started understanding the basics o .. toctree:: :maxdepth: 1 + Basic/Interfaces-Topics-Services-Actions Basic/About-Nodes Basic/About-Discovery - Basic/About-Interfaces - Basic/About-Topics - Basic/About-Services - Basic/About-Actions Basic/About-Parameters Basic/About-Command-Line-Tools Basic/About-Launch diff --git a/source/Concepts/Basic/Interfaces-Topics-Services-Actions.rst b/source/Concepts/Basic/Interfaces-Topics-Services-Actions.rst new file mode 100644 index 00000000000..dddf9a89415 --- /dev/null +++ b/source/Concepts/Basic/Interfaces-Topics-Services-Actions.rst @@ -0,0 +1,137 @@ +.. redirect-from:: + + How-To-Guides/Topics-Services-Actions + +.. _interfaces-topics-services-actions: + +Interfaces (topics, services, actions) +====================================== + +Interfaces in ROS define how nodes exchange data. +This article explains the different types of ROS interface and the differences between them. +With this information, you'll be able to select the right interfaces for your purposes. + +**Area: ROS-framework | Content-type: concept | Experience: beginner** + +.. contents:: Table of Contents + :depth: 2 + :local: + +.. toctree:: + :hidden: + + About-Interfaces + About-Topics + About-Services + About-Actions + +Summary +------- + +ROS nodes typically communicate through the following three types of interfaces: + +* Topics: For continuous data streams. +* Services: For synchronous request/response interactions (short tasks which happen immediately). +* Actions: For long-running tasks with feedback (tasks that may take some time to complete). + +For consistent communication, each interface uses definitions provided in ``.msg``, ``.srv``, or ``.action`` files. + +:doc:`Learn more about nodes ` + +Topics +------ + +The topic interface is meant for continuous data streams, for example, streaming sensor data or the status of your robot. +Topic definitions are stored in ``.msg`` files. +Topics implement a publish/subscribe pattern. +A node publishes data to a topic, and other nodes subscribe to receive that data. +This interface type has the following main characteristics: + +* Asynchronous, one-way communication +* Multiple publishers and subscribers can share the same topic + +.. mermaid:: + + flowchart LR + P[Publisher node] -->|Publishes messages| T[Topic] + T -->|Delivers messages| S1[Subscriber node] + T -->|Delivers messages| S2[Subscriber node] + +Topic keys identify individual publishers on a topic so nodes and tools can distinguish where messages come from. +Each topic key makes it easier to track data sources when several publishers share the same topic. + +Topic statistics +---------------- +Topic statistics are built-in measurements that help you understand how messages behave when a subscription receives them. +When enabled, they automatically track two things: + +:Message age: How old a message is when it arrives, based on its timestamp. +:Message period: The time between incoming messages. + +For both message age and period, ROS calculates the average, minimum, maximum, standard deviation, and the number of samples, using a moving window that updates every time a new message arrives. +These calculations run in constant time and memory using the dedicated utilities. +When you enable topic statistics for a subscription, ROS publishes the collected data at regular intervals as a ``MetricsMessage`` on a statistics topic. +This gives you a clear view of timing patterns, delays, and irregularities, making it easier to assess system performance or diagnose problems related to the message flow. + +.. tip:: + + The default interval is 1 second. + The default statistics topic is ``/statistics``. + +:doc:`Learn how to enable topic statistics ` + +Services +-------- + +The service interface is meant for synchronous request/response interactions, for example, when you want to send a query requesting the configuration of a specific robot. +Service definitions are stored in ``.srv`` files. +Services implement a request/response pattern. +A client sends a request, and a server replies with a response. +This interface type has the following main characteristics: + +* Synchronous communication +* Ideal for short-lived operations that require confirmation, or provide a result in response to a request + +.. mermaid:: + + sequenceDiagram + participant Service client + participant Service server + Service client->>Service server: Request + Service server-->>Service client: Response + +Actions +------- + +The action interface is meant for long-running tasks with feedback, for example, moving a robot to a specific position, or asking the robot to perform a complex motion. +Action definitions are stored in ``.action`` files. +Actions allow clients to send goals, receive feedback during the execution, cancel if needed, and return a result if available. +This interface type has the following main characteristics: + +* Asynchronous, with feedback and result +* Suitable for operations that take time + +.. mermaid:: + + sequenceDiagram + participant Action client + participant Action server + Client->>Action Server: Sends a goal + Action server-->>Action client: Provides feedback (periodic) + Action server-->>Action client: Sends a result + +Key differences between ROS interfaces +-------------------------------------- + +All three interfaces enable communication between nodes, but each serves a different purpose. +The table below summarizes the differences between ROS interface types: + ++--------------+----------------------+-----------------------+-----------------+--------------------+---------------+ +| | Pattern | Direction | Provided result | Typical use case | Cancellation | ++==============+======================+=======================+=================+====================+===============+ +| **Topics** | Publish/Subscribe | One-way | No | Continuous data | Not supported | ++--------------+----------------------+-----------------------+-----------------+--------------------+---------------+ +| **Services** | Request/Response | Two-way | Yes | Quick queries | Not supported | ++--------------+----------------------+-----------------------+-----------------+--------------------+---------------+ +| **Actions** | Goal/Feedback/Result | Two-way with feedback | Yes | Long-running tasks | Supported | ++--------------+----------------------+-----------------------+-----------------+--------------------+---------------+ diff --git a/source/How-To-Guides.rst b/source/How-To-Guides.rst index a6ece034f7a..cdc6a6eaba8 100644 --- a/source/How-To-Guides.rst +++ b/source/How-To-Guides.rst @@ -41,7 +41,6 @@ If you are new and looking to learn the ropes, start with the :doc:`Tutorials `. -This is written to provide the reader with guidelines about when to use each type of interface. - -Topics ------- - -* Should be used for continuous data streams (sensor data, robot state, ...) -* Are for continuous data flow. - Data might be published and subscribed at any time independent of any senders/receivers. - Many to many connection. - Callbacks receive data once it is available. - The publisher decides when data is sent. - -Services --------- - -* Should be used for remote procedure calls that terminate quickly, e.g. for querying the state of a node or doing a quick calculation such as IK. - They should never be used for longer running processes, in particular processes that might be required to preempt if exceptional situations occur and they should never change or depend on state to avoid unwanted side effects for other nodes. - -Actions -------- - -* Should be used for any discrete behavior that moves a robot or that runs for a longer time but provides feedback during execution. -* The most important property of actions is that they can be preempted and preemption should always be implemented cleanly by action servers. -* Actions can keep state for the lifetime of a goal, i.e. if executing two action goals in parallel on the same server, for each client a separate state instance can be kept since the goal is uniquely identified by its id. -* Slow perception routines which take several seconds to terminate or initiating a lower-level control mode are good use cases for actions. -* More complex non-blocking background processing. - Used for longer tasks like execution of robot actions. - Semantically for real-world actions.