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.
Dispatch message – On the Nodes tab, above the properties: dispatch a message from the selected node. Pick the message type from the list, fill in the arguments you want (one row per declared argument; the Web UI checks only the number of components of a composite value, and the application checks the rest and names any argument it refuses), and Dispatch. The first dispatch of a message asks for confirmation and shows its routing and which arguments will be left at their default; dispatching the same message again does not ask. The result line says whether a handler marked the message handled, and a refusal says why. See Dispatching a message.
Property Inspector – View and edit properties on selected nodes. A string property is edited in a multi-line text box, so its value can hold line breaks; emptying the box clears the string. A Resource-typed property shows the resource it references, with its class, and takes a resource URL or a ResourceID; Clear releases the reference, and setting the URL back restores it. See Resource-typed properties.
Resource Viewer – Browse resources in two views. Loaded shows overwatch.resources, the resources that have a URL, and All shows overwatch.allresources, every resource the ResourceManager holds, with a name filter. In Loaded, the count and the CPU and GPU totals above the table cover every resource the manager holds, so they can exceed the rows listed; All lists the rest. See Which resource list to use. Both views show 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). The toolbar reports the ResourceManager memory strategy and lets you switch the default for resources acquired from then on. Read it before reading a Purge Resources result; after a switch, a purge covers resources acquired under both strategies. See The memory strategy behind a purge. The toolbar also takes a URL and an Acquire button to force a resource into existence, and each row with a URL offers unregister, which drops the URL association so the next acquire rebuilds the resource — the way to pick up a file:// asset you edited on disk. Each URL listed on the Engine tab’s KZB sub-tab is marked loaded or not, from an unfiltered overwatch.allresources, which counts a URL as loaded while it is registered: a URL that is not loaded has an acquire action for the same purpose, and a loaded one has unregister. See Forcing a resource into existence, and letting go of one. Selecting a resource also lists its properties in the viewer, editable in place with the same rows the Nodes tab uses, for any resource that has them: brushes, materials, render passes. See Reading and setting properties on any resource.
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. Framebuffer captures – the screenshot, the Capture tab’s frames, breakpoint captures – are oriented from the rowOrder each response reports rather than from a convention compiled into the browser. Kanzi Monitor reports "bottom-up" on every backend today, so if one ever stored its rows the other way round the plugin would have to learn that first; what the reported field buys is that the Web UI, the MCP server and your own clients then need no change of their own. Texture and render-pass previews carry no such report and follow the Flip vertical checkbox, which is flipped by default to match screen orientation. The moment you change that checkbox it takes over for every image, reported or not, and the images already on screen are corrected to match – so a host that misreports its row order is still yours to fix. 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.
Capture – Record a bounded sequence of screen frames into memory as a keep-last-N ring: Record arms it, Stop freezes it, Fetch frames retrieves what the ring holds, and Play steps or plays the frames back as a filmstrip you can scrub and download. Drives the capture.* commands. See Using the Capture service.
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.
Debug – Set property breakpoints and view the screenshots they capture. Add a breakpoint by node path, property name, value and optional hit count; list, refresh and clear the ones already set. A breakpoint on a property the node has no value for yet is labeled Dormant until the first write to it. Drives the debug.* commands. See Using the Debug service.
DataSources – Inspect and edit DataSource and DataObject trees. A string data object is edited in a multi-line text box, as a string property is. 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. The Profiling Categories card lists every profiling category Kanzi Monitor can find (kzTrace categories are separate), with a checkbox to enable or disable each one, a filter field (ProfilingCategoryFilter syntax, for example *=off;MainLoop=on) and a Reset button that returns every category to its code default and applies the startup filter again, a defined state rather than an undo. A disabled category records nothing, so this decides what a capture can contain; see Choosing which profiling categories are recorded. The kzTrace Categories card beside it lists the kzTrace categories, with their descriptions and ids. It is read-only, because Kanzi 4.1 cannot switch them, and in a Release build it says that kzTrace is not available; see Listing the kzTrace categories.
Logs – Log entries with severity and category filters, live auto-refresh, editable buffer size, and download as TXT.
Engine – Runtime introspection of what the application was built with, in four views: KZB Files, Property Types, Message Types and Metaclasses. Filter any view by name and cap the number of rows returned. Drives the introspection commands the Engine tab shares with the MCP server. Under Kanzi Studio Preview, KZB Files does not list the project being authored: Kanzi holds the kzb of each patch from Kanzi Studio only while it applies the patch. The project’s loaded resources are still in the Resource Viewer, in both views, and reachable by URL and handle; acquiring one that is not loaded, including after unregister, fails until the next patch. An exported kzb that an application loads is listed as usual. See kzb files. In Metaclasses, each class lists its base class and, in the Mixins column, the concepts mixed into it, which declare property and message types for the class without being on its base chain. The runtime leaves out the unnamed concept template instantiations, and a note above the table says how many. See Reading the type graph: base classes and mixins. Each metaclass row has a Schema button that lists the property and message types the class declares across its base chain and its mixed-in concepts, each attributed to the class that declares it, with the walk that produced the union. That differs from the row’s own counts, which cover the class alone: Kanzi.TextBlock3D declares 2 property types itself and 65 with its base chain and concepts. Neither is everything that affects a node of that class: attached properties and inherited values are declared by other classes. See What a class declares, in one call.
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.