Introduce blackboard support

docs/source/scxml-jani-conversion.rst

@@ -33,14 +33,68 @@ Low-Level SCXML Conversion
 
 Low-Level SCXML is the standard SCXML format defined `here <https://www.w3.org/TR/scxml/>`_.
 
-Our converter is able to transform high-level SCXML to low-level SCXML by translating the ROS specific features to standard SCXML features.
-In case of timers, we need additional information that cannot be encoded in SCXML, such that information is generated at runtime.
+Our converter is able to transform High-Level (HL) SCXML to Low-Level (LL) SCXML by translating ROS and BT specific features to standard SCXML features.
+This applies also for timers: we generate an additional SCXML FSM encoding a global clock, sending out events to trigger the timers defined in the model at the correct rate.
 
-The conversion between the two SCXML formats is implemented in ScxmlRoot.as_plain_scxml(). TODO: Link to API.
+The next subsections describe our conversion strategy from HL-SCXML to LL-SCXML.
+The entry-point for the conversion is implemented in ScxmlRoot.as_plain_scxml(). TODO: Link to API.
 
-TODO: Describe how we translate the high-level SCXML to the low-level SCXML.
+Handling of (ROS) Timers
+__________________________
+
+TODO
+
+Handling of (ROS) Services
+_____________________________
+
+ROS services, as well as ROS topics, can be handled directly in the ROS to plain SCXML conversion, without the need of adding JANI-specific features, as for the ROS timers.
+
+The main structure of the SCXML related state machines can be inspected in the diagram below:
+
+.. image:: graphics/ros_service_to_scxml.drawio.svg
+    :alt: Handling of ROS Services
+    :align: center
+
+The automata of clients and services are converted directly from the existing ROS-SCXML files, while the "Extra Service Handler" is autogenerated starting from the provided clients and services.
+
+
+Handling of (ROS) Actions
+_____________________________
+
+ROS actions are handled similarly to ROS Services: a ROS-SCXML description of the system is converted to plain SCXML, and an additional automaton is generated to handle the synchronization between the clients and the server.
+
+The structure of a client-server communication through actions and additional threads looks as follows:
+
+.. image:: graphics/ros_action_to_scxml.drawio.svg
+    :alt: Handling of ROS Actions
+    :align: center
+
+
+Handling the BT Blackboard
+_____________________________
+
+The Blackboard is a container that shares variables across different BT plugins. The value if those variables normally changes over time, and is expected to be updated at each tick.
+
+In LL-SCXML, this is handled by an autogenerated SCXML FSM, that receives the updates from the various plugins and, upon request, provides the data.
+This diagram summarizes the FSM structure.
+
+.. image:: graphics/blackboard_to_scxml.drawio.svg
+    :alt: Blackboard FSM
+    :align: center
 
-TODO: Timers are useful for SCAN as well: instead of keeping them in a runtime object, we can consider to list them in an intermediary XML file.
+
+Setting Blackboard Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This can be done using the tag `bt_set_output` in HL-SCXML. In LL-SCXML this translates to a send event, that is received by the Blackboard FSM to update the internal data.
+
+Reading Blackboard Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At the current state, to read the internal variables there needs to be some message exchange between the plugin FSM and the Blackboard FSM.
+This needs to happen for each and every Blackboard variable that is read.
+
+Optimization is nevertheless possible (sending the whole set of blackboard variables each time), but this would diverge from the Blackboard.CPP implementation, so it should rather be an automatic conversion.
 
 JANI Conversion
 ----------------
@@ -114,34 +168,3 @@ The JANI model resulting from applying the conversion strategies we just describ
     :align: center
 
 It can be seen how new self loop edges are added in the `A_B_receiver` automaton (the dashed ones) and how the `ev_a_on_send` is now duplicated in the composition table, one advancing the `A sender` automaton and the other one advancing the `A_B sender` automaton.
-
-
-Handling of (ROS) Timers
-__________________________
-
-TODO
-
-Handling of (ROS) Services
-_____________________________
-
-ROS services, as well as ROS topics, can be handled directly in the ROS to plain SCXML conversion, without the need of adding JANI-specific features, as for the ROS timers.
-
-The main structure of the SCXML related state machines can be inspected in the diagram below:
-
-.. image:: graphics/ros_service_to_scxml.drawio.svg
-    :alt: Handling of ROS Services
-    :align: center
-
-The automata of clients and services are converted directly from the existing ROS-SCXML files, while the "Extra Service Handler" is autogenerated starting from the provided clients and services.
-
-
-Handling of (ROS) Actions
-_____________________________
-
-ROS actions are handled similarly to ROS Services: a ROS-SCXML description of the system is converted to plain SCXML, and an additional automaton is generated to handle the synchronization between the clients and the server.
-
-The structure of a client-server communication through actions and additional threads looks as follows:
-
-.. image:: graphics/ros_action_to_scxml.drawio.svg
-    :alt: Handling of ROS Actions
-    :align: center

ros_support_interfaces/grid_robot_interfaces/CMakeLists.txt

@@ -0,0 +1,42 @@
+cmake_minimum_required(VERSION 3.5)
+project(grid_robot_interfaces)
+
+# Default to C99
+if(NOT CMAKE_C_STANDARD)
+  set(CMAKE_C_STANDARD 99)
+endif()
+
+# Default to C++14
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 14)
+endif()
+
+if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  add_compile_options(-Wall -Wextra -Wpedantic)
+endif()
+
+# find dependencies
+find_package(ament_cmake REQUIRED)
+# uncomment the following section in order to fill in
+# further dependencies manually.
+find_package(std_msgs REQUIRED)
+
+find_package(rosidl_default_generators REQUIRED)
+
+rosidl_generate_interfaces(${PROJECT_NAME}
+  "msg/Int2D.msg"
+  DEPENDENCIES std_msgs
+ )
+
+if(BUILD_TESTING)
+  find_package(ament_lint_auto REQUIRED)
+  # the following line skips the linter which checks for copyrights
+  # uncomment the line when a copyright and license is not present in all source files
+  #set(ament_cmake_copyright_FOUND TRUE)
+  # the following line skips cpplint (only works in a git repo)
+  # uncomment the line when this package is not in a git repo
+  #set(ament_cmake_cpplint_FOUND TRUE)
+  ament_lint_auto_find_test_dependencies()
+endif()
+
+ament_package()

ros_support_interfaces/grid_robot_interfaces/README.md

@@ -0,0 +1 @@
+Used in `test/jani_generator/_test_data/grid_robot_blackboard`

ros_support_interfaces/grid_robot_interfaces/msg/Int2D.msg

@@ -0,0 +1,2 @@
+int32 x
+int32 y

ros_support_interfaces/grid_robot_interfaces/package.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>grid_robot_interfaces</name>
+  <version>0.0.0</version>
+  <description>TODO: Package description</description>
+  <maintainer email="[email protected]">root</maintainer>
+  <license>TODO: License declaration</license>
+
+  <buildtool_depend>ament_cmake</buildtool_depend>
+  <depend>std_msgs</depend>
+  <test_depend>ament_lint_auto</test_depend>
+  <test_depend>ament_lint_common</test_depend>
+
+  <build_depend>rosidl_default_generators</build_depend>
+  <exec_depend>rosidl_default_runtime</exec_depend>
+  <member_of_group>rosidl_interface_packages</member_of_group>
+
+  <export>
+    <build_type>ament_cmake</build_type>
+  </export>
+</package>

src/as2fm/jani_generator/scxml_helpers/top_level_interpreter.py

@@ -36,7 +36,11 @@
 from as2fm.jani_generator.ros_helpers.ros_service_handler import RosServiceHandler
 from as2fm.jani_generator.ros_helpers.ros_timer import RosTimer, make_global_timer_scxml
 from as2fm.jani_generator.scxml_helpers.scxml_to_jani import convert_multiple_scxmls_to_jani
-from as2fm.scxml_converter.bt_converter import bt_converter
+from as2fm.scxml_converter.bt_converter import (
+    bt_converter,
+    generate_blackboard_scxml,
+    get_blackboard_variables_from_models,
+)
 from as2fm.scxml_converter.scxml_entries import EventsToAutomata, ScxmlRoot
 
 
@@ -174,6 +178,7 @@ def generate_plain_scxml_models_and_timers(
     all_timers: List[RosTimer] = []
     all_services: Dict[str, RosCommunicationHandler] = {}
     all_actions: Dict[str, RosCommunicationHandler] = {}
+    bt_blackboard_vars: Dict[str, str] = get_blackboard_variables_from_models(ros_scxmls)
     for scxml_entry in ros_scxmls:
         plain_scxmls, ros_declarations = scxml_entry.to_plain_scxml_and_declarations()
         # Handle ROS timers
@@ -197,6 +202,9 @@ def generate_plain_scxml_models_and_timers(
             ros_declarations._action_clients,
         )
         plain_scxml_models.extend(plain_scxmls)
+    # Generate sync SCXML model for BT Blackboard (if needed)
+    if len(bt_blackboard_vars) > 0:
+        plain_scxml_models.append(generate_blackboard_scxml(bt_blackboard_vars))
     # Generate sync SCXML models for services and actions
     for plain_scxml in generate_plain_scxml_from_handlers(all_services | all_actions):
         plain_scxml_models.append(plain_scxml)