Merge pull request #2 from fjrodl/rolling

Pull request for adding Doxygen documentation

.github/workflows/doxygen-doc.yml

@@ -0,0 +1,23 @@
+name: Doxygen Deployment
+
+on:
+  pull_request:
+    branches:
+      - rolling
+  push:
+    branches:
+      - rolling
+  schedule:
+      - cron: '0 0 * * 6'     
+
+jobs:
+  doxygen_generation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Generate Doxygen for cs4home
+        uses: mattnotmitt/doxygen-action@edge
+        with:
+          doxyfile-path: ".github/Doxyfile"

README.md

@@ -1,4 +1,29 @@
 # cs4home_architecture
-[![rolling](https://github.com/CoreSenseEU/cs4home_architecture/actions/workflows/rolling.yaml/badge.svg)](https://github.com/CoreSenseEU/cs4home_architecture/actions/workflows/rolling.yaml)
+
+This work presents a model for the integration and management of the functional components of a general robotic system, using ROS 2 as a technical foundation. The proposal is inspired by the organization of the human nervous system, developing a management metamodel based on neuroregulatory centers and structured into afferent and efferent components that facilitate information flow and processing within the robotic system.
+
+The model introduces a service-oriented management approach adapted to the distributed environment of ROS 2. This enables the creation and coordination of functional entities according to principles inspired by the human neuroregulatory system, where afferent components gather and process data from the environment, while efferent components distribute and execute commands, using ROS 2 communication patterns such as publish-subscribe, services, and actions.
+
+This structure addresses traditional challenges in robotics, such as hardware-business logic coupling, the need for rapid development of robotic systems, and the complexity of incorporating new knowledge and technologies into existing systems. Key features of this model include:
+
+- Uniform management of system components: Functional elements are managed in a homogeneous way, where each component contributes from a modular and functional perspective. Using ROS 2, interoperability and modular control are achieved, allowing the simplified integration of afferent and efferent components within the system.
+
+- Metamodel inspired by the human neuroregulatory system: The organization of components follows dynamics similar to the nervous system, using ROS 2 nodes and their lifecycle to manage activations and deactivations. Afferent nodes capture sensory data and external signals, while efferent nodes act on the system based on decisions made, allowing controlled and adaptive responses.
+
+- Integration of functional entities via ROS 2 technologies: The proposal incorporates ROS 2's publish-subscribe, service, and action techniques for distributed integration of functional entities, facilitating dynamic and adaptable component connections.
+
+This model is designed as an adaptable solution for a wide variety of robotic systems based on ROS 2, from low-level controls to complex inter-robot coordination and communication. This adaptability allows the scaling and distribution of components across diverse architectures, facilitating the incorporation of new functionalities without the need for redesign.
+
+
+## Examples
+
 
 Implementation of the architecture from the Social Testbed point of view
+
+
+
+
+## status
+
+[![rolling](https://github.com/CoreSenseEU/cs4home_architecture/actions/workflows/rolling.yaml/badge.svg)](https://github.com/CoreSenseEU/cs4home_architecture/actions/workflows/rolling.yaml)
+

cs4home_core/include/cs4home_core/Afferent.hpp

@@ -25,29 +25,75 @@
 #include "rclcpp_lifecycle/lifecycle_node.hpp"
 #include "rclcpp/rclcpp.hpp"
 #include "rclcpp/macros.hpp"
+#include "rclcpp/serialization.hpp"
+#include "rclcpp/create_generic_subscription.hpp"
 
 namespace cs4home_core
 {
 
+/**
+ * @class Afferent
+ * @brief Manages afferent processing in robotic nodes, including message handling,
+ *        subscriptions, and modes for processing serialized data.
+ */
 class Afferent
 {
 public:
   RCLCPP_SMART_PTR_DEFINITIONS(Afferent)
 
+  /**
+  * @enum EfferentProcessMode
+  * @brief Defines processing modes for serialized message handling.
+  */
   enum EfferentProcessMode {CALLBACK, ONDEMAND};
 
+  /**
+   * @brief Constructor for the Afferent class.
+   * @param parent Shared pointer to the lifecycle node managing this instance.
+   */
   explicit Afferent(rclcpp_lifecycle::LifecycleNode::SharedPtr parent);
 
+  /**
+   * @brief Configures the afferent component; intended for subclass implementation.
+   * @return True if configuration is successful.
+   */
   virtual bool configure() = 0;
 
+  /**
+   * @brief Sets the processing mode and an optional callback function.
+   *
+   * @param mode Processing mode for handling messages.
+   * @param cb Optional callback function for handling serialized messages in CALLBACK mode.
+   */
   void set_mode(
     EfferentProcessMode mode,
     std::function<void(std::unique_ptr<rclcpp::SerializedMessage>)> cb = nullptr);
 
+
+  /**
+   * @brief Gets the current processing mode.
+   * @return The current EfferentProcessMode.
+   */
   EfferentProcessMode get_mode() {return mode_;}
+
+  /**
+   * @brief Sets the maximum queue size for storing messages.
+   * @param size Maximum number of messages the queue can hold.
+   */
   void set_max_queue_size(size_t size) {max_queue_size_ = size;}
+
+  /**
+   * @brief Gets the maximum queue size.
+   * @return The maximum queue size.
+   */
   size_t get_max_queue_size() {return max_queue_size_;}
 
+  /**
+  * @brief Converts a serialized message to a typed message.
+  * @tparam MessageT Type of the message to deserialize.
+  * @param msg Serialized message to convert.
+  * @return A unique pointer to the deserialized message.
+  */
   template<class MessageT> std::unique_ptr<MessageT> get_msg(
     std::unique_ptr<rclcpp::SerializedMessage> msg)
   {
@@ -58,6 +104,11 @@ class Afferent
     return std::move(typed_msg);
   }
 
+  /**
+   * @brief Retrieves the next message from the queue, if available.
+   * @tparam MessageT Type of message to retrieve.
+   * @return A unique pointer to the next message, or nullptr if the queue is empty.
+   */
   template<class MessageT> std::unique_ptr<MessageT> get_msg()
   {
     if (msg_queue_.empty()) {
@@ -71,17 +122,30 @@ class Afferent
   }
 
 protected:
+  /** Shared pointer to the parent node. */
   rclcpp_lifecycle::LifecycleNode::SharedPtr parent_;
+  /** List of subscriptions. */
   std::vector<std::shared_ptr<rclcpp::GenericSubscription>> subs_;
 
-  EfferentProcessMode mode_ {ONDEMAND};
+  EfferentProcessMode mode_ {ONDEMAND}; /**< Current processing mode. */
 
+  /** Default maximum queue size. */
   const size_t MAX_DEFAULT_QUEUE_SIZE = 100;
+  /** Maximum queue size. */
   size_t max_queue_size_ {MAX_DEFAULT_QUEUE_SIZE};
+  /** Queue for serialized messages. */
   std::queue<std::unique_ptr<rclcpp::SerializedMessage>> msg_queue_;
 
+  /** Callback for serialized messages. */
   std::function<void(std::unique_ptr<rclcpp::SerializedMessage>)> callback_;
 
+
+  /**
+   * @brief Creates a subscriber for a specific topic and message type.
+   * @param topic Topic to subscribe to.
+   * @param type Type of message for the subscription.
+   * @return True if the subscriber was created successfully.
+   */
   bool create_subscriber(const std::string & topic, const std::string & type);
 };
 

cs4home_core/include/cs4home_core/CognitiveModule.hpp

@@ -12,12 +12,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-
 #ifndef CS4HOME_CORE__COGNITIVEMODULE_HPP_
 #define CS4HOME_CORE__COGNITIVEMODULE_HPP_
 
 #include <dlfcn.h>
-
 #include <tuple>
 #include <string>
 
@@ -34,37 +32,89 @@
 namespace cs4home_core
 {
 
+/**
+ * @class CognitiveModule
+ * @brief Extends the LifecycleNode to manage cognitive processing components in a ROS 2 lifecycle,
+ *        including afferent, efferent, core, meta, and coupling components.
+ */
 class CognitiveModule : public rclcpp_lifecycle::LifecycleNode
 {
 public:
   RCLCPP_SMART_PTR_DEFINITIONS(CognitiveModule)
-  using CallbackReturnT =
-    rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface::CallbackReturn;
+  using CallbackReturnT = rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface::CallbackReturn;
+
 
+  /**
+   * @brief Constructs a CognitiveModule with the specified node options.
+   * @param options Node options for configuring the lifecycle node.
+   */
   explicit CognitiveModule(
     const std::string & name,
     const rclcpp::NodeOptions & options = rclcpp::NodeOptions());
 
+
+  /**
+   * @brief Lifecycle transition callback for configuration.
+   * @param state The current lifecycle state.
+   * @return Result of the configuration, typically success or failure.
+   */
   CallbackReturnT on_configure(const rclcpp_lifecycle::State & state);
+
+  /**
+   * @brief Lifecycle transition callback for activation.
+   * @param state The current lifecycle state.
+   * @return Result of the activation, typically success or failure.
+   */
   CallbackReturnT on_activate(const rclcpp_lifecycle::State & state);
+
+  /**
+   * @brief Lifecycle transition callback for deactivation.
+   * @param state The current lifecycle state.
+   * @return Result of the deactivation, typically success or failure.
+   */
   CallbackReturnT on_deactivate(const rclcpp_lifecycle::State & state);
+
+  /**
+   * @brief Lifecycle transition callback for cleanup.
+   * @param state The current lifecycle state.
+   * @return Result of the cleanup, typically success or failure.
+   */
   CallbackReturnT on_cleanup(const rclcpp_lifecycle::State & state);
+
+  /**
+   * @brief Lifecycle transition callback for shutdown.
+   * @param state The current lifecycle state.
+   * @return Result of the shutdown, typically success or failure.
+   */
   CallbackReturnT on_shutdown(const rclcpp_lifecycle::State & state);
+
+  /**
+   * @brief Lifecycle transition callback for error handling.
+   * @param state The current lifecycle state.
+   * @return Result of the error handling, typically success or failure.
+   */
   CallbackReturnT on_error(const rclcpp_lifecycle::State & state);
 
 protected:
-  Afferent::SharedPtr afferent_;
-  Efferent::SharedPtr efferent_;
-  Core::SharedPtr core_;
-  Meta::SharedPtr meta_;
-  Coupling::SharedPtr coupling_;
-
-  std::string core_name_;
-  std::string afferent_name_;
-  std::string efferent_name_;
-  std::string meta_name_;
-  std::string coupling_name_;
-
+  Afferent::SharedPtr afferent_; /**< Pointer to the Afferent component. */
+  Efferent::SharedPtr efferent_; /**< Pointer to the Efferent component. */
+  Core::SharedPtr core_; /**< Pointer to the Core component. */
+  Meta::SharedPtr meta_; /**< Pointer to the Meta component. */
+  Coupling::SharedPtr coupling_; /**< Pointer to the Coupling component. */
+
+  std::string core_name_; /**< Name of the Core component. */
+  std::string afferent_name_; /**< Name of the Afferent component. */
+  std::string efferent_name_; /**< Name of the Efferent component. */
+  std::string meta_name_; /**< Name of the Meta component. */
+  std::string coupling_name_; /**< Name of the Coupling component. */
+
+  /**
+   * @brief Loads a specified component by name and returns a shared pointer to it.
+   * @tparam T Type of the component to load.
+   * @param name Name of the component to load.
+   * @param parent Shared pointer to the parent lifecycle node.
+   * @return A tuple containing the loaded component pointer and its name.
+   */
   template<class T>
   std::tuple<typename T::SharedPtr, std::string> load_component(
     const std::string & name, rclcpp_lifecycle::LifecycleNode::SharedPtr parent);

cs4home_core/include/cs4home_core/Core.hpp

@@ -12,13 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-
 #ifndef CS4HOME_CORE__CORE_HPP_
 #define CS4HOME_CORE__CORE_HPP_
 
 #include <memory>
 
-
 #include "cs4home_core/Afferent.hpp"
 #include "cs4home_core/Efferent.hpp"
 
@@ -28,23 +26,58 @@
 namespace cs4home_core
 {
 
+/**
+ * @class Core
+ * @brief Manages core functionality for a robotic component, including lifecycle transitions
+ *        and connections to afferent and efferent processing components.
+ */
 class Core
 {
 public:
   RCLCPP_SMART_PTR_DEFINITIONS(Core)
 
+  /**
+   * @brief Constructs a Core object associated with a parent lifecycle node.
+   * @param parent Shared pointer to the lifecycle node managing this Core instance.
+   */
   explicit Core(rclcpp_lifecycle::LifecycleNode::SharedPtr parent);
 
+  /**
+   * @brief Configures the Core component.
+   * @return True if configuration is successful.
+   */
   virtual bool configure() = 0;
+
+  /**
+   * @brief Activates the Core component.
+   * @return True if activation is successful.
+   */
   virtual bool activate() = 0;
+
+  /**
+   * @brief Deactivates the Core component.
+   * @return True if deactivation is successful.
+   */
   virtual bool deactivate() = 0;
 
+  /**
+   * @brief Sets the Afferent component associated with this Core.
+   * @param afferent Shared pointer to an Afferent component.
+   */
   void set_afferent(cs4home_core::Afferent::SharedPtr afferent) {afferent_ = afferent;}
+
+  /**
+   * @brief Sets the Efferent component associated with this Core.
+   * @param efferent Shared pointer to an Efferent component.
+   */
   void set_efferent(cs4home_core::Efferent::SharedPtr efferent) {efferent_ = efferent;}
 
 protected:
+  /** Shared pointer to the parent lifecycle node. */
   rclcpp_lifecycle::LifecycleNode::SharedPtr parent_;
+  /** Shared pointer to the Afferent component. */
   cs4home_core::Afferent::SharedPtr afferent_;
+  /** Shared pointer to the Efferent component. */
   cs4home_core::Efferent::SharedPtr efferent_;
 };