VulcanAI Tutorials (#256)

* Refs #23739: Tutorial base

Signed-off-by: cferreiragonz <[email protected]>

* Refs #23739: Basic tools tutorials

Signed-off-by: cferreiragonz <[email protected]>

* Refs #23739: Add turtlesim tutorial

Signed-off-by: cferreiragonz <[email protected]>

* Refs #23739: Unify package name

Signed-off-by: cferreiragonz <[email protected]>

* Refs #23739: Add whole package

Signed-off-by: cferreiragonz <[email protected]>

* Refs #23739: Pentagon video, update imports, split tools code

Signed-off-by: cferreiragonz <[email protected]>

* Refs #23739: Fix timeout arg name

Signed-off-by: Carlos Ferreira González <[email protected]>

* Refs #23739: Apply typos review

Signed-off-by: Carlos Ferreira González <[email protected]>

* Refs #23739: Move tutorial, fix imports, spelling

Signed-off-by: Carlos Ferreira González <[email protected]>

* Refs #23739: Url

Signed-off-by: Carlos Ferreira González <[email protected]>

* Refs #23739: Revision & Spelling wordlist

Signed-off-by: Carlos Ferreira González <[email protected]>

* Refs #23739: Add Beta note, figure, minor fixes

Signed-off-by: Carlos Ferreira González <[email protected]>

* Refs #23739: Pip installation warning

Signed-off-by: Carlos Ferreira González <[email protected]>

---------

Signed-off-by: cferreiragonz <[email protected]>
Signed-off-by: Carlos Ferreira González <[email protected]>

Author: cferreiragonz

code/vulcanai_turtlesim/vulcanai_turtlesim_demo/package.xml

@@ -0,0 +1,21 @@
+<?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>vulcanai_turtlesim_demo</name>
+  <version>0.1.0</version>
+  <description>Demo package for VulcanAI library with ROS 2 turtlesim</description>
+  <author email="[email protected]">Carlos Ferreira</author>
+  <maintainer email="[email protected]">Carlos Ferreira</maintainer>
+  <license>Apache License 2.0</license>
+
+  <depend>rclpy</depend>
+  <depend>std_srvs</depend>
+  <depend>geometry_msgs</depend>
+  <depend>turtlesim</depend>
+
+  <exec_depend>python3-vulcanai</exec_depend>
+
+  <export>
+      <build_type>ament_python</build_type>
+  </export>
+</package>

code/vulcanai_turtlesim/vulcanai_turtlesim_demo/resource/vulcanai_turtlesim_demo

@@ -0,0 +1,4 @@
+[develop]
+script_dir=$base/lib/vulcanai_turtlesim_demo
+[install]
+install_scripts=$base/lib/vulcanai_turtlesim_demo

code/vulcanai_turtlesim/vulcanai_turtlesim_demo/setup.cfg

@@ -0,0 +1,29 @@
+from setuptools import find_packages, setup
+
+package_name = 'vulcanai_turtlesim_demo'
+
+setup(
+    name=package_name,
+    version='0.0.0',
+    packages=find_packages(exclude=['test']),
+    data_files=[
+        ('share/ament_index/resource_index/packages',
+            ['resource/' + package_name]),
+        ('share/' + package_name, ['package.xml']),
+    ],
+    install_requires=['setuptools'],
+    zip_safe=True,
+    maintainer='root',
+    maintainer_email='[email protected]',
+    description='TODO: Package description',
+    license='TODO: License declaration',
+    # tests_require=['pytest'],
+    entry_points={
+        "console_scripts": [
+            "vulcanai_turtlesim_demo = vulcanai_turtlesim_demo.ros2_node:main",
+        ],
+        "turtle_tools": [
+            "turtle_tools = vulcanai_turtlesim_demo.turtlesim_tools",
+        ],
+    },
+)

code/vulcanai_turtlesim/vulcanai_turtlesim_demo/setup.py

@@ -0,0 +1,92 @@
+"""
+This file contains a ROS 2 SharedNode and the main entrypoint to test the turtlesim tools.
+"""
+
+import threading
+
+import rclpy
+from rclpy.node import Node
+from rclpy.task import Future
+
+from vulcanai import VulcanConsole
+
+
+class SharedNode(Node):
+    def __init__(self, name: str = "vulcanai_shared_node"):
+        super().__init__(name)
+        # Dictionary to store created clients
+        self._vulcan_clients = {}
+        # Dictionary to store created publishers
+        self._vulcan_publishers = {}
+
+        # Ensure entities creation is thread-safe.
+        self.node_lock = threading.Lock()
+
+    def get_client(self, srv_type, srv_name):
+        """
+        Get a cached client for the specified service type and name or
+        create a new one if it doesn't exist.
+        """
+        key = (srv_type, srv_name)
+        with self.node_lock:
+            if key not in self._vulcan_clients:
+                client = self.create_client(srv_type, srv_name)
+                self._vulcan_clients[key] = client
+                self.get_logger().info(f"Created new client for {srv_name}")
+            return self._vulcan_clients[key]
+
+    def get_publisher(self, msg_type, topic_name):
+        """
+        Get a cached publisher for the specified message type and topic name or
+        create a new one if it doesn't exist.
+        """
+        key = (msg_type, topic_name)
+        with self.node_lock:
+            if key not in self._vulcan_publishers:
+                publisher = self.create_publisher(msg_type, topic_name, 10)
+                self._vulcan_publishers[key] = publisher
+                self.get_logger().info(f"Created new publisher for {topic_name}")
+            return self._vulcan_publishers[key]
+
+    def wait_for_message(self, msg_type, topic: str, timeout_sec: float = None):
+        """
+        Block until a message is received or timeout expires.
+        Subscriptions are created on demand and destroyed after use to avoid
+        handling spins and callbacks in a separate thread.
+        """
+        future = Future()
+
+        def callback(msg):
+            if not future.done():
+                future.set_result(msg)
+
+        sub = self.create_subscription(msg_type, topic, callback, 10)
+
+        rclpy.spin_until_future_complete(self, future, timeout_sec=timeout_sec)
+        self.destroy_subscription(sub)
+
+        if future.done():
+            return future.result()
+        return None
+
+
+def main(args=None):
+    # Create a ROS 2 node that will be used by the tools to avoid
+    # recurrent creation and destruction of DDS Participants
+    rclpy.init(args=args)
+    node = SharedNode(name="vulcanai_shared_node")
+
+    user_context = """\
+You are controlling the turtlesim simulation from ROS 2.
+The simulation has one or more turtles that can move around, drawing on the screen as they go."""
+
+    console = VulcanConsole()
+    console.manager.register_tools_from_entry_points("turtle_tools")
+    console.manager.add_user_context(user_context)
+    # Add the shared node to the console manager blackboard to be used by tools
+    console.manager.bb["main_node"] = node
+    console.run()
+
+
+if __name__ == '__main__':
+    main()