190 lines
7.7 KiB
Markdown
190 lines
7.7 KiB
Markdown
# Lightweight Cobot
|
|
|
|
<p align="center">
|
|
<a href="README.md">Русский</a> · <strong>English</strong>
|
|
</p>
|
|
|
|
**Lightweight Cobot (LWC)** is an open control system for the **KUKA LBR iiwa 7 R800** collaborative robot built on ROS 2. It combines physical robot control through FRI and `ros2_control`, a Webots digital twin, MoveIt 2 motion planning, RViz and Foxglove visualization, plus REST and MCP interfaces for external applications and AI agents.
|
|
|
|
<table>
|
|
<tr>
|
|
<th align="center">LBR iiwa 7 R800</th>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">
|
|
<img src="https://raw.githubusercontent.com/lbr-stack/lbr_fri_ros2_stack/jazzy/lbr_fri_ros2_stack/doc/img/foxglove/iiwa7_r800.png" alt="LBR iiwa 7 R800" width="300">
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
## Problems solved by the project
|
|
|
|
- Provides one software stack for both the physical robot and simulation without duplicating control code.
|
|
- Connects KUKA Sunrise Cabinet to ROS 2 through FRI and exposes standard `ros2_control` interfaces.
|
|
- Executes joint-space and Cartesian motions using MoveIt 2, OMPL, and Pilz.
|
|
- Simplifies installation, configuration, builds, and startup through the `cobot` CLI.
|
|
- Keeps the main robot, tool, and service parameters in one `cobot-setting.yaml` file.
|
|
- Provides monitoring and integration through RViz, Foxglove, HTTP/WebSocket APIs, and MCP.
|
|
|
|
## Features
|
|
|
|
| Component | Purpose |
|
|
|---|---|
|
|
| Physical robot | KUKA LBR iiwa 7 R800 control through FRI and `ServerFriRos2` |
|
|
| Digital twin | Robot, tool, and environment simulation in Webots |
|
|
| Motion planning | Joint-space and Cartesian trajectories through MoveIt 2 |
|
|
| Control | `ros2_control`, ROS 2 actions/services, REST API, and MCP |
|
|
| Monitoring | RViz, Foxglove, and system state through the web interface |
|
|
| Infrastructure | Native or Docker environment, a unified CLI, and centralized configuration |
|
|
|
|
## Compatibility
|
|
|
|
| Component | Supported version |
|
|
|---|---|
|
|
| Operating system | **Ubuntu 24.04 LTS** — verified for native installation |
|
|
| ROS 2 | Jazzy |
|
|
| Webots | 2025a |
|
|
| CLI Python | 3.11 |
|
|
| KUKA Sunrise OS | 1.16 |
|
|
| KUKA FRI | 1.16 |
|
|
|
|
Docker is available as an alternative environment on a compatible Linux host. Full Windows and macOS support is not claimed. Sunrise Workbench is used separately to prepare and synchronize the KUKA controller project.
|
|
|
|
## Repositories and documentation
|
|
|
|
| Resource | Link |
|
|
|---|---|
|
|
| Primary repository | [GitVerse](https://gitverse.ru/daniel-robotics/lightweight-cobot) |
|
|
| Mirror | [GitHub](https://github.com/Daniel-Robotic/lightweight-cobot) |
|
|
| Online documentation | [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot/) |
|
|
| Documentation mirror | [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/) |
|
|
|
|
The detailed guide starts on the [Overview](doc/lwc-doc/docs/getting-started/index.md) page. Documentation sources are stored under `doc/lwc-doc/docs`.
|
|
|
|
## Quick start
|
|
|
|
### Requirements
|
|
|
|
- Ubuntu 24.04 LTS;
|
|
- internet access;
|
|
- `sudo` privileges;
|
|
- a physical KUKA LBR iiwa 7 R800, or a computer if only the simulator will be used.
|
|
|
|
### Install the CLI
|
|
|
|
Run the installer:
|
|
|
|
```bash
|
|
curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/install.sh | bash
|
|
```
|
|
|
|
The installer checks the basic tools, installs Docker, `uv`, and Python 3.11 when required, clones the project into `~/.lwc`, and installs the `cobot` CLI. Set `COBOT_INSTALL_DIR` to use a different location.
|
|
|
|
Open a new terminal or reload the shell environment, then start the first-time setup wizard:
|
|
|
|
```bash
|
|
cobot setup
|
|
```
|
|
|
|
The wizard offers to start the local documentation, configure `cobot-setting.yaml`, and prepare either a native ROS 2 or Docker build environment.
|
|
|
|
### Simulation only
|
|
|
|
A physical robot and Sunrise Workbench are not required for Webots simulation. Run:
|
|
|
|
```bash
|
|
cobot run
|
|
```
|
|
|
|
Choose the native or Docker environment, then select **Webots simulator**.
|
|
|
|
### Physical robot
|
|
|
|
Before the first run, prepare the controller and `ServerFriRos2` as described in [Sunrise Workbench setup](doc/lwc-doc/docs/getting-started/sunrise-setup.md). Verify the KONI/KLI network, IP addresses, FRI period, selected tool, and its Load Data.
|
|
|
|
Then run:
|
|
|
|
```bash
|
|
cobot run
|
|
```
|
|
|
|
Choose the native or Docker environment, then select **Physical controller**. See the [ServerFriRos2](doc/lwc-doc/docs/sunrise/kuka/programs/server-fri-ros2.md) page for details about the controller-side application.
|
|
|
|
## Main commands
|
|
|
|
| Command | Purpose |
|
|
|---|---|
|
|
| `cobot setup` | Configure documentation, robot parameters, and the build environment |
|
|
| `cobot robot-setup` | Edit `cobot-setting.yaml` interactively |
|
|
| `cobot local-setup` | Install ROS 2 Jazzy and build the workspace natively |
|
|
| `cobot docker-setup` | Pull or build the Docker images |
|
|
| `cobot run` | Select an environment and launch the physical robot or Webots interactively |
|
|
| `cobot run local` | Use native ROS 2, then select the physical robot or Webots |
|
|
| `cobot run docker` | Use Docker, then select the physical robot or Webots |
|
|
| `cobot rebuild` | Rebuild the ROS 2 workspace |
|
|
| `cobot clean` | Remove the `build`, `install`, and `log` artifacts |
|
|
| `cobot update` | Update the project and reinstall the CLI |
|
|
| `cobot --help` | Show every available command |
|
|
|
|
## Local documentation
|
|
|
|
Docker is required for the local documentation server.
|
|
|
|
```bash
|
|
cobot doc-setup
|
|
```
|
|
|
|
By default, the site is available at [http://localhost:8000](http://localhost:8000). Markdown source changes are watched automatically.
|
|
|
|
| Command | Purpose |
|
|
|---|---|
|
|
| `cobot doc-setup` | Start the local documentation server |
|
|
| `cobot doc-setup build` | Build the static site and combined PDF under `doc/lwc-doc/site` |
|
|
| `cobot doc-setup rebuild` | Rebuild the Docker image and restart the server |
|
|
| `cobot doc-setup down` | Stop the local server |
|
|
|
|
The online documentation is hosted on [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot/), with a mirror on [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/).
|
|
|
|
## Packages
|
|
|
|
| Package | Description |
|
|
|---|---|
|
|
| `iiwa_bringup` | Launch files for Webots, the physical FRI robot, MoveIt, and RViz |
|
|
| `iiwa_config` | MoveIt, `ros2_control`, kinematics, and shared configuration files |
|
|
| `iiwa_controller` | Real-time FRI hardware interface for `ros2_control` |
|
|
| `iiwa_description` | URDF/Xacro robot description, meshes, tools, and Webots worlds |
|
|
| `iiwa_msgs` | ROS 2 actions and services for joint, Cartesian, and named-pose motions |
|
|
| `iiwa_planning` | C++ and Python motion nodes based on MoveIt 2, OMPL, Pilz, and `moveit_py` |
|
|
| `iiwa_utils` | Configuration loading, data conversion, and Webots object/camera utilities |
|
|
| `iiwa_web` | REST API, WebSocket, and MCP interfaces for monitoring and external control |
|
|
|
|
Java applications for KUKA Sunrise Cabinet live separately under `src/iiwa_sunrise` and are not part of the colcon build.
|
|
|
|
## Safety
|
|
|
|
Before commanding the physical robot, verify the work area, joint limits, active tool, load model, and selected control mode. LWC does not replace KUKA safety functions, a robotic-cell risk assessment, or operator supervision.
|
|
|
|
## License
|
|
|
|
This project is available under the [Apache License 2.0](LICENSE).
|
|
|
|
## Citation
|
|
|
|
If you use the project in research or development, cite the repository:
|
|
|
|
```bibtex
|
|
@software{lightweight_cobot_2026,
|
|
author = {Hrabar, Daniil},
|
|
title = {Lightweight Cobot: ROS 2 stack for KUKA LBR IIWA 7},
|
|
year = {2026},
|
|
url = {https://gitverse.ru/daniel-robotics/lightweight-cobot}
|
|
}
|
|
```
|
|
|
|
## Acknowledgements
|
|
|
|
| Organization | Notes |
|
|
|---|---|
|
|
| [Komsomolsk-on-Amur State University (KnAGU)](https://knastu.ru/) | Research was conducted at KnAGU |
|
|
| [Russian Science Foundation (RSF)](https://rscf.ru/) | Work supported by the Russian Science Foundation |
|