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

```bash
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):

```text
+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

```bash
source /path/to/marte_debug/env.sh
```

### B.2 Add `DebugService` to Your Config

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

+App = {
    Class = RealTimeApplication
    ...
}
```

### B.3 Start the GUI Client

```bash
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:

```bash
# 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](API.md).