Merge pull request #131 from fzi-forschungszentrum-informatik/dev

Sync Dev to Main 28-10-2024

.github/workflows/industrial_ci.yml

@@ -19,6 +19,7 @@ jobs:
         distro:
           - humble
           - iron
+          - jazzy
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -27,7 +28,7 @@ jobs:
           ROS_DISTRO: ${{ matrix.distro }}
           BASEDIR: ${{ github.workspace }}/.build
           ROS_REPO: main
-          AFTER_INSTALL_TARGET_DEPENDENCIES: "pip3 install coverage[toml]"
+          AFTER_INSTALL_TARGET_DEPENDENCIES: 'if [ "$ROS_DISTRO" == "jazzy" ]; then pip3 install --break-system-packages coverage[toml]; else pip3 install coverage[toml]; fi;'
           ENABLE_COVERAGE_TESTING: "true"
 
       - name: Upload Test Results

CHANGELOG.md

@@ -7,11 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+### Added
+
+### Removed
+
+### Changed
+
+### Fixed
+
+[unreleased]: https://github.com/fzi-forschungszentrum-informatik/ros2_ros_bt_py/compare/v0.1.0...main
+
+## [v0.1.0]
+
+### Added
+
+- Tests for NodeConfig class
+- Tree storage path is now a launch argument
+- Action results can now be processed when using ABC Actions
+- Documentation on how to use custom node classes with the library
+- New node module `Time` in the standard node library including a `TimeNow` node that gives back a
+  `builtin_interfaces/Time` message of the current timestamp.
+
+### Changed
+
+- Fixed up documentation from ROS 1 version
+- Updated Web-GUI version to 2.0.5
+- Subtree manager is now its own class and not inside the debug manager
+- Updated NodeDiagnostics
+- Library can now be installed with symlink install
+- Module List is now generated in a separate function
+- WebGUI is now launched on default
+- Service and Action Nodes now directly expose Request/Response and Goal/Result/Feedback fields
+- RandomInt now gives a number from [min, max] instead of [min, max) to make it more intuitive
+
+### Fixed
+
+- Fixed missing attributes in the Action node.
+- Fixed high level exception catching masking errors.
+- Fixed race condition when setting the tree state.
+- Fixed package manager to be able to handle more than one package
+- Fixed python version to python3
+- Fixed Action Node and internal state machine
+- Fixed Wait Node to reset before shutdown
+
+[v0.1.0]: https://github.com/fzi-forschungszentrum-informatik/ros2_ros_bt_py/compare/v0.0.1...v0.1.0
+
 ## [v0.0.1]
 
-[unreleased]: https://github.com/fzi-forschungszentrum-informatik/ros2_ros_bt_py/compare/v0.0.1...dev
 [v0.0.1]: https://github.com/fzi-forschungszentrum-informatik/ros2_ros_bt_py/releases/tag/v0.0.1
-
 <!---
 ## [vx.x.x] - YYYY-MM-DD
 
@@ -37,4 +80,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 [vx.x.x]: https://github.com/fzi-forschungszentrum-informatik/ros2_ros_bt_py/compare/OLDTAG...NEWTAG
 -->
-

CONTRIBUTING.md

@@ -13,15 +13,19 @@ All types of contributions are encouraged and valued. See the [Table of Contents
 
 ## Table of Contents
 
-- [I Have a Question](#i-have-a-question)
-- [I Want To Contribute](#i-want-to-contribute)
-- [Reporting Bugs](#reporting-bugs)
-- [Suggesting Enhancements](#suggesting-enhancements)
-- [Your First Code Contribution](#your-first-code-contribution)
-- [Improving The Documentation](#improving-the-documentation)
-- [Styleguides](#styleguides)
-- [Commit Messages](#commit-messages)
-- [Join The Project Team](#join-the-project-team)
+- [Contributing to CONTRIBUTING.md](#contributing-to-contributingmd)
+  - [Table of Contents](#table-of-contents)
+  - [I Have a Question](#i-have-a-question)
+  - [I Want To Contribute](#i-want-to-contribute)
+    - [Legal Notice](#legal-notice)
+    - [Reporting Bugs](#reporting-bugs)
+      - [Before Submitting a Bug Report](#before-submitting-a-bug-report)
+      - [How Do I Submit a Good Bug Report?](#how-do-i-submit-a-good-bug-report)
+    - [Suggesting Enhancements](#suggesting-enhancements)
+      - [Before Submitting an Enhancement](#before-submitting-an-enhancement)
+      - [How Do I Submit a Good Enhancement Suggestion?](#how-do-i-submit-a-good-enhancement-suggestion)
+  - [Styleguides](#styleguides)
+  - [Attribution](#attribution)
 
 
 ## I Have a Question

ros_bt_py/CONTRIBUTING.md

@@ -13,15 +13,19 @@ All types of contributions are encouraged and valued. See the [Table of Contents
 
 ## Table of Contents
 
-- [I Have a Question](#i-have-a-question)
-- [I Want To Contribute](#i-want-to-contribute)
-- [Reporting Bugs](#reporting-bugs)
-- [Suggesting Enhancements](#suggesting-enhancements)
-- [Your First Code Contribution](#your-first-code-contribution)
-- [Improving The Documentation](#improving-the-documentation)
-- [Styleguides](#styleguides)
-- [Commit Messages](#commit-messages)
-- [Join The Project Team](#join-the-project-team)
+- [Contributing to CONTRIBUTING.md](#contributing-to-contributingmd)
+  - [Table of Contents](#table-of-contents)
+  - [I Have a Question](#i-have-a-question)
+  - [I Want To Contribute](#i-want-to-contribute)
+    - [Legal Notice](#legal-notice)
+    - [Reporting Bugs](#reporting-bugs)
+      - [Before Submitting a Bug Report](#before-submitting-a-bug-report)
+      - [How Do I Submit a Good Bug Report?](#how-do-i-submit-a-good-bug-report)
+    - [Suggesting Enhancements](#suggesting-enhancements)
+      - [Before Submitting an Enhancement](#before-submitting-an-enhancement)
+      - [How Do I Submit a Good Enhancement Suggestion?](#how-do-i-submit-a-good-enhancement-suggestion)
+  - [Styleguides](#styleguides)
+  - [Attribution](#attribution)
 
 
 ## I Have a Question

ros_bt_py/doc/source/advanced_launch_configuration.rst

@@ -0,0 +1,92 @@
+.. _advanced-launch-config:
+
+#############################
+Advanced Launch Configuration
+#############################
+
+Using the standard ros_bt_py launch file is all you need for designing and executing BTs with the
+standard bt_py nodes.
+Utilizing the Package Loader in the GUI you can also extend this to custom Node Classes to enhance
+your bt_py experience!
+
+While this is nice for development, using BTs in production has other constraints and conditions,
+such as automatically loading custom node classes or starting a tree on launch.
+
+In general you will want to create a custom package for your launch files, similar to the custom
+nodes, to keep your ``ros_bt_py`` repository clean.
+
+**************************************
+Using Custom Node Classes in a Project
+**************************************
+
+After writing and testing all the node classes needed inside ``your_awesome_package`` you will need
+to include them when launching ``ros_bt_py`` to actually use them.
+
+All you need to do is to write a new launch file and overwrite the ``module_list`` argument to
+include your node modules::
+
+  from launch import LaunchDescription
+  from launch.actions import IncludeLaunchDescription
+  from launch.launch_description_sources import PythonLaunchDescriptionSource
+  from launch_ros.substitutions import FindPackageShare
+
+  def generate_module_list():
+      module_list = [
+          "ros_bt_py.nodes",
+          "ros_bt_py.ros_nodes",
+          "your_awesome_package.nodes",
+      ]
+      return str(module_list)
+
+  def generate_launch_description():
+      ros_bt_py_launch = IncludeLaunchDescription(
+          PythonLaunchDescriptionSource(
+              [
+                  FindPackageShare("ros_bt_py"),
+                  "/launch",
+                  "/ros_bt_py.launch.py",
+              ]
+          ),
+          launch_arguments={"node_modules": generate_module_list()}.items(),
+      )
+
+      return LaunchDescription(
+          [
+              ros_bt_py_launch
+          ]
+      )
+
+Because ``LaunchDescription`` only takes strings as launch arguments the custom
+``generate_module_list`` function is used to allow for adding multiple new modules while also
+allowing for line breaks for readability.
+
+********************************
+Other Important Launch Arguments
+********************************
+
+Other relevant launch arguments you might find useful:
+
+.. list-table:: Launch Options
+   :widths: auto
+   :header-rows: 1
+
+   * - Launch Argument
+     - Description
+     - Default Value
+     - Tip
+   * - enable_web_interface
+     - Start web GUI on startup.
+     - False
+     - For working in production the interface is not necessary
+   * - load_default_tree
+     - Load the default tree on startup
+     - False
+     - Needs to be set to true to load a tree
+   * - default_tree_path
+     - Path to the default tree to load on startup!
+     - ""
+     - path to load the tree, can be used with ``file://`` or ``package://``
+   * - default_tree_control_command
+     - Command to execute per default after loading the default tree on startup!
+     - 2
+     - DO_NOTHING = 0, TICK_ONCE = 1, TICK_PERIODICALLY = 2, TICK_UNTIL_RESULT = 3

ros_bt_py/doc/source/advanced_tutorial.rst

@@ -0,0 +1,79 @@
+.. _advanced-tutorial:
+
+#################
+Advanced Tutorial
+#################
+
+In this Tutorial more advanced concepts are introduced.
+
+****************
+Using OptionRefs
+****************
+
+As you have seen there are nodes like the constant node that can change the types of their
+Parameters (Options, Inputs and Outputs are collectively called Parameters).
+
+While bt_py uses only strongly typed parameters, we might want to edit them during three creation
+instead of while defining Node Classes.
+
+To understand how this is done, it is helpful to take a look at the formal definition:
+
+.. image:: _static/option_ref_def_0.png
+   :alt: OptionRef Definition
+
+The Type t of a Parameter can be either a set from T that contains the legal values for the
+Parameter to take (like N or the set of all valid Python str objects), or a Reference to an Option.
+In the latter case, p_ref is required to have the form (n, option, T), where T is, again, the set
+of all the sets that can be used as values for the Type t.
+In particular, as T only contains sets, it does not include References, so cyclic References are
+not possible.
+
+So a parameter can either be defined with a given Type (as we did in the earlier examples) or by
+providing a reference to an option.
+Thee parameter value is defined in the referenced parameter type:
+
+.. image:: _static/option_ref_def_1.png
+   :alt: Parameter Type Definition
+
+The Values of Options are static, so their initial Values are their only Values and are defined
+separately.
+In practice, Option Values are supplied as a dictionary to the constructor of a Node.
+Static, in this case, does not mean that it can not be changed in the overall BT, but not during
+runtime.
+So while the "Constant" Node can be parameterized with various constants during construction of the
+tree in the editor, it will not change this value during runtime.
+
+Defining OptionRefs in the NodeConfig
+=====================================
+
+Lets look at an example:
+
+.. code-block:: python
+
+   @define_bt_node(NodeConfig(
+        options ={ ' passthrough_type ': type },
+        inputs ={ ' in ': OptionRef ( ' passthrough_type ')} ,
+        outputs ={ ' out ': OptionRef ( ' passthrough_type ')} ,
+        max_children =0))
+   class PassthroughNode ( Leaf ):
+       """
+       Pass through a piece of data
+       Useful for testing , and to mark the inputs of
+       a BT that is meant to be loaded as a subtree .
+       """
+   # implementation ...
+
+The PassthroughNode defines option "passthrough_type" which is set by the user while instantiating
+the node.
+Its Inputs ("in") and Outputs ("out") respectively are defined as OptionRef('passthrough_type')
+which will be resolved to the given type at runtime.
+
+Here is what this looks like:
+
+.. image:: _static/option_ref_ex.png
+   :alt: Parameter Type Example
+
+Note that you need to update the node and then reload the paramter view by closing and opening it
+again for the changes to show.
+By default the PassthroughNode initializes to int.
+Change this to string by entering "str" as type and then select "Update Node"

ros_bt_py/doc/source/api.rst

@@ -1,5 +1,6 @@
+###
 API
-===
+###
 
 ros\_bt\_py\.debug\_manager module
 ----------------------------------