Actions proposal

articles/actions.md

@@ -0,0 +1,338 @@
+---
+layout: default
+title: Actions
+permalink: articles/actions.html
+abstract:
+  Actions are one of the three core types of interaction between ROS nodes.
+  This article specifies the requirements for actions, how they've changed from ROS 1, and how they're communicated.
+author: '[Geoffrey Biggs](https://github.com/gbiggs)'
+published: true
+---
+
+{:toc}
+
+# {{ page.title }}
+
+<div class="abstract" markdown="1">
+{{ page.abstract }}
+</div>
+
+Original Author: {{ page.author }}
+
+## Background
+
+There are three forms of communication in ROS: topics, services, and actions.
+Topic publishers broadcast to multiple subscribers, but communication is one-way.
+Service clients send a request to a service server and get a response, but there is no information about the progress.
+Similar to services, actions clients ask an action server reach some end state and will get a response.
+Unlike services, while the action is being peformed the action server sends progress updates to the client.
+
+Actions are useful when a response may take a significant length of time.
+They allow a client to track the progress of a request, get the final outcome, and optionally cancel the request it before it completes.
+
+This document defines requirements for actions, how they are specified in the ROS Message IDL, and how they are communicated by the middleware.
+
+## Entities Involved in Actions
+
+There are two entities involved in actions: an action server and an action client.
+
+### Action Server
+
+An action server provides an action.
+Like topics and services, an action server has a name and a type.
+There is only one server per name.
+
+It is responsible for
+
+* advertising the action to other ROS entities
+* accepting or rejecting requests from one or more action clients
+* executing the action when a request is received and accepted
+* optionally providing feedback about the progress of all executing actions
+* optionally handling requests to cancel an action
+* sending the result of the action, including whether it succeed, failed, or was cancelled, to the client when the action completes
+
+### Action Client
+
+An action client requests an action to be performed and monitors its progress.
+There may be multiple clients per server; however, it is up to the server to decide how requests from multiple clients will be handled.
+
+It is responsible for
+
+* making a request to the action server
+* optionally monitoring the feedback from the action server
+* optionally requesting that the action server cancel the action execution
+* optionally checking the result of the action received from the action server
+
+## Differences between ROS 1 and ROS 2 actions
+
+### First Class Support
+In ROS 1, actions are implemented as a separate library `actionlib` which is built on top of the client libraries.
+This was done to avoid increasing the work required to create a client library in a new language, but actions turned out to be very important to packages like the navigation stack<sup>[1](#separatelib)</sup>.
+In ROS 2 actions will be included in the client library implementations.
+The work of writing a client library in a new language will be reduced by creating a common implmentation in C.
+
+### Services used for Actions
+
+In ROS 1 actions were implemented using a set of topics under a namespace taken from the action name.
+ROS 1 Services were not used because they are inherently synchronous, and actions need to be asynchronous.
+Actions also needed to send status/feedback and be cancelable.
+In ROS 2 services are asynchronous in the common C implementation, so actions will use a combination of services and topics.
+
+### Goal Identifiers
+
+In ROS 1, Action clients are responsible for creating a goal ID when submitting a goal.
+In ROS 2 the action server will be responsible for generating the goal ID and notifying the client.
+
+The server is better equiped to generate a unique goal id than the client because there may be multiple clients who could independently generate the same goal id.
+Another reason is to avoid a race condition between goal creation and cancellation that exists in ROS 1.
+In ROS 1 if a client submits a goal and immediatly tries to cancel it then the cancelation may or may not happen.
+If the cancelation is processed before the goal submission then `actionlib` will ignore the cancellation request without notifying the user's code.
+
+### Namespacing of Generated Messages and Services
+
+Multiple message and service definitions are generated from a single action definition.
+In ROS 1, the generated messages were prefixed with the name of the action to avoid conflicts with other messages and services.
+In ROS 2, the generated service and message definitions will exist in a different namespace to be impossible to conflict with non-action message and service definitions.
+For example, in Python the code from the generated definitions should be in the module `action` instead of `srv` and `msg`.
+In C++, the generated code should be in the namespace and folder `action` instead of `srv` and `msg`.
+
+### Visibility of Action Services and Topics
+
+In ROS 1 `rostopic list` would show all action topics in its output.
+In ROS 2 `ros2 topic list` and `ros2 service list` will not show topics and services used by actions by default.
+The can still be shown by passing an option to the commands to show hidden services and topics.
+
+## Action Interface Definition
+
+Actions are specified using a form of the ROS Message IDL.
+The specification contains three sections, each of which is a message specification:
+
+1. Goal
+
+   This describes what the action should achieve and how it should do it.
+   It is sent to the action server when it is requested to execute an action.
+
+1. Result
+
+   This describes the outcome of an action.
+   It is sent from the server to the client when the action execution ends, whether successfully or not.
+
+1. Feedback
+
+   This describes the progress towards completing an action.
+   It is sent to the client of the action from the action server between commencing action execution and prior to the action completing.
+   This data is used by the client to understand the progress of executing the action.
+
+Any of these sections may be empty.
+Between each of the three sections is a line containing three hyphens, `---`.
+Action specifications are stored in a file ending in `.action`.
+There is one action specification per `.action` file.
+
+### Example
+
+```
+# Define a goal of washing all dishes
+uint32 dishwasher_id  # Specify which dishwasher we want to use
+---
+# Define the result that will be published after the action execution ends.
+uint32 total_dishes_cleaned
+---
+# Define a feedback message that will be published during action execution.
+float32 percent_complete
+uint32 number_dishes_cleaned
+```
+
+## Introspection tools
+
+Actions, like topics and services, are introspectable from the command line.
+In ROS 1, actions are visible in the output of the `rostopic` tool.
+
+In ROS 2, actions will not be visible by default as a set of topics nor a set of services.
+Instead they will be visible using a separate `ros2 action` command line tool.
+
+The command line tool will be able to:
+
+* list action servers and action clients
+* display active goals on an action server
+* display the arguments for an action's goal
+* display the type of an action's feedback and result
+* find actions by action type
+* call an action, display feedback as it is received, display the result when received, and cancel the action (when the tool is terminated prematurely).
+
+Each action will be listed and treated as a single unit by this tool.
+
+## Goal States
+
+The action server maintains a state machine for each goal it accepts from a client.
+Rejected goals are not part of the state machine.
+
+![Action Server State Machine](../img/actions/action_server_state_machine.png)
+
+There are two active states:
+
+- **EXECUTING** - The goal has been accepted and is currently being executed by the action server.
+- **CANCELING** - The client has requested that the goal be canceled and the action server has accepted the cancel request.
+This state is useful for any "clean up" that the action server may have to do.
+
+And three terminal states:
+
+- **SUCCEEDED** - The goal was achieved successfully by the action server.
+- **ABORTED** - The goal was terminated by the action server without an external request.
+- **CANCELED** - The goal was canceled after an external request from an action client.
+
+State transitions triggered by the action server:
+
+- **set_succeeded** - Notify that the goal completed successfully.
+- **set_aborted** - Notify that an error was encountered during processing of the goal and it had to be aborted.
+- **set_canceled** - Notify that canceling the goal completed successfully.
+
+State transitions triggered by the action client:
+
+- **send_goal** - A goal is sent to the action server.
+The state machine is only started if the action server *accepts* the goal.
+- **cancel_goal** - Request that the action server stop processing the goal.
+A transition only occurs if the action server *accepts* the request to cancel the goal.
+The goal may transition to CANCELING or CANCELED depending on the action server implementation.
+
+## API
+
+Proposed examples can be in the respository [examples (branch: actions_proposal)](https://github.com/ros2/examples/tree/actions_proposal).
+
+C++:
+
+- [examples/rclcpp/minimal_action_server](https://github.com/ros2/examples/tree/actions_proposal/rclcpp/minimal_action_server)
+- [examples/rclcpp/minimal_action_client](https://github.com/ros2/examples/tree/actions_proposal/rclcpp/minimal_action_client)
+
+Python:
+
+- [examples/rclpy/actions](https://github.com/ros2/examples/tree/actions_proposal/rclpy/actions)
+
+## Middleware implementation
+
+Under the hood, an action is made up of three services and two topics, each descibed in detail here.
+
+![Action Client/Server Interaction Overview](../img/actions/interaction_overview.png)
+
+### Goal Submission Service
+
+* **Direction**: Client calls Server
+* **Request**: Description of goal
+* **Response**: Whether goal was accepted or rejected, a unique identifier for the goal, and the time when the goal was accepted.
+
+The purpose of this service is to submit a goal to the action server.
+It is the first service called to begin an action, and is expected to return quickly.
+A user-define description of the goal is sent as the request.
+The response indicates whether or not the goal was accepted, and if so the identifier the server will use to describe the goal.
+
+The QoS settings of this service should be set the so the client is guaranteed to receive a response or an action could be executed without a client being aware of it.
+
+### Cancel Request Service
+
+* **Direction**: Client calls Server
+* **Request**: Goal identifier, time stamp
+* **Response**: Goals that will be attempted to be canceled
+
+The purpose of this service is to request to cancel one or more goals on the action server.
+A cancellation request may cancel multiple goals.
+The result indicates which goals will be attempted to be canceled.
+Whether or not a goal is actually canceled is indicated by the status topic and the result service.
+
+The cancel request policy is the same as in ROS 1.
+
+* If the goal ID is empty and time is zero, cancel all goals
+* If the goal ID is empty and time is not zero, cancel all goals accepted at or before the time stamp
+* If the goal ID is not empty and time is not zero, cancel the goal with the given id regardless of the time it was accepted
+* If the goal ID is not empty and time is zero, cancel the goal with the given id and all goals accepted at or before the time stamp
+
+### Get Result Service
+
+* **Direction**: Client calls Server
+* **Request**: Goal ID
+* **Response**: Status of goal and user defined result
+
+The purpose of this service is to get the final result of a service.
+After a goal has been accepted the client should call this service to receive the result.
+The result will indicate the final status of the goal and any user defined data.
+
+Once the server sends the result to the client it should free up any resources used by the action.
+If the client never asks for the result then the server should discard the result after a timeout period.
+
+### Goal Status Topic
+
+* **Direction**: Server publishes
+* **Content**: List of in-progress goals with: Goal ID, time accepted, and an enum indicating the status
+
+This topic is published by the server to broadcast the status of goals it has accepted.
+The purpose of the topic is for introspection; it is not used by the action client.
+Messages are published when transitions from one status to another occur.
+
+The default QoS settings for a DDS middleware should be TRANSIENT LOCAL with a history size of 1.
+This allows new subscribers to always get the latest state.
+
+The possible statuses are:
+
+* *Accepted*
+  * The goal has been accepted by the action server and may now be executing
+* *Cancelling*
+  * The action server will try to cancel the indicated goal
+* *Cancelled*
+  * The action server successfully canceled the goal
+* *Succeeded*
+  * The action server successfully reached the goal
+* *Aborted*
+  * The action server failed reached the goal
+
+### Feedback Topic
+
+* **Direction**: Server publishes
+* **Content**: Goal id, user defined feedback message
+
+This topic is published by the server to send application specific progress about the goal.
+It is up to the author of the action server to decide how often to publish the feedback.
+
+### Client/Server Interaction Examples
+
+Here are a couple of sequence diagrams depicting typical interactions between an action client and action server.
+
+#### Example 1
+
+In this example, the action client request a goal and gets a response from the server accepting the goal (synchronous).
+Upon accepting the goal, the action server starts a user defined execution method for completing the goal.
+Following the goal request, the client makes an asynchronous request for the result.
+The user defined method publishes feedback to the action client as it executes the goal.
+Ultimately, the user defined method populates a result message that is used as part of the result response.
+
+![Goal Lifecycle Example 0](../img/actions/interaction_example_0.png)
+
+#### Example 2
+
+This example is almost identical to the first, but this time the action  client requests for the goal to be canceled mid-execution.
+Note that the user defined method is allowed to perform any shutdown operations after the cancel request before returning with the cancellation result.
+
+![Goal Lifecycle Example 1](../img/actions/interaction_example_1.png)
+
+#### Example 3
+
+Here is a more complex example involving multiple goals.
+
+TODO
+
+## Bridging between ROS 1 and ROS 2
+
+TODO
+
+## Alternatives
+
+These alternative approaches to actions in ROS 2 were considered.
+
+### Actions in rmw
+
+An alternative to using services and topics is to implement actions in the rmw layer.
+This would enable using middleware specific features better suited actions.
+The default middleware in ROS 2 uses DDS, and there don't appear to be any DDS features better for actions than what are used for services and topics.
+Additionally implementing actions in the rmw implementations increases the complexity of writing an rmw implementation.
+For these reasons actions will be implemented at a higher level.
+
+## References
+
+1. <a name="separatelib" href="https://discourse.ros.org/t/actions-in-ros-2/6254/5">https://discourse.ros.org/t/actions-in-ros-2/6254/5</a>