279 add system overview to documentation. (#279)

Add system overview to documentation.

---------

Signed-off-by: Jelmer de Wolde <[email protected]>

Author: Jelmerdw

docs/conf.py

@@ -24,11 +24,13 @@
     "sphinx_rtd_theme",
     "sphinx_copybutton",
     "sphinxcontrib.video",
+    "sphinxcontrib.mermaid",
 ]
 
 myst_enable_extensions = ["colon_fence"]
 templates_path = ["_templates"]
 exclude_patterns = []
+mermaid_version = "11.6.0"
 
 
 # -- Options for HTML output -------------------------------------------------

docs/content/system_overview.md

@@ -0,0 +1,51 @@
+<!--
+SPDX-FileCopyrightText: Alliander N. V.
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# System Overview
+
+The following diagram gives a very simplified overview of the current state of our robot system:
+
+:::{mermaid} ../diagrams/system_overview.mmd
+:::
+
+You can see two robots (`franka` and `panther`) and four sensors (`realsense`, `zed`, `teltonika` and `velodyne`). Note that the output of the teltonika (gps) and the output of the velodyne (pointcloud) are used in `nav2` to navigate the panther. Output of the depth camera's are not used at the moment. There are three ways to control the robot:
+
+:::{mermaid} ../diagrams/node_definitions.mmd
+:::
+
+*joystick*:
+\
+This joystick contains a `joystick_topic_manager` to switch the control between franka and panther. A `joy_to_twist` node converts the joy message to a twist message. For panther, this twist message can be directly send to the drive controller. For franka, `moveit_servo` is used to calculate the required joint command that results in the desired twist command of the end effector.
+
+*moveit_manager*:
+\
+For robot arms, we created a `moveit_manager` node as a layer above the `moveit_ros_move_group` node. This manager provides functionality like moving to a default configuration or moving the end effector to a given pose.
+
+*nav2*
+\
+For robot vehicles, we use `nav2`, a set of nodes that provide functionality like navigating to a pose or following waypoints.
+
+At the moment, we can use the joystick, or functionality of the moveit_manager or nav2 to control the robots.
+
+**vendor elements**
+\
+Note that the elements in <font color="purple">purple</font> are provided by the vendor of the robot or sensor. We expect some basic functionality, like a controller for a robot and the data output of sensor, provided by the vendor of the product. We only make small adjustments or support for simulation when required.
+
+**default ROS elements**
+\
+Note that the elements in <font color="blue">blue</font> are default in ROS and not created by us.
+
+**namespaces**
+\
+Note that each robot and sensor *lives* in it's own namespace. This enables us to add as many robots and sensors to our system as we like, even when they are the same. For example: if we would have a second Franka arm, we can define the namespaces `franka1` and `franka2`.
+
+**modularity**
+\
+With this setup we focus on the modularity of the system. We can add sensors and robots if we like and reuse nodes that we already developed. If we add another robot arm, we expect the vendor to provide the correct controller nodes. We only need to define the related parameters and should be able to use it again with our Moveit Manager and the default Moveit nodes provided in ROS. And if we add another robot vehicle, we can still use our current Nav2 setup, only requiring the correct definition of the related parameters.
+
+**central controller**
+\
+At the moment, a human is still the central controller in our system. A human can control both the robots using the joystick or via service/action calls to the Moveit Manager or Nav2. Our goal is to get the human out of the loop.

docs/diagrams/node_definitions.mmd

@@ -0,0 +1,28 @@
+classDiagram
+
+class joystick{
+    mapping parameters
+
+    joy_topic_manager()
+    joy_to_twist(franka)
+    joy_to_twist(panther)
+}
+
+class moveit_manager:::moveit_manager{
+    arm parameters
+
+    move_to_configuration()
+    move_hand_to_pose()
+    add_object()
+    clear_objects()
+}
+
+class nav2:::nav2{
+    vehicle parameters
+
+    navigate_to_pose()
+    follow_waypoints()
+}
+
+classDef moveit_manager stroke: #ff0000
+classDef nav2 stroke: #00ff00

docs/diagrams/node_definitions.mmd.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: Alliander N. V.
+
+SPDX-License-Identifier: Apache-2.0

docs/diagrams/system_overview.mmd

@@ -0,0 +1,68 @@
+---
+  config:
+    class:
+        hideEmptyMembersBox: true
+---
+
+classDiagram
+
+%% Franka:
+
+namespace franka {
+    class franka.moveit_manager:::moveit_manager
+
+    class franka.moveit_servo:::external_node
+
+    class franka.moveit_ros_move_group:::external_node
+
+    class franka.controller:::vendor
+}
+
+franka.moveit_manager --> franka.moveit_ros_move_group
+franka.moveit_servo --> franka.controller
+franka.moveit_ros_move_group --> franka.controller
+
+%% Panther:
+
+namespace panther{
+    class panther.nav2:::nav2
+
+    class panther.controller:::vendor
+}
+
+panther.nav2 --> panther.controller
+
+
+%% Sensors:
+
+namespace realsense{
+    class realsense.depth_image:::vendor
+}
+
+namespace zed{
+    class zed.depth_image:::vendor
+}
+
+namespace velodyne{
+    class velodyne.pointcloud:::vendor
+}
+
+namespace teltonika{
+    class teltonika.gps:::vendor
+}
+
+velodyne.pointcloud --> panther.nav2
+teltonika.gps --> panther.nav2
+
+%% Joystick:
+
+class joystick
+
+joystick --> franka.moveit_servo
+joystick --> panther.controller
+
+
+classDef external_node stroke: #0000ff
+classDef moveit_manager stroke: #ff0000
+classDef nav2 stroke: #00ff00
+classDef vendor stroke: #ff00ff

docs/diagrams/system_overview.mmd.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: Alliander N. V.
+
+SPDX-License-Identifier: Apache-2.0

docs/index.rst

@@ -17,6 +17,7 @@
    Home <self>
 
    content/getting_started.md
+   content/system_overview.md
 
    content/franka.md
    content/panther.md

pyproject.toml

@@ -36,6 +36,7 @@ dependencies = [
     "sphinx-autobuild>=2024.10.3",
     "sphinx-copybutton>=0.5.2",
     "sphinx-rtd-theme>=3.0.2",
+    "sphinxcontrib-mermaid>=1.0.0",
     "sphinxcontrib-video>=0.4.1",
     "termcolor>=3.1.0",
     "tornado>=6.5.1",