Merge branch 'main' into humble

Author: mhubii

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

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
 <img src="https://www.kcl.ac.uk/newimages/Wellcome-EPSRC-Centre-medical-engineering-logo.xa827df3f.JPG?f=webp" alt="wellcome" height="45" width="65" align="left">
 

paper/img/fri_dependency_architecture.pdf

@@ -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,27 +51,31 @@ 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
 <!-- statement of need in a research context -->
 
 An overview of existing work that interfaces the KUKA LBRs from an external computer is given in Table 1. We broadly classify these works into custom communication solutions [@iiwa_stack; @kuka_sunrise_toolbox; @libiiwa] and communication solutions through KUKA's FRI UDP channel [@iiwa_ros; @iiwa_ros2]. The former can offer greater flexibility while the latter offer a well defined interface and direct software support from KUKA. Contrary to the custom communication solutions, the FRI solutions additionally enable hard real-time communication, that is beneficial for mission critical development. Stemming from translational medical research, this work therefore focuses on the FRI.
 
 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**).