Import

Docs/architecture.rst

@@ -0,0 +1,64 @@
+Architecture
+============
+
+
+.. figure:: images/graphs/scenario_execution_structure.png
+   :alt: Architecture of Scenario Execution
+
+   Architecture of Scenario Execution
+
+The scenario execution contains several sub-packages, namely
+
+-  `scenario_execution_base <#scenario-execution-base-package>`__
+-  `scenario_execution <#scenario-execution-package>`__
+-  `scenario_execution_gazebo <#scenario-execution-gazebo-package>`__
+-  `scenario_execution_control <#scenario-execution-control-package>`__
+-  `scenario_execution_interfaces <#scenario-execution-interfaces-package>`__
+-  `scenario_execution_rviz <#scenario-execution-rviz-package>`__
+-  `scenario_execution_kubernetes <#scenario-execution-kubernetes-package>`__
+
+The architecture aims at modularity with each package implementing a
+specific functionality.
+
+Design for Modularity
+---------------------
+
+Scenario execution is designed to be easily extensible through libraries.
+An example is available here: :ref:`scenario_library`.
+
+The entry points are defined like this:
+
+.. code-block::
+
+  entry_points={
+   'scenario_execution.action_plugins': [
+       'custom_action = example_library.custom_action:CustomAction',
+   ],
+    'scenario_execution.osc_libraries': [
+        'example = example_library.get_osc_library:get_example_library',
+    ]
+  }
+
+Scenario Parsing
+----------------
+
+.. figure:: images/parsing.png
+   :alt: Architecture of Scenario Parsing
+
+   Architecture of Scenario Parsing
+
+
+Modules
+-------
+
+- ``scenario_execution_base``: The base package for scenario execution. It provides the parsing of OpenSCENARIO 2.0 files and the conversion to py-trees. It's middleware agnostic and can therefore be used as a basis for more specific implementations (e.g. ROS). It also provides basic OpenSCENARIO 2.0 libraries and actions.
+- ``scenario_execution``: This package uses ``scenario_execution_base`` as a basis and implements a ROS2 version of scenario execution. It provides a OpenSCENARIO 2.0 library with basic ROS2-related actions like publishing on a topic or calling a service.
+- ``scenario_execution_control``: Provides code to control scenario execution (in ROS2) from another application such as RViz.
+- ``scenario_coverage``: Provides tools to generate concrete scenarios from abstract OpenSCENARIO 2.0 scenario definition and execute them.
+- ``scenario_execution_gazebo``: Provides a `Gazebo <https://gazebosim.org/>`_-specific OpenSCENARIO 2.0 library with actions.
+- ``scenario_execution_interfaces``: Provides ROS2 `interfaces <https://docs.ros.org/en/rolling/Concepts/Basic/About-Interfaces.html>`__, more specifically, messages and services, which are used to interface ROS2 with the ``scenario_execution_control`` package.
+- ``scenario_execution_rviz``: Contains several `rviz <https://github.com/ros2/rviz>`__ plugins for visualizing and controlling scenarios when working with ROS2.
+- ``simulation/gazebo_tf_publisher``: Publish ground truth transforms from simulation within TF.
+- ``simulation/tb4_bringup``: Run `Turtlebot4 <https://turtlebot.github.io/turtlebot4-user-manual/software/turtlebot4_simulator.html>`_ within simulation, controlled by scenario execution.
+- ``tools/message_modification``: ROS2 nodes to modify messages.
+- ``tools/scenario_status``: Publish the current scenario status on a topic (e.g. to be capture within a ROS bag).

Docs/conf.py

@@ -0,0 +1,53 @@
+# pylint: disable=all
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import datetime
+
+project = "Scenario Execution"
+copyright = f"{datetime.datetime.now()}, Intel"
+author = "Intel"
+
+version = '0.0.0'
+release = '0.0.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinx.ext.extlinks',
+              'sphinxcontrib.spelling']
+
+extlinks = {'repo_link': ('https://github.com/intel-innersource/applications.robotics.mobile.scenario-execution/blob/main/%s', '%s')}
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+language = 'english'
+
+linkcheck_ignore = [
+    r'https://github.com/intel-innersource/applications.robotics.mobile.scenario-execution/.*',
+    r'https://github.intel.com/.*',
+]
+
+spelling_word_list_filename = 'dictionary.txt'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+# html_static_path = ['.']
+
+# https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
+github_user, github_repo = os.environ["GITHUB_REPOSITORY"].split("/", maxsplit=1)
+html_context = {
+    'display_github': True,
+    'github_user': github_user,
+    'github_repo': github_repo,
+    'github_version': os.environ["GITHUB_REF_NAME"] + '/docs/',
+}

Docs/development.rst

@@ -0,0 +1,102 @@
+
+Development
+===========
+
+Contribute
+----------
+
+Before pushing your code, please ensure that the code formatting is
+correct by running:
+
+.. code-block:: bash
+
+   make
+
+In case of errors you can run the autoformatter by executing:
+
+.. code-block:: bash
+
+   make format
+
+Testing
+-------
+
+To run only specific tests:
+
+.. code-block:: bash
+
+   #using py-test
+   colcon build --packages-up-to scenario_execution && reset && pytest-3 -s scenario_execution/test/<TEST>.py 
+
+   #manual run
+   colcon build --packages-up-to scenario_execution && reset && ros2 launch scenario_execution scenario_launch.py scenario:=<...> debug:=True
+
+
+Developing and Debugging with Visual Studio Code
+------------------------------------------------
+
+To prevent certain issues, please use the following command for building (remove /build and /install if another command was used before).
+
+.. code-block:: bash
+
+   colcon build --symlink-install
+
+
+In VSCode create new debugging configuration file: Run -> "Add Configuration..."
+
+Add the following entry to the "configurations" element within the previously created `launch.json` file (replace the arguments as required):
+
+
+.. code-block:: json
+
+           {
+               "name": "scenario_execution",
+               "type": "python",
+               "request": "launch",
+               "program": "./install/scenario_execution/lib/scenario_execution/scenario_execution",
+               "console": "integratedTerminal",
+               "cwd": "${workspaceFolder}",
+               "args": ["-o", "TEST_SCENARIO.osc"],
+           }
+
+
+To execute the debug configuration either switch to debug view (on the left) and click on "play" or press F5.
+
+On the first run, there will be errors because of missing dependencies. Within the terminal showing the errors, run:
+
+.. code-block:: bash
+
+   source /opt/ros/humble/setup.bash
+   source install/setup.bash
+
+Afterwards, press F5 again and the execution should succeed. You can now add breakpoints etc.
+
+Execute Tests
+^^^^^^^^^^^^^
+
+Create an `.env` file by executing:
+
+.. code-block:: bash
+
+   source /opt/ros/humble/setup.bash
+   source install/setup.bash
+   echo PYTHONPATH=$PYTHONPATH > .env
+   echo HOME=$HOME >> .env
+   echo AMENT_PREFIX_PATH=$AMENT_PREFIX_PATH >> .env
+   echo LD_LIBRARY_PATH=$LD_LIBRARY_PATH >> .env
+
+
+In vscode, open user settings and enable the following settings:
+
+.. code-block::
+
+   "python.terminal.activateEnvInCurrentTerminal": true
+
+
+
+Creating an Action
+------------------
+
+-  If an action setup() should fail, raise an exception
+-  Use a state machine, if multiple steps are required
+-  Implement a ``cleanup`` method to cleanup on scenario end.

Docs/dictionary.txt

@@ -0,0 +1,31 @@
+Nav
+turtlebot
+devcontainer
+rviz
+unmapped
+Structs
+kubernetes
+submodules
+namespace
+enums
+multiline
+amsrl
+buildkit
+autoformatter
+nvidia
+behavior
+amr
+modularity
+middleware
+nav
+backend
+osc
+py
+vscode
+QoS
+dataset
+whitespace
+odometry
+tf
+amcl
+RViz