Using the Monitor Web UI¶

The Monitor Web UI is a browser-based graphical interface for remotely inspecting and debugging Kanzi applications. It connects to the Overwatch service through a Python WebSocket bridge and provides visual tools for browsing the scene graph, editing properties, previewing textures and screenshots, monitoring performance, and capturing traces.

The tool is located in tools/monitor-web-ui/. See tools/monitor-web-ui/README.md for the full reference.

Requirements¶

Python 3.7 or later
websockets library: pip install websockets
For serial and UART connections: pip install pyserial-asyncio-fast

Starting the Monitor Web UI¶

To start the Monitor Web UI:

Make sure that the Overwatch service is enabled (enabled by default). To disable property editing, set OverwatchPropertyChangeEnabled = 0 in kanzimonitor.cfg.
Start the Kanzi application with Kanzi Monitor.
Start the WebSocket bridge:
```
cd tools/monitor-web-ui
pip install websockets
python bridge.py
```
The bridge connects to Kanzi Monitor at 127.0.0.1:56000 and serves the web UI at http://localhost:8765.
Open http://localhost:8765 in your browser.

Connecting to remote or embedded targets¶

To connect to Kanzi Monitor running on a different machine:

python bridge.py --monitor-host 192.168.1.100

To connect through serial and UART for embedded targets with SerialConsoleEnabled = 1:

pip install pyserial-asyncio-fast
python bridge.py --serial-port COM3
python bridge.py --serial-port /dev/ttyUSB0 --baud-rate 921600

Features¶

The Monitor Web UI provides these features:

Node Tree – Live scene graph with expand/collapse, auto-refresh, and node type icons.
Property Inspector – View and edit properties on selected nodes.
Resource Viewer – Browse all resources with texture type details (including cubemap face count), texture preview, per-face cubemap preview (all six faces shown as a thumbnail strip, click to enlarge), GPU readback, full-resolution toggle, and download (PNG and Raw RGBA).
Performance – FPS and frame timing metrics, rendering statistics, GPU object counts, staging buffer usage, configurable performance watchers, auto-refresh. Includes a SuspendWhenIdle status indicator and toggle. When SuspendWhenIdle is active, the application only renders on input or state changes, which affects FPS measurement accuracy.
Screen Capture – Screenshot with full-resolution toggle and download. Inspect and download framebuffer previews. All image previews are flipped vertically by default to match screen orientation (GPU framebuffer data is bottom-up); use the Flip vertical checkbox to toggle. Overlay controls for the PerformanceInfo level (perfinfolevel), Monitor UI visibility (ui), BasicUI screen selection (basicui), and font scale (fontscale). Controls auto-detect which commands are available. Note that when the Monitor UI overlay is visible, it captures touch input from the application.
Render Passes – Render pass tree with CompositionTarget preview and download (PNG and Raw RGBA). Selecting any pass shows its properties, editable in place with the same rows the Nodes tab uses. Turning RenderPass.Enabled off and re-reading the preview of the composition target above it shows what that pass contributes.
DataSources – Inspect and edit DataSource and DataObject trees. DataObjectList nodes display an item count badge and expand to show individual list items as tree children.
Fonts – Browse active FontRuntime instances with font identity, style definition, glyph cache state, font metrics, and glyph atlas texture preview. Edit the glyph cache texture size for newly created caches. Shows an informational message when the node tree is not available.
Trace – Capture and view profiling traces with summary stats and download. Use the Trace Source selector to switch between Monitor Profiling (all builds, with engine-internal instrumentation in Profiling builds) and kzTrace (Debug/Profiling builds), and the Format selector to see and switch the active trace writer (chrometrace, perfetto, or both — the runtime’s writer set, re-read on every Trace-tab entry and after a change from this tab). Capture Trace fetches whichever format the capture actually produced: the runtime reports the written filename and the tab routes on its extension, so a perfetto-only configuration works end to end without touching the fetch buttons. A new capture clears every cached trace display, and a fetch that serves a file that cannot be the one the capture wrote — an older same-format trace, or a JSON when the capture produced a .perfetto-trace — is called out in the status line instead of shown as current. The Fetch .perfetto-trace button retrieves the native Perfetto protobuf file — the bridge ships the binary as base64 over the line protocol and the UI decodes and holds it in memory; a single Download button (labeled after the loaded format) is the explicit save action for either format. The View in Perfetto button opens the most recently fetched trace directly in Perfetto UI (new browser tab) via Perfetto’s official postMessage embedding protocol; trace bytes stay in your browser. The button works for both chrometrace JSON and .perfetto-trace formats and prefers the binary one when both are loaded.
Logs – Log entries with severity and category filters, live auto-refresh, editable buffer size, and download as TXT.
Graphics Info – GPU and graphics details.
Interactive Console – Send arbitrary commands to Kanzi Monitor.

Using the standalone executable¶

All platform packages include a prebuilt standalone executable monitor-web-ui-win64.exe under tools/monitor-web-ui/dist/. Double-click to launch. The browser opens automatically.

To rebuild it from source:

cd tools/monitor-web-ui
build_exe.bat

This creates dist/monitor-web-ui.exe (approximately 10-15 MB).

Command-line options:

monitor-web-ui.exe --monitor-host 192.168.1.100    Connect to remote Monitor
monitor-web-ui.exe --serial-port COM3               Connect through serial/UART
monitor-web-ui.exe --no-browser                     Do not auto-open browser

Understanding the architecture¶

                                                     TCP (default)
+-----------------+     WebSocket      +-----------------+<--------------->+-----------------+
|   Web Browser   |<----------------->|   bridge.py     |  localhost:56000|    Monitor      |
|   (index.html)  |   ws://localhost   |   (Python)      |                 |  (Kanzi Plugin) |
+-----------------+       :8765        +-----------------+<--------------->+-----------------+
                                                        Serial (--serial-port)
                                                         COM3 / /dev/ttyUSB0

The web UI sends overwatch.* commands through WebSocket. The bridge forwards them to the Kanzi Monitor console (TCP or serial) and returns JSON responses.

Capturing screenshots¶

Screenshot capture schedules a framebuffer readback for the next render frame. If the application is not rendering new frames, the capture cannot complete and the UI reports Screenshot timed out — render stage did not complete. When running under Studio Preview, enable Allow preview to update if not in focus so the preview keeps rendering while the Monitor Web UI has focus.

Serial bandwidth considerations¶

At 115200 baud (approximately 11.5 KB/s), large responses like texture previews or screenshots can be slow. The UI automatically reduces default image sizes on serial connections.

Recommendations:

Use a higher baud rate when the hardware supports it (--baud-rate 921600).
Text-based commands (nodes, props, perf) work well even at 115200 baud.
Avoid full-resolution images over serial unless necessary. The UI shows a confirmation dialog before proceeding.
Trace files can be several MB. The UI does not auto-fetch them over serial.