Add tutorial for warehouse_ros(_sqlite)

doc/persistent_scenes_and_states/persistent_scenes_and_states.rst

@@ -0,0 +1,63 @@
+Warehouse - Persistent Scenes and States
+========================================
+
+The "MotionPlanning" plugin of RViz offers the possibility to save
+complete planning scenes and robot states persistently.
+Currently, two storage plugins (based on
+`warehouse_ros <https://github.com/ros-planning/warehouse_ros>`_) are available:
+
+* `warehouse_ros_mongo <https://github.com/ros-planning/warehouse_ros_mongo>`_, which uses MongoDB as backend
+* `warehouse_ros_sqlite <https://github.com/gleichdick/warehouse_ros_sqlite>`_, which uses SQLite as backend
+
+You can install both of them with your favourite package manager
+(e.g. ``apt-get install ros-noetic-warehouse-ros-mongo``) or
+`build them from source <../getting_started/getting_started.html>`_
+(of course, you'll have to check out the corresponding repository into your ``src`` folder for that).
+
+Storage plugin selection
+------------------------
+
+The warehouse plugin and settings have to be specified in the launch files of your MoveIt configuration.
+You should adapt ``warehouse_settings.launch.xml`` and possibly also ``warehouse.launch`` if you do not wish to use the MongoDB plugin.
+The storage plugin is determined by the parameter ``warehouse_plugin``.
+Valid options are ``warehouse_ros_mongo::MongoDatabaseConnection`` for MongoDB and
+``warehouse_ros_sqlite::DatabaseConnection`` for SQLite.
+Furthermore, the parameters ``warehouse_host`` and ``warehouse_port`` configure the connection details.
+In case of the SQLite plugin, ``warehouse_host`` contains the path to the database file,
+and ``warehouse_port`` is unused.
+
+.. tutorial-formatter:: ./warehouse_settings.launch.xml
+
+.. tutorial-formatter:: ./warehouse.launch
+
+Connecting to the storage backend
+---------------------------------
+
+After choosing the storage plugin and configuring the launch file(s),
+run RViz using ::
+
+   roslaunch moveit_resources_panda_moveit_config demo.launch db:=true
+
+In RViz, make sure that the "MotionPlanning" plugin is present in the "Displays" view.
+Otherwise add it with the "Add" button below.
+Navigate to the "Context" tab of the "MotionPlanning" window.
+Verify the connection details (host/port for MongoDB, file path for SQLite)
+and click on "Connect".
+
+.. image:: rviz_connect.png
+    :width: 600px
+
+After that, a dialogue box will appear and ask you whether you'd like to erase all current
+states and scenes in RViz (not in the database, the persistent data is not affected by that).
+As you just started RViz, you can safely select "yes".
+
+Saving/Loading scenes and states
+--------------------------------
+
+Now that you connected successfully,
+you can save and restore robot states and planned scenes.
+This can be done in the "Stored Scenes" resp. "Stored States" tab in RViz.
+
+To save a start state, drag the green manipulator to the correct position and click "Save Start".
+The goal state (orange manipulator) can be saved with the "Save Goal" button.
+To restore a state, select it in the list and click on "Set as Start" resp. "Set as Goal".

doc/persistent_scenes_and_states/warehouse.launch

@@ -0,0 +1,19 @@
+<launch>
+
+  <!-- The path to the database must be specified -->
+  <arg name="moveit_warehouse_database_path" />
+
+  <!-- Load warehouse parameters -->
+  <include file="$(find moveit_resources_panda_moveit_config)/launch/warehouse_settings.launch.xml" />
+
+## BEGIN_TUTORIAL
+## Optionally, start the MongoDB Server (comment/uncomment the following in ``warehouse.launch``)
+  <!-- <node name="$(anon mongo_wrapper_ros)" cwd="ROS_HOME" type="mongo_wrapper_ros.py" pkg="warehouse_ros_mongo">
+    <param name="overwrite" value="false"/>
+    <param name="database_path" value="$(arg moveit_warehouse_database_path)" />
+  </node> -->
+## END_TUTORIAL
+
+
+
+</launch>

doc/persistent_scenes_and_states/warehouse_settings.launch.xml

@@ -0,0 +1,20 @@
+<launch>
+## BEGIN_TUTORIAL
+  <!-- Set the parameters for the warehouse. -->
+
+## Parameters for warehouse_ros_sqlite
+  <arg name="moveit_warehouse_host" default="/path/to/your/file.sqlite" />
+  <arg name="moveit_warehouse_port" default="0" />
+  <param name="warehouse_plugin" value="warehouse_ros_sqlite::DatabaseConnection" />
+
+## For warehouse_ros_mongodb use the following instead
+  <!-- <arg name="moveit_warehouse_port" default="33829" />
+  <arg name="moveit_warehouse_host" default="localhost" />
+  <param name="warehouse_plugin" value="warehouse_ros_mongo::MongoDatabaseConnection" /> -->
+
+## END_TUTORIAL
+
+  <!-- Set parameters for the warehouse -->
+  <param name="warehouse_port" value="$(arg moveit_warehouse_port)"/>
+  <param name="warehouse_host" value="$(arg moveit_warehouse_host)"/>
+</launch>

doc/quickstart_in_rviz/quickstart_in_rviz_tutorial.rst

@@ -235,3 +235,5 @@ Next Tutorials
 * To easily control your robot using Python, check out the `Move Group Python Interface <../move_group_python_interface/move_group_python_interface_tutorial.html>`_
 
 * To create your own ``*_moveit_config`` package, check out the `Setup Assistant <../setup_assistant/setup_assistant_tutorial.html>`_
+
+* Save and restore robot states from a database or from disk using `warehouse_ros <../persistent_scenes_and_states/persistent_scenes_and_states.html>`_

index.rst

@@ -83,6 +83,7 @@ Configuration
    doc/trajopt_planner/trajopt_planner_tutorial
    doc/pilz_industrial_motion_planner/pilz_industrial_motion_planner
    doc/planning_adapters/planning_adapters_tutorial.rst
+   doc/persistent_scenes_and_states/persistent_scenes_and_states
 
 Miscellaneous
 ----------------------------