martino/marte-debug
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

interface added and web ui created

Browse Source
This commit is contained in:
Martino Ferrari
2026-05-07 10:49:24 +02:00
parent 340b024ae4
commit 774808a054
21 changed files with 4986 additions and 362 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TUTORIAL.md
+200 -37
View File
@@ -1,56 +1,219 @@
# Tutorial: High-Speed Observability with MARTe2 Debug GUI
# Tutorial: Observability and Debugging with the MARTe2 Debug Suite
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.
This guide covers both transport options. Choose the one that fits your workflow:
## 1. Environment Setup
| | `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
### 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:
```bash
./run_debug_app.sh
cd /path/to/your/marte2/project
source /path/to/marte_debug/env.sh
```
*Note: You should see logs indicating the `DebugService` has started on port 8080 and `TcpLogger` on port 8082.*
### Start the GUI Client
In a new terminal window, navigate to the client directory and run the GUI:
### 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
```
## 2. Exploring the Object Tree
Once connected, the left panel (**Application Tree**) displays the live hierarchy of your application.
The GUI connects to `localhost:8080` automatically and requests the tree on startup.
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.
### B.4 Exploring the Object Tree
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.
The **Application Tree** panel on the left shows the live ORD.
## 4. Signal Forcing (Manual Override)
Forcing allows you to bypass the framework logic and manually set a signal's value in memory.
1. Expand `Root → App → Data`.
2. Click **ℹ Info** next to any node to see its JSON config in the bottom-left pane.
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
### B.5 Real-Time Signal Tracing (Oscilloscope)
### 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.
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.
### Log Terminal
The bottom panel displays every `REPORT_ERROR` event from the C++ framework, powered by the standalone `TcpLogger` service.
- **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.
---
### 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).