kss doc

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`**
+`ros2 lifecycle set robot_manager activate`

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`
 

kuka_kss_rsi_driver/krl/ros_rsi_ethernet.xml

@@ -1,7 +1,7 @@
 <ROOT>
    <CONFIG>
       <IP_NUMBER>ip.address.of.rospc</IP_NUMBER>   <!-- IP-number of the external socket -->
-      <PORT>port.of.rospc</PORT>                   <!-- Port-number of the external socket -->      
+      <PORT>59152</PORT>                   <!-- Port-number of the external socket -->      
       <SENTYPE>KROSHU</SENTYPE>        <!-- The name of your system send in <Sen Type="" > -->     
       <ONLYSEND>FALSE</ONLYSEND>       <!-- TRUE means the client don't expect answers. Do not send anything to robot -->
    </CONFIG>