diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..2d2fbd4 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,24 @@ +cff-version: 1.2.0 +message: "If you enjoyed using this repository for your work, we would really appreciate ❤️ if you could cite it, as it helps us to continue offering support." +authors: + - family-names: Huber + given-names: Martin + orcid: https://orcid.org/0000-0003-4603-6773 + - family-names: Mower + given-names: Christopher E. + orcid: https://orcid.org/0000-0002-3929-9391 + - family-names: Ourselin + given-names: Sebastien + orcid: https://orcid.org/0000-0002-5694-5340 + - family-names: Vercauteren + given-names: Tom + orcid: https://orcid.org/0000-0003-1794-0456 + - family-names: Bergeles + given-names: Christos + orcid: https://orcid.org/0000-0002-9152-3194 + + +title: "LBR-Stack: ROS 2 and Python Integration of KUKA FRI for Med and IIWA Robots" +version: 1.3.1 +doi: 10.48550/arXiv.2311.12709 +date-released: 2023-11-22 diff --git a/README.md b/README.md index 2adbf21..990fbf5 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # lbr_stack_doc [![Documentation Status](https://readthedocs.org/projects/lbr-fri-ros2-stack-doc/badge/?version=humble)](https://lbr-fri-ros2-stack-doc.readthedocs.io/en/humble/?badge=humble) +[![status](https://joss.theoj.org/papers/c43c82bed833c02503dd47f2637192ef/status.svg)](https://joss.theoj.org/papers/c43c82bed833c02503dd47f2637192ef) This repository holds the documentation for the [lbr-stack](https://github.com/lbr-stack). @@ -43,15 +44,30 @@ Open and browse the documentation by opening `doc/source/html/index.html`. To build the [paper](paper/paper.md) via [Docker](https://joss.readthedocs.io/en/latest/submitting.html#docker), run ```shell -docker run --rm \ - --volume $PWD/paper:/data \ - --user $(id -u):$(id -g) \ - --env JOURNAL=joss \ - openjournals/inara +docker run --rm -it \ + -v $PWD:/data \ + -u $(id -u):$(id -g) \ + openjournals/inara \ + -o pdf,crossref,preprint \ + paper/paper.md ``` inside the `lbr_stack_doc` repository. +## Citation +If you enjoyed using this repository for your work, we would really appreciate ❤️ if you could cite it, as it helps us to continue offering support. + +``` +@misc{huber2023lbrstack, + title={LBR-Stack: ROS 2 and Python Integration of KUKA FRI for Med and IIWA Robots}, + author={Martin Huber and Christopher E. Mower and Sebastien Ourselin and Tom Vercauteren and Christos Bergeles}, + year={2023}, + eprint={2311.12709}, + archivePrefix={arXiv}, + primaryClass={cs.RO} +} +``` + ## Acknowledgements wellcome diff --git a/paper/img/fri_dependency_architecture.pdf b/paper/img/fri_dependency_architecture.pdf new file mode 100644 index 0000000..6199205 Binary files /dev/null and b/paper/img/fri_dependency_architecture.pdf differ diff --git a/paper/img/joss_figure.png b/paper/img/joss_figure.png new file mode 100644 index 0000000..f3eb374 Binary files /dev/null and b/paper/img/joss_figure.png differ diff --git a/paper/paper.md b/paper/paper.md index 5d14938..6b8fb89 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -33,12 +33,16 @@ authors: affiliations: - name: School of Biomedical Engineering and Image Sciences, King's College London, United Kingdom index: 1 -date: 12 May 2023 +date: 21 November 2023 bibliography: paper.bib --- +![Supported robots in the LBR-Stack. From left to right: KUKA LBR IIWA7, IIWA14, Med7, Med14. Visualizations made using Foxglove [^1].](img/joss_figure.png) + +[^1]: Foxglove: [https://foxglove.dev/ros](https://foxglove.dev/ros). + # Summary -The `LBR-Stack` is a collection of packages that simplify the usage and extend the capabilities of KUKA's Fast Robot Interface (FRI) [@fri]. It is designed for mission critical hard real-time applications. Supported are the `KUKA LBR Med7/14` and `KUKA LBR iiwa7/14` robots in the Gazebo simulation [@gazebo] and for communication with real hardware. A demo video can be found [here](https://www.linkedin.com/posts/mhubii_robotics-opensource-ros2-activity-7009974676017848320-S3U5/?utm_source=share&utm_medium=member_desktop). +The `LBR-Stack` is a collection of packages that simplify the usage and extend the capabilities of KUKA's Fast Robot Interface (FRI) [@fri]. It is designed for mission critical hard real-time applications. Supported are the `KUKA LBR Med7/14` and `KUKA LBR IIWA7/14` robots in the Gazebo simulation [@gazebo] and for communication with real hardware. A demo video can be found [here](https://www.linkedin.com/posts/mhubii_robotics-opensource-ros2-activity-7009974676017848320-S3U5/?utm_source=share&utm_medium=member_desktop). An overview of the software architecture is shown in Figure \ref{fig:fri}. At the `LBR-Stack`'s core are two packages: @@ -47,19 +51,23 @@ At the `LBR-Stack`'s core are two packages: All other packages are built on top. These include Python bindings and packages for integration into the Robot Operating System (ROS) and ROS 2: - - **pyFRIClient**: Python bindings for the **fri**. + - **pyFRI**: Python bindings for the **fri**. - **lbr_fri_ros2_stack**: ROS 1/2 integration of the `KUKA LBR`s through the **fri_vendor**. For brevity, and due to the architectural advantages over ROS [@ros2], only ROS 2 is considered in the following. The **lbr_fri_ros2_stack** comprises the following packages: - **lbr_bringup**: Python library for launching the different components. -- **lbr_description**: Description files for the `Med7/14` and `iiwa7/14` robots. +- **lbr_description**: Description files for the `Med7/14` and `IIWA7/14` robots. - **lbr_demos**: Demonstrations for simulation and the real robots. - **lbr_fri_msgs**: Interface Definition Language (IDL) equivalent of FRI protocol buffers. - **lbr_fri_ros2**: FRI ROS 2 interface through `realtime_tools` [@ros_control]. -- **lbr_hardware_interface**: Interface for `ros2_control` [@ros2_control]. +- **lbr_ros2_control**: Interface and controllers for `ros2_control` [@ros2_control]. - **lbr_moveit_config**: MoveIt 2 configurations [@moveit]. +![An overview of the overall software architecture. There exists a single source for KUKA's FRI. This design facilitates that downstream packages, i.e. the Python bindings and the ROS 2 package, can easily support multiple FRI versions. The ROS 2 side utilizes vcstool[^2].\label{fig:fri}](img/fri_dependency_architecture.pdf) + +[^2]: vcstool: [https://github.com/dirk-thomas/vcstool](https://github.com/dirk-thomas/vcstool). + # Statement of need @@ -67,7 +75,7 @@ An overview of existing work that interfaces the KUKA LBRs from an external comp Limitations with the current FRI solutions are: -1. Only support `iiwa7/14` robots, not `Med7/14`. +1. Only support `IIWA7/14` robots, not `Med7/14`. 2. Don't provide Python bindings. 3. Maintainability: * Modified client source code [iiwa_ros](https://github.com/epfl-lasa/iiwa_ros). @@ -78,14 +86,14 @@ Limitations with the current FRI solutions are: The first original contribution of this work is to add support for the `KUKA LBR Med7/14` robots, which, to the best author's knowledge, does not exist in any other work. The second novel contribution of this work is to provide Python bindings. This work solves the maintainability by outsourcing the FRI into the separate **fri** and **fri_vendor** packages, which leaves the FRI's source code untouched and simply provides build support. 4. is solved by defining an IDL message to KUKA's `nanopb` command and state protocol buffers in **lbr_fri_msgs**. These messages can then be interfaced from ROS 1/2 topics or from the ROS 1/2 hardware abstraction layer. -| Framework | iiwa | Med | ROS | ROS 2 | RT | FRI | Pos | Imp | Cart Imp | HW IF | -| --------------- | ---- |---- | --- | ------ | -- | ---- | --- | --- | -------- | ------ | -|[lbr_fri_ros2_stack](https://github.com/lbr-stack/lbr_fri_ros2_stack) | \bullet | \bullet | \bullet | \bullet | \bullet | \bullet | \bullet | \bullet | \bullet | \bullet | -| [iiwa_ros](https://github.com/epfl-lasa/iiwa_ros) | \bullet | | \bullet | | \bullet | \bullet | \bullet | \bullet | | \bullet | -| [iiwa_ros2](https://github.com/ICube-Robotics/iiwa_ros2) | \bullet | | | \bullet | \bullet | \bullet | \bullet | \bullet | | \bullet | -| [iiwa-stack](https://github.com/IFL-CAMP/iiwa_stack) | \bullet | | \bullet | | | | \bullet | \bullet | \bullet | | -| [libiiwa](https://github.com/Toni-SM/libiiwa) | \bullet | | \bullet | \bullet | | | \bullet | \bullet | \bullet | | -| [KST-KUKA](https://github.com/Modi1987/KST-Kuka-Sunrise-Toolbox) | \bullet | | | | | | \bullet | \bullet | \bullet | | +| Framework | IIWA | Med | ROS | ROS 2 | RT | FRI | pyFRI | Pos | Imp | Cart Imp | HW IF | +| --------------- | ---- |---- | --- | ------ | -- | --- | ----- | --- | --- | -------- | ------ | +| [lbr-stack](https://github.com/lbr-stack) | $\bullet$ | $\bullet$ | $\bullet$ | $\bullet$ | $\bullet$ | $\bullet$ | $\bullet$ | $\bullet$ | $\bullet$ | $\bullet$ | $\bullet$ | +| [iiwa_ros](https://github.com/epfl-lasa/iiwa_ros) | $\bullet$ | | $\bullet$ | | $\bullet$ | $\bullet$ | | $\bullet$ | $\bullet$ | | $\bullet$ | +| [iiwa_ros2](https://github.com/ICube-Robotics/iiwa_ros2) | $\bullet$ | | | $\bullet$ | $\bullet$ | $\bullet$ | | $\bullet$ | $\bullet$ | | $\bullet$ | +| [iiwa-stack](https://github.com/IFL-CAMP/iiwa_stack) | $\bullet$ | | $\bullet$ | | | | | $\bullet$ | $\bullet$ | $\bullet$ | | +| [libiiwa](https://github.com/Toni-SM/libiiwa) | $\bullet$ | | $\bullet$ | $\bullet$ | | | | $\bullet$ | $\bullet$ | $\bullet$ | | +| [KST-KUKA](https://github.com/Modi1987/KST-Kuka-Sunrise-Toolbox) | $\bullet$ | | | | | | | $\bullet$ | $\bullet$ | $\bullet$ | | Table: Overview of existing frameworks for interfacing the KUKA LBRs. A square indicates support for the respective feature. List of abbreviations: Hard Real-time (**RT**), Position Control (**Pos**), Impedance Control (**Imp**), Cartesian Impedance Control (**Cart Imp**), Hardware Interface (**HW IF**).