marte-debug/SPECS.md

MARTe2 Debug Suite Specifications

1. Goal

Implement a "Zero-Code-Change" observability layer for the MARTe2 real-time framework, providing live telemetry, signal forcing, and execution control without modifying existing application source code.

2. Requirements

2.1 Functional Requirements (FR)

• FR-01 (Discovery): Discover the full MARTe2 object hierarchy at runtime.
• FR-02 (Telemetry): Stream high-frequency signal data (verified up to 100Hz) to a remote client.
• FR-03 (Forcing): Allow manual override of signal values in memory during execution.
• FR-04 (Logs): Stream global framework logs to a dedicated terminal via a standalone TcpLogger service.
• FR-05 (Log Filtering): The client must support filtering logs by type (Debug, Information, Warning, FatalError) and by content using regular expressions.
• FR-06 (Execution & UI):
  • Provide a native GUI for visualization.
  • Support Pause/Resume of real-time execution threads via scheduler injection.
• FR-07 (Session Management):
  • The top panel must provide a "Disconnect" button to close active network streams.
  • Support runtime re-configuration and "Apply & Reconnect" logic.
• FR-08 (Decoupled Tracing): Clicking trace activates telemetry; data is buffered and shown as a "Last Value" in the sidebar, but not plotted until manually assigned.
• FR-08 (Advanced Plotting):
  • Support multiple plot panels with perfectly synchronized time (X) axes.
  • Drag-and-drop signals from the traced list into specific plots.
  • Automatic distinct color assignment for each signal added to a plot.
  • Plot modes: Standard (Time Series) and Logic Analyzer (Stacked rows).
  • Signal transformations: Gain, offset, units, and custom labels.
  • Visual styling: Deep customization of colors, line styles (Solid, Dashed, etc.), and marker shapes (Circle, Square, etc.).
• FR-09 (Navigation):
  • Context menus for resetting zoom (X, Y, or both).
  • "Fit to View" functionality that automatically scales both axes to encompass all available buffered data points.
• FR-10 (Scope Mode):
  • High-performance oscilloscope mode with configurable time windows (10ms to 10s).
  • Global synchronization of time axes across all plot panels.
  • Support for Free-run and Triggered acquisition (Single/Continuous, rising/falling edges).
• FR-11 (Data Recording):
  • Record any traced signal to disk in Parquet format.
  • Native file dialog for destination selection.
  • Visual recording indicator in the GUI.

2.2 Technical Constraints (TC)

• TC-01: No modifications allowed to the MARTe2 core library or component source code.
• TC-02: Instrumentation must use Runtime Class Registry Patching.
• TC-03: Real-time threads must remain lock-free; use FastPollingMutexSem or atomic operations for synchronization.
• TC-04: Telemetry must be delivered via UDP to minimize impact on real-time jitter.

3. Performance Metrics

• Latency: Telemetry dispatch overhead < 5 microseconds per signal.
• Throughput: Support for 100Hz+ sampling rates with zero packet loss on local networks.
• Scalability: Handle up to 4096 unique signals and 16 simultaneous client connections.