Document SMACC2 Client Library Components

docs/source/components

@@ -0,0 +1,182 @@
+● SMACC2 Client Library Components - Complete Analysis Including Nova Carter
+
+  1. Publisher-Subscriber Pattern Components
+
+  Core Communication Infrastructure
+
+  - CpTopicSubscriber<MessageType> (smacc2/core)
+    - Generic ROS topic subscription with event generation
+    - Features: Configurable QoS, first message tracking, signal-slot integration
+  - CpTopicPublisher<MessageType> (smacc2/core)
+    - ROS topic publishing infrastructure
+    - Features: Template-based message publishing, periodic publishing support
+
+  Navigation Publishers
+
+  - CpAmcl (nav2z_client)
+    - AMCL initial pose publisher
+    - Features: Initial pose setting for localization
+  - CpWaypointsVisualizer (nav2z_client)
+    - Waypoint visualization publisher
+    - Features: RViz marker publishing for waypoint display
+
+  Nova Carter Perception Publishers
+
+  - CpAprilTagVisualization (nova_carter/cl_april_tag_detector)
+    - AprilTag detection visualization publisher
+    - Features: MarkerArray publishing, aggregated tag position calculation, real-time marker updates
+    - Update Pattern: Implements ISmaccUpdatable
+    - Thread Safety: Mutex-protected transform data
+
+  2. State Tracking Pattern Components
+
+  Navigation State Trackers
+
+  - CpSlamToolbox (nav2z_client)
+    - SLAM toolbox state tracking (Resumed/Paused)
+    - Features: Blind state tracking, toggle operations
+    - Pattern: Internal state enum with getter methods
+
+  Manipulation State Trackers
+
+  - CpGraspingComponent (moveit2z_client)
+    - Object manipulation state and collision object management
+    - Features: Attached object tracking, gripper state, finger tip management
+    - State: Current attached object name, collision object database
+
+  Nova Carter Object Tracking
+
+  - CpObjectTracker1 (nova_carter/cl_foundationpose)
+    - 3D object detection state management
+    - Features: Detection database with ID-based tracking, pose extraction
+    - Data Structure: Map of detected objects with vision_msgs integration
+    - Event Generation: EvObjectDetected on new detections
+
+  3. Configuration Management Pattern Components
+
+  Navigation Configuration Managers
+
+  - CpPlannerSwitcher (nav2z_client)
+    - Navigation2 planner/controller runtime switching
+    - Features: Global planner switching, local controller switching, goal checker selection
+    - Publishers: planner_selector, controller_selector, goal_checker_selector
+  - CpGoalCheckerSwitcher (nav2z_client)
+    - Navigation goal verification switching
+    - Features: Runtime goal checker algorithm selection
+    - Publisher: goal_checker_selector topic
+  - CpCostmapSwitch (nav2z_client)
+    - Costmap layer enable/disable control
+    - Features: Dynamic costmap layer management, standard layer presets
+    - Includes: CpCostmapProxy helper class for dynamic reconfigure
+
+  4. Data Buffer Pattern Components
+
+  Motion History Buffers
+
+  - CpOdomTracker (nav2z_client)
+    - Comprehensive odometry and path tracking system
+    - Features: Path stack management, multi-mode operation (RECORD/CLEAR/IDLE)
+    - Data Structures: Path stack, aggregated stack path, goal tracking
+    - Thread Safety: Full mutex protection
+  - CpTrajectoryHistory (moveit2z_client)
+    - MoveIt2 trajectory execution history
+    - Features: Named trajectory storage, execution result tracking
+    - Data Structure: Vector of TrajectoryHistoryEntry with metadata
+    - Retrieval: By index, last trajectory access
+
+  Nova Carter Sensor Data Buffers
+
+  - CpForwardObstacleDetector (nova_carter/cl_lidar)
+    - LiDAR-based forward obstacle distance tracking
+    - Features: Security distance calculation, ray filtering, real-time distance updates
+    - Data Storage: Latest scan message, selected forward distance
+    - Safety: Configurable security distance threshold (0.4m default)
+
+  5. Transform Management Pattern Components
+
+  Spatial Coordinate Systems
+
+  - CpPose (nav2z_client)
+    - Real-time pose tracking and transform management
+    - Features: TF2 integration, frame conversion, pose freezing
+    - Update Pattern: Implements ISmaccUpdatable
+    - Thread Safety: Mutex-protected pose data
+    - Reference Frames: Configurable (map, odom, base_link)
+  - CpTfListener (moveit2z_client)
+    - Transform listener wrapper (referenced but minimal implementation)
+    - Features: TF tree monitoring, transform buffering
+
+  Nova Carter Advanced Transform Management
+
+  - CpObjectTrackerTf (nova_carter/cl_foundationpose)
+    - TF-based object pose tracking with temporal filtering
+    - Features:
+        - Multi-object tracking via TF frames
+      - Historical pose buffering (512 sample max)
+      - Median filtering for pose stabilization
+      - Enable/disable state management
+      - Reset capabilities
+    - Update Pattern: Implements ISmaccUpdatable
+    - Thread Safety: Full mutex protection
+    - Event Generation: EvObjectDetected on successful tracking
+
+  6. Mission Control Pattern Components
+
+  Waypoint Navigation Orchestration
+
+  - CpWaypointNavigatorBase (nav2z_client)
+    - Abstract waypoint navigation foundation
+    - Features: Base class for waypoint management systems
+    - Pattern: Template method pattern for waypoint operations
+  - CpWaypointNavigator (nav2z_client)
+    - Sequential waypoint navigation controller
+    - Features: Waypoint list management, goal sending with options
+    - State Management: Success-based progression
+    - Integration: Navigation2 action client integration
+  - CpWaypointsEventDispatcher (nav2z_client)
+    - Waypoint navigation event coordination
+    - Features: Event routing for waypoint-based state machines
+    - Pattern: Event dispatcher for multi-waypoint missions
+
+  ---
+  Updated Summary by Pattern
+
+  | Pattern                  | Component Count | Primary Domain                | Nova Carter Extensions       |
+  |--------------------------|-----------------|-------------------------------|------------------------------|
+  | Publisher-Subscriber     | 5 (+1)          | Communication & Visualization | AprilTag visualization       |
+  | State Tracking           | 3 (+1)          | System State Management       | 3D object detection tracking |
+  | Configuration Management | 3               | Runtime Parameter Control     | -                            |
+  | Data Buffer              | 3 (+1)          | Historical Data Storage       | LiDAR obstacle detection     |
+  | Transform Management     | 3 (+1)          | Spatial Coordinate Systems    | Advanced TF object tracking  |
+  | Mission Control          | 3               | High-Level Task Orchestration | -                            |
+
+  Total Components: 20 (+4 from Nova Carter)
+
+  Updated Pattern Distribution Analysis
+
+  1. Publisher-Subscriber (25%): Foundation communication layer + perception visualization
+  2. Mission Control (15%): High-level coordination and orchestration
+  3. Transform Management (15%): Enhanced spatial awareness with object tracking
+  4. Configuration Management (15%): Runtime system adaptation
+  5. Data Buffer (15%): Historical tracking + real-time sensor processing
+  6. State Tracking (15%): System + object state awareness
+
+  Nova Carter Architectural Contributions
+
+  Perception Enhancement:
+  - Vision Integration: AprilTag and FoundationPose object detection components
+  - Sensor Processing: LiDAR-based safety and obstacle detection
+  - Advanced Filtering: Temporal median filtering for stable object tracking
+
+  Real-Time Processing:
+  - Update Patterns: Multiple components implement ISmaccUpdatable for real-time processing
+  - Event Generation: Immediate event posting for perception-based state transitions
+  - Safety Integration: LiDAR safety distance calculations for navigation behaviors
+
+  Industrial Robustness:
+  - Temporal Filtering: Median-based pose stabilization over 512 samples
+  - Enable/Disable Controls: Runtime perception system control
+  - Thread Safety: Comprehensive mutex protection for multi-threaded perception
+
+  The Nova Carter extensions demonstrate SMACC2's extensibility for perception-heavy applications, adding sophisticated sensor processing, object tracking, and safety monitoring capabilities while
+  maintaining the same architectural patterns and integration mechanisms.