marte-debug/TUTORIAL.md

Tutorial: Observability and Debugging with the MARTe2 Debug Suite

This guide covers both transport options. Choose the one that fits your workflow:

	WebDebugService	DebugService
Client	Any web browser	Rust native GUI
Setup	Config only	Config + cargo run
Best for	Quick inspection, remote access	High-performance plots, scripted tooling

---

Part A — Web UI (WebDebugService)

A.1 Environment Setup

cd /path/to/your/marte2/project
source /path/to/marte_debug/env.sh

A.2 Add WebDebugService to Your Config

Add the service as a sibling of the +App node (not inside it):

+WebDebugService = {
    Class    = WebDebugService
    HttpPort = 8090
}

+App = {
    Class = RealTimeApplication
    ...
}

Restart your application. You should see:

[WebDebugService] HTTP server listening on port 8090

A.3 Open the Web UI

Navigate to http://localhost:8090 in any browser. The UI connects automatically via SSE.

---

A.4 Exploring the Object Tree

The Application Tree panel on the left mirrors your live ORD hierarchy.

1. Expand Root → App → Data to find data sources.
2. Click Info next to any node to see its class, config, and signals in the details panel.
3. Click List to expand just the immediate children without recursing.

---

A.5 Real-Time Signal Tracing

1. Locate a signal in the tree, e.g. Root.App.Data.Timer.Counter.
2. Click Trace next to the signal. The signal appears in the Traced Signals list with its live last value.
3. Click Plot to open it in the real-time Chart.js graph. Use the Follow toggle to keep the time axis scrolling.
4. To set the sampling decimation (e.g. every 10th sample), use the command box at the bottom of the page:

   TRACE App.Data.Timer.Counter 1 10
   

5. Click Trace again (or send TRACE … 0) to stop.

---

A.6 Signal Forcing

1. Find a GAM output signal, e.g. Root.App.Data.DDB.Counter.
2. Click Force. A modal dialog appears.
3. Enter a value (e.g. 9999) and click Apply.
4. The signal is locked at that value every RT cycle.
5. Click Unforce (or use the Active Controls panel) to release.

---

A.7 Breakpoints

1. Click Break next to a signal.
2. Select an operator (>, <, ==, etc.) and enter a threshold.
3. When the condition fires, the application pauses automatically. The status bar shows PAUSED and the GAM name where execution stopped.
4. Use Step to advance one cycle at a time, or Resume to continue.
5. Click Break OFF to clear the breakpoint.

---

A.8 Execution Stepping

While paused (after a breakpoint or manual Pause):

1. Enter a step count in the Step box (e.g. 5) and click Step.
2. The RT loop runs exactly 5 output-broker cycles, then pauses again.
3. The status SSE event ({"type":"status","remaining":…}) keeps the UI updated.

---

A.9 Signal Monitoring

Monitoring polls a signal at a slow rate without using the RT trace path — useful for DataSourceI signals not connected to any GAM.

1. Click Monitor next to a signal.
2. Enter a poll period in milliseconds (e.g. 500).
3. The signal's current value arrives via SSE every 500 ms as a {"type":"monitor",…} event.

---

A.10 Log Viewer

The Logs panel at the bottom shows every REPORT_ERROR call forwarded as SSE events. Use the level buttons (D / I / W / E) to filter by severity, or type a keyword to search.

---

Part B — Rust Native GUI (DebugService)

B.1 Environment Setup

source /path/to/marte_debug/env.sh

B.2 Add DebugService to Your Config

+DebugService = {
    Class       = DebugService
    ControlPort = 8080
    UdpPort     = 8081
    LogPort     = 8082
}

+App = {
    Class = RealTimeApplication
    ...
}

B.3 Start the GUI Client

cd Tools/gui_client
cargo run --release

The GUI connects to localhost:8080 automatically and requests the tree on startup.

---

B.4 Exploring the Object Tree

The Application Tree panel on the left shows the live ORD.

1. Expand Root → App → Data.
2. Click ℹ Info next to any node to see its JSON config in the bottom-left pane.

---

B.5 Real-Time Signal Tracing (Oscilloscope)

1. Locate Root.App.Data.Timer.Counter.
2. Click 📈 Trace. The Oscilloscope panel begins plotting.
3. The UDP Packets counter in the top bar increments — confirming high-speed telemetry on port 8081.
4. Drag additional signals from the Traced Signals list into the oscilloscope panel for multi-signal overlay.

---

B.6 Signal Forcing

1. Find Root.App.Data.DDB.Counter.
2. Click ⚡ Force.
3. Enter a value (e.g. 9999) and click Apply Force.
4. The oscilloscope plot immediately jumps to and holds at 9999.
5. Click ❌ in the Active Controls panel to release the force.

---

B.7 Global Pause and Resume

• Click ⏸ Pause in the top bar to halt all RT threads.
• Click ▶ Resume to continue.

---

B.8 Log Terminal

The bottom panel shows all REPORT_ERROR events forwarded from TcpLogger (port 8082).

• Regex Filter: Type a keyword (e.g. Timer) to isolate events.
• ⏸ Pause Logs: Stop scrolling while continuing to capture.

---

Part C — Scripted / Programmatic Access

Both transports accept plain text commands. You can use nc or any TCP client:

# DebugService
echo -e "DISCOVER\nTRACE App.Data.DDB.Counter 1" | nc localhost 8080

# WebDebugService
curl -s -X POST http://localhost:8090/api/command \
     -H "Content-Type: text/plain" \
     -d "DISCOVER"

For the full command reference see API.md.