This project encapsulates the ROS [SimpleActionServer](http://wiki.ros.org/actionlib/DetailedDescription) to simplify its use by the ROS node developers. See the general [actionlib](http://wiki.ros.org/actionlib) documentation and the more [detailed description](http://wiki.ros.org/actionlib/DetailedDescription) available at the ROS wiki for more information on the ROS action interface.
This project is implemented as a templated C++ class for any of the ROS action messages available. When instantiating an object of this class, the user must specify:
***ActionSpec**: The actual action message used for the new object. For example, to use the MoveBase.action message, use move_base_msgs::MoveBaseAction.
***ROS node handle**: This node handle is used to create the action topics (goal, cancel, status, result and feedback). It should be the private node handle of the ROS node where the object is instantiated, so that the action topics are created inside the namespace of the node.
***Action name**: This name will be used to create a namespace, under the name space provided by the previous ROS node handle, in which all the action topics will be created.
The main features of this class are listed next, and a detailed description can be found below.
* User configurable callbacks for all the main functions (start_action, stop_action, is_finished, has_succeeded, get_result and get_feedback).
* Parallel thread to execute the main action control loop with a configurable rate.
<details><summary>Detailed features description</summary>
<p>
### User configurable callbacks
This class provides a set of callback functions to notify the user when something happens (*start_action* and *stop_action*) or to allow the user to provide the necessary information when required (*is_finished*, *has succeeded*, *get_result* and *get_feedback*). The callback functions can be set by the user using the corresponding register*Callback functions. No default implementation of these functions is provided and the action server requires all of them to operate properly.
The main purpose of each of the callback functions is as follows:
***void start_action_callback(const GoalConstPtr&)**: This callback is called when a new goal is received by the action server and should be used to actually start the desired action. It has the goal defined in the action message as a parameter, which should have all the necessary information to execute the desired action.
***void stop_action_callback()**: this callback is called when the action is cancelled by the client, or the ROS node has been signaled to shutdown, to allow the user to properly finish the current action.
***bool is_finished_callback()**: when an action is active, this callback function is periodically called to know whether the action has finished (it should return true) or it is still active (it should return false). For this function, it is not important if the action has succeeded or not.
***bool has_succeeded_callback()**: when the action has finished, this callback function is called to know whether the action has succeeded (it should return true) or has failed (it should return false).
***void get_result_callback(ResultPtr&)**: this callback function is called when the current action has finished to get the result information defined in the action message. This information is automatically published by this class.
***void get_feedback_callback(FeedbackPtr&)**: this callback function is periodically called while the action is active to get the feedback information defined in the action message. This information is automatically published by this class.
For more information on when these callback functions are used see the flow chart below.
### Parallel thread
This class uses the SimpleActionServer version with a parallel thread to execute the action control loop function. This function is only executed when a new goal is received and stops when the action has finished. The implemention of this loop is shown in the next flow chart.
<imgsrc="doc/images/iri_action_server_flow_chart.png"alt="Flow chart of the action control loop function"width="890"height="1029">
The states colored in blue correspond to the actual states of the SimpleActionServer, and the states colored in gray correspond to the user callback functions presented in the previous section.
The default rate of the action control loop is 10 Hz, and it can be modified by the user with the *setLoopRate()* function.
</p>
</details>
# ROS Interface
### Action server
-*~/<action_name\>/\** (desired action message):
The action topics (goal, cancel, status, result and feedback) are grouped together inside a namespace with the name provided in the constructor.
# Dependencies
This class has the following ROS dependencies:
*[actionlib](http://wiki.ros.org/actionlib)
# How to use it
An object if this class can be instantiated with the desired action type in any ROS node. However, to simplify its use there is an script (*add_action_server_client*) which automatically adds it to a ROS node created with the *create_driver_package* or *create_algorithm_package* scripts.
Check the [IRI ROS scripts](https://gitlab.iri.upc.edu/labrobotica/ros/iri_core/iri_ros_scripts) page for further information on all these scripts.
## Disclaimer
Copyright (C) Institut de Robòtica i Informàtica Industrial, CSIC-UPC.
Mantainer IRI labrobotics (labrobotica@iri.upc.edu)
This package is distributed in the hope that it will be useful, but without any warranty. It is provided "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. should the program prove defective, the GMR group does not assume the cost of any necessary servicing, repair or correction.
In no event unless required by applicable law the author will be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if the author has been advised of the possibility of such damages.
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>
