From 99498dc4f8d42fe4c9f94fa40a791219e0e0f433 Mon Sep 17 00:00:00 2001 From: Svastits Date: Wed, 3 Jan 2024 11:25:58 +0100 Subject: [PATCH] kss doc --- doc/wiki/KSS_RSI.md | 133 +++++++++++++++++-- doc/wiki/iiQKA_EAC.md | 6 +- kuka_kss_rsi_driver/krl/ros_rsi_ethernet.xml | 2 +- 3 files changed, 125 insertions(+), 16 deletions(-) diff --git a/doc/wiki/KSS_RSI.md b/doc/wiki/KSS_RSI.md index 319cb5d7..d3ace8fc 100644 --- a/doc/wiki/KSS_RSI.md +++ b/doc/wiki/KSS_RSI.md @@ -1,32 +1,139 @@ -## KUKA KSS driver (RSI) +## KSS driver (RSI) ### Setup -See instructions for [KRC4](../../kuka_kss_rsi_driver/krl/README_KRC4.md) and [KRC5](../../kuka_kss_rsi_driver/krl/README_KRC4.md). +#### Client side +It is recommended to use the driver in a real-time capable client machine (further information about setting up the PREEMPT_RT patch can be found [here](Realtime.md)). + +To set up the controller with WorkVisual (which is necessary if RSI is not yet installed), a Windows machine is also required. + +##### Client IP configuration +1. Set a fixed IP in the subnet of the KLI interface for the Windows machine, which is required to connect to WorkVisual and transfer the project +2. Set a fixed IP in the subnet of the RSI interface for the real-time machine, which is required to send commands via the RSI interface. + +#### Controller side +These instructins were tested with RSI 4.1.3 (on KSS8.6) and RSI 5.0.2 (on KSS8.7) + +##### 1. Controller network configuration + +Windows runs behind the SmartHMI on the teach pad. Make sure that the **Windows interface** of the controller and the **PC with ROS** is connected to the same subnet. + +1. Log in as **Expert** or **Administrator** on the teach pad and navigate to **Network configuration** (**Start-up > Network configuration > Activate advanced configuration**). + There should already be an interface checked out as the **Windows interface**. + - **Windows interface checkbox** should be checked. +2. Add a new network for RSI: + **KRC4:** + - Minimize the SmartHMI (**Start-up > Service > Minimize HMI**). + - Run **RSI-Network** from the Windows Start menu (**All Programs > RSI-Network**). + - Check that the **Network - Kuka User Interface** shows the Windows interface with the specified IP address. + - Add a new IP address on another subnet for the **RSI interface**. + - Select the entry **New** under **RSI Ethernet** in the tree structure and press **Edit**. + - Enter the IP address and confirm with **OK**. + - Close **RSI-Network** and maximize the SmartHMI. + + **KRC5:** + - Press the **Advanced** button and **New interface**. + - Select **Mixed IP address** and keep the default **Receiving task: Target subnet** and **Real-time receiving Task: UDP** + - Set the IP address to a different subnet then the **KLI interface**. + - **Default gateway**: leave it empty + - **Windows interface checkbox** should NOT be checked + +3. Reboot the controller with a cold restart (**Shutdown > Check *Force cold start* and *Reload files* > Reboot control PC**). + +If your PC has an IP address on the same subnet as the **Windows interface** on the controller, the controller should receive answers from the PC: +- If this is the case, add another IP address to the current PC connection on the same subnet as the **RSI** interface. + +##### 2. Update and upload configuration files +There are 3 files necessary for RSI that are available in the `krl` directory: + +- `ros_rsi_ethernet.xml`: specifies the data transferred via RSI and contains the IP configuration of the client machine: + - The `IP_NUMBER` tag should be modified so that it corresponds to the IP address previously added for your (real-time) PC. + - The `PORT` might be left as it is (59152), but can be also changed if a different port is to be used on the client machine. + +- `ros_rsi.src`: This contains the KRL program that starts external control and should not be modified. +- `ros_rsi.rsix`: This contains the RSI context (can be visualized with **RSIVisual**). It can be modified for example to add filtering behaviour, but this is not recommended and should be implemented on the client side instead. + +There are two options to upload these files to the controller: + +Method 1: +1. Copy the files to a USB-stick. +2. Plug it into the teach pad or controller. +3. Log in as **Expert** or **Administrator**. +4. Copy the `ros_rsi.src` file to `KRC:\R1\Program`. +5. Copy the rest of the files to `C:\KRC\ROBOTER\Config\User\Common\SensorInterface`. + +Method 2: +1. Use the WorkVisual, connect to the KRC +2. Log in as **Expert** or **Administrator**. +4. Copy the `ros_rsi.src` file to `KRC:\R1\Program` in the WorkVisual +5. Copy the rest of the files to `C:\KRC\ROBOTER\Config\User\Common\SensorInterface` in the WorkVisual +6. Deploy the project + +### Configuration + +#### Startup configuration + +The following configuration files are available in the `config` directory of the package: +- `driver_config.yaml`: contains the IP address of the client machine +- `ros2_controller_config.yaml`: contains the controller types for every controller name. Should be only modified if a different controller is to be used. The `configure_components_on_start` parameter should never be modified, which ensures that the hardware interface is not activated at startup. +- configuration files for specific controllers, for further information, see the documentation of the given controller + +##### IP configuration +The following parameters must be set in the driver configuration file: +- `client_ip`: IP address of the client machine, should be identical to the one set in `ros_rsi_ethernet.xml` +- `client_port`: port of the real-time communication on the client machine, should be identical to the one set in `ros_rsi_ethernet.xml` + +#### Runtime parameters + +The KSS driver currently does not have runtime parameters. Control mode cannot be changed if the driver is running, as that also requires modifying the RSI context on the controller. ### Usage -Start the launch file in the package to start all required nodes: +#### Starting the driver + +1. To start the driver, two launch file are available, with and without `rviz`. To launch (without `rviz`), run: + + - `ros2 launch kuka_kss_rsi_driver startup.launch.py` + - This starts the 3 core components of every driver (described in the *Non-real-time interface* section of the [project overview](Project%20overview.md)) and the following controllers: + - `joint_state_broadcaster` (no configuration file, all state interfaces are published) + - `joint_trajectory_controller` ([configuration file](../../kuka_kss_rsi_driver/config/joint_trajectory_controller_config.yaml)) + + - After succesful startup, the `robot_manager` node has to be activated to start the cyclic communication with the robot controller, see further steps (before this only a collapsed robot is visible in `rviz`): + +2. `ros2 lifecycle set robot_manager configure` +3. Start the `KRC:\R1\Program\ros_rsi.src` program on the controller and move to the step before `RSI_MOVECORR()` is run + - in T1, a warning (*!!! Attention - Sensor correction goes active !!!*) should be visible after reaching `RSI_MOVECORR()` +4. ```ros2 lifecycle set robot_manager activate``` + - The hardware interface is now waiting for the robot controller to connect, the timeout for this is currently 10 seconds +5. Start step RSI_MOVECORR() within the given timeout + - in T1 this can be done with confirming the previously described warning + +On successful activation the brakes of the robot will be released and external control is started. To test moving the robot, the `rqt_joint_trajectory_controller` is not recommended, use the launch file in the `iiqka_moveit_example` package instead (usage is described in the *Additional packages* section of the [project overview](Project%20overview.md)). + + +##### Launch arguments -**`ros2 launch kuka_kss_rsi_driver startup.launch.py`** +Both launch files support the following arguments: +- `robot_model` and `robot_family`: defines which robot to use. The available options for the valid model and family combinations can be found in the [readme](https://github.com/kroshu/kuka_robot_descriptions?tab=readme-ov-file#what-data-is-verified) of the `kuka_robot_descriptions` repository. +- `use_fake_hardware`: if true, the `mock_components/GenericSystem` will be used instead of the `KukaRSIHardwareInterface`. This enables trying out the driver without actual hardware -After all components have started successfully, the system needs to be configured and activated to start external control: +#### Stopping external control -**`ros2 lifecycle set robot_manager configure`** +To stop external control, all components have to be deactivated with `ros2 lifecycle set robot_manager deactivate` -**`ros2 lifecycle set robot_manager activate`** +BEWARE, that this is a non-realtime process including lifecycle management, so the connection is not terminated immediately, in cases where an abrupt stop is needed, the safety stop of the Teach Pendant should be used! ### Simulation -To try out the driver with an open-loop simulation the driver and the `kuka_rsi_simulator` must be started, (before activation only a "collapsed" robot will be visible in `rviz`): +To try out the driver with an open-loop simulation, the driver and the `kuka_rsi_simulator` must be started, (before activation only a "collapsed" robot will be visible in `rviz`): -**`ros2 launch kuka_kss_rsi_driver startup_with_rviz.launch.py`** +`ros2 launch kuka_kss_rsi_driver startup_with_rviz.launch.py` -**`ros2 launch kuka_rsi_simulator kuka_rsi_simulator_launch.py`** +`ros2 launch kuka_rsi_simulator kuka_rsi_simulator_launch.py` -After all components have started successfully, the system needs to be configured and activated to start the simulation, the robot will be visible in rviz after activation: +After all components have started successfully, the system needs to be configured and activated to start the simulation. The robot will be visible in rviz after activation: -**`ros2 lifecycle set robot_manager configure`** +`ros2 lifecycle set robot_manager configure` -**`ros2 lifecycle set robot_manager activate`** \ No newline at end of file +`ros2 lifecycle set robot_manager activate` \ No newline at end of file diff --git a/doc/wiki/iiQKA_EAC.md b/doc/wiki/iiQKA_EAC.md index 8861f884..38a4615f 100644 --- a/doc/wiki/iiQKA_EAC.md +++ b/doc/wiki/iiQKA_EAC.md @@ -1,4 +1,4 @@ -## iiQKA driver (ECI) +## iiQKA driver (EAC) ### Setup @@ -7,6 +7,8 @@ It is recommended to use the driver in a real-time capable client machine (furth The driver depends on some KUKA-specific packages, which are only available with the real robot, therefore a mock mode is provided to enable trying out solutions with the same components running. By default, the mock libraries are used, this can be changed in the `CmakeLists.txt` file by setting `MOCK_KUKA_LIBS` to `FALSE` before building. +Set a fixed IP in the subnet of the RSI interface for the real-time machine, which is required to send commands via the RSI interface. + #### Controller side - Install ExternalAPI.Control toolbox (requires iiQKA 1.2) @@ -56,7 +58,7 @@ This starts the 3 core components of every driver (described in the *Non-real-ti - `effort_controller` (of type `JointGroupPositionController`, [configuration file](../../kuka_iiqka_eac_driver/config/effort_controller_config.yaml)) - [`control_mode_handler`](https://github.com/kroshu/kuka_controllers?tab=readme-ov-file#control_mode_handler) (no configuration file) -After succesful startup, the `robot_manager` node has to be activated to start the cyclic communication with the robot controller: +After succesful startup, the `robot_manager` node has to be activated to start the cyclic communication with the robot controller (before this only a collapsed robot is visible in `rviz`): `ros2 lifecycle set robot_manager configure` diff --git a/kuka_kss_rsi_driver/krl/ros_rsi_ethernet.xml b/kuka_kss_rsi_driver/krl/ros_rsi_ethernet.xml index aadb5a8a..51b18164 100755 --- a/kuka_kss_rsi_driver/krl/ros_rsi_ethernet.xml +++ b/kuka_kss_rsi_driver/krl/ros_rsi_ethernet.xml @@ -1,7 +1,7 @@ ip.address.of.rospc - port.of.rospc + 59152 KROSHU FALSE