This project is intended to be used as a base class for ROS nodes that have to communicate with external hardware. The next diagram shows the basic structure of the IRI ROS base driver node:
<imgsrc="doc/images/LabRobotica_Philosophy.png"alt="Basic structure of the IRI ROS base driver node"width="1103"height="596">
This node was originally base on the [ROS driver_base node](http://wiki.ros.org/driver_base) which is now deprecated. Since then, it re-implements most of the driver_base features.
This node is structured into two parts:
## Driver
This part is intended for the implementation of the driver itself. The use of an external library to implement the driver is strongly recommended to separate the driver functionality from the ROS middleware. However it is also possible to implement the driver here. The main features of this part are listed next, and a detailed description can be found below.
* State machine to control the open, close, start and stop action of he driver.
<details><summary>Detailed features description</summary>
<p>
### State machine
The next figure shows the possible states and transitions (actions) between them of the state machine implemented for the driver.
<imgsrc="doc/images/state_machine.png"alt="State diagram of the state machine implemented in the driver part"width="635"height="455">
The driver tries to transition form the initial state (CLOSED) to the RUNNING state every second until it succeeds. To do so, each transition calls a function that must be implemented by the inherited class (openDriver(), closeDriver(), startDriver() and stopDriver()). These functions should interact with the actual hardware to perform the desired action. If the hardware does not support one or more of these actions, the corresponding functions should do nothing but return success (true).
Some of the parameters of the driver may not be changed on the RUNNING state. Therefore, each of the parameters defined in the dynamic reconfigure interface of the driver node (see below for more information) provides the driver state in which it should be modified. Whenever the value of one of these parameters is changed, the state machine automatically transitions to the desired state, and the returns to the previous one, once the parameter has been updated.
In addition to the driver transition action functions, a set of callback functions are also provided so that the driver node can perform some action (if necessary) after the drives has been opened (postOpenHook) or started (postStartHook), and before it is stopped (preStopHook) or closed (preCloseHook). These functions do nothing by default, but may be implemented by the inherited class to perform any required action.
</p>
</details>
## Driver node
This part is intended for the implementation of the ROS interfaces (topics, services and actions) and other ROS tools. The main features of this part are listed next, and a detailed description can be found below.
* Independent thread with configurable rate.
* Dynamic reconfigure server.
* Diagnostics publisher.
* Public and private ROS node handlers.
<details><summary>Detailed features description</summary>
<p>
### Threads
The driver node provides three separate threads:
* The spin thread is used to call the ROS spin() function. The single threaded version of this function is used, so that all callbacks are executed, sequentially, in the same thread.
* The user thread is used to provide the ability to execute code in parallel and avoid blocking the callback functions. This thread is handled internally when the class is created and destroyed and a single function is provided to the user (mainNodeThread) which is called at a desired rate. The thread rate can be handled with the *setRate()* and *getRate()* functions. The user thread function is only called when the driver is in the RUNNING state.
* The main thread is used to handle the state machine of the driver and publish the node diagnostics data.
### Dynamic reconfigure
A dynamic reconfigure server is initialized by default. It has an associated .cfg file located in the *cfg* folder where the user can define all the parameters that can be updated at run-time. Whenever a parameter value is changed (using the [rqt_reconfigure](http://wiki.ros.org/rqt_reconfigure)) application) two callback functions are called:
* reconfigure callback at the driver part (config_update).
* reconfigure callback at the driver node part (node_config_update)
Each callback receives the whole dynamic reconfigure data structure, but should only use its associated parameters.
All node parameters can be defined this way, but it is recommended to only use it for run-time dynamic parameters.
### Diagnostic publisher
A diagnostic publisher is also initialized by default. It provides the ability to collect status data from the driver and the driver node, and publishes it. The [rqt_runtime_monitor](http://wiki.ros.org/rqt_runtime_monitor) application can be used to monitor the diagnostics.
By default a single diagnostic is published with the current status of the driver (CLOSED, OPENED or RUNNING). Additional diagnostics can be added at star-up by the user with the addNodeDiagnostics() function which can be implemented in the inherited class. For further information on ROS diagnostics feature go [here](http://wiki.ros.org/diagnostics).
### ROS node Handlers
The driver node provides two separate ROS NodeHandlers:
* the public node handle is initialized by a node handle provided to the constructor of the driver node. If no node handle is defined, "/" will be used.
* the private node handle is initialized to "~" by default.
These node handlers can be used to get/set ROS parameters and to set-up ROS interfaces. Depending on the node handle used, the namespace of the corresponding parameter or interfacewill be different.
roscd && cd .. && catkin_make -DCMAKE_BUILD_TYPE=Release
```
# How to use it
This ROS node is not deigned to be used on its own, an inherited class is always required.
To simplify the process of inheriting from this class, there is an script (*create_driver_package*) which creates a ROS driver package using this node as a base class.
Also, there exist other scripts to easily add ROS interfaces (topic publishers or subscribers, service servers or clients and action servers or clients) and also TF publishers or subscribers.
Check the [IRI ROS scripts](https://gitlab.iri.upc.edu/labrobotica/ros/iri_core/scripts-catkin) 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/>
