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

docs: update README files with project features and compatibility details

Browse Source
This commit is contained in:
Даниил Грабарь
2026-08-13 17:01:34 +03:00
parent 4547b786a3
commit 08ebd40671
2 changed files with 244 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README_en.md
+127 -76
View File
@@ -1,119 +1,176 @@
# Lightweight Cobot
> **Draft documentation — work in progress**
<p align="center">
<a href="README.md">Русский</a> · <strong>English</strong>
</p>
ROS 2 packages for controlling the **KUKA LBR IIWA 7 R800**: communication with the real robot via [FRI](https://github.com/lbr-stack/fri) (Fast Robot Interface) and simulation in [Webots](https://cyberbotics.com/).
**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>
<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">
<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
## Status
- 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.
| OS | ROS Distribution | FRI Version |
| :--- | :--- | :--- |
| `Ubuntu 24.04` | `jazzy` | `1.16` |
## 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 |
## Quick Start
## Compatibility
Install everything with a single command:
| 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 script installs ROS 2 Jazzy, Webots, builds the workspace, and installs the `cobot` CLI.
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:
## `cobot` Commands
After installation, manage the system via CLI:
```
cobot <command>
```bash
cobot setup
```
### Setup
The wizard offers to start the local documentation, configure `cobot-setting.yaml`, and prepare either a native ROS 2 or Docker build environment.
| Command | Description |
| :--- | :--- |
| `cobot setup` | First-time setup: documentation server, build environment, robot config |
| `cobot local-setup` | Install ROS 2 Jazzy natively and build the project with colcon |
| `cobot docker-setup` | Build or pull Docker images |
| `cobot doc-setup` | Deploy or stop the MkDocs documentation server |
| `cobot robot-setup` | Configure `cobot-setting.yaml` interactively |
### Simulation only
### Run
A physical robot and Sunrise Workbench are not required for Webots simulation. Run:
| Command | Description |
| :--- | :--- |
| `cobot run` | Launch the robot controller or Webots simulator (local or Docker) |
```bash
cobot run
```
### Build
Choose the native or Docker environment, then select **Webots simulator**.
| Command | Description |
| :--- | :--- |
| `cobot rebuild` | Rebuild ROS 2 packages in `src/` with colcon |
| `cobot clean` | Remove colcon build artifacts (`build/` `install/` `log/`) |
### Physical robot
### Management
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.
| Command | Description |
| :--- | :--- |
| `cobot update` | Pull latest changes from the remote git branch and reinstall `cobot` |
| `cobot delete` | Remove the project, Docker images, containers, and optionally ROS 2 |
Then run:
---
```bash
cobot run
```
## Demo
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.
> GIF animations will be added in upcoming releases
## Main commands
<table>
<tr>
<th align="center" width="33%">Webots Simulation</th>
<th align="center" width="33%">Joint-Space Control</th>
<th align="center" width="33%">Cartesian Control</th>
</tr>
<tr>
<td align="center"><i>— coming soon —</i></td>
<td align="center"><i>— coming soon —</i></td>
<td align="center"><i>— coming soon —</i></td>
</tr>
</table>
| 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: Webots simulation, real robot via FRI, MoveIt motion planning and RViz visualization |
| `iiwa_config` | Configuration files: MoveIt, ros2_control controllers, kinematics and general system settings |
| `iiwa_controller` | Hardware interface: real-time joint control via FRI within the ros2_control ecosystem |
| `iiwa_description` | URDF/XACRO robot description and Webots world configuration |
| `iiwa_msgs` | ROS 2 interfaces: action messages for joint-space and Cartesian motion, services for named poses |
| `iiwa_planning` | Motion planning: C++ and Python nodes built on MoveIt 2 (OMPL, Pilz, moveit_py) |
| `iiwa_utils` | System utilities: configuration loading, object and camera spawning in Webots, data conversion |
| `iiwa_web` | Web interface for monitoring and remote control of the cobot via browser |
|---|---|
| `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 this project in your work, please leave a star ⭐ and cite it:
If you use the project in research or development, cite the repository:
```bibtex
@software{lightweight_cobot_2026,
@@ -124,15 +181,9 @@ If you use this project in your work, please leave a star ⭐ and cite it:
}
```
---
## Acknowledgements
We gratefully acknowledge the support of the following organizations and grants:
| 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 |
| <!-- TODO --> | <!-- TODO --> |
| <!-- TODO --> | <!-- TODO --> |