diff --git a/README.md b/README.md index ec36fcde161ddddc9e58610168202f6c2de758b3..bd63f8edb0e1f8de6fdb63a34f5ce562bb602da1 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ 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). +ROS actions are designed to handle tasks that may take a long time to finish. Sometimes 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 stuck 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). @@ -32,7 +32,7 @@ This class provides the following features: * **Configurable watchdog**: it uses the [watchdog](#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](#Timeout) class presented before to control the maximum amount 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. +* **Configurable timeout**: it uses the [timeout](#Timeout) class presented before to control the maximum amount of time the action can be active before succeeding or aborting. * **Internal ROS node handle**: The parent ROS node name-space and the desired action name are provided at construction time to generate the name-space used to create the action topics. @@ -64,7 +64,7 @@ Additionally, more advanced features can be developed on top of the basic ones ( The ROS node which implements the top level control loop for large scale scenarios needs several basic and advanced features to carry out the desired task, and therefore it has to deal with several action and/or service clients and topics. Taking into account only the amount of lines of code, variables and callback functions required to handle each of the ROS interfaces, the complexity of the development and maintenance may increase quite a lot. Furthermore, different top level control ROS nodes may re-implement the same code (or similar) to handle each of the features, which negates the possibility of code re-usability. -On possible solution to simplify this problem is to create what we call a **IRI ROS module** for each of the basic and advances features. Such module is implemented as a shared library that can be included in any ROS node and it implements a simple control loop with all the required client side ROS interfaces, providing a simple API to the user. The main idea is sketched in the next Figure. +One possible solution to simplify this problem is to create what we call a **IRI ROS module** for each of the basic and advances features. Such module is implemented as a shared library that can be included in any ROS node and it implements a simple control loop with all the required client side ROS interfaces, providing a simple API to the user. The main idea is sketched in the next Figure. <img src="doc/images/module.png" alt="Basic structure of the IRI ROS module" width="838" height="595"> @@ -72,9 +72,9 @@ The IRI ROS module is implemented as a base class that provides the main feature The main features of the IRI ROS modules are listed and described next: -* ** ROS interfaces**: Although the ROS interfaces are not directly handled by the IRI ROS module base class itself, it is recommended to use the [action client wrapper](#Action-client-wrapper) and the [service client wrapper](#Service-client-wrapper) presented in the previous sections. This way, the module code is more easily developed and maintained. +* **ROS interfaces**: Although the ROS interfaces are not directly handled by the IRI ROS module base class itself, it is recommended to use the [action client wrapper](#Action-client-wrapper) and the [service client wrapper](#Service-client-wrapper) presented in the previous sections. This way, the module code is more easily developed and maintained. -* **Internal thread**: The control code to handle the IRI ROS module (implemented as a state machine, behavior tree, ...) is executed in a parallel thread. This make it possible to assign a different execution rate to each module, and also simplifies the the user interface. A mutex object is provided to ensure unique access to the module attributes. The inherited class has to start the execution of the thread with the *start_operation* functions, and implement the control code in the *state_machine* function. +* **Internal thread**: The control code to handle the IRI ROS module (implemented as a state machine, behavior tree, ...) is executed in a parallel thread. This makes it possible to assign a different execution rate to each module, and also simplifies the user interface. A mutex object is provided to ensure unique access to the module attributes. The inherited class has to start the execution of the thread with the *start_operation* functions, and implement the control code in the *state_machine* function. * **User interface through an API**: All the features of a ROS node can be accessed through a set of functions, and all the ROS message handling is performed internally in the IRI ROS module. With the API approach, some complex features that would require one or more ROS interfaces and some logic, can be started and handled using simple function calls with the required parameters. This also contributes to the code re-usability. @@ -88,12 +88,12 @@ All the ROS tools included in this project depend on the following IRI dependenc # How to use it -To use any of the tools provided in this ROS package, add the iri_ros_tools dependency to the package.xml and CMakeLists.txt files as any other ROS dependency. +To use any of the tools provided in this ROS package, add the *iri_ros_tools* dependency to the *package.xml* and *CMakeLists.txt* files as any other ROS dependency. -Also add the following lines to the CMakeLists.txt to include the [iriutils](https://gitlab.iri.upc.edu/labrobotica/algorithms/iriutils) dependency: +Also add the following lines to the *CMakeLists.txt* to include the [iriutils](https://gitlab.iri.upc.edu/labrobotica/algorithms/iriutils) dependency: ``` -CMakeLists.txt +find_package(iriutils REQUIRED) include_directories(${iriutils_INCLUDE_DIR}) target_link_libraries(${PROJECT_NAME} ${iriutils_LIBRARY}) ```