Using the Command Processor service¶

The Command Processor service provides a command-line interface (CLI) for interacting with the Kanzi Engine at runtime. You can enter commands from a local console (stdin/stdout), send them remotely over a TCP socket connection, or send them over a serial port (UART) connection. The service includes built-in commands for inspecting and controlling the Kanzi Engine, and you can register custom commands through the API.

All platform packages include prebuilt RemoteConsoleClient and SerialConsoleClient applications for Windows and Linux under tools/RemoteConsoleClient/bin/ and tools/SerialConsoleClient/bin/. The source code is also included for rebuilding (see Building the tools from source).

Platform support¶

The Command Processor service builds from sources on all Kanzi target platforms supported by this release.

The local console requires stdin/stdout access.
The remote console uses the Windows Sockets API on Windows and POSIX sockets on Android and Linux.
The serial console uses the Windows COM port API on Windows and POSIX termios on Android and Linux.

How the Command Processor service works¶

The Command Processor service operates as a pipeline:

Input – A console (local or remote) reads a command string from the user.
Parse – The first word is the command name, the rest is passed as arguments.
Lookup – The command registry is searched for a matching command.
Execute – The command handler runs and writes output to the console.
Response – The console delivers the output back to the user, followed by execution time.

The service supports three console types that can run simultaneously:

Local console – Uses stdin and stdout for interactive terminal use. Suitable for development and testing on desktop platforms.
Remote console – A TCP socket server that accepts connections from the RemoteConsoleClient or any TCP client. Suitable for deployed applications, headless targets, and Android devices.
Serial console – A serial port (UART) connection that accepts commands from the SerialConsoleClient or any serial terminal. Suitable for embedded targets where TCP is not available, such as Android hardware and Linux embedded systems.

All consoles share the same command registry. Commands registered by any service or by application code are available from all consoles.

Building the tools from source¶

The RemoteConsoleClient and SerialConsoleClient source, Visual Studio solutions (vs2015 / v140 toolset), and CMake projects are included under tools/.

On Windows, build both console clients with the convenience script, which places the executables in each tool’s bin/ directory:

scripts\build_tools.bat Release

Alternatively, open tools/RemoteConsoleClient/RemoteConsoleClient.sln (or tools/SerialConsoleClient/SerialConsoleClient.sln) in Visual Studio and build the Release configuration.

On Linux, build each tool with its CMake project:

cd tools/RemoteConsoleClient
mkdir build && cd build
cmake ..
cmake --build .

This produces RemoteConsoleClient-linux-x86_64 (and likewise SerialConsoleClient-linux-x86_64 for the serial client). The clients use the Windows socket / COM-port APIs on Windows and POSIX sockets / termios on Linux.

Using the local console¶

The local console provides an interactive command prompt on stdin/stdout. When enabled, the console displays a welcome message and the prompt Enter Command >.

The local console is automatically disabled when Kanzi Monitor is running in Kanzi Studio Preview, because Kanzi Studio Preview does not provide stdin/stdout to plugins. The remote console remains available in Kanzi Studio Preview.

Using the remote console¶

The remote console is a TCP socket server that listens for incoming connections. It accepts one client connection at a time. When a client disconnects, the server returns to listening for a new connection.

Understanding the protocol¶

The remote console uses a simple line-based text protocol:

The client sends a command followed by a newline character (\n).
The server responds with one or more lines of output, terminated by an empty line (\n\n).
The client reads response lines until it encounters the empty terminating line.

Do not send empty commands. The server silently drops empty commands without sending a response, which causes the client to wait indefinitely for a response that never arrives.

Connecting with the RemoteConsoleClient¶

The RemoteConsoleClient is a standalone console application for Windows and Linux for connecting to the remote console. Prebuilt executables are included in all platform packages under tools/RemoteConsoleClient/bin/; you can also build it from source (see Building the tools from source).

RemoteConsoleClient-win64.exe [options] [serverAddress] [port]

The default server address is 127.0.0.1 and the default port is 56000.

Options:

-c, --command <cmd> – Send a single command and exit (non-interactive mode).
-h, --help – Show usage information.

Interactive mode (default) – The client connects and enters an interactive session:

Disconnected state – The client shows the prompt RemoteConsole> and accepts these local commands:

connect – Attempt to connect to the server.
exit – Quit the client.
help – Show usage help.

Connected state – The client shows the prompt Enter Command > and sends all input to the server. Two local commands are handled by the client:

disconnect – Close the connection and return to disconnected state.
exit – Quit the client.

The client automatically attempts to connect on startup. If the connection fails, it enters the disconnected state where you can retry with the connect command.

Single-command mode – When invoked with -c, the client connects, sends the command, prints the response to stdout, and exits with code 0 on success or 1 on error. This is useful for scripting and CI automation.

REM Send a single command and exit
RemoteConsoleClient-win64.exe -c "overwatch.status"

REM Single command to a remote host
RemoteConsoleClient-win64.exe 192.168.1.100 56000 -c "kzinfo"

Connecting with other TCP clients¶

Any TCP client that supports the line-based protocol can connect to the remote console.

For example, using a raw TCP connection:

telnet 127.0.0.1 56000

Using the serial console¶

The serial console provides command access over a serial port (UART) connection. It is designed for embedded targets where TCP networking is not available, such as Android hardware and Linux embedded systems.

The serial console is disabled by default. To enable it, set SerialConsoleEnabled = 1 in the configuration file and configure the port name and baud rate.

Unlike the remote console, the serial console does not use a listen/accept pattern. Serial is point-to-point: the plugin opens the configured port and immediately begins reading commands. When the remote end disconnects, the console continues to wait for new input on the same port.

Configuring the serial console¶

Set the serial port and baud rate in kanzimonitor.cfg:

SerialConsoleEnabled = 1
SerialConsolePort = COM7
SerialConsoleBaudRate = 115200

On Linux and Android, use the device path:

SerialConsolePort = /dev/ttyUSB0

The supported baud rates are: 9600, 19200, 38400, 57600, 115200, 230400, 460800. If an unsupported baud rate is configured, the console defaults to 115200 with a warning.

If the configured serial port cannot be opened (for example, the device does not exist or is in use), the application logs a warning and continues without the serial console.

Connecting with the SerialConsoleClient¶

The SerialConsoleClient is a standalone console application for Windows and Linux for connecting to the serial console. Prebuilt executables are included in all platform packages under tools/SerialConsoleClient/bin/; you can also build it from source (see Building the tools from source).

SerialConsoleClient-win64.exe [options] [portName] [baudRate]

The default port is COM3 on Windows and /dev/ttyUSB0 on Linux. The default baud rate is 115200.

Options:

-c, --command <cmd> – Send a single command and exit (non-interactive mode).
-h, --help – Show usage information.

The client uses the same command protocol and user interface as the RemoteConsoleClient, including support for single-command mode:

Disconnected state – The client shows the prompt SerialConsole> and accepts these local commands:

connect – Open the serial port.
exit – Quit the client.
help – Show usage help.

Connected state – The client shows the prompt Enter Command > and sends all input over the serial port. Two local commands are handled by the client:

disconnect – Close the serial port and return to disconnected state.
exit – Quit the client.

Single-command mode – When invoked with -c, the client opens the serial port, sends the command, prints the response to stdout, and exits with code 0 on success or 1 on error.

SerialConsoleClient-win64.exe COM5 115200 -c "overwatch.status"

Testing with virtual serial ports¶

On Windows, use com0com to create a virtual COM port pair (for example, COM7 and COM8). Configure the plugin on one port and the client on the other.

On Linux, use socat to create a virtual serial port pair:

socat -d -d pty,raw,echo=0 pty,raw,echo=0

This creates two pseudo-terminal devices (for example, /dev/pts/3 and /dev/pts/4). Configure the plugin on one and the client on the other.

Connecting to Android Emulator¶

The Android Studio Emulator runs on its own network within the host PC. Applications running in the emulator do not share the same localhost (127.0.0.1) as the host PC.

To connect from the host PC to a socket in the emulator, use port forwarding:

adb forward tcp:56000 tcp:56000

This maps the port of the emulator to the port of the host PC, allowing the RemoteConsoleClient to connect to 127.0.0.1:56000.

Inspecting the runtime environment¶

The kzinfo command displays Kanzi and Kanzi Monitor version information, the platform OS, the build configuration, and whether graphics-API-call logging is available:

kzinfo

Example output:

Kanzi version: 3.6.21
Kanzi Monitor 1.6.0
Platform OS: Windows
Build configuration: Release
Graphics logging: available

The build configuration is derived from the Kanzi compile-time defines (Debug, Profiling, or Release). Graphics-logging availability reflects whether the engine’s runtime graphics backend is compiled in (KZ_RUNTIME_GRAPHICS_BACKEND): it is always available for the desktop OpenGL profile (including Windows, in all configurations), but only in debug builds for the embedded GLES profiles.

The reported fields:

Kanzi version – The version of the Kanzi Engine that the application is linked against.
Kanzi Monitor version – The Kanzi Monitor plugin version.
Platform OS – The detected operating system: Windows, Android, Linux, or Other.

Adding custom commands¶

You can register custom commands through the Command Processor service API.

A command handler has this signature:

int myCommandHandler(CommandProcessingManager* commandProcessor,
                     Console* console,
                     const kanzi::string& args,
                     void* userData);

The handler receives the command processor, the console for writing output, the argument string, and optional user data. Return 0 for success.

To register a command:

KanziMonitorModule* module = getKanziMonitorModule(domain);
CommandProcessorService* service = module->getCommandProcessorService();
service->addCommand("mycommand", myCommandHandler, myUserData,
                    "Description of my command. Usage: mycommand [arg]");

For commands that accept arguments, include Usage: command [args] at the end of the help text. This convention is used by all built-in commands and helps users discover the expected arguments through the help command.

The Kanzi Monitor example application’s CustomPerformanceTools plugin demonstrates this pattern with the glyphcachestress command. It cycles mixed Latin and CJK text through all TextBlock nodes in the scene to provoke glyph cache flush conditions, which is useful together with the font glyph-cache tools.

Usage: glyphcachestress [interval_ms] [node_filter] starts the test (default interval 100 ms; an optional node-path filter limits it to matching nodes). glyphcachestress stop restores the original text and prints a summary. The command mutates node text, so it requires OverwatchPropertyChangeEnabled=1. A CJK-capable font is needed for the full effect.

The recurring update is driven by a Kanzi message-dispatcher timer (kanzi::addTimerHandler), not the per-frame service contract — the work is not tied to a specific main-loop stage. See examples/monitor_example/Application/src/plugin/src/cpt_tests.cpp for the implementation.

Available commands¶

The built-in commands registered by the Command Processor service:

Command	Description
`help`	Shows available commands with their description.
`kzinfo`	Shows Kanzi and Kanzi Monitor version information.
`graphicsinfo`	Shows graphics subsystem information.
`meminfo`	Shows Resource Manager memory usage.
`resinfo`	Lists all loaded resources with memory usage.
`purge`	Purges unused resources and shows freed memory.
`profcats`	Enables or disables all profiling categories. Usage: `profcats [0\|1]`
`graphicslog`	Enables or disables graphics API call logging. Usage: `graphicslog [0\|1] [dump]`
`fontinfo`	Shows glyph-cache information for all active fonts.
`nodetreeinfo`	Shows node tree information. Usage: `nodetreeinfo [index]`
`echo`	Echoes the arguments back to the console.
`appquit`	Quits the application.
`idlesuspend`	Gets and sets MainLoop SuspendWhenIdle. Usage: `idlesuspend [0\|1]`

Note

On Kanzi 3.6, idlesuspend with no argument reports the value last set through Monitor, not the Kanzi Engine’s live state, because Kanzi 3.6 provides no getter for it. Setting the value (idlesuspend 0 / idlesuspend 1, the Web UI toggle, or the MCP set_idle_suspend tool) always applies correctly and keeps the reported value in sync; the report can drift only if the application changes idle-suspend by another path. See Known issues.

Other services and the application register their own commands with the same registry — for example perfinfo2 / watch (Performance service), appfpsinfo / perfinfolevel (application performance, registered by the Command Processor service), ui / basicui / fontscale (UI service), loginfo / logdiag (Log service), trace (Trace service), and the overwatch.* commands (Overwatch service). See the corresponding service pages.