grabardm/lightweight-cobot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Add documentation for KUKA Sunrise features and programs

Browse Source 
- Created a new document for the Station interface, detailing its menu structure, process data, safety functions, frames, and smartPAD function buttons.
- Added a document for RobotPowerControl, explaining its purpose for safely shutting down or restarting the KUKA Sunrise Cabinet controller.
- Introduced ServerFriRos2 documentation, outlining its role in establishing an FRI connection between the KUKA LBR iiwa and a ROS 2 computer.
- Documented the TeachKuka application, which allows manual teaching of the KUKA LBR iiwa, including position capturing and trajectory recording.
- Added an overview of Sunrise Workbench, including installation instructions for Windows and Linux.
- Created a section on installing a Windows compatibility tool (PortProton) on Linux.
- Documented the installation process for SunriseWorkbench on Linux using PortProton.
- Added installation instructions for SunriseWorkbench on Windows.
- Created troubleshooting documentation for configuration errors and SSL errors during installation.
- Implemented a hook to generate the shared PDF only during the default-language build.
This commit is contained in:
Даниил Грабарь
2026-08-13 18:01:59 +03:00
parent 08ebd40671
commit 79d88db930
42 changed files with 2973 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/lwc-doc/docs/sunrise/kuka/programs/robot-power-control.en.md
+45
View File
@@ -0,0 +1,45 @@
# RobotPowerControl
**RobotPowerControl** is a SunriseWorkbench background task for safely shutting down or quickly restarting the KUKA Sunrise Cabinet controller from the smartPAD. When the task starts, a **System** panel appears on the smartPAD with two user buttons: **REBOOT** and **SHUTDOWN**.
This is particularly useful when the controller battery is faulty, because pressing the physical power button may cause an abrupt shutdown. The task lets you shut down the controller correctly or restart it without going to the control cabinet.
!!! warning "Before shutdown or restart"
Stop robot motion and make sure that the operation is safe for the entire robot cell. These buttons control power to the **controller**. After confirmation, the robot connection and running applications are interrupted.
## Source code
The Java task class is located at [`src/iiwa_sunrise/src/RobotPowerControl.java`](https://github.com/Daniel-Robotic/lightweight-cobot/blob/dev/src/iiwa_sunrise/src/RobotPowerControl.java). Open or download it from this link to add it to a Sunrise project.
The shutdown and restart scripts are already installed on the controller. The task calls them through `cmd.exe` at `D:\Programme\reboot.cmd` and `D:\Programme\shutdown.cmd`.
## Starting the task
`RobotPowerControl` runs as a background application (`backgroundTask`). See [smartHMI Applications](../features/applications.md) for details.
![RobotPowerControl in the background application list](../../assets/programms/power_control/apps.png)
The screenshot shows `RobotPowerControl` in the **Background applications** list with a green status indicator.
## Using the smartPAD buttons
| Button | Action |
|---|---|
| **REBOOT** | Runs `reboot.cmd` and restarts the controller |
| **SHUTDOWN** | Runs `shutdown.cmd` and safely shuts down the controller |
Open the user buttons from the smartPAD side menu. See [smartPAD function buttons](../features/station.md#smartpad-function-buttons) for details. The **System** panel contains the **REBOOT** and **SHUTDOWN** buttons.
![System panel with power controls](../../assets/programms/power_control/choose.png)
Each button requires confirmation to prevent accidental activation:
1. Press **REBOOT** or **SHUTDOWN**. smartHMI displays a warning about the critical operation.
2. Press the button again in the confirmation dialog only if you intend to perform the selected action.
3. The corresponding script starts. The button indicator briefly turns yellow. If the script cannot be started, it turns red for two seconds and then returns to gray.
![Confirming a critical operation](../../assets/programms/power_control/use-btn.png)
The image shows the dialog displayed after the first press. Press the button again to start the operation.
The task hands the script to the operating system and does not wait for it to finish. The controller begins shutdown or restart independently. If the indicator turns red, ask the controller administrator to check the system scripts.
doc/lwc-doc/docs/sunrise/kuka/programs/server-fri-ros2.en.md
+180
View File
@@ -0,0 +1,180 @@
# ServerFriRos2
**ServerFriRos2** is a KUKA Sunrise Cabinet controller program that creates an FRI connection between the KUKA LBR iiwa and a ROS 2 computer. Through this connection, `ros2_control` receives the current robot state and, depending on the selected mode, sends motion commands to the controller.
The program connects the two parts of the system: the KUKA controller application and the ROS 2 control node on the external computer. A physical robot cannot be controlled through ROS 2 unless `ServerFriRos2` is running.
The program has been tested on a KUKA LBR iiwa 7 R800 with Sunrise OS 1.16 and FRI 1.16. The source code is located at [`src/iiwa_sunrise/src/ServerFriRos2.java`](https://github.com/Daniel-Robotic/lightweight-cobot/blob/dev/src/iiwa_sunrise/src/ServerFriRos2.java).
See [FRI protocol](../../../getting-started/concepts/fri-protocol.md) for an overview of the communication channel and [SunriseWorkbench setup](../../../getting-started/sunrise-setup.md) for cabling and Sunrise project preparation.
!!! warning "Before starting"
Verify that the configured initial positions are safe for the installed tool and robot cell. Keep the workspace clear during automatic motion. Impedance and manual-guidance modes do not replace standard KUKA safety functions.
## Required configuration
Before synchronizing the project with the controller, open `ServerFriRos2.java` in Sunrise Workbench and check the parameters for your setup.
### Network addresses
The Java class contains addresses of the **ROS 2 computer** as seen through each controller interface:
```java
private static final String KONI_IP = "192.170.10.10";
private static final String KLI_IP = "192.168.21.31";
```
Do not confuse these with `robot.ip` in `cobot-setting.yaml`. That parameter is the address of the **KUKA controller** accessed by the ROS 2 computer. See [System configuration](../../../getting-started/configuration.md) for details.
### Tool and load data
The program attaches the tool named in the `@Named` annotation to the flange:
```java
@Named("tool1")
private Tool _tool;
```
Replace `tool1` with the tool name from **Sunrise Workbench → Object Templates**. In Monitor mode, **Load Data** must contain the mass, center of mass, and inertia tensor. Before enabling gravity compensation, the program checks these parameters and warns the operator if the load model is invalid.
See [Load data](../features/robot-menu.md#load-data) for calibration and verification instructions.
### Initial positions
Before FRI starts, the robot automatically moves to one of the configured joint positions:
```java
private static final double[] ZERO_POSITION =
{0, 0, 0, 0, 0, 0, 0};
private static final double[] MONITOR_WORKING_POSITION =
{0, 0, 0, -1.57, 0, 1.57, 0};
```
`ZERO_POSITION` is used in Position and JointImpedance modes. In Monitor mode, the robot first passes through the zero position and then moves to `MONITOR_WORKING_POSITION`. If necessary, change these arrays to prevent collisions with fixtures, the table, or the installed tool.
### FRI period
For Position and JointImpedance, the value selected on the smartPAD must match `robot.fri_cycle_ms` in `cobot-setting.yaml`:
| Selected period | Update rate | When to use it |
|---|---:|---|
| 10 ms | 100 Hz | Standard and most stable option; required for KLI |
| 5 ms | 200 Hz | Higher-rate control through the dedicated KONI interface |
Monitor uses a fixed 2 ms period and does not display a separate period-selection dialog.
## Starting the application
Open [Applications](../features/applications.md) on the smartPAD, find `ServerFriRos2` in the robot application list, and activate it. The program then appears in the top smartHMI bar.
![Selecting ServerFriRos2 in the application list](../../assets/programms/server_fri_ros2/apps.png)
Press the green **Start** button on the smartPAD. The program prompts you to select a network interface, control mode, and any additional FRI parameters required by that mode.
## Step 1: selecting the network interface
The first dialog displays the configured ROS 2 computer addresses. Select the interface to which the control computer is physically connected.
![Selecting the FRI network interface](../../assets/programms/server_fri_ros2/chose-interface.png)
| Interface | Characteristics | Available modes | Period |
|---|---|---|---|
| **KONI (X66)** | Dedicated FRI network; recommended | Position, JointImpedance, Monitor | 5 or 10 ms; Monitor: 2 ms |
| **KLI (X6)** | Shared control network; fallback option | Position, JointImpedance | 10 ms only |
KONI is better suited to real-time control because its dedicated channel provides lower latency and a more stable cycle. Use KLI when KONI is unavailable. Monitor mode is disabled over KLI because of shared-network latency.
## Step 2: selecting the control mode
Available buttons depend on the selected network interface.
Over KLI, only Position and JointImpedance are available:
![Selecting the control mode over KLI](../../assets/programms/server_fri_ros2/chose-interface-kli.png)
Over KONI, Monitor is also available:
![Selecting the control mode over KONI](../../assets/programms/server_fri_ros2/koni-choose-mode.png)
### Position
Position is the primary mode for ordinary ROS 2 control, including MoveIt trajectory execution. The controller follows position commands precisely; joint stiffness cannot be adjusted in this mode.
After the parameters are selected, the robot moves to `ZERO_POSITION`, creates an FRI session in `POSITION` command mode, and waits for the ROS 2 client.
![Waiting for the ROS 2 client in Position mode](../../assets/programms/server_fri_ros2/pose-start.png)
### JointImpedance
JointImpedance also receives position commands from ROS 2, but executes them with configured joint stiffness. Use this mode to control mechanical impedance while following a target trajectory.
After selecting the mode, the program asks for one stiffness value for all seven joints:
![Selecting joint stiffness](../../assets/programms/server_fri_ros2/koni-choose-jointImpedance-stiffnes.png)
| Stiffness | Robot behavior |
|---:|---|
| 1500 Nm/rad | Stiffest command tracking among the available options |
| 1000 Nm/rad | High joint stiffness |
| 800 Nm/rad | Medium joint stiffness |
| 500 Nm/rad | Softest behavior among the available options |
The program sets damping to 0.7 for every joint. After configuration, the robot moves to `ZERO_POSITION` and waits for an FRI client as in Position mode.
![Waiting for the ROS 2 client in JointImpedance mode](../../assets/programms/server_fri_ros2/jointmpedance-start.png)
### Monitor
Monitor is intended for manual guidance while transmitting the current robot state to ROS 2. The computer sends no motion commands: the FRI session uses `NO_COMMAND_MODE`, and the controller transmits joint positions and torques every 2 ms.
Before connecting, the robot moves through `ZERO_POSITION` to `MONITOR_WORKING_POSITION`. The program then checks the tool Load Data and enables joint impedance with zero stiffness and damping of 0.7. Gravity compensation allows the robot to be guided carefully by hand.
Start the ROS 2 node on the computer before confirming the dialog. Press **OK — ROS2 ready** only after `ros2_control_node` is active.
![Starting the ROS 2 client for Monitor mode](../../assets/programms/server_fri_ros2/monitor-start.png)
!!! danger "Monitor and the load model"
Do not enable manual guidance with invalid tool parameters. Incorrect mass, center of mass, or inertia makes gravity compensation inaccurate: the robot may resist the operator or drift unexpectedly.
## Step 3: selecting the send period
For Position or JointImpedance over KONI, the program offers a 10 or 5 ms period. Over KLI, this step is skipped because the period is fixed at 10 ms.
![Selecting the FRI send period](../../assets/programms/server_fri_ros2/koni-choose-pose-and-jointImpedance-time.png)
Start with 10 ms unless the task requires a higher control rate. Use 5 ms over KONI only for tasks that need a 200 Hz cycle.
## Connecting ROS 2
Start the physical-robot stack on the ROS 2 computer:
```bash
cobot run
```
Select the physical robot when prompted. The command starts `ros2_control_node`, the FRI hardware interface, controllers, MoveIt, and configured additional services. See [cobot CLI commands](../../../getting-started/cli-reference.md) and [Control via ROS 2](../../../getting-started/control/ros2-control.md).
For the most reliable startup, run `cobot run` on the computer first and then start `ServerFriRos2` on the smartPAD. If the KUKA application is already waiting for a client, ROS 2 must start within 30 seconds. After the timeout, the program closes the FRI session and reports an error in the log.
After connection, the smartHMI log displays:
- FRI session state;
- connection quality;
- `latency`;
- packet delivery time variation (`jitter`).
When the FRI client stops, the session closes, the active mode ends, and connection resources are released. Start the smartPAD application again for a new connection.
## If the connection cannot be established
Check the following first:
1. The selected interface is the one connected to the ROS 2 computer.
2. `KONI_IP` or `KLI_IP` matches the computer address on the selected network.
3. `cobot-setting.yaml` contains the KUKA controller address, not the computer address.
4. The 5/10 ms period in the Java program matches `robot.fri_cycle_ms`.
5. `ros2_control_node` starts before the 30-second timeout expires.
6. FRI UDP port `30200` is configured and not blocked by a firewall.
If the application cannot start because the tool or frame configuration was lost, see [Configuration error](../../../troubleshooting/config-error.md).
doc/lwc-doc/docs/sunrise/kuka/programs/teach-kuka.en.md
+114
View File
@@ -0,0 +1,114 @@
# TeachKuka
**TeachKuka** is a SunriseWorkbench application for manually teaching the KUKA LBR iiwa. Without writing a trajectory in code, an operator can guide the robot by hand, save a position, and record and replay a motion sequence.
The program uses gravity compensation. When enabled, the robot is easy to guide by hand and holds the position set by the operator. This is useful for quickly teaching simple operations, checking the workspace, and preparing repeatable motions.
The source code is located at [`src/iiwa_sunrise/src/TeachKuka.java`](https://github.com/Daniel-Robotic/lightweight-cobot/blob/dev/src/iiwa_sunrise/src/TeachKuka.java). Open or download the file to add it to a Sunrise project.
!!! warning "Safety"
Before starting, make sure that the workspace is clear and that the robot is not executing another motion. Continuously monitor the robot during trajectory playback. Do not run the program near people or objects if motion could cause injury or equipment damage.
## Tool configuration
The program attaches a tool to the robot flange through this annotation:
=== "java"
```java
@Named("tool1")
private Tool _gripper;
```
Replace `tool1` with the name of your tool.
Check the tool and its parameters in Sunrise Workbench:
1. Open the robot project.
2. Go to **Object Templates**.
3. Find the tool installed on the robot.
4. Check its name and **Load data**.
5. Replace `tool1` in the `TeachKuka` class's `@Named(...)` annotation with this name.
6. Verify that mass, center of gravity, and inertia match the physical gripper.
!!! warning "Correct load model"
The program may start with incorrect load data, but gravity compensation will be inaccurate. The robot may feel too heavy, drift unexpectedly, or fail to hold its position. Calibrate the tool mass and center of gravity to avoid equipment damage.
## Starting the program and main menu
When `TeachKuka` starts, the robot first moves to **Home**. Before entering any operating mode, it passes through Home and moves to the configured working position. The tool named in `@Named(...)` is attached to the robot flange first.
Find and start the program under [Applications](../features/applications.md) on the smartPAD. That section also describes application states and activation.
![Selecting TeachKuka under Applications](../../assets/programms/teach_kuka/apps.png)
smartHMI displays the **Select operating mode** menu:
| Menu item | Purpose |
|---|---|
| **Mode 1: Position** | Guide the robot by hand and read the selected position coordinates |
| **Mode 2: Trajectory** | Record, play, and repeat a motion trajectory |
| **Exit** | End the program and return the robot to Home |
In **Position** mode, the robot can be moved by hand. In **Trajectory** mode, the program records the robot motion for later playback. **Exit** ends the program and returns the robot to Home.
![Selecting the TeachKuka operating mode](../../assets/programms/teach_kuka/choose-mode.png)
## Mode 1: capturing a position
After selecting the mode, the program moves to the working position, checks the load model, and enables gravity compensation. You can now guide the robot by hand; it follows the operator and remains at the selected position.
The following actions are available:
| Action | Result |
|---|---|
| **Get position** | Writes flange `X/Y/Z` in millimeters, `A/B/C` orientation in degrees, and joint positions in degrees and radians to the log |
| **Back** | Disables gravity compensation, stops motion, and engages the brake |
The **Get position** button writes the Cartesian robot pose (`X/Y/Z`, `A/B/C`) and joint positions to the log. **Back** returns to the previous step and moves the robot to `(0, 0, 0, -1.57, 0, 1.57, 0)`.
![Manual motion mode](../../assets/programms/teach_kuka/move-mode.png)
The following video demonstrates manual guidance in this mode:
<video controls autoplay muted loop playsinline width="50%">
<source src="../../../../../sunrise/assets/programms/video/HandMode.mp4" type="video/mp4">
Your browser does not support video playback.
</video>
## Mode 2: recording and playing a trajectory
When this mode starts, the program clears the previous recording, enables gravity compensation, and begins saving current joint positions. A new point is recorded every 100 ms.
Recording is limited to 3,000 points, or about five minutes of motion. When the limit is reached, the program stops recording and writes a message to the log.
### Mode actions
| Action | Result |
|---|---|
| **Replay trajectory** | Stops recording, moves the robot to the initial point, and plays the saved trajectory; a new recording starts afterward |
| **Restart** | Deletes the current trajectory and immediately starts a new recording |
| **Back** | Stops recording and gravity compensation and exits the mode |
After guiding the robot along the required path, select **Replay trajectory**. The program moves the robot to `(0, 0, 0, -1.57, 0, 1.57, 0)` and then replays the recorded motion. If an error occurred during teaching, press **Restart** to discard the recording and begin again. **Back** returns to the previous menu and moves the robot to the working position.
![Trajectory recording mode](../../assets/programms/teach_kuka/traj-mode.png)
### Playback
Before playback, the program pauses for two seconds so that the operator can move away. It then moves to the first recorded point and replays the motion through SmartServo at 20% relative speed.
During playback, the program monitors external joint torques. If torque on any joint exceeds 6 Nm, the robot holds its current position and pauses the trajectory. Playback continues from the paused point after the path is cleared.
!!! note "Obstacle detection limitation"
External-torque monitoring can stop a trajectory when unexpected resistance occurs, but it does not replace standard KUKA safety functions. The operator must continuously monitor the workspace.
The following video demonstrates trajectory recording and playback:
<video controls autoplay muted loop playsinline width="50%">
<source src="../../../../../sunrise/assets/programms/video/TeachMode.mp4" type="video/mp4">
Your browser does not support video playback.
</video>
## Finishing operation
When the main menu is closed, the program stops active recording and gravity-compensation threads, cancels the active motion, returns the robot to **Home**, and then exits.