Add documentation for KUKA Sunrise features and programs
- 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:
Даниил Грабарь
@@ -1,9 +1,12 @@
|
||||
document.addEventListener("DOMContentLoaded", function () {
|
||||
const siteRoot = document.querySelector('meta[name="site-root"]')?.content ?? "";
|
||||
const isEnglish = document.documentElement.lang.toLowerCase().startsWith("en");
|
||||
const btn = document.createElement("a");
|
||||
btn.href = siteRoot + "/pdf/documentation.pdf";
|
||||
btn.download = "lwc-documentation.pdf";
|
||||
btn.title = "Скачать всю документацию в PDF";
|
||||
btn.title = isEnglish
|
||||
? "Download all documentation as PDF"
|
||||
: "Скачать всю документацию в PDF";
|
||||
btn.style.cssText = [
|
||||
"position: fixed",
|
||||
"bottom: 80px",
|
||||
@@ -22,7 +25,7 @@ document.addEventListener("DOMContentLoaded", function () {
|
||||
"gap: 8px",
|
||||
"transition: opacity .2s",
|
||||
].join(";");
|
||||
btn.innerHTML = "📄 Скачать PDF";
|
||||
btn.innerHTML = isEnglish ? "📄 Download PDF" : "📄 Скачать PDF";
|
||||
btn.onmouseenter = () => (btn.style.opacity = "0.85");
|
||||
btn.onmouseleave = () => (btn.style.opacity = "1");
|
||||
document.body.appendChild(btn);
|
||||
|
||||
@@ -0,0 +1,169 @@
|
||||
# cobot CLI commands
|
||||
|
||||
`cobot` is the single entry point for managing the entire project. Use it for operations involving the robot, simulator, Docker containers, and documentation.
|
||||
|
||||
## Help
|
||||
|
||||
```bash
|
||||
cobot -h
|
||||
```
|
||||
|
||||
The help output is divided into four command groups:
|
||||
|
||||
- **Setup commands** — system configuration;
|
||||
- **Run commands** — starting the project;
|
||||
- **Build commands** — building ROS 2;
|
||||
- **Management commands** — package management.
|
||||
|
||||
Some commands have their own subcommands. For example:
|
||||
|
||||
```bash
|
||||
cobot doc-setup rebuild # rebuild subcommand of doc-setup
|
||||
cobot doc-setup --help # help for a command's subcommands
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Setup commands
|
||||
|
||||
Commands for initial and repeated system setup.
|
||||
|
||||
### `cobot setup`
|
||||
|
||||
First-run setup wizard. It guides you through three steps:
|
||||
|
||||
1. Configure the documentation server.
|
||||
2. Configure robot parameters in `cobot-setting.yaml`: IP address, FRI port, and tool.
|
||||
3. Select a build environment: native ROS 2 Jazzy or a Docker image.
|
||||
|
||||
```bash
|
||||
cobot setup
|
||||
```
|
||||
|
||||
Use this command for the first installation instead of running each setup command manually.
|
||||
|
||||
---
|
||||
|
||||
### `cobot local-setup`
|
||||
|
||||
Installs ROS 2 Jazzy locally without Docker: downloads dependencies with `rosdep` and builds the workspace with `colcon`.
|
||||
|
||||
```bash
|
||||
cobot local-setup
|
||||
```
|
||||
|
||||
!!! note
|
||||
After the command finishes, run `source ~/.bashrc` or open a new terminal.
|
||||
|
||||
---
|
||||
|
||||
### `cobot docker-setup`
|
||||
|
||||
Builds or downloads the Docker images used to run the project in isolation. Two options are available:
|
||||
|
||||
- **Build from the Dockerfile** — slower, but produces an up-to-date image;
|
||||
- **Download a prebuilt image** — faster, using a published image.
|
||||
|
||||
```bash
|
||||
cobot docker-setup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `cobot doc-setup`
|
||||
|
||||
Deploys a local MkDocs documentation server containing a full copy of the [online documentation](https://daniel-robotics.gitverse.site/lightweight-cobot/).
|
||||
|
||||
```bash
|
||||
cobot doc-setup # start/build the documentation
|
||||
cobot doc-setup rebuild # rebuild the documentation image
|
||||
```
|
||||
|
||||
After startup, the documentation is available at `http://localhost:8000`.
|
||||
|
||||
---
|
||||
|
||||
### `cobot robot-setup`
|
||||
|
||||
Interactive wizard for configuring `cobot-setting.yaml`. It asks for the robot IP address, FRI port, active tool, and other parameters.
|
||||
|
||||
```bash
|
||||
cobot robot-setup
|
||||
```
|
||||
|
||||
!!! tip
|
||||
Use this command to change the configuration. It validates the entered values and prevents YAML syntax errors. See [System configuration](configuration.md) for parameter details.
|
||||
|
||||
---
|
||||
|
||||
## Run commands
|
||||
|
||||
### `cobot run`
|
||||
|
||||
Starts the full stack: hardware interface, MoveIt 2, RViz, and optional components such as Foxglove and the REST API. At startup, it asks you to select:
|
||||
|
||||
- **Docker or local execution**;
|
||||
- **Webots simulation or the physical robot**.
|
||||
|
||||
```bash
|
||||
cobot run # select the mode interactively
|
||||
cobot run --simulate # force simulation mode
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build commands
|
||||
|
||||
### `cobot rebuild`
|
||||
|
||||
Rebuilds the ROS 2 workspace with `colcon`. Use it after changing package source code.
|
||||
|
||||
```bash
|
||||
cobot rebuild
|
||||
```
|
||||
|
||||
!!! note
|
||||
This command is available only for a local installation, not Docker. It is equivalent to `colcon build --mixin release`.
|
||||
|
||||
---
|
||||
|
||||
### `cobot clean`
|
||||
|
||||
Removes generated build directories. It prompts you to select which directories to remove:
|
||||
|
||||
- `build/` — compilation artifacts;
|
||||
- `install/` — installed package files;
|
||||
- `log/` — build logs.
|
||||
|
||||
```bash
|
||||
cobot clean
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Management commands
|
||||
|
||||
### `cobot update`
|
||||
|
||||
Downloads the latest project version from GitVerse and reinstalls the `cobot` CLI.
|
||||
|
||||
```bash
|
||||
cobot update
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `cobot delete`
|
||||
|
||||
Removes project components from the system. It lets you remove only the project, the Docker images and containers, or ROS 2 as well.
|
||||
|
||||
```bash
|
||||
cobot delete
|
||||
```
|
||||
|
||||
!!! danger
|
||||
This operation is irreversible. Removed files and Docker images must be installed again.
|
||||
|
||||
---
|
||||
|
||||
**Robot control:** [Control via the REST API](control/rest-api.md)
|
||||
@@ -0,0 +1,15 @@
|
||||
# System architecture
|
||||
|
||||
!!! info "Work in progress"
|
||||
A detailed description of the system architecture is being prepared.
|
||||
|
||||
LWC is built as a set of interconnected ROS 2 packages. Key components:
|
||||
|
||||
- **iiwa_bringup** — launch files and the entry point for starting the system
|
||||
- **iiwa_controller** — hardware interface connecting to the KUKA controller over FRI
|
||||
- **iiwa_planning** — MoveIt 2-based motion planning
|
||||
- **iiwa_web** — REST API and MCP server for external control
|
||||
- **iiwa_description** — URDF robot description and Webots worlds
|
||||
- **iiwa_config** — configuration files for MoveIt, controllers, and cameras
|
||||
- **iiwa_utils** — helper Python utilities and configuration loading
|
||||
- **iiwa_msgs** — custom ROS 2 message types (action and srv)
|
||||
@@ -0,0 +1,23 @@
|
||||
# FRI protocol
|
||||
|
||||
!!! info "Work in progress"
|
||||
A detailed description of the FRI protocol is being prepared.
|
||||
|
||||
**FRI (Fast Robot Interface)** is a UDP protocol for low-level real-time control of a KUKA robot. It runs over Ethernet and provides a deterministic data exchange cycle between an external PC and the KUKA controller.
|
||||
|
||||
## Main characteristics
|
||||
|
||||
- **Transport:** UDP (no delivery guarantee, which is important for real-time operation)
|
||||
- **Cycle period:** 5 ms (200 Hz) or 10 ms (100 Hz), configured in `cobot-setting.yaml` → `robot.fri_cycle_ms`
|
||||
- **Control modes:** position, torque, and impedance
|
||||
|
||||
## Network requirements
|
||||
|
||||
!!! warning "Important: a 5 ms cycle requires KONI"
|
||||
A **5 ms (200 Hz)** cycle requires the **KONI** port (KUKA Optional Network Interface).
|
||||
The KLI port supports only a 10 ms cycle. Set `fri_cycle_ms: 10` when using KLI.
|
||||
|
||||
| Port | Minimum cycle | Purpose |
|
||||
|---|---|---|
|
||||
| **KONI** | 5 ms | High-frequency control, recommended for FRI |
|
||||
| **KLI** | 10 ms | Standard control and programming |
|
||||
@@ -0,0 +1,23 @@
|
||||
# Motion planning
|
||||
|
||||
!!! info "Work in progress"
|
||||
A detailed description of motion planning is being prepared.
|
||||
|
||||
LWC uses **MoveIt 2**, the standard motion-planning framework for ROS 2.
|
||||
|
||||
## Key concepts
|
||||
|
||||
- **Planning group** (`iiwa_arm`) — the set of joints for which a plan is generated. Defined in SRDF.
|
||||
- **Planner** — the trajectory-generation algorithm. Available planners:
|
||||
- `ompl` — general-purpose probabilistic planner (default)
|
||||
- `pilz_industrial_motion_planner` — deterministic PTP, LIN, and CIRC trajectories
|
||||
- **TCP (Tool Center Point)** — the tool point for which the target pose is specified. Set in `cobot-setting.yaml` → `planning.pose_link`.
|
||||
- **Reference frame** — the coordinate system for targets. Default: `base_link`.
|
||||
|
||||
## `cobot-setting.yaml` settings
|
||||
|
||||
| Parameter | Description |
|
||||
|---|---|
|
||||
| `planning.default_planner` | Default planner: `ompl` or `pilz_industrial_motion_planner` |
|
||||
| `planning.planning_attempts` | Number of attempts after a planning failure |
|
||||
| `planning.pose_link` | TCP link for Cartesian targets |
|
||||
@@ -0,0 +1,18 @@
|
||||
# Simulation (Webots)
|
||||
|
||||
!!! info "Work in progress"
|
||||
A detailed simulator guide is being prepared.
|
||||
|
||||
**Webots** is an open-source robot simulator. LWC uses it as a digital twin of the KUKA LBR IIWA 7, allowing control algorithms to be developed and debugged without a physical robot.
|
||||
|
||||
## Key features
|
||||
|
||||
- The simulator uses the same ROS 2 topics and interfaces as the real robot.
|
||||
- The simulation world is set in `cobot-setting.yaml` → `digital_twin.webots.world`.
|
||||
- Start it with `cobot run --simulate`.
|
||||
|
||||
## Differences from the real robot
|
||||
|
||||
- There are no real safety constraints, so motion can be faster.
|
||||
- Physics is approximate, including inertia, friction, and elasticity.
|
||||
- FRI is not used; communication goes through the Webots ROS 2 driver.
|
||||
@@ -0,0 +1,176 @@
|
||||
# System configuration
|
||||
|
||||
## Main configuration file
|
||||
|
||||
All system parameters are stored in a single file: **`cobot-setting.yaml`** in the project root. It is the single source of truth for the robot IP address, ports, configuration paths, planner settings, and web server settings.
|
||||
|
||||
!!! info "No manual configuration is needed before installation"
|
||||
When you run `cobot setup`, the wizard offers to configure this file automatically in **step 2**. Return to this section when you want to change parameters after the initial installation.
|
||||
|
||||
!!! danger "Do not edit the file manually"
|
||||
Use only `cobot robot-setup`. The interactive wizard validates values and prevents syntax errors. Editing the YAML manually may cause parsing errors and prevent the system from starting.
|
||||
|
||||
```bash
|
||||
cobot robot-setup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `robot` section — robot parameters
|
||||
|
||||
Controls the connection to the physical KUKA controller through FRI.
|
||||
|
||||
```yaml
|
||||
robot:
|
||||
name: "iiwa7"
|
||||
ip: "192.170.10.2"
|
||||
port: 30200
|
||||
fri_cycle_ms: 10
|
||||
joint_position_tau: 0.04
|
||||
joint_velocity_tau: 0.01
|
||||
active_controller: "jtc"
|
||||
description: pkg://iiwa_description/urdf/iiwa7.urdf.xacro
|
||||
```
|
||||
|
||||
| Parameter | Description | Recommendation |
|
||||
|---|---|---|
|
||||
| `name` | Robot model | Do not change: `iiwa7` |
|
||||
| `ip` | KUKA controller IP address | **Change** to the actual controller address |
|
||||
| `port` | FRI UDP port | Default: `30200`; change only if the port conflicts |
|
||||
| `fri_cycle_ms` | FRI cycle: `5` ms = 200 Hz, `10` ms = 100 Hz | Use `10` for stable operation or `5` for high-precision tasks |
|
||||
| `joint_position_tau` | Position EMA filter [s], smoothing commands before transmission | Decrease for a faster response; increase if vibration occurs |
|
||||
| `joint_velocity_tau` | Velocity EMA filter [s], removing finite-difference spikes | Tune in the same way as `joint_position_tau` |
|
||||
| `active_controller` | Control mode: `jtc` (MoveIt / JointTrajectory) or `forward` (direct control) | Use `jtc` for most tasks |
|
||||
| `description` | Path to the robot URDF | Do not change |
|
||||
|
||||
---
|
||||
|
||||
## `digital_twin` section — simulator
|
||||
|
||||
Configures the Webots environment and RViz visualization.
|
||||
|
||||
```yaml
|
||||
digital_twin:
|
||||
webots:
|
||||
world: pkg://iiwa_description/worlds/iiwa.wbt
|
||||
transform: "-0.25 0 0.79"
|
||||
rotation: "0 0 1 0"
|
||||
controller_timer: "50"
|
||||
cameras:
|
||||
- pkg://iiwa_config/config/cameras/d455_top.yaml
|
||||
rviz:
|
||||
config: pkg://iiwa_config/config/rviz/rviz_moveit.rviz
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
|---|---|
|
||||
| `webots.world` | Path to the simulator `.wbt` world |
|
||||
| `webots.transform` | Robot base offset in the world `[x y z]`, in meters |
|
||||
| `webots.rotation` | Base orientation `[x y z angle]`, in radians |
|
||||
| `webots.cameras` | List of YAML configurations for connected cameras |
|
||||
| `rviz.config` | Path to the RViz configuration |
|
||||
|
||||
---
|
||||
|
||||
## `tool` section — active tool
|
||||
|
||||
Specifies which gripper or tool is attached to the robot.
|
||||
|
||||
```yaml
|
||||
tool:
|
||||
active: "patron"
|
||||
```
|
||||
|
||||
| Value | Description |
|
||||
|---|---|
|
||||
| `none` | No tool |
|
||||
| `patron` | Patron chuck/gripper |
|
||||
|
||||
Available tools are defined in `src/iiwa_config/config/tools.yaml`. To add a tool, describe it there and then set its name in `tool.active`.
|
||||
|
||||
---
|
||||
|
||||
## `planning` section — motion planning
|
||||
|
||||
Configures MoveIt 2 and the trajectory planner.
|
||||
|
||||
```yaml
|
||||
planning:
|
||||
pose_link: "tcp"
|
||||
planning_group: "iiwa_arm"
|
||||
default_frame: "base_link"
|
||||
default_planner: "ompl"
|
||||
planning_attempts: 3
|
||||
```
|
||||
|
||||
| Parameter | Description | Recommendation |
|
||||
|---|---|---|
|
||||
| `pose_link` | TCP link used for Cartesian targets | Must match the URDF frame; do not change without updating the URDF |
|
||||
| `planning_group` | Planning group from the SRDF | Do not change: `iiwa_arm` |
|
||||
| `default_frame` | Default reference frame | Do not change: `base_link` |
|
||||
| `default_planner` | Planner: `ompl` or `pilz_industrial_motion_planner` | `ompl` is general purpose; `pilz` produces predictable trajectories |
|
||||
| `planning_attempts` | Number of planning attempts after failure | Increase for difficult trajectories |
|
||||
|
||||
---
|
||||
|
||||
## `web` section — REST API and MCP server
|
||||
|
||||
Configures the FastAPI server used to control the robot over HTTP and MCP for AI-agent integration.
|
||||
|
||||
```yaml
|
||||
web:
|
||||
enabled: true
|
||||
host: "0.0.0.0"
|
||||
port: 8007
|
||||
endpoints: pkg://iiwa_config/config/api_endpoints.yaml
|
||||
joint_limits: pkg://iiwa_config/config/moveit/joint_limits.yaml
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
|---|---|
|
||||
| `enabled` | Enable (`true`) or disable (`false`) the web server |
|
||||
| `host` | Listening address: `0.0.0.0` for all interfaces or `127.0.0.1` for local access only |
|
||||
| `port` | HTTP API port; default: `8007` |
|
||||
| `endpoints` | Path to the REST endpoint description |
|
||||
| `joint_limits` | Path to joint limits used for command validation |
|
||||
|
||||
After startup, the REST API is available at `http://<host>:8007`, and MCP is available at `/mcp`.
|
||||
|
||||
---
|
||||
|
||||
## `foxglove` section — Foxglove Studio monitoring
|
||||
|
||||
[Foxglove Studio](https://foxglove.dev/) visualizes and monitors ROS 2 topics in real time.
|
||||
|
||||
```yaml
|
||||
foxglove:
|
||||
enabled: true
|
||||
port: 8765
|
||||
debug: false
|
||||
address: 0.0.0.0
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
|---|---|
|
||||
| `enabled` | Enable or disable Foxglove Bridge |
|
||||
| `port` | WebSocket port used by Foxglove Studio; default: `8765` |
|
||||
| `debug` | Detailed logging for the bridge process |
|
||||
| `address` | WebSocket listening address |
|
||||
|
||||
The remaining parameters (`tls`, `topic_whitelist`, `min_qos_depth`, and others) are intended for advanced configuration and normally do not need to be changed.
|
||||
|
||||
---
|
||||
|
||||
## What to change and what to keep
|
||||
|
||||
| | Parameter | Action |
|
||||
|---|---|---|
|
||||
| ✅ | `robot.ip` | **Must be changed** to the controller IP address |
|
||||
| ✅ | `robot.fri_cycle_ms` | Select `10` (standard) or `5` (high frequency) |
|
||||
| ✅ | `tool.active` | Set the active tool |
|
||||
| ✅ | `web.enabled` | Set to `false` if the web interface is not needed |
|
||||
| ⚠️ | `robot.active_controller` | Change only when intentionally switching the control mode |
|
||||
| ⚠️ | `planning.*` | Change only when another planner or other parameters are required |
|
||||
| ❌ | `robot.description` | Do not change; this is the URDF path |
|
||||
| ❌ | `controller.moveit.*` | Do not change; these are package-internal MoveIt configuration paths |
|
||||
| ❌ | `digital_twin.webots.world` | Do not change unless you understand the Webots world structure |
|
||||
@@ -0,0 +1,10 @@
|
||||
# Control via Foxglove Studio
|
||||
|
||||
!!! info "Work in progress"
|
||||
Detailed control and monitoring instructions for Foxglove Studio are being prepared.
|
||||
|
||||
[Foxglove Studio](https://foxglove.dev/home) is a tool for visualizing and monitoring ROS 2 data in real time. It connects to the running stack through a WebSocket bridge (port `8765` by default, configured in the `foxglove` section of `cobot-setting.yaml`).
|
||||
|
||||
## Download Foxglove Studio
|
||||
|
||||
Visit the [official Foxglove website](https://foxglove.dev/home) and download the application for your operating system.
|
||||
@@ -0,0 +1,651 @@
|
||||
# Control via the REST API
|
||||
|
||||
The REST API reads robot state and sends commands over HTTP. It is intended for application scripts, integrations with other systems, and quick checks through Swagger UI.
|
||||
|
||||
Motion requests are synchronous: the response is returned after planning and execution finish or an internal timeout occurs. The API has no command queue. Wait for the current request to finish before sending another one.
|
||||
|
||||
!!! warning "Safety"
|
||||
The REST API does not replace the standard KUKA safety system or emergency stop. Before the first run on a physical robot, check the Sunrise program, safety zones, tool, and workspace. Begin using the API in simulation.
|
||||
|
||||
## Starting and accessing the server
|
||||
|
||||
The web server starts with the robot stack when the **web** section is enabled in the root **cobot-setting.yaml** file:
|
||||
|
||||
~~~ yaml
|
||||
web:
|
||||
enabled: true
|
||||
host: 0.0.0.0
|
||||
port: 8007
|
||||
endpoints: pkg://iiwa_config/config/api_endpoints.yaml
|
||||
joint_limits: pkg://iiwa_config/config/moveit/joint_limits.yaml
|
||||
~~~
|
||||
|
||||
After starting the stack with **cobot run**, the server is available at **http://server-address:8007**. Swagger UI shows the actual request schema and lets you run individual tests:
|
||||
|
||||
- locally: [http://localhost:8007/docs](http://localhost:8007/docs);
|
||||
- from another computer: `http://server-address:8007/docs`;
|
||||
- OpenAPI JSON schema: `http://server-address:8007/openapi.json`.
|
||||
|
||||
There is no separate health-check endpoint. If Swagger UI opens, the HTTP server is running. Readiness of ROS components is checked when a specific endpoint is called.
|
||||
|
||||
By default, the server listens on all network interfaces and does not use authentication. Do not expose port 8007 to an untrusted network. For local access, set **host: 127.0.0.1**. For remote access, restrict the network with firewall rules or a VPN.
|
||||
|
||||
## Preparing the examples
|
||||
|
||||
The tabs on this page are synchronized. Select a language once and the same tab will be selected in subsequent examples.
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
HOST=http://localhost:8007
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
import httpx
|
||||
|
||||
HOST = "http://localhost:8007"
|
||||
T_READ = 10
|
||||
T_MOVE = 60
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
HOST = 'http://localhost:8007';
|
||||
T_READ = 10;
|
||||
T_MOVE = 60;
|
||||
|
||||
readOpts = weboptions('Timeout', T_READ);
|
||||
moveOpts = weboptions('MediaType', 'application/json', 'Timeout', T_MOVE);
|
||||
~~~
|
||||
|
||||
MATLAB uses the built-in `webwrite` function for JSON requests. Uploading CSV and JSON files requires `matlab.net.http`, available in modern desktop versions of MATLAB.
|
||||
|
||||
## API overview
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
|---|---|---|
|
||||
| GET | /robot/joint_states | Current joint state |
|
||||
| GET | /robot/pose | TCP pose relative to base_link |
|
||||
| GET | /robot/positions | Named positions from the SRDF |
|
||||
| POST | /robot/move/named | Move to a named position |
|
||||
| POST | /robot/move/pose | Cartesian TCP motion |
|
||||
| POST | /robot/move/joints | Move the seven joints to specified angles |
|
||||
| POST | /trajectory/send | Publish a trajectory from JSON |
|
||||
| POST | /trajectory/send_csv | Upload and publish a trajectory from CSV |
|
||||
| GET | /trajectory/logs | Latest trajectory module log entries |
|
||||
| POST | /sequences/start | Start a sequence from a JSON file |
|
||||
| GET | /sequences/status | Running sequence status |
|
||||
| GET | /sequences/logs | Sequence process output |
|
||||
| POST | /stop | Stop API commands and the planner |
|
||||
|
||||
## Reading robot state
|
||||
|
||||
### Joint state
|
||||
|
||||
GET **/robot/joint_states** returns the latest message from the ROS **/joint_states** topic. The **position**, **velocity**, and **effort** fields use the same order as the **name** array. Angles in **position** are in radians.
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS --max-time 10 $HOST/robot/joint_states | python3 -m json.tool
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
response = httpx.get(f"{HOST}/robot/joint_states", timeout=T_READ)
|
||||
response.raise_for_status()
|
||||
state = response.json()
|
||||
print(dict(zip(state["name"], state["position"])))
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
jointState = webread([HOST '/robot/joint_states'], readOpts);
|
||||
disp(jointState.position)
|
||||
~~~
|
||||
|
||||
Typical response:
|
||||
|
||||
~~~ json
|
||||
{
|
||||
"name": ["joint1", "joint2", "joint3", "joint4", "joint5", "joint6", "joint7"],
|
||||
"position": [0.0, 0.0, 0.0, -1.57, 0.0, 1.57, 0.0],
|
||||
"velocity": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
|
||||
"effort": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
|
||||
}
|
||||
~~~
|
||||
|
||||
If no controller messages arrive within two seconds, the API returns 503. This usually means that the controller or robot has not started yet.
|
||||
|
||||
### TCP pose
|
||||
|
||||
GET **/robot/pose** computes forward kinematics with the MoveIt **/compute_fk** service. Position is specified in meters. Orientation is returned as both a quaternion and Euler angles:
|
||||
|
||||
- **euler_rad** — radians;
|
||||
- **euler_deg** — degrees;
|
||||
- **A, B, C** follow the KUKA ABC convention: rotation around Z, then Y, then X.
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS --max-time 10 $HOST/robot/pose | python3 -m json.tool
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
response = httpx.get(f"{HOST}/robot/pose", timeout=T_READ)
|
||||
response.raise_for_status()
|
||||
pose = response.json()
|
||||
print(pose["position"])
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
pose = webread([HOST '/robot/pose'], readOpts);
|
||||
fprintf('TCP: x=%.3f, y=%.3f, z=%.3f m\n', ...
|
||||
pose.position.x, pose.position.y, pose.position.z);
|
||||
fprintf('ABC: A=%.1f, B=%.1f, C=%.1f deg\n', ...
|
||||
pose.orientation.euler_deg.a, ...
|
||||
pose.orientation.euler_deg.b, ...
|
||||
pose.orientation.euler_deg.c);
|
||||
~~~
|
||||
|
||||
This endpoint depends on both **/joint_states** and MoveIt. If either is unavailable, it returns 503.
|
||||
|
||||
### Named positions
|
||||
|
||||
GET **/robot/positions** reads `group_state` positions from the SRDF. The list is not hardcoded in the API; it reflects the current robot configuration. The standard configuration includes **home**, **work**, and **transport**.
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS $HOST/robot/positions | python3 -m json.tool
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
response = httpx.get(f"{HOST}/robot/positions", timeout=T_READ)
|
||||
response.raise_for_status()
|
||||
for position in response.json():
|
||||
print(position["name"], "—", position["description"])
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
namedPositions = webread([HOST '/robot/positions'], readOpts);
|
||||
for i = 1:numel(namedPositions)
|
||||
fprintf('%s — %s\n', namedPositions(i).name, ...
|
||||
namedPositions(i).description);
|
||||
end
|
||||
~~~
|
||||
|
||||
Call this endpoint before **/robot/move/named** to obtain the exact name, planning group, and target joint angles.
|
||||
|
||||
## Motion commands
|
||||
|
||||
All three commands below use MoveIt. A response has this form:
|
||||
|
||||
~~~ json
|
||||
{"success": true, "message": "Motion completed successfully"}
|
||||
~~~
|
||||
|
||||
**success: false** means that the planner could not plan or execute the trajectory. The HTTP status may still be 200, so application code must check both the HTTP status and the **success** field.
|
||||
|
||||
### Moving to a named position
|
||||
|
||||
POST **/robot/move/named** moves the manipulator to a position from the SRDF.
|
||||
|
||||
| Field | Required | Value |
|
||||
|---|---:|---|
|
||||
| name | yes | Position name from /robot/positions |
|
||||
| speed | no | Speed scale from 0.01 to 1.0; default: 0.1 |
|
||||
| accel_scale | no | Acceleration scale from 0 to 1.0; 0 uses speed |
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS --max-time 60 -X POST $HOST/robot/move/named \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "home", "speed": 0.1, "accel_scale": 0.0}'
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
response = httpx.post(
|
||||
f"{HOST}/robot/move/named",
|
||||
json={"name": "home", "speed": 0.1, "accel_scale": 0.0},
|
||||
timeout=T_MOVE,
|
||||
)
|
||||
response.raise_for_status()
|
||||
result = response.json()
|
||||
if not result["success"]:
|
||||
raise RuntimeError(result["message"])
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
body = struct('name', 'home', 'speed', 0.1, 'accel_scale', 0.0);
|
||||
reply = webwrite([HOST '/robot/move/named'], body, moveOpts);
|
||||
assert(reply.success, reply.message)
|
||||
~~~
|
||||
|
||||
### Cartesian TCP motion
|
||||
|
||||
POST **/robot/move/pose** accepts a TCP position in meters and an ABC orientation in radians. If **frame_id** is empty, the frame from the planning settings is used; in the standard configuration this is **base_link**.
|
||||
|
||||
| Field | Required | Value |
|
||||
|---|---:|---|
|
||||
| x, y, z | yes | TCP coordinates, m |
|
||||
| a, b, c | no | KUKA ABC angles, rad; default: 0 |
|
||||
| speed | no | Speed scale from 0.01 to 1.0; default: 0.1 |
|
||||
| planner | no | ompl, ptp, lin, circ, or chomp; default: ptp |
|
||||
| frame_id | no | Target pose frame; an empty string uses the default frame |
|
||||
|
||||
The **planner** value is converted to lowercase. PTP is suitable for transitions between points; LIN produces straight-line tool motion. CIRC is appropriate only when it is supported by the planner and target pose.
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS --max-time 60 -X POST $HOST/robot/move/pose \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"x": 0.40, "y": 0.00, "z": 0.50,
|
||||
"a": 0.0, "b": 3.14159, "c": 0.0,
|
||||
"speed": 0.1, "planner": "ptp", "frame_id": ""
|
||||
}'
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
target = {
|
||||
"x": 0.40, "y": 0.00, "z": 0.50,
|
||||
"a": 0.0, "b": 3.14159, "c": 0.0,
|
||||
"speed": 0.1, "planner": "ptp", "frame_id": "",
|
||||
}
|
||||
response = httpx.post(f"{HOST}/robot/move/pose", json=target, timeout=T_MOVE)
|
||||
response.raise_for_status()
|
||||
print(response.json())
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
body = struct( ...
|
||||
'x', 0.40, 'y', 0.00, 'z', 0.50, ...
|
||||
'a', 0.0, 'b', pi, 'c', 0.0, ...
|
||||
'speed', 0.1, 'planner', 'ptp', 'frame_id', '');
|
||||
reply = webwrite([HOST '/robot/move/pose'], body, moveOpts);
|
||||
assert(reply.success, reply.message)
|
||||
~~~
|
||||
|
||||
### Moving by joint angles
|
||||
|
||||
POST **/robot/move/joints** accepts exactly seven angles in J1–J7 order. The API validates the number of values and the current limits from **joint_limits.yaml**.
|
||||
|
||||
| Joint | Allowed angle, rad |
|
||||
|---|---:|
|
||||
| J1 | -2.97 to 2.97 |
|
||||
| J2 | -2.10 to 2.10 |
|
||||
| J3 | -2.97 to 2.97 |
|
||||
| J4 | -2.10 to 2.10 |
|
||||
| J5 | -2.97 to 2.97 |
|
||||
| J6 | -2.10 to 2.10 |
|
||||
| J7 | -3.05 to 3.05 |
|
||||
|
||||
If the limits file changes, use Swagger UI as the reference. The table above describes the supplied configuration.
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS --max-time 60 -X POST $HOST/robot/move/joints \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"joints": [0.0, 0.5, 0.0, -1.57, 0.0, 1.57, 0.0], "speed": 0.1}'
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
response = httpx.post(
|
||||
f"{HOST}/robot/move/joints",
|
||||
json={
|
||||
"joints": [0.0, 0.5, 0.0, -1.57, 0.0, 1.57, 0.0],
|
||||
"speed": 0.1,
|
||||
},
|
||||
timeout=T_MOVE,
|
||||
)
|
||||
response.raise_for_status()
|
||||
print(response.json())
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
body = struct( ...
|
||||
'joints', [0.0, 0.5, 0.0, -1.57, 0.0, 1.57, 0.0], ...
|
||||
'speed', 0.1);
|
||||
reply = webwrite([HOST '/robot/move/joints'], body, moveOpts);
|
||||
assert(reply.success, reply.message)
|
||||
~~~
|
||||
|
||||
## Joint trajectories
|
||||
|
||||
Endpoints under **/trajectory** publish a `JointTrajectory` message directly to **/iiwa_arm_controller/joint_trajectory**. A **status: sent** response confirms publication, not completion of motion or absence of controller errors. Monitor **/robot/joint_states** and inspect **/trajectory/logs** when necessary.
|
||||
|
||||
### JSON trajectory
|
||||
|
||||
POST **/trajectory/send** accepts one or more points.
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| points | Non-empty point list |
|
||||
| points[].positions | Exactly 7 J1–J7 angles in radians |
|
||||
| points[].time_from_start | Time from trajectory start in seconds, at least 0 |
|
||||
| validate_limits | Validate joint limits; default: true |
|
||||
|
||||
The server does not check that time increases between points. Set increasing values yourself to make controller behavior predictable.
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS --max-time 20 -X POST $HOST/trajectory/send \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"points": [
|
||||
{"positions": [0, 0, 0, 0, 0, 0, 0], "time_from_start": 0.0},
|
||||
{"positions": [0, 0.5, 0, -1.0, 0, 1.0, 0], "time_from_start": 3.0},
|
||||
{"positions": [0, 0, 0, 0, 0, 0, 0], "time_from_start": 6.0}
|
||||
],
|
||||
"validate_limits": true
|
||||
}'
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
trajectory = {
|
||||
"points": [
|
||||
{"positions": [0.0] * 7, "time_from_start": 0.0},
|
||||
{"positions": [0.0, 0.5, 0.0, -1.0, 0.0, 1.0, 0.0], "time_from_start": 3.0},
|
||||
{"positions": [0.0] * 7, "time_from_start": 6.0},
|
||||
],
|
||||
"validate_limits": True,
|
||||
}
|
||||
response = httpx.post(f"{HOST}/trajectory/send", json=trajectory, timeout=T_READ)
|
||||
response.raise_for_status()
|
||||
print(response.json())
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
p1 = struct('positions', [0, 0, 0, 0, 0, 0, 0], ...
|
||||
'time_from_start', 0.0);
|
||||
p2 = struct('positions', [0, 0.5, 0, -1.0, 0, 1.0, 0], ...
|
||||
'time_from_start', 3.0);
|
||||
trajectory.points = [p1, p2];
|
||||
trajectory.validate_limits = true;
|
||||
|
||||
opts = weboptions('MediaType', 'application/json', 'Timeout', T_READ);
|
||||
reply = webwrite([HOST '/trajectory/send'], trajectory, opts);
|
||||
disp(reply)
|
||||
~~~
|
||||
|
||||
### Uploading CSV
|
||||
|
||||
POST **/trajectory/send_csv** accepts a CSV file in the multipart **file** field. The first row must be a header. Joint columns may be named **joint1** or **joint_1**, case-insensitively. The time column may be named **t**, **time**, or **time_from_start**. Columns may appear in any order.
|
||||
|
||||
Example file:
|
||||
|
||||
~~~ csv
|
||||
joint1,joint2,joint3,joint4,joint5,joint6,joint7,t
|
||||
0,0,0,0,0,0,0,0.0
|
||||
0,0.5,0,-1.0,0,1.0,0,3.0
|
||||
~~~
|
||||
|
||||
Pass **separator** and **validate_limits** in the query string, not as form fields. The default separator is a comma and limit validation is enabled.
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS --max-time 20 -X POST \
|
||||
"$HOST/trajectory/send_csv?separator=%2C&validate_limits=true" \
|
||||
-F "file=@trajectory.csv;type=text/csv"
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
with open("trajectory.csv", "rb") as csv_file:
|
||||
response = httpx.post(
|
||||
f"{HOST}/trajectory/send_csv",
|
||||
params={"separator": ",", "validate_limits": True},
|
||||
files={"file": ("trajectory.csv", csv_file, "text/csv")},
|
||||
timeout=T_READ,
|
||||
)
|
||||
response.raise_for_status()
|
||||
print(response.json())
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
import matlab.net.http.*
|
||||
import matlab.net.http.io.*
|
||||
|
||||
uri = URI([HOST '/trajectory/send_csv?separator=%2C&validate_limits=true']);
|
||||
form = MultipartFormProvider('file', FileProvider('trajectory.csv'));
|
||||
request = RequestMessage('post', [], form);
|
||||
httpOpts = HTTPOptions('ConnectTimeout', T_READ, 'ResponseTimeout', T_READ);
|
||||
response = request.send(uri, httpOpts);
|
||||
|
||||
disp(response.Body.Data)
|
||||
~~~
|
||||
|
||||
For a semicolon-delimited file, replace `%2C` with `%3B`.
|
||||
|
||||
### Trajectory module log
|
||||
|
||||
GET **/trajectory/logs?n=50** returns up to 300 latest entries. The **n** parameter must be between 1 and 300.
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS "$HOST/trajectory/logs?n=20" | python3 -m json.tool
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
response = httpx.get(f"{HOST}/trajectory/logs", params={"n": 20}, timeout=T_READ)
|
||||
response.raise_for_status()
|
||||
for line in response.json()["lines"]:
|
||||
print(line)
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
logs = webread([HOST '/trajectory/logs?n=20'], readOpts);
|
||||
disp(logs.lines)
|
||||
~~~
|
||||
|
||||
Use the common **POST /stop** endpoint to interrupt a trajectory. The API has no **/trajectory/stop** endpoint.
|
||||
|
||||
## Motion sequences
|
||||
|
||||
POST **/sequences/start** launches a separate `motion_sequence_runner` process. It reads the uploaded JSON file and sends `MoveToJoints` or `MoveToPose` targets in sequence.
|
||||
|
||||
| Form field | Default | Purpose |
|
||||
|---|---:|---|
|
||||
| config | — | Sequence JSON file; required |
|
||||
| n_iterations | 3 | Number of repetitions; at least 1 |
|
||||
| delay_between_iterations | 5.0 | Delay between iterations, s |
|
||||
| bag_path | empty | rosbag output path; an empty string disables recording |
|
||||
| topics | empty | Comma-separated rosbag topics; empty means all discovered topics |
|
||||
| joints_action | cobot/move_to_joints | Action name for joint targets |
|
||||
| pose_action | cobot/move_to_pose | Action name for Cartesian targets |
|
||||
|
||||
Minimal configuration:
|
||||
|
||||
~~~ json
|
||||
{
|
||||
"home": {
|
||||
"joints": [0, 0, 0, -1.57, 0, 1.57, 0],
|
||||
"speed": 0.1
|
||||
},
|
||||
"waypoints": [
|
||||
{
|
||||
"x": 0.6, "y": 0.1, "z": 0.55,
|
||||
"a": 3.14, "b": 0.31, "c": 2.79,
|
||||
"speed": 0.2, "planner": "lin"
|
||||
},
|
||||
{
|
||||
"joints": [0.5, 0.3, 0, -1.2, 0, 1.4, 0],
|
||||
"speed": 0.2
|
||||
}
|
||||
]
|
||||
}
|
||||
~~~
|
||||
|
||||
A point containing **joints** is treated as a joint target. Otherwise, the runner expects Cartesian fields **x**, **y**, **z**, **a**, **b**, and **c**.
|
||||
|
||||
### Starting a sequence
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS --max-time 10 -X POST $HOST/sequences/start \
|
||||
-F "config=@motion_sequence_config.json;type=application/json" \
|
||||
-F "n_iterations=3" \
|
||||
-F "delay_between_iterations=5.0"
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
with open("motion_sequence_config.json", "rb") as config:
|
||||
response = httpx.post(
|
||||
f"{HOST}/sequences/start",
|
||||
files={"config": ("motion_sequence_config.json", config, "application/json")},
|
||||
data={"n_iterations": "3", "delay_between_iterations": "5.0"},
|
||||
timeout=T_READ,
|
||||
)
|
||||
response.raise_for_status()
|
||||
print(response.json())
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
import matlab.net.http.*
|
||||
import matlab.net.http.io.*
|
||||
|
||||
form = MultipartFormProvider( ...
|
||||
'config', FileProvider('motion_sequence_config.json'), ...
|
||||
'n_iterations', '3', ...
|
||||
'delay_between_iterations', '5.0');
|
||||
request = RequestMessage('post', [], form);
|
||||
httpOpts = HTTPOptions('ConnectTimeout', T_READ, 'ResponseTimeout', T_READ);
|
||||
response = request.send(URI([HOST '/sequences/start']), httpOpts);
|
||||
|
||||
disp(response.Body.Data)
|
||||
~~~
|
||||
|
||||
A **status: started** response confirms that the process started, not that the JSON is valid or that every motion succeeds. If the runner exits with an error, inspect its status and log.
|
||||
|
||||
### Sequence status and log
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS $HOST/sequences/status | python3 -m json.tool
|
||||
curl -sS "$HOST/sequences/logs?n=50" | python3 -m json.tool
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
status = httpx.get(f"{HOST}/sequences/status", timeout=T_READ)
|
||||
status.raise_for_status()
|
||||
print(status.json())
|
||||
|
||||
logs = httpx.get(f"{HOST}/sequences/logs", params={"n": 50}, timeout=T_READ)
|
||||
logs.raise_for_status()
|
||||
for line in logs.json()["lines"]:
|
||||
print(line)
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
status = webread([HOST '/sequences/status'], readOpts);
|
||||
logs = webread([HOST '/sequences/logs?n=50'], readOpts);
|
||||
disp(status)
|
||||
disp(logs.lines)
|
||||
~~~
|
||||
|
||||
Statuses:
|
||||
|
||||
- **idle** — no sequence has been started;
|
||||
- **running** — the process is running;
|
||||
- **finished** — the process has exited; the response includes **returncode**.
|
||||
|
||||
Only one sequence can run at a time. A second POST to **/sequences/start** while one is running returns 409. Use **POST /stop** to stop it; there is no separate **/sequences/stop** endpoint.
|
||||
|
||||
## Common stop command
|
||||
|
||||
POST **/stop** stops the running sequence runner, publishes a hold point at the current position to the trajectory controller, and calls the MoveIt **cobot/stop** service. If current joint states are unavailable, it publishes an empty trajectory instead.
|
||||
|
||||
=== "curl"
|
||||
|
||||
~~~ bash
|
||||
curl -sS --max-time 10 -X POST $HOST/stop | python3 -m json.tool
|
||||
~~~
|
||||
|
||||
=== "Python"
|
||||
|
||||
~~~ python
|
||||
response = httpx.post(f"{HOST}/stop", timeout=T_READ)
|
||||
response.raise_for_status()
|
||||
print(response.json())
|
||||
~~~
|
||||
|
||||
=== "MATLAB"
|
||||
|
||||
~~~ matlab
|
||||
reply = webwrite([HOST '/stop'], struct(), ...
|
||||
weboptions('MediaType', 'application/json', 'Timeout', T_READ));
|
||||
disp(reply)
|
||||
~~~
|
||||
|
||||
This command cancels software operations, but does not remove robot power or replace the standard emergency stop. After calling it, verify both the response message and the physical robot state.
|
||||
|
||||
## Errors and diagnostics
|
||||
|
||||
| Code | When it occurs |
|
||||
|---:|---|
|
||||
| 200 | The request was processed; for motion commands, also check the success field |
|
||||
| 409 | A motion sequence is already running |
|
||||
| 422 | Invalid request structure, joint count, speed, planner, or joint limits |
|
||||
| 503 | A ROS topic, service, action server, or MoveIt is unavailable; a wait timeout may also have occurred |
|
||||
|
||||
When troubleshooting, proceed from simple checks to more complex ones:
|
||||
|
||||
1. Open **/docs** and verify that the server is running and the endpoint appears in the schema.
|
||||
2. Check **/robot/joint_states**. Without it, pose retrieval does not work and trajectory stopping cannot generate a hold point.
|
||||
3. Make sure that the complete stack is running: `controller_manager`, MoveIt, and `iiwa_motion_server`.
|
||||
4. After starting a sequence, inspect **/sequences/logs**. After publishing a trajectory, inspect **/trajectory/logs**.
|
||||
|
||||
The MCP server runs in the same process but provides a separate interface at **http://server-address:8007/mcp/mcp**. For ordinary HTTP integrations, use the endpoints documented on this page.
|
||||
@@ -0,0 +1,11 @@
|
||||
# Control via ROS 2
|
||||
|
||||
!!! info "Work in progress"
|
||||
Detailed instructions for control through ROS 2 topics and action servers are being prepared.
|
||||
|
||||
This method sends commands directly to ROS 2 using CLI tools (`ros2 topic pub`, `ros2 action send_goal`) or custom ROS 2 nodes written in Python or C++.
|
||||
|
||||
## Additional resources
|
||||
|
||||
- [ROS 2 Jazzy documentation](https://docs.ros.org/en/jazzy/index.html) — official documentation for topics, services, action servers, and node development
|
||||
- [MATLAB Robotics System Toolbox](https://www.mathworks.com/help/ros/index.html?s_tid=CRUX_lftnav) — control the robot through ROS 2 from MATLAB
|
||||
@@ -0,0 +1,24 @@
|
||||
# Getting started
|
||||
|
||||
This section explains how to prepare the environment, connect to the controller, install the project, and start controlling the robot.
|
||||
|
||||
## Quick start
|
||||
|
||||
1. [**Sunrise Workbench setup**](sunrise-setup.md) — prepare the KUKA controller, upload `ServerFriRos2`, and configure the network. *(Physical robot only.)*
|
||||
2. [**Connect to the server**](remote-access.md) — choose local or remote deployment and connect to the control server over SSH.
|
||||
3. [**Install the project**](installation.md) — install LWC using `curl`, `git`, or manually.
|
||||
4. [**Configure the system**](configuration.md) — configure `cobot-setting.yaml` with the robot IP, ports, and tools.
|
||||
5. [**cobot CLI**](cli-reference.md) — learn the commands for running, building, and updating the project.
|
||||
|
||||
!!! tip "Simulation only?"
|
||||
Skip the physical-controller setup and run `cobot run --simulate` after installation.
|
||||
|
||||
## Concepts and control
|
||||
|
||||
- [System architecture](concepts/architecture.md)
|
||||
- [FRI protocol](concepts/fri-protocol.md)
|
||||
- [Webots simulation](concepts/simulation.md)
|
||||
- [Motion planning](concepts/motion-planning.md)
|
||||
- [ROS 2 Control](control/ros2-control.md)
|
||||
- [Foxglove](control/foxglove.md)
|
||||
- [REST API](control/rest-api.md)
|
||||
@@ -0,0 +1,114 @@
|
||||
# Project installation
|
||||
|
||||
## Quick installation
|
||||
|
||||
The easiest option is to install the project with a single `curl` command. Make sure that `curl` is installed:
|
||||
|
||||
```bash
|
||||
sudo apt update && sudo apt upgrade -y && sudo apt install curl
|
||||
```
|
||||
|
||||
Go to your home directory and run the installation script:
|
||||
|
||||
=== "Stable version (master)"
|
||||
|
||||
```bash
|
||||
cd ~
|
||||
curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/install.sh | bash
|
||||
```
|
||||
|
||||
=== "Development version (dev)"
|
||||
|
||||
```bash
|
||||
cd ~
|
||||
curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/dev/install.sh | bash -s dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation with Git
|
||||
|
||||
The project is available on both [GitVerse](https://gitverse.ru/daniel-robotics/lightweight-cobot) (preferred) and [GitHub](https://github.com/Daniel-Robotic/lightweight-cobot).
|
||||
|
||||
!!! tip "New to Git?"
|
||||
If this is your first time using Git and GitHub, see the [GitHub getting-started guide](https://docs.github.com/en/get-started/start-your-journey/hello-world).
|
||||
|
||||
Clone the repository and run the installation script:
|
||||
|
||||
=== "GitVerse"
|
||||
|
||||
```bash
|
||||
cd ~
|
||||
git clone https://gitverse.ru/daniel-robotics/lightweight-cobot.git
|
||||
cd ~/lightweight-cobot
|
||||
sudo chmod +x ./install.sh
|
||||
./install.sh
|
||||
```
|
||||
|
||||
=== "GitHub"
|
||||
|
||||
```bash
|
||||
cd ~
|
||||
git clone https://github.com/Daniel-Robotic/lightweight-cobot.git
|
||||
cd ~/lightweight-cobot
|
||||
sudo chmod +x ./install.sh
|
||||
./install.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Manual installation
|
||||
|
||||
If neither `curl` nor `git` is available, download the project archive manually from the repository page using the **Download ZIP** button, extract it, and run:
|
||||
|
||||
```bash
|
||||
cd ~/lightweight-cobot
|
||||
sudo chmod +x ./install.sh
|
||||
./install.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation process
|
||||
|
||||
The [`install.sh`](https://gitverse.ru/daniel-robotics/lightweight-cobot/raw/branch/master/install.sh) script automatically installs:
|
||||
|
||||
- **Git** — version control system;
|
||||
- **Docker** — containerization for isolated execution;
|
||||
- **`cobot` CLI** — the main project management tool;
|
||||
- Ubuntu system dependencies.
|
||||
|
||||
### Restarting after installation
|
||||
|
||||
After the script finishes, a restart may be required for Docker to work:
|
||||
|
||||
```bash
|
||||
sudo reboot now
|
||||
```
|
||||
|
||||
Watch the terminal output: the script will indicate whether a restart is required.
|
||||
|
||||
### If the log is empty
|
||||
|
||||
If the script produces no output, reload the Bash environment and continue setup manually:
|
||||
|
||||
```bash
|
||||
source ~/.bashrc # refresh environment variables
|
||||
cobot setup # continue system setup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verifying the installation
|
||||
|
||||
After installation, make sure that `cobot` is available:
|
||||
|
||||
```bash
|
||||
cobot -h
|
||||
```
|
||||
|
||||
If the command displays the list of available subcommands, installation was successful.
|
||||
|
||||
---
|
||||
|
||||
**Next step:** [System configuration](configuration.md)
|
||||
@@ -0,0 +1,76 @@
|
||||
# Connecting to the server
|
||||
|
||||
## Deployment options
|
||||
|
||||
The project can be deployed in two ways:
|
||||
|
||||
| Option | Description | When to use it |
|
||||
|---|---|---|
|
||||
| **Local** | Install on your PC | Development, simulation, and debugging |
|
||||
| **Remote (server)** | Install on a dedicated server connected to the KUKA controller | Working with the physical robot |
|
||||
|
||||
With remote deployment, you control the server from your PC over an **SSH connection**.
|
||||
|
||||
---
|
||||
|
||||
## SSH clients
|
||||
|
||||
Choose any of the following applications:
|
||||
|
||||
- [**Termius**](https://termius.com/) — cross-platform SSH client with a convenient GUI;
|
||||
- [**MobaXterm**](https://mobaxterm.mobatek.net/) — multifunctional terminal for Windows;
|
||||
- [**PuTTY**](https://putty.software/) — classic SSH client for Windows;
|
||||
- the **built-in terminal or command prompt**, as described below.
|
||||
|
||||
For instructions on configuring Termius, MobaXterm, or PuTTY, refer to their official documentation.
|
||||
|
||||
---
|
||||
|
||||
## Connection details
|
||||
|
||||
```
|
||||
IP address: 192.168.21.1
|
||||
Username: cobot
|
||||
Password: 12345678
|
||||
```
|
||||
|
||||
!!! warning "Network requirement"
|
||||
Your PC must be on the **same network/subnet as the robot** (for example, the KnASU network). Otherwise, the connection cannot be established.
|
||||
|
||||
---
|
||||
|
||||
## Connecting from the built-in terminal
|
||||
|
||||
=== "Linux"
|
||||
|
||||
Any distribution can be used. Open a terminal and run:
|
||||
|
||||
```bash
|
||||
ssh cobot@192.168.21.1
|
||||
```
|
||||
|
||||
=== "Windows"
|
||||
|
||||
**Windows 10** or later is required for the built-in SSH client. Open **Command Prompt** or **PowerShell** and run:
|
||||
|
||||
```powershell
|
||||
ssh cobot@192.168.21.1
|
||||
```
|
||||
|
||||
The command will prompt for a password:
|
||||
|
||||
```
|
||||
cobot@192.168.21.1's password:
|
||||
```
|
||||
|
||||
Enter `12345678`. Characters are not displayed while you type; this is normal security behavior. Press ++enter++.
|
||||
|
||||
After a successful connection, the server command prompt appears:
|
||||
|
||||
```
|
||||
cobot@server:~$
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Next step:** [Project installation](installation.md)
|
||||
@@ -0,0 +1,85 @@
|
||||
# SunriseWorkbench setup
|
||||
|
||||
!!! info "Physical robot only"
|
||||
This section applies only when working with a physical KUKA LBR IIWA 7. For simulation, proceed to [Project installation](installation.md).
|
||||
|
||||
---
|
||||
|
||||
## Physical hardware setup
|
||||
|
||||
### Ethernet connection
|
||||
|
||||
Connect an Ethernet cable from your PC or control server to one of the KUKA controller's network ports:
|
||||
|
||||
- **KLI** (KUKA Line Interface) — the primary port used for control and programming;
|
||||
- **KONI** (KUKA Optional Network Interface) — the additional port used for FRI.
|
||||
|
||||
Both ports can be connected at the same time. You can select the interface when configuring the server.
|
||||
|
||||
> Connect the KLI and KONI ports according to the KUKA controller wiring diagram.
|
||||
|
||||
---
|
||||
|
||||
## Synchronizing the SunriseWorkbench project
|
||||
|
||||
### Checking for ServerFriRos2
|
||||
|
||||
Make sure that your Sunrise project contains `ServerFriRos2.java`. If the file is missing, download it from the repository. Its path is `src/iiwa_sunrise/src/ServerFriRos2.java`.
|
||||
|
||||
=== "curl"
|
||||
|
||||
```bash
|
||||
curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/src/iiwa_sunrise/src/ServerFriRos2.java \
|
||||
-o ServerFriRos2.java
|
||||
```
|
||||
|
||||
=== "wget"
|
||||
|
||||
```bash
|
||||
wget -O ServerFriRos2.java \
|
||||
https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/src/iiwa_sunrise/src/ServerFriRos2.java
|
||||
```
|
||||
|
||||
After downloading it, add the file to the Sunrise project and synchronize the project with the controller.
|
||||
|
||||
### Synchronizing with the controller
|
||||
|
||||
Open **SunriseWorkbench** and click the project synchronization button:
|
||||
|
||||
> In SunriseWorkbench, use the project synchronization button.
|
||||
|
||||
Before synchronizing, make sure that the PC and KUKA controller are on the same network. The current controller network settings can be checked directly in SunriseWorkbench:
|
||||
|
||||
> The controller network parameters are available in the SunriseWorkbench settings window.
|
||||
|
||||
---
|
||||
|
||||
## Configuring ServerFriRos2
|
||||
|
||||
Open `ServerFriRos2.java` in SunriseWorkbench and change the following parameters to match your network configuration:
|
||||
|
||||
```java
|
||||
// IP address of the KONI interface
|
||||
KONI_IP = "192.170.10.10";
|
||||
|
||||
// IP address of the KLI interface
|
||||
KLI_IP = "192.168.21.31";
|
||||
|
||||
// Zero position (all joints at 0°)
|
||||
ZERO_POSITION = {0, 0, 0, 0, 0, 0, 0};
|
||||
|
||||
// Working position for monitoring
|
||||
MONITOR_WORKING_POSITION = {0, 0, 0, -1.57, 0, 1.57, 0};
|
||||
|
||||
// Tool used by default
|
||||
@Named("tool1")
|
||||
```
|
||||
|
||||
!!! warning "Important"
|
||||
`KONI_IP` and `KLI_IP` in the Java program are addresses of the ROS 2 computer that the controller can reach through the corresponding networks. Conversely, `robot.ip` in `cobot-setting.yaml` is the address of the KUKA controller as seen from the computer. Incorrect or swapped addresses prevent the FRI connection from being established.
|
||||
|
||||
After making the changes, synchronize the project with the controller again.
|
||||
|
||||
---
|
||||
|
||||
**Next step:** [Connecting to the control server](remote-access.md)
|
||||
@@ -17,7 +17,7 @@
|
||||
|
||||
Вы можете подключить оба порта одновременно — при конфигурации сервера будет выбор, какой интерфейс использовать.
|
||||
|
||||
|
||||
> Подключите порты KLI и KONI согласно схеме подключения контроллера KUKA.
|
||||
|
||||
---
|
||||
|
||||
@@ -48,11 +48,11 @@
|
||||
|
||||
Откройте **SunriseWorkbench** и нажмите кнопку синхронизации проекта:
|
||||
|
||||
|
||||
> В SunriseWorkbench используйте кнопку синхронизации проекта.
|
||||
|
||||
Перед синхронизацией убедитесь, что ПК и контроллер KUKA находятся в одной сети. Текущие сетевые параметры контроллера можно быстро проверить прямо в SunriseWorkbench:
|
||||
|
||||
|
||||
> Сетевые параметры контроллера доступны в окне настроек SunriseWorkbench.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
hide:
|
||||
- navigation
|
||||
- toc
|
||||
- footer
|
||||
---
|
||||
|
||||
<meta http-equiv="refresh" content="0; url=./getting-started/">
|
||||
# Overview
|
||||
|
||||
**Lightweight Cobot (LWC)** is an open system for controlling the **KUKA LBR IIWA 7 R800** collaborative robot based on **ROS 2 Jazzy**. It supports both a physical robot through the FRI protocol and a virtual Webots simulation. The project includes the `cobot` CLI, a ROS 2 Control hardware interface, MoveIt 2 motion planning, and REST/MCP APIs for AI-agent integration.
|
||||
|
||||
## Repositories
|
||||
|
||||
| Platform | Link | Status |
|
||||
|---|---|---|
|
||||
| **GitVerse** (preferred) | [daniel-robotics/lightweight-cobot](https://gitverse.ru/daniel-robotics/lightweight-cobot) | primary |
|
||||
| GitHub | [Daniel-Robotic/lightweight-cobot](https://github.com/Daniel-Robotic/lightweight-cobot) | mirror |
|
||||
|
||||
## Online documentation
|
||||
|
||||
- [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot) — primary
|
||||
- [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/) — mirror
|
||||
|
||||
## Requirements
|
||||
|
||||
- A physical **KUKA LBR IIWA 7 R800** for real-robot operation, or
|
||||
- **Webots** if you only want to use simulation;
|
||||
- A PC or server running **Ubuntu 24.04**, or SSH access to an existing server;
|
||||
- Network access to the robot controller.
|
||||
|
||||
## Recommended order
|
||||
|
||||
1. [**Sunrise Workbench setup**](getting-started/sunrise-setup.md) — prepare the KUKA controller. *(Physical robot only.)*
|
||||
2. [**Connect to the server**](getting-started/remote-access.md) — choose local or remote deployment and connect over SSH.
|
||||
3. [**Install the project**](getting-started/installation.md) — install LWC using `curl`, `git`, or manually, then run `cobot setup`.
|
||||
4. [**Configure the system**](getting-started/configuration.md) — set the robot IP, ports, and tools in `cobot-setting.yaml`.
|
||||
5. [**cobot CLI**](getting-started/cli-reference.md) — review commands for running, building, and updating the project.
|
||||
|
||||
!!! tip "Simulation only?"
|
||||
If a physical robot is unavailable, skip step 1 and start with the [project installation](getting-started/installation.md). Launch the simulator with `cobot run --simulate`.
|
||||
|
||||
!!! info "`cobot setup` automates steps 3–4"
|
||||
After installing the project, run `cobot setup`. The wizard will configure the documentation, robot parameters, and the ROS 2 or Docker build environment.
|
||||
@@ -0,0 +1,85 @@
|
||||
# Installing libraries
|
||||
|
||||
Additional libraries distributed as `.zip` archives must be installed for the SunriseWorkbench project to work fully.
|
||||
|
||||
!!! note "Prerequisite"
|
||||
Before installing the libraries, make sure that the project has been created or loaded. See [Creating a new project](new-project.md) or [Loading an existing project](load-project.md).
|
||||
|
||||
## Opening the settings
|
||||
|
||||
In the SunriseWorkbench main menu, select **Window → Preferences**. In the window that opens, go to **Install/Update → Available Software Sites**.
|
||||
|
||||
|
||||
|
||||
## Adding library archives
|
||||
|
||||
Click **Add**. In the dialog, click **Archive...** and add a library `.zip` archive.
|
||||
|
||||
|
||||
|
||||
### Windows users
|
||||
|
||||
Use the standard file-selection dialog to locate and select the archive.
|
||||
|
||||
### Linux users
|
||||
|
||||
Because SunriseWorkbench runs in an emulated Windows environment, use the following procedure to access the Linux file system:
|
||||
|
||||
1. In the file-selection dialog, click **Look in:** and select **My Computer**.
|
||||
|
||||
|
||||
|
||||
2. A list of mounted drives appears. It may contain more entries than the number of physical drives because of how the compatibility environment works.
|
||||
|
||||
|
||||
|
||||
3. Check each drive in turn. One of them contains the Linux file system (drive H in this example).
|
||||
|
||||
|
||||
|
||||
4. Open the directory containing the libraries, select one of the `.zip` archives, and click **OK**.
|
||||
|
||||
|
||||
|
||||
5. Confirm the selected archive by clicking **OK** in the next window.
|
||||
|
||||
|
||||
|
||||
## Adding the remaining archives
|
||||
|
||||
The archive appears in the **Available Software Sites** list. Repeat the procedure for every remaining library `.zip` file.
|
||||
|
||||
|
||||
|
||||
After adding all archives, click **OK** to save the settings.
|
||||
|
||||
## Installing the libraries
|
||||
|
||||
Select **Help → Install New Software...** from the menu. In the **Work with** field, select **All Available Sites**. Components from all added archives appear in the list.
|
||||
|
||||
|
||||
|
||||
Select every available component and click **Next**. Review the installation summary and click **Next** again.
|
||||
|
||||
|
||||
|
||||
Accept the license agreements and click **Finish** to begin installation.
|
||||
|
||||
|
||||
|
||||
!!! warning "Installation duration"
|
||||
Installing the libraries may take a significant amount of time. Do not interrupt the process.
|
||||
|
||||
|
||||
## Restarting the application
|
||||
|
||||
When installation finishes, SunriseWorkbench prompts you to restart. Click **Restart Now**.
|
||||
|
||||
|
||||
|
||||
After the restart, the interface switches to Russian and all installed libraries appear in `StationSetup.cat`.
|
||||
|
||||
|
||||
|
||||
!!! tip "Next step"
|
||||
If the project has not yet been configured, see [Creating a new project](new-project.md) or [Loading an existing project](load-project.md).
|
||||
@@ -0,0 +1,30 @@
|
||||
# Loading a project from the controller
|
||||
|
||||
This section explains how to import an existing project directly from the KUKA controller into SunriseWorkbench.
|
||||
|
||||
!!! note "Prerequisite"
|
||||
Make sure that SunriseWorkbench is installed and running. See the [Windows](../sun_install/windows.md) and [Linux](../sun_install/linux/linux.md) installation guides.
|
||||
|
||||
## Starting the project import wizard
|
||||
|
||||
In the main SunriseWorkbench window, click **New Sunrise Project**.
|
||||
|
||||
|
||||
|
||||
In the dialog that opens, select **Load project from controller** and enter the IP address of the KUKA Sunrise Cabinet controller.
|
||||
|
||||
|
||||
|
||||
!!! info "Controller IP address"
|
||||
The default controller IP address is `172.31.1.147`. If the controller has been reconfigured, enter its current address. This configuration uses `192.168.21.147`. To find the current address, see [Station configuration](../kuka/features/station.md).
|
||||
|
||||
Click **Next** to begin downloading the project from the controller.
|
||||
|
||||
|
||||
|
||||
When the download is complete, the imported project appears in the SunriseWorkbench project tree. In this example, the project is named `SunriseProject`.
|
||||
|
||||
|
||||
|
||||
!!! tip "Next step"
|
||||
All required libraries must be installed for full robot operation. See [Installing libraries](libraries.md).
|
||||
@@ -3,7 +3,7 @@
|
||||
В данном разделе описана процедура импорта существующего проекта непосредственно с контроллера KUKA в среду SunriseWorkbench.
|
||||
|
||||
!!! note "Предварительное требование"
|
||||
Убедитесь, что SunriseWorkbench установлен и запущен. Инструкции по установке приведены в разделах [Windows](../install/windows.md) и [Linux](../install/linux/linux.md).
|
||||
Убедитесь, что SunriseWorkbench установлен и запущен. Инструкции по установке приведены в разделах [Windows](../sun_install/windows.md) и [Linux](../sun_install/linux/linux.md).
|
||||
|
||||
## Запуск мастера импорта проекта
|
||||
|
||||
@@ -27,4 +27,4 @@
|
||||
|
||||
|
||||
!!! tip "Следующий шаг"
|
||||
Для полноценной работы с роботом необходимо установить все требуемые библиотеки. Инструкции приведены в разделе [Установка библиотек](libraries.md).
|
||||
Для полноценной работы с роботом необходимо установить все требуемые библиотеки. Инструкции приведены в разделе [Установка библиотек](libraries.md).
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
# Creating a new project
|
||||
|
||||
This section explains how to create a SunriseWorkbench project and perform the initial configuration for a KUKA LBR IIWA 7.
|
||||
|
||||
!!! note "Prerequisite"
|
||||
Before creating a project, make sure that SunriseWorkbench is installed. See the [Windows](../sun_install/windows.md) and [Linux](../sun_install/linux/linux.md) installation guides.
|
||||
|
||||
## Starting the new-project wizard
|
||||
|
||||
In the main SunriseWorkbench window, click **New Sunrise Project**.
|
||||
|
||||
|
||||
|
||||
## Configuring the controller connection
|
||||
|
||||
Enter the IP address of the KUKA Sunrise Cabinet controller in the dialog.
|
||||
|
||||
|
||||
|
||||
!!! warning "Controller IP address"
|
||||
The default controller IP address is `172.31.1.147`. If your configuration uses a different address, replace it with the current value.
|
||||
|
||||
## Project name
|
||||
|
||||
Enter the project name in the corresponding field.
|
||||
|
||||
|
||||
|
||||
## Selecting the robot model
|
||||
|
||||
Select the robot model from the drop-down list. For a KUKA LBR IIWA 7, choose **LBR iiwa 7 R800**.
|
||||
|
||||
|
||||
|
||||
## Selecting the flange
|
||||
|
||||
Select the flange type that matches your robot configuration.
|
||||
|
||||
|
||||
|
||||
!!! warning "Flange selection"
|
||||
The flange type must exactly match the physical robot configuration. This setup uses **Medien-Flansch elektrisch**. Leave its orientation at the default value of 0°.
|
||||
|
||||
## Reviewing the configuration
|
||||
|
||||
Review all parameters in the summary window. If they are correct, click **Finish**.
|
||||
|
||||
|
||||
|
||||
## Selecting an application template
|
||||
|
||||
After the project is created, the template selection dialog opens. Select one of the examples and click **Finish**.
|
||||
|
||||
|
||||
|
||||
## Main editor window
|
||||
|
||||
After the wizard completes successfully, SunriseWorkbench opens the new project in its main editor window.
|
||||
|
||||
|
||||
|
||||
!!! tip "Next step"
|
||||
All required libraries must be installed for full robot operation. See [Installing libraries](libraries.md).
|
||||
@@ -3,7 +3,7 @@
|
||||
В данном разделе описан процесс создания нового проекта в SunriseWorkbench и его первоначальная конфигурация для работы с роботом KUKA LBR IIWA 7.
|
||||
|
||||
!!! note "Предварительное требование"
|
||||
Перед созданием проекта убедитесь, что SunriseWorkbench установлен. Инструкции по установке приведены в разделах [Windows](../install/windows.md) и [Linux](../install/linux/linux.md).
|
||||
Перед созданием проекта убедитесь, что SunriseWorkbench установлен. Инструкции по установке приведены в разделах [Windows](../sun_install/windows.md) и [Linux](../sun_install/linux/linux.md).
|
||||
|
||||
## Запуск мастера создания проекта
|
||||
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# Applications
|
||||
|
||||
The **Applications** section lets you select and control programs developed in SunriseWorkbench and deployed to the controller. Open it with the **Applications** button in the smartHMI navigation bar.
|
||||
|
||||
## Application list
|
||||
|
||||
The application selection page has two columns:
|
||||
|
||||
| Column | Description |
|
||||
|---|---|
|
||||
| Robot applications | Control programs started manually by the operator |
|
||||
| Background applications | Programs that run automatically as a `backgroundTask` |
|
||||
|
||||
Each list entry contains:
|
||||
|
||||
- a **status indicator** — the colored dot to the left of the name;
|
||||
- the **application name** — the Java class name;
|
||||
- the **package** — namespace or category such as `[application]`, `[ros]`, or `[demo]`;
|
||||
- a **checkbox** — used to select or deactivate the application.
|
||||
|
||||
|
||||
|
||||
The **Reset selected robot application** button (hand icon) clears the active application selection without stopping it. Running background applications are shown with a green dot and a **Stop** button.
|
||||
|
||||
## Selecting and activating an application
|
||||
|
||||
Click an application name in the list to select it. The selected application is highlighted in orange, its checkbox is selected (✓), and its name appears in the smartHMI navigation bar. The system automatically opens the **Application control** page, which shows the current program state and execution log.
|
||||
|
||||
## Application states
|
||||
|
||||
### Activated
|
||||
|
||||
A gray circular indicator means that the application has been selected and loaded into the controller but has not started yet.
|
||||
|
||||
|
||||
|
||||
### Running
|
||||
|
||||
A green play indicator means that the program is running. Events defined by the developer appear in the log in real time. If the program requires operator interaction, a selection dialog appears over the log.
|
||||
|
||||
|
||||
|
||||
### Motion paused
|
||||
|
||||
A yellow pause indicator means that execution has been interrupted. Resume the program in the same way it was started.
|
||||
|
||||
|
||||
|
||||
### Error
|
||||
|
||||
A red indicator means that an unhandled exception occurred during execution. The status line displays the error code. Logic errors must be corrected in SunriseWorkbench.
|
||||
|
||||
|
||||
|
||||
## Deactivating an application
|
||||
|
||||
Open **Applications**, find the active application (orange highlight and selected checkbox), and click its checkbox to deactivate it.
|
||||
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
# Extra menu
|
||||
|
||||
In addition to the main functional areas under [Station](station.md), smartHMI provides additional robot control parameters through the smartPAD side panel. These panels open over the current view without navigating to another section.
|
||||
|
||||
## Manual control method
|
||||
|
||||
The **Manual method options** panel configures manual motion: the active tool, control point (TCP), base coordinate system, and motion frame.
|
||||
|
||||
|
||||
|
||||
### Selecting the tool and TCP
|
||||
|
||||
| Parameter | Description |
|
||||
|---|---|
|
||||
| Tool | Active tool attached to the flange. Default: `Flange` |
|
||||
| TCP | Tool control point. Default: `Flange (Root)` |
|
||||
|
||||
### Selecting the base
|
||||
|
||||
The base coordinate system relative to which manual motion is performed. Select it from the frames defined in the project, for example `P1`.
|
||||
|
||||
### Motion frame
|
||||
|
||||
Determines the coordinate system used by the A1–A7 axis buttons:
|
||||
|
||||
| Mode | Description |
|
||||
|---|---|
|
||||
| Axes | Joint-by-joint control. Each button moves its corresponding axis independently. |
|
||||
| World | Motion in the universal (world) coordinate system. |
|
||||
| Base | Motion in the selected base coordinate system. |
|
||||
| Tool | Motion in the coordinate system of the active tool (TCP). |
|
||||
|
||||
## Control speed
|
||||
|
||||
The **Speed** panel sets the percentage limit for manual motion and program execution speed.
|
||||
|
||||
|
||||
|
||||
## Motion mode
|
||||
|
||||
The **Motion mode** panel controls how the **Start** button works and how the robot approaches frames.
|
||||
|
||||
|
||||
|
||||
### Application mode
|
||||
|
||||
| Mode | Description |
|
||||
|---|---|
|
||||
| Start — continuous | The Start button runs the application continuously (default). |
|
||||
| Step execution | The Start button executes one program step at a time. Used for debugging. |
|
||||
|
||||
### Approaching a frame
|
||||
|
||||
| Type | Description |
|
||||
|---|---|
|
||||
| PTP approach | Motion along the shortest path in joint space (Point-to-Point). |
|
||||
| LIN approach | Straight-line TCP motion in Cartesian space (Linear). |
|
||||
|
||||
The **Open frame view** button opens the Frames section.
|
||||
|
||||
## Clock
|
||||
|
||||
Clicking the clock icon displays the controller's current system time and date.
|
||||
|
||||
|
||||
|
||||
!!! note
|
||||
System time is synchronized with the KUKA Sunrise Cabinet controller clock. Change it in the controller operating system settings.
|
||||
|
||||
## User group
|
||||
|
||||
The **Log on** dialog changes the active user group and the corresponding HMI access level.
|
||||
|
||||
|
||||
|
||||
The access level determines which operations are available, including editing frames, managing Safety settings, and changing the project configuration.
|
||||
|
||||
## Changing the language
|
||||
|
||||
The **Language selection** dialog changes the smartHMI interface language.
|
||||
|
||||
|
||||
|
||||
The change takes effect immediately without restarting the system. The current interface locale appears in the lower-left corner of smartHMI, for example `ru-RU`.
|
||||
@@ -0,0 +1,41 @@
|
||||
# IO Group menu
|
||||
|
||||
The **I/O groups** section provides monitoring and manual control of digital input/output signals configured in the Sunrise project. Open it from the smartHMI navigation bar.
|
||||
|
||||
## Available groups
|
||||
|
||||
Click **I/O groups** in the navigation bar to open the list of available groups. This project defines the following groups:
|
||||
|
||||
|
||||
|
||||
| Group | Description |
|
||||
|---|---|
|
||||
| FRI | FRI (Fast Robot Interface) signal group |
|
||||
| IO_group | Custom digital input/output group |
|
||||
|
||||
## Viewing signals
|
||||
|
||||
Selecting a group opens a page containing all of its signals.
|
||||
|
||||
|
||||
|
||||
### Signal table structure
|
||||
|
||||
| Column | Description |
|
||||
|---|---|
|
||||
| Input / Output | Signal direction icon |
|
||||
| Name | Signal name, such as `In_1` or `Out_16` |
|
||||
| Type | Signal type; digital Boolean for this group |
|
||||
| Value | Current signal state (`0` / `1`) |
|
||||
|
||||
## Controlling output signals
|
||||
|
||||
For signals whose direction is **Output**, the lower panel provides buttons that force a value:
|
||||
|
||||
| Button | Action |
|
||||
|---|---|
|
||||
| True | Set the output signal to `1` (active) |
|
||||
| False | Set the output signal to `0` (inactive) |
|
||||
|
||||
!!! note
|
||||
**Input** signals are read-only.
|
||||
@@ -0,0 +1,146 @@
|
||||
# Robot menu
|
||||
|
||||
The **Robot** section is one of the main areas of KUKA smartHMI. It provides diagnostic robot-state information, mastering functions, tool and base calibration, and load parameters.
|
||||
|
||||
|
||||
|
||||
The table below lists the main menu items.
|
||||
|
||||
| Item | Description |
|
||||
|---|---|
|
||||
| Axis position | Displays the current position of each robot axis in degrees |
|
||||
| Cartesian position | Displays the current tool position in Cartesian coordinates |
|
||||
| Axis torques | Displays the current torque on each robot axis |
|
||||
| Mastering | Provides axis mastering and tool-offset teaching functions |
|
||||
| Load data | Enters or calibrates the load parameters at the flange |
|
||||
| Move enable | Displays the manual-motion enable signal state |
|
||||
| Log | Displays events and errors; equivalent to the item under [Station](station.md) |
|
||||
| Device state | Displays the current device state with a color indicator |
|
||||
| Calibration | Provides tool and base calibration functions |
|
||||
|
||||
## Axis position
|
||||
|
||||
This section displays the current angular position of each of the robot's seven axes in degrees. Values update in real time. Software limits are also shown as minimum and maximum permitted values for each axis.
|
||||
|
||||
|
||||
|
||||
## Cartesian position
|
||||
|
||||
This section displays the tool center point (TCP) position in Cartesian coordinates relative to the selected base. The following parameters are available:
|
||||
|
||||
- **X, Y, Z** — linear TCP coordinates in millimeters;
|
||||
- **A, B, C** — orientation angles in degrees.
|
||||
|
||||
!!! info "Angle-axis correspondence"
|
||||
**A** is rotation around Z, **B** around Y, and **C** around X, following the ZYX convention.
|
||||
|
||||
The current calculation context is also displayed:
|
||||
|
||||
- selected Tool;
|
||||
- active TCP;
|
||||
- selected Base.
|
||||
|
||||
Change these values under **Manual method options**; see [Extra menu](extra-menu.md). After selecting another tool, TCP, or base, the values on this page are recalculated accordingly.
|
||||
|
||||
|
||||
|
||||
## Axis torques
|
||||
|
||||
This section displays current torque on each of the seven axes in newton-meters (Nm). Values update in real time. This information lets the operator:
|
||||
|
||||
- monitor the load on each axis;
|
||||
- diagnose possible mechanical problems;
|
||||
- identify characteristic torque values for later control-program tuning.
|
||||
|
||||
|
||||
|
||||
## Mastering
|
||||
|
||||
Mastering maps the mechanical robot position to its software model. Without correct mastering, software coordinates do not match the actual axis positions.
|
||||
|
||||
The main mastering menu provides functions for updating mastering data, unmastering individual axes, and teaching tool offsets.
|
||||
|
||||
|
||||
|
||||
Use **Update mastering data** to save new mastering values after completing the procedure. The controller records the current mechanical axis positions as references.
|
||||
|
||||
|
||||
|
||||
**Unmaster** removes mastering data from a selected axis. An unmastered axis is considered uncalibrated and may move beyond software limits.
|
||||
|
||||
|
||||
|
||||
!!! warning "When should an axis be unmastered?"
|
||||
Unmaster an axis if it reaches a software limit and cannot continue moving. After moving it away from the limit, master it again to restore correct robot operation.
|
||||
|
||||
**Teach tool offset** applies a correction to an axis zero position without repeating the complete mastering procedure. Use it for small mechanical offsets.
|
||||
|
||||
|
||||
|
||||
!!! warning "Important"
|
||||
Select the tool whose offset will be taught before activating this function.
|
||||
|
||||
## Load data
|
||||
|
||||
Correct load parameters are required for accurate motion planning, prevention of axis overload, and proper operation of Power and Force Limiting (PFL).
|
||||
|
||||
The main load-data menu lists the available tool slots. Load parameters can be entered or calibrated for each tool.
|
||||
|
||||
|
||||
|
||||
Under **Determine load data**, enter or automatically determine mass, center of mass, and inertia tensor.
|
||||
|
||||
|
||||
|
||||
The **Tool mass calibration** procedure lets the controller measure the attached tool mass automatically by performing test motions. Follow the on-screen instructions.
|
||||
|
||||
|
||||
|
||||
When the procedure finishes, the controller displays the measured load parameters. Review them and verify that they match the actual tool characteristics.
|
||||
|
||||
|
||||
|
||||
After confirmation, the controller saves and immediately applies the updated load data.
|
||||
|
||||
|
||||
|
||||
## Move enable
|
||||
|
||||
This item displays the state of the manual-motion enable signal. The signal is activated by pressing the enable button on the manipulator body. smartHMI indicates the active state by changing the axis indicators from gray to white.
|
||||
|
||||
!!! note "Mode limitation"
|
||||
Move enable is unavailable in **automatic mode** (AUT). The signal is active only in manual modes T1 and T2.
|
||||
|
||||
## Log
|
||||
|
||||
This section is equivalent to **Log** under [Station](station.md). It displays controller events, warnings, and errors so that the operator can review their chronology and diagnose faults.
|
||||
|
||||
## Device state
|
||||
|
||||
This section displays the current device state with a color indicator:
|
||||
|
||||
| Color | State |
|
||||
|---|---|
|
||||
| Green | The device is operating normally |
|
||||
| Yellow | A warning or potential issue requires attention |
|
||||
| Red | A critical error or fault has been detected |
|
||||
|
||||
## Calibration
|
||||
|
||||
The **Calibration** section contains procedures for determining the geometric parameters of tools and bases used by the controller to calculate Cartesian coordinates.
|
||||
|
||||
The main menu contains two categories: base calibration and tool calibration.
|
||||
|
||||
|
||||
|
||||
**Base calibration** defines the position of a working coordinate system relative to the World coordinate system. It associates the program with the physical location of a workpiece or equipment in the robot cell.
|
||||
|
||||
|
||||
|
||||
**Tool calibration** determines the TCP position and tool orientation relative to the robot flange. Several calibration methods are available for each tool.
|
||||
|
||||
|
||||
|
||||
The selected method determines the procedure. The common **XYZ 4-Point** method approaches one reference point from four different orientations.
|
||||
|
||||
|
||||
@@ -0,0 +1,168 @@
|
||||
# Station
|
||||
|
||||
The **Station** section is the main navigation level of KUKA smartHMI. Open it by pressing **Station** in the smartPAD navigation bar. It provides access to the primary robot-cell control functions.
|
||||
|
||||
|
||||
|
||||
## Menu structure
|
||||
|
||||
The Station interface contains four functional areas:
|
||||
|
||||
| Area | Description |
|
||||
|---|---|
|
||||
| Navigation menu | Station, Applications, Robot menu, and IO Group menu |
|
||||
| Station menu | Process data, Safety, Frames, KUKA_Sunrise_cabinet, HMI status, Information, and Log |
|
||||
| Extra menu | Motion mode, clock, and user buttons |
|
||||
| smartPAD function buttons | Program and motion control |
|
||||
|
||||
## Process data
|
||||
|
||||
**Process data** displays the current state of the active application, for example `Ok`. Use it to monitor parameters of the running program in real time.
|
||||
|
||||
## Safety
|
||||
|
||||
The **Safety** section provides access to robot safety-system settings and status.
|
||||
|
||||
|
||||
|
||||
### Safety functions
|
||||
|
||||
| Function | Description |
|
||||
|---|---|
|
||||
| Status | Displays the current safety configuration state |
|
||||
| Activation | Activates or deactivates the safety configuration |
|
||||
|
||||
### Actions on the Activation page
|
||||
|
||||
| Action | Description |
|
||||
|---|---|
|
||||
| Activate | Apply and activate the current safety configuration |
|
||||
| Deactivate | Disable the active safety configuration |
|
||||
| Reset | Restore the previous safety configuration state |
|
||||
|
||||
The **Safety configuration ID** field displays the unique identifier of the loaded configuration, for example `2BCAB6DD`.
|
||||
|
||||
|
||||
|
||||
## Frames
|
||||
|
||||
The **Frames** section opens the coordinate-system editor.
|
||||
|
||||
|
||||
|
||||
It lists all frames defined in the Sunrise project and lets you inspect, correct, and navigate their hierarchy.
|
||||
|
||||
### Frame table structure
|
||||
|
||||
| Column | Description |
|
||||
|---|---|
|
||||
| Frame name | Frame name in the project |
|
||||
| X, Y, Z | Axis offsets in millimeters |
|
||||
| A, B, C | Orientation in degrees |
|
||||
|
||||
Frame data is also available in SunriseWorkbench.
|
||||
|
||||
### Navigation and correction
|
||||
|
||||
To open child frames, press **>** next to the required frame. The breadcrumb path updates automatically. Select an item in the breadcrumb to return to a previous level.
|
||||
|
||||
|
||||
|
||||
Press **Correct** to open a dialog that compares current and new values. Press **Save** to confirm or **Cancel** to discard the changes.
|
||||
|
||||
|
||||
|
||||
Frames support multiple nesting levels. The navigation bar displays the complete hierarchy path, for example `World > grant_RNF > P4`.
|
||||
|
||||
|
||||
|
||||
## KUKA_Sunrise_cabinet
|
||||
|
||||
**KUKA_Sunrise_Cabinet** displays the status of the controller hardware components.
|
||||
|
||||
|
||||
|
||||
| Component | Description |
|
||||
|---|---|
|
||||
| Boot status | Controller boot status |
|
||||
| Fieldbuses | EtherCAT bus status |
|
||||
|
||||
## HMI status
|
||||
|
||||
**HMI status** displays the connection state between smartHMI and the Sunrise Cabinet controller.
|
||||
|
||||
## Log
|
||||
|
||||
The **Log** section opens the system event log.
|
||||
|
||||
|
||||
|
||||
### Log filters
|
||||
|
||||
| Filter | Description |
|
||||
|---|---|
|
||||
| Source(s) | Station, LBR_iiwa_7_R800, or both |
|
||||
| Level | Information, warning, or error |
|
||||
| Time period | Time range to display |
|
||||
|
||||
Each entry contains a severity icon, event date and time, source, name, and description.
|
||||
|
||||
## Information
|
||||
|
||||
The **Information** section contains detailed system information about the controller and connected robot.
|
||||
|
||||
|
||||
|
||||
## smartPAD function buttons
|
||||
|
||||
The physical smartPAD buttons are divided into three groups: program control buttons on the left, manual axis control buttons on the right, and user buttons.
|
||||
|
||||
### Program control buttons
|
||||
|
||||
| Button | Description |
|
||||
|---|---|
|
||||
| Edit | Enters Teach mode and enables manual modification of program points |
|
||||
| Stop | Stops program execution or robot motion |
|
||||
| Backward step | Executes one program step in reverse; used for debugging |
|
||||
| Start | Starts the selected application or resumes a stopped program; in T1/T2, the enabling device must be held |
|
||||
|
||||
!!! note
|
||||
Editing from the smartPAD is not used in this project. Programs are written in Java and changed only in SunriseWorkbench.
|
||||
|
||||
### Axis control buttons (T1 and T2)
|
||||
|
||||
| Button | Description |
|
||||
|---|---|
|
||||
| A1 − / A1 + | Move axis 1 in the negative or positive direction |
|
||||
| A2 − / A2 + | Move axis 2 in the negative or positive direction |
|
||||
| A3 − / A3 + | Move axis 3 in the negative or positive direction |
|
||||
| A4 − / A4 + | Move axis 4 in the negative or positive direction |
|
||||
| A5 − / A5 + | Move axis 5 in the negative or positive direction |
|
||||
| A6 − / A6 + | Move axis 6 in the negative or positive direction |
|
||||
| A7 − / A7 + | Move axis 7 in the negative or positive direction |
|
||||
|
||||
In Cartesian control mode, the same buttons move the TCP along X, Y, and Z and rotate it around A, B, and C.
|
||||
|
||||
### Speed control (Override)
|
||||
|
||||
| Button | Description |
|
||||
|---|---|
|
||||
| 0 | Decrease manual motion speed |
|
||||
| 100 | Increase manual motion speed |
|
||||
|
||||
The value is displayed as a percentage of maximum speed. In T1 mode, TCP speed is hardware-limited to 250 mm/s.
|
||||
|
||||
### User buttons
|
||||
|
||||
Four white round buttons are located at the bottom of the left panel. Their behavior is programmed through the Sunrise project API. They are unassigned by default.
|
||||
|
||||
## Operating modes
|
||||
|
||||
| Mode | Description |
|
||||
|---|---|
|
||||
| T1 | Manual control with TCP speed limited to 250 mm/s; the enabling device must be held |
|
||||
| T2 | Manual control at normal speed; the enabling device must be held |
|
||||
| AUT | Automatic mode; axis buttons are unavailable and Start/Stop buttons control execution |
|
||||
|
||||
!!! tip "Extra menu"
|
||||
See [Extra menu](extra-menu.md) for additional control parameters.
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
| 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:
|
||||
|
||||
|
||||
|
||||
Over KONI, Monitor is also available:
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
### 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:
|
||||
|
||||
|
||||
|
||||
| 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.
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
!!! 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.
|
||||
|
||||
|
||||
|
||||
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).
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## 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)`.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Sunrise Workbench overview
|
||||
|
||||
Programming the KUKA LBR IIWA 7 requires **SunriseWorkbench**, an Eclipse-based integrated development environment for writing, debugging, and deploying control programs to the KUKA Sunrise Cabinet controller.
|
||||
|
||||
!!! info "About the installer"
|
||||
The SunriseWorkbench distribution is not publicly available.
|
||||
Contact your system administrator to obtain the installer and confirm its location.
|
||||
|
||||
This guide explains how to install SunriseWorkbench on the following operating systems:
|
||||
|
||||
- [Windows](sun_install/windows.md)
|
||||
- [Linux](sun_install/linux/linux.md)
|
||||
@@ -0,0 +1,73 @@
|
||||
# Installing a Windows compatibility tool
|
||||
|
||||
Windows applications can be run on Linux with **PortProton**, installed from the **Flathub** repository using the **Flatpak** package manager.
|
||||
|
||||
## Installing Flatpak
|
||||
|
||||
On Ubuntu 18.10 or later, run:
|
||||
|
||||
=== "Bash"
|
||||
```bash
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
sudo apt install flatpak
|
||||
```
|
||||
|
||||
## Installing the GNOME Software plugin
|
||||
|
||||
To add Flatpak support to GNOME Software:
|
||||
|
||||
=== "Bash"
|
||||
```bash
|
||||
sudo apt install gnome-software-plugin-flatpak
|
||||
```
|
||||
|
||||
## Adding the Flathub repository
|
||||
|
||||
=== "Bash"
|
||||
```bash
|
||||
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
|
||||
```
|
||||
|
||||
!!! warning "Restart required"
|
||||
Restart the system after adding the repository so that the changes take effect.
|
||||
|
||||
## Installing PortProton
|
||||
|
||||
PortProton can be installed either from the terminal or through GNOME Software.
|
||||
|
||||
**From the terminal:**
|
||||
|
||||
=== "Bash"
|
||||
```bash
|
||||
flatpak install flathub ru.linux_gaming.PortProton
|
||||
```
|
||||
|
||||
Start it with:
|
||||
|
||||
=== "Bash"
|
||||
```bash
|
||||
flatpak run ru.linux_gaming.PortProton
|
||||
```
|
||||
|
||||
**From GNOME Software:**
|
||||
|
||||
After Flathub has been added, PortProton is also available in GNOME Software.
|
||||
|
||||
|
||||
|
||||
## Initial setup
|
||||
|
||||
On first launch, PortProton automatically installs the required Wine dependencies and helper components. This process takes several minutes.
|
||||
|
||||
|
||||
|
||||
After initialization, the application's main functions become available, including:
|
||||
|
||||
- **Wine settings** — manage the Wine environment;
|
||||
- **Windows command prompt** — run `cmd.exe` inside Wine;
|
||||
- **File manager** — access the virtual Windows file system.
|
||||
|
||||
|
||||
|
||||
!!! tip "Next step"
|
||||
After installing PortProton, proceed to [Installing SunriseWorkbench](workbench.md).
|
||||
@@ -0,0 +1,11 @@
|
||||
# Installation on Linux
|
||||
|
||||
SunriseWorkbench is compatible only with Windows. On Linux, install a compatibility tool that can run Windows applications.
|
||||
|
||||
Several popular solutions are available:
|
||||
|
||||
- **PortProton**
|
||||
- **ProtonPlus**
|
||||
- **Bottles**
|
||||
|
||||
The [Windows emulator installation](emulator.md) section explains how to install each of these tools.
|
||||
@@ -0,0 +1,57 @@
|
||||
# Installing SunriseWorkbench
|
||||
|
||||
This section explains how to install SunriseWorkbench on Linux using PortProton.
|
||||
|
||||
!!! note "Prerequisite"
|
||||
Before starting, make sure that PortProton is installed and configured. See [Installing a Windows compatibility tool](emulator.md).
|
||||
|
||||
## Starting the installer
|
||||
|
||||
**Step 1.** Open the directory containing the SunriseWorkbench installer. Right-click the `.exe` file and select **Open with → PortProton**. Leave the default settings in the dialog and click **Run**.
|
||||
|
||||
|
||||
|
||||
## Installation process
|
||||
|
||||
**Step 2.** Select the installation language (English by default) and click **OK**.
|
||||
|
||||
|
||||
|
||||
**Step 3.** Click **Next** in the installation wizard's welcome window.
|
||||
|
||||
|
||||
|
||||
**Step 4.** Review the license agreement and accept its terms.
|
||||
|
||||
|
||||
|
||||
**Step 5.** Keep the default installation path unless you have a specific reason to change it.
|
||||
|
||||
|
||||
|
||||
**Step 6.** Select **Desktop** to create a SunriseWorkbench desktop shortcut.
|
||||
|
||||
|
||||
|
||||
**Step 7.** Click **Install** and wait until all required components have been installed.
|
||||
|
||||
|
||||
|
||||
Click **Create shortcut** to place the shortcut on the desktop.
|
||||
|
||||
## First launch
|
||||
|
||||
**Step 8.** Start SunriseWorkbench from the desktop shortcut. Click **Run** so that PortProton can initialize the application environment.
|
||||
|
||||
|
||||
|
||||
**Step 9.** The application asks for a workspace path. Keep the default value and select **Use this as the default and do not ask again**.
|
||||
|
||||
|
||||
|
||||
**Step 10.** After the main window loads, click **New Sunrise Project**.
|
||||
|
||||
|
||||
|
||||
!!! tip "Further configuration"
|
||||
See [Creating a new project](../../config/new-project.md) for project configuration instructions. You should also [install the required libraries](../../config/libraries.md).
|
||||
@@ -0,0 +1,42 @@
|
||||
# Installation on Windows
|
||||
|
||||
This section explains how to install SunriseWorkbench on Windows.
|
||||
|
||||
## Installing SunriseWorkbench
|
||||
|
||||
**Step 1.** Start the SunriseWorkbench installer. Select the installation language (English by default) and click **OK**.
|
||||
|
||||
|
||||
|
||||
**Step 2.** Click **Next** in the installation wizard's welcome window.
|
||||
|
||||
|
||||
|
||||
**Step 3.** Review the license agreement and accept its terms.
|
||||
|
||||
|
||||
|
||||
**Step 4.** Keep the default installation path unless you have a specific reason to change it.
|
||||
|
||||
|
||||
|
||||
**Step 5.** Select **Create Desktop Shortcut** for convenient access.
|
||||
|
||||
|
||||
|
||||
**Step 6.** Click **Install** and wait until all required components have been installed.
|
||||
|
||||
|
||||
|
||||
## First launch
|
||||
|
||||
**Step 7.** On first launch, the application asks for a workspace path. Keep the default path and select **Use this as the default and do not ask again**.
|
||||
|
||||
|
||||
|
||||
**Step 8.** After the main window loads, click **New Sunrise Project** to create a project.
|
||||
|
||||
|
||||
|
||||
!!! tip "Further configuration"
|
||||
See [Creating a new project](../config/new-project.md) for project configuration instructions. You should also [install the required libraries](../config/libraries.md).
|
||||
@@ -0,0 +1,44 @@
|
||||
# Configuration error
|
||||
|
||||
When a control program starts, it may report that a tool or frame cannot be found. This can happen after an emergency controller shutdown causes the configuration to be lost.
|
||||
|
||||
## Symptoms
|
||||
|
||||
The problem appears when starting **TeachKuka** or **ServerFriRos2**. The main smartHMI menu shows the following diagnostic signs:
|
||||
|
||||
- yellow warning indicators under **Process data**;
|
||||
- yellow warning indicators under **Frames**.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Resolution steps
|
||||
|
||||
Follow these steps:
|
||||
|
||||
1. Connect an external monitor to the robot controller.
|
||||
2. Restart the controller.
|
||||
3. Sign in with the following credentials:
|
||||
- Username: `KukaUser`
|
||||
- Password: `68kuka1secpw59`
|
||||
|
||||
!!! warning "Keyboard layout"
|
||||
The controller uses the German keyboard layout (`DE`) by default. Take this into account when entering the password.
|
||||
|
||||
4. Copy the complete project to a USB drive.
|
||||
5. Open File Explorer with ++win+e++.
|
||||
6. Go to:
|
||||
|
||||
```
|
||||
C:\KRC\Projects
|
||||
```
|
||||
|
||||
7. Replace all files in this directory with the versions from the USB drive.
|
||||
8. Run the system restart application from the controller desktop.
|
||||
|
||||
|
||||
|
||||
After the restart, the configuration is restored and the control programs should start normally.
|
||||
@@ -0,0 +1,183 @@
|
||||
# SSL error during installation
|
||||
|
||||
## Problem description
|
||||
|
||||
When running `cobot setup` or `rosdep update`, an SSL handshake error may occur while downloading ROS dependency indexes from GitHub.
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
- network restrictions such as a corporate firewall or ISP filtering;
|
||||
- GitHub being blocked by the router or ISP;
|
||||
- DNS resolution problems for `raw.githubusercontent.com`;
|
||||
- restricted TLS connections caused by Deep Packet Inspection.
|
||||
|
||||
## Symptoms
|
||||
|
||||
=== "cobot setup"
|
||||
```
|
||||
[rosdep] Initializing rosdep...
|
||||
ERROR: unable to process source [https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/base.yaml]:
|
||||
<urlopen error _ssl.c:983: The handshake operation timed out>
|
||||
ERROR: unable to process source [https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/python.yaml]:
|
||||
<urlopen error _ssl.c:983: The handshake operation timed out>
|
||||
ERROR: Not all sources were able to be updated.
|
||||
```
|
||||
|
||||
=== "rosdep update"
|
||||
```
|
||||
/usr/bin/rosdep:6: DeprecationWarning: pkg_resources is deprecated as an API.
|
||||
from pkg_resources import load_entry_point
|
||||
ERROR: unable to process source [https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/base.yaml]:
|
||||
<urlopen error _ssl.c:983: The handshake operation timed out> (https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/base.yaml)
|
||||
ERROR: unable to process source [https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/python.yaml]:
|
||||
<urlopen error _ssl.c:983: The handshake operation timed out> (https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/python.yaml)
|
||||
ERROR: Not all sources were able to be updated.
|
||||
[[[
|
||||
ERROR: unable to process source [https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/base.yaml]:
|
||||
<urlopen error _ssl.c:983: The handshake operation timed out> (https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/base.yaml)
|
||||
ERROR: unable to process source [https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/python.yaml]:
|
||||
<urlopen error _ssl.c:983: The handshake operation timed out> (https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/python.yaml)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Solution: WireGuard VPN
|
||||
|
||||
The recommended way to bypass network restrictions is to establish a WireGuard VPN tunnel. For **WireGuard server** setup, see the [official WireGuard documentation](https://www.wireguard.com/quickstart/) or your cloud provider's documentation.
|
||||
|
||||
The following steps configure the **client** on the workstation.
|
||||
|
||||
---
|
||||
|
||||
### 1. Install WireGuard
|
||||
|
||||
```bash
|
||||
sudo apt update && sudo apt install -y wireguard-tools
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Configure the client
|
||||
|
||||
Create the configuration file:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/wireguard/wg0.conf
|
||||
```
|
||||
|
||||
Add the following content and substitute your server details:
|
||||
|
||||
```ini
|
||||
[Interface]
|
||||
# Client private key (generate with: wg genkey)
|
||||
PrivateKey = <YOUR_PRIVATE_KEY>
|
||||
# Client address on the VPN network
|
||||
Address = 10.0.0.2/24
|
||||
# DNS servers (optional)
|
||||
DNS = 8.8.8.8, 1.1.1.1
|
||||
|
||||
[Peer]
|
||||
# WireGuard server public key
|
||||
PublicKey = <SERVER_PUBLIC_KEY>
|
||||
# Server address and UDP port
|
||||
Endpoint = <SERVER_IP>:51820
|
||||
# Route all traffic through the VPN
|
||||
AllowedIPs = 0.0.0.0/0
|
||||
# Keepalive for clients behind NAT
|
||||
PersistentKeepalive = 25
|
||||
```
|
||||
|
||||
!!! tip "Generating keys"
|
||||
If you do not have a key pair, generate one:
|
||||
```bash
|
||||
# Private key
|
||||
wg genkey | tee privatekey
|
||||
|
||||
# Public key (send it to the server administrator)
|
||||
cat privatekey | wg pubkey
|
||||
```
|
||||
|
||||
!!! note "Split routing"
|
||||
To route only GitHub traffic through the VPN, replace `AllowedIPs` with:
|
||||
```ini
|
||||
AllowedIPs = 140.82.112.0/20, 185.199.108.0/22
|
||||
```
|
||||
|
||||
!!! warning "MTU problems"
|
||||
If the connection is established but packets are lost, reduce the MTU in `[Interface]`:
|
||||
```ini
|
||||
MTU = 1420
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Manage the tunnel
|
||||
|
||||
```bash
|
||||
# Start the tunnel
|
||||
sudo wg-quick up wg0
|
||||
|
||||
# Check connection status and statistics
|
||||
sudo wg show
|
||||
|
||||
# Stop the tunnel
|
||||
sudo wg-quick down wg0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Start automatically at boot
|
||||
|
||||
```bash
|
||||
sudo systemctl enable wg-quick@wg0
|
||||
sudo systemctl start wg-quick@wg0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Verify the connection
|
||||
|
||||
```bash
|
||||
# Verify that the interface is up
|
||||
ip addr show wg0
|
||||
|
||||
# Check routes
|
||||
ip route show
|
||||
|
||||
# Ping the VPN server
|
||||
ping 10.0.0.1
|
||||
|
||||
# Check the external IP (it should match the VPN server IP)
|
||||
curl -s ifconfig.me
|
||||
```
|
||||
|
||||
After the connection succeeds, run installation again:
|
||||
|
||||
```bash
|
||||
cobot setup
|
||||
```
|
||||
|
||||
or update only rosdep:
|
||||
|
||||
```bash
|
||||
rosdep update
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Diagnostics
|
||||
|
||||
If the tunnel does not start, inspect the system log:
|
||||
|
||||
```bash
|
||||
sudo journalctl -u wg-quick@wg0 -f
|
||||
```
|
||||
|
||||
Make sure that UDP port `51820` is open on the **server**:
|
||||
|
||||
```bash
|
||||
# Check on the server
|
||||
sudo ufw status
|
||||
# or
|
||||
sudo iptables -L -n | grep 51820
|
||||
```
|
||||
Reference in New Issue
Block a user