Improve README setup instructions (#27)

Author: sivral

README.md

@@ -13,28 +13,14 @@ Package for controlling the [Robotiq Hand-E gripper](https://robotiq.com/product
 
 ## Quick Start
 
-### Connection Setup
+### Workspace setup
 
-#### Without Physical Hardware
-* You are ready to go - just remember to pass the `use_fake_hardware:=true` argument.
-
-#### Modbus RTU
-* Connect the serial port to your system and locate the TTY device (typically `/dev/ttyX`).
-* You will need to configure the serial connection in your `.xacro.urdf` file ([example](https://github.com/AGH-CEAI/robotiq_hande_description/blob/humble/urdf/robotiq_hande_gripper.urdf.xacro) in `robotiq_hande_description`).
-
-#### Modbus TCP
-* You can create a local `TCP` <-> `Virtual Serial Port` server with the `socat` command.
-  * An example usage (in the form of a Python ROS 2 wrapper) can be found in `ur_robot_driver`'s [scripts/tool_communication.py](https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/blob/204e215c8a7371f6357e6a09f7e106364e566931/ur_robot_driver/scripts/tool_communication.py#L64).
-  * Example: `socat pty,link=/tmp/ttyUR,raw,ignoreeof,waitslave tcp:192.168.1.2:54321`
-* For the UR's `ur_robot_driver`, the default path to the virtual serial port is `/tmp/ttyUR`.
-
-
-### Package setup
 ```bash
-cd ~/ceai_ws/src
-git clone git@github.com:AGH-CEAI/robotiq_hande_driver.git ./src
-vcs import src < src/robotiq_hande_driver/robotiq_hande_driver.repos &&
-colcon build --symlink-install --packages-select robotiq_hande_driver
+mkdir -p ~/ceai_ws
+cd ~/ceai_ws
+git clone git@github.com:AGH-CEAI/robotiq_hande_driver.git src/robotiq_hande_driver
+vcs import src < src/robotiq_hande_driver/robotiq_hande_driver/robotiq_hande_driver.repos
+colcon build --symlink-install
 source ./install/local_setup.sh
 ```
 > [!NOTE]
@@ -44,18 +30,112 @@ source ./install/local_setup.sh
 
 
 ### Launch preview
+
+Start the driver:
 ```bash
 ros2 launch robotiq_hande_driver gripper_controller_preview.launch.py use_fake_hardware:=true
-# In other terminal
+```
+
+Send a command to the gripper in another terminal:
+```bash
 ros2 action send_goal /gripper_action_controller/gripper_cmd control_msgs/action/GripperCommand \
 "command:
   position: 0.0
   max_effort: 0.0
 "
 ```
 
-### Examples
-**An example integration usage can be find** in the [AGH-CEAI/aegis_ros](https://github.com/AGH-CEAI/aegis_ros) repository.
+## Connection modes
+
+You can run the gripper in three ways.
+
+### Without the physical hardware
+
+If you only want to test the gripper behavior or visualize it in RViz without connecting to the actual device, you can use the fake hardware mode. In this case, simply pass the `use_fake_hardware:=true` argument:
+```bash
+ros2 launch robotiq_hande_driver gripper_controller_preview.launch.py use_fake_hardware:=true
+```
+
+All other connection options will be ignored; this mode does not communicate with any physical port or network but simulates responses and allows the controller to run.
+
+### Modbus RTU
+
+If you want to work with the real gripper via direct serial communication, the computer connects to the gripper through a USB-to-RS485 adapter. The wiring is represented as:
+
+Computer → USB adapter ↔ RS485 ↔ Hand-E gripper
+
+In this case, you need to set `use_fake_hardware:=false` and provide serial port to establish connection using `tty_port`:
+```bash
+ros2 launch robotiq_hande_driver gripper_controller_preview.launch.py use_fake_hardware:=false tty_port:=/dev/ttyUSB0
+```
+
+You can check available serial devices with:
+```bash
+dmesg | grep tty
+```
+
+or
+
+```bash
+ls -l /dev/tty*
+```
+
+Make sure your user has permissions to access the serial port:
+```bash
+sudo usermod -a -G dialout $USER
+```
+
+### Modbus RTU tunneled over TCP via UR Tool Communication
+
+If your setup involves a UR robot, its controller can expose the RS-485 tool port over TCP using the pTool Communication URCap](https://docs.universal-robots.com/Universal_Robots_ROS2_Documentation/doc/ur_robot_driver/ur_robot_driver/doc/setup_tool_communication.html). The wiring is represented as:
+
+UR controller RS-485 tool port ↔ URCap forwarder ↔ TCP socket ↔ Computer
+
+Although this is a TCP connection, the driver uses a pseudo-TTY to translate TCP packets into RTU frames. Typically, the virtual serial port is `/tmp/ttyUR`.
+
+To enable this mode, set `use_fake_hardware:=false`, `create_socat_tty:=true`, and specify the `socat_ip_address` and `socat_port` of the UR forwarder:
+```bash
+ros2 launch robotiq_hande_driver gripper_controller_preview.launch.py \
+  use_fake_hardware:=false \
+  create_socat_tty:=true \
+  tty_port:=/tmp/ttyUR \
+  socat_ip_address:=192.168.1.2 \
+  socat_port:=54321 \
+  frequency_hz:=10 \
+  launch_rviz:=true
+```
+
+ The driver will then use `tty_port:=/tmp/ttyUR` as if it were a real serial port.
+
+You can also start `socat` manually, for example:
+```bash
+socat pty,link=/tmp/ttyUR,raw,ignoreeof,waitslave tcp:192.168.100.10:54321
+```
+
+> [!WARNING]
+> Do not use both the `use_tool_communication:=true` flag for the **ur_driver** and the `create_socat_tty:=true` flag for the **robotiq_hande_driver**!
+> Both options will invoke the `socat` command to create the `/tmp/ttyUR` virtual serial port.
+> However, the initialization of the Hand-E driver may suffer from a race condition: **the tty link must exist before initialization**.
+> It is recommended to use the provided `create_socat_tty` option.
+
+## Integration with (other) robots
+
+To integrate the Robotiq Hand-E gripper into your existing robot, you first need to create a [Xacro (URDF) file](https://docs.ros.org/en/humble/Tutorials/Intermediate/URDF/URDF-Main.html) that includes the Hand-E macros and defines all necessary parameters.
+
+A working example of such a file can be found [here](https://github.com/AGH-CEAI/aegis_ros/blob/humble-devel/aegis_description/urdf/modules/robotiq_hande_gripper.xacro). You can use this file as a starting point for your own integration.
+
+Next, include this Xacro file in your main robot description tree at the appropriate tool link.
+
+An example of including it in a robot Xacro can be found [here](https://github.com/AGH-CEAI/aegis_ros/blob/humble-devel/aegis_description/urdf/aegis.xacro).
+
+The included robotiq_hande_gripper macro automatically sets up the `<ros2_control>` block pointing to the Robotiq Hand-E driver plugin. This ensures that your robot can control the gripper via the standard ROS 2 control interfaces.
+
+You can easliy dig into the `ros2_control` concepts with [its documentation](https://control.ros.org/rolling/doc/ros2_control/doc/index.html#concepts). There is also a [plenty of examples](https://control.ros.org/humble/doc/ros2_control_demos/doc/index.html#examples)
+
+> [!IMPORTANT]
+> The `robotiq_hande_driver` currently provides only a **hardware component** (i.e. _hardware interface_) to control the fingers' joints.
+
+The included `robotiq_hande_gripper` macro automatically sets up the `<ros2_control>` block pointing to the Robotiq Hand-E driver plugin. This ensures that your robot can control the gripper via the standard ROS 2 control interfaces, including the gripper action controller and joint state broadcaster, without additional manual plugin configuration.
 
 ---
 ## Development notes
@@ -79,4 +159,5 @@ cd ~/ceai/ros_ws/build/robotiq_hande_driver
 
 ---
 ## License
+
 This repository is licensed under the Apache 2.0, see LICENSE for details.

robotiq_hande_driver/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* [PR-27](https://github.com/AGH-CEAI/robotiq_hande_driver/pull/27) - Added additional launch arguments and provided better instructions in README.
+
 * [PR-21](https://github.com/AGH-CEAI/robotiq_hande_driver/pull/21) - Added:
   * `SocatManager` for managing the external `socat` process.
   * Added colored logging.
@@ -19,6 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+* [PR-27](https://github.com/AGH-CEAI/robotiq_hande_driver/pull/27) - Renamed `ip_adress` to `socat_ip_address` and `port` to `socat_port`.
+
 * [PR-21](https://github.com/AGH-CEAI/robotiq_hande_driver/pull/21) - Refactored the modbus communication to use multithreads:
   * Renamed `application.hpp/cpp` to `hande_gripper.hpp/cpp`.
   * Changed plain arrays `uint8_t bytes_[]` into `std::array<uint8_t, *>`.

robotiq_hande_driver/bringup/launch/gripper_controller_preview.launch.py

@@ -38,7 +38,42 @@ def generate_launch_description():
         DeclareLaunchArgument(
             "tf_prefix",
             default_value="",
-            description="transforms prefix",
+            description="Add prefix to the all robot's links & joints.",
+        )
+    )
+    declared_arguments.append(
+        DeclareLaunchArgument(
+            "frequency_hz",
+            default_value="10",
+            description="Set update rate for controller.",
+        )
+    )
+    declared_arguments.append(
+        DeclareLaunchArgument(
+            "tty_port",
+            default_value="/tmp/ttyUR",
+            description="Set serial port for RTU communication.",
+        )
+    )
+    declared_arguments.append(
+        DeclareLaunchArgument(
+            "create_socat_tty",
+            default_value="false",
+            description="Create virtual serial port in Linux for RTU simulation.",
+        )
+    )
+    declared_arguments.append(
+        DeclareLaunchArgument(
+            "socat_ip_address",
+            default_value="192.168.100.10",
+            description="Set IP address for TCP connection.",
+        )
+    )
+    declared_arguments.append(
+        DeclareLaunchArgument(
+            "socat_port",
+            default_value="54321",
+            description="Set TCP port for connection.",
         )
     )
 
@@ -107,6 +142,11 @@ def prepare_robot_state_publisher_node() -> Node:
     # tf_prefix is implicitly used in ParameterValue()
     tf_prefix = LaunchConfiguration("tf_prefix", default="")  # noqa: F841
     use_fake_hardware = LaunchConfiguration("use_fake_hardware")
+    frequency_hz = LaunchConfiguration("frequency_hz")
+    tty_port = LaunchConfiguration("tty_port")
+    create_socat_tty = LaunchConfiguration("create_socat_tty")
+    socat_ip_address = LaunchConfiguration("socat_ip_address")
+    socat_port = LaunchConfiguration("socat_port")
 
     robot_description_str = Command(
         [
@@ -122,6 +162,24 @@ def prepare_robot_state_publisher_node() -> Node:
             " ",
             "use_fake_hardware:=",
             use_fake_hardware,
+            " ",
+            "tf_prefix:=",
+            tf_prefix,
+            " ",
+            "frequency_hz:=",
+            frequency_hz,
+            " ",
+            "tty_port:=",
+            tty_port,
+            " ",
+            "create_socat_tty:=",
+            create_socat_tty,
+            " ",
+            "socat_ip_address:=",
+            socat_ip_address,
+            " ",
+            "socat_port:=",
+            socat_port,
         ]
     )
     return Node(

robotiq_hande_driver/hardware/src/hande_hardware_interface.cpp

@@ -37,8 +37,8 @@ HWI::CallbackReturn RobotiqHandeHardwareInterface::on_init(const HWI::HardwareIn
     bool manage_virutal_serial = str_to_lower(info_.hardware_parameters["create_socat_tty"])
                                  == "true";
     if(manage_virutal_serial) {
-        auto ip_addr = info_.hardware_parameters["ip_adress"];
-        auto port = info_.hardware_parameters["port"];
+        auto ip_addr = info_.hardware_parameters["socat_ip_address"];
+        auto port = info_.hardware_parameters["socat_port"];
         auto tty_port = info_.hardware_parameters["tty_port"];
 
         RCLCPP_INFO(

robotiq_hande_driver/test/test_load_hw_interface.cpp

@@ -36,8 +36,8 @@ class TestHWInterface : public ::testing::Test {
                     <param name="slave_id">9</param>
                     <param name="frequency_hz">10</param>
                     <param name="create_socat_tty">false</param>
-                    <param name="ip_adress">127.0.0.1</param>
-                    <param name="port">8888</param>
+                    <param name="socat_ip_address">127.0.0.1</param>
+                    <param name="socat_port">8888</param>
                 </hardware>
                 <joint name="joint1">
                     <command_interface name="position"/>