marte-debug/TUTORIAL.md

Tutorial: High-Speed Observability with MARTe2 Debug GUI

This guide will walk you through the process of tracing and forcing signals in a real-time MARTe2 application using the native Rust GUI client.

1. Environment Setup

Launch the MARTe2 Application

First, start your application using the provided debug runner. This script launches the standard MARTeApp.ex while injecting the debugging layer:

./run_debug_app.sh

Note: You should see logs indicating the DebugService has started on port 8080.

Start the GUI Client

In a new terminal window, navigate to the client directory and run the GUI:

cd Tools/gui_client
cargo run --release

2. Exploring the Object Tree

Once connected, the left panel (Application Tree) displays the live hierarchy of your application.

1. Navigate to Data: Expand Root -> App -> Data.
2. Inspect Nodes: Click the ℹ Info button next to any node (like Timer or DDB).
3. View Metadata: The bottom-left pane will display the full JSON configuration of that object, including its class, parameters, and signals.

3. Real-Time Signal Tracing (Oscilloscope)

Tracing allows you to see signal values exactly as they exist in the real-time memory map.

1. Find a Signal: In the tree, locate Root.App.Data.Timer.Counter.
2. Activate Trace: Click the 📈 Trace button.
3. Monitor the Scope: The central Oscilloscope panel will begin plotting the signal.
4. Verify Data Flow: Check the UDP Packets counter in the top bar; it should be increasing rapidly, confirming high-speed data reception (Port 8081).
5. Multi-Signal Trace: You can click 📈 Trace on other signals (like Time) to overlay multiple plots.

4. Signal Forcing (Manual Override)

Forcing allows you to bypass the framework logic and manually set a signal's value in memory.

1. Locate Target: Find a signal that is being written by a GAM, such as Root.App.Data.DDB.Counter.
2. Open Force Dialog: Click the ⚡ Force button next to the signal.
3. Inject Value: In the popup dialog, enter a new value (e.g., 9999) and click Apply Force.
4. Observe Effect: If you are tracing the same signal, the oscilloscope plot will immediately jump to and hold at 9999.
5. Release Control: To stop forcing, click the ❌ button in the Active Controls (Right Panel) under "Forced Signals". The framework will resume writing its own values to that memory location.

5. Advanced Controls

Global Pause

If you need to "freeze" the entire application to inspect a specific state:

• Click ⏸ Pause in the top bar. The real-time threads will halt at the start of their next cycle.
• Click ▶ Resume to restart the execution.

Log Terminal

The bottom panel displays every REPORT_ERROR event from the C++ framework.

• Regex Filter: Type a keyword like Timer in the filter box to isolate relevant events.
• Pause Logs: Toggle ⏸ Pause Logs to stop the scrolling view while data continues to be captured in the background.