Commit 6fbd59d1 authored by Sergi Hernandez's avatar Sergi Hernandez
Browse files

Added a partial README file.

parent c766735d
# Description
This ROS package contains several tools that may be helpfull to develop new ROS nodes. They have been mainly developed for large scale ROS control nodes that need to handle several ROS interfaces (action, services and topics) to carry out a given task, using state machines or behabior trees, but they can be also used in other scenarios.
These tools are describes in the following sections.
## Timeout
ROS actions are designed to handle tasks that may take a long time to finish. Some times these actions may take too long to finish, so it may be interesting to limit their maximum duration (for example in robot navigation).
The timeout class can be used to limit the execution time of any given action and therefore prevent the control loop from getting stucked waiting for it to finish. The timeout should be started at the same time as the action, and in normal operation the action will finish before the timeout gets active. However, if something goes wrong, the timeout will get active, allowing the user to decide what to do (cancel the action, wait more time, etc).
This class does not provide any means of asynchronous notifications when the desired time has elapsed, instead the timeout has to be polled. The class is thread safe and can be used from different thread contexts.
## Watchdog
Many ROS nodes depend on the periodic or continuous publication of data through topics, for example sensor data or the action feedback.
The watchdog class can be used to detect the possible failures of the ROS nodes publishing the desired data by limiting the time maximum between two consecutive topic receptions. In normal operation, the watchdog is reset whenever new data is received before it gets active (in the topic subscriber function), but if the topic stops receiving data, the watchdog will eventually activate to indicate something may be wrong with the publishing ROS nodes.
The class is thread safe and can be used from different thread contexts.
## Action client wrapper
ROS action client interface requires several callback functions (active, done and feedback) as well as several variables and lines of code to handle it. When a single ROS node has to handle several actions clients, the complexity of developing and maintainging the code increases.
The action client wrapper class is a template of any action message, and it is intended to simplify the use of the ROS action client. This class handles the execution of the action and all the associated callback functions and variables internally, and provides a simple API interface. The class is thread safe and can be used from different thread contexts.
This class provides the following features:
* **Configurable maximum number of retries**: this class will not report an error until the action has been tried to start for a given ammount of times. Instead it will return a pending condition.
* **Configurable watchdog**: is uses the watchdog class presented before to monitor the reception of the feedback topic. This is specially useful for low quality wireless connections were data can be lost.
* **Configurable timeout**: it uses the timeout class presented before to control the maximum ammount of time the action can be active before succeeding or aborting. This is specially useful for low quality wireless connections were data can be lost.
* **Internal ROS node handle**: The parent ROS node namespace and the desired action name are provided at construction time to generate the namespace used to create the action topics.
* **Can be disabled**: the operation of the action client can be disabled to avoid the actual execution of the action. In this case, the class will report the action has completed successfully immediatelly after being started. This is specially useful to skip certain part of large scale ROS control nodes.
## Service client wrapper
Eventhough the ROS service client interface is not as complex as the ROS action client interface, handling several of them may also inclrease the complexity of developing and maintainging the code.
This class is a template of any service message, and it is intended to simplify the use of the ROS service client. This class handles the call of the service and all the associated variables and functions, and provides a simple API interface. The class is thread safe and can be used from different thread contexts.
This class provides the following features:
* **Configurable maximum number of retries**: this class will not report an error until the service has been tried to call for a given ammount of times. Instead it will return a pending condition.
* **Service answer evaluation callback**: this class can use a user defined function to evaluate the answer returned by the service server to check wheter it is correct or not. The default function always returns success.
* **Internal ROS node handle**: The parent ROS node namespace and the desired service name are provided at construction time to generate the namespace used to create the service.
* **Can be disabled**: the operation of the service client can be disabled to avoid the actual call. In this case, the class will report the service has completed successfully immediatelly. This is specially useful for large scale ROS control nodes.
An inherited class of the templated service client wrapper is provided for the dynamic_reconfigure/Reconfigure.srv service, used by the dynamic reconfigure ROS tool. With this class it is possible to access the parameters defined by the dynamic reconfigure server of any ROS node through code. It provides functions to get and set any of the four data types supported by the service (int, double, bool and string).
## ROS modules.
# Dependencies
# How to use it
## 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/>
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment