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 preview, 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. The PerformanceInfo Level control requires the Application to be registered with Monitor. 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).
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.
Trace – Capture and view profiling traces with summary stats and download as JSON. Use the Trace Source selector to switch between Monitor Profiling (all builds, with engine-internal instrumentation in Profiling builds) and kzTrace (Debug/Profiling builds).
Logs – Log entries with severity filter, live auto-refresh, 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.

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.