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.

Platform support

The Command Processor service builds from sources on all known Kanzi target platforms.

  • The local console requires stdin/stdout access.

  • The remote console uses the Windows Sockets API on Windows and POSIX sockets on Android, Linux, and QNX.

  • The serial console uses the Windows COM port API on Windows and POSIX termios on Android, Linux, and QNX.

How the Command Processor service works

The Command Processor service operates as a pipeline:

  1. Input – A console (local or remote) reads a command string from the user.

  2. Parse – The first word is the command name, the rest is passed as arguments.

  3. Lookup – The command registry is searched for a matching command.

  4. Execute – The command handler runs and writes output to the console.

  5. 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 QNX boards, 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 code and CMake projects are included under tools/.

To build all tools from source on Windows:

scripts\build_tools.bat vs2022 Release

To build all tools from source on Linux:

scripts/build_tools.sh Release

The built executables are placed in tools/bin/.

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/.

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.

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

# 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 QNX boards, 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, QNX, 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/.

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 information about the Kanzi runtime environment:

kzinfo

Example output:

Kanzi Engine 4.0.0
Kanzi Monitor Plugin 1.40.0
Platform OS: Windows
GraphicsOutput: 640x480
GraphicsOutput Type: WindowedGraphicsOutput
Window Size: 640x480
NativeWindowHandle: HWND
Graphics Backend: OpenGL
Graphics API Version: 4.6
Graphics Device: Intel(R) Arc(TM) 140V GPU (16GB)

The reported fields:

  • Kanzi Engine version – The version of the Kanzi Engine that the application is linked against.

  • Kanzi Monitor Plugin version – The version of the Kanzi Monitor that is loaded.

  • Platform OS – The detected operating system: Windows, Android, Linux, QNX, or Other.

  • GraphicsOutput – The layout area size in pixels.

  • GraphicsOutput Type – WindowedGraphicsOutput (windowed platforms) or Non-windowed (headless/offscreen). Reports “Not available” if no graphics output is present.

  • Window Size – The window size in platform-specific units (windowed outputs only).

  • NativeWindowHandle – The platform-specific window handle type: HWND (Windows), ANativeWindow* (Android), (X11) uint32_t, (Wayland), QNX screen_window_t, or Unknown.

  • Graphics Backend – The active graphics API: Vulkan, OpenGL, OpenGL ES, or Unknown.

  • Graphics API Version – The version of the active graphics API.

  • Graphics Device – The GPU device name reported by the graphics driver.

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.

Available commands

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

Command

Description

help

Shows available commands with their description. Usage: help [command]

kzinfo

Shows Kanzi Runtime information including engine version, platform, graphics output, and GPU device.

perfinfo

Shows Performance information.

meminfo

Shows Memory usage information.

resinfo

Shows Resource Manager information.

graphicsinfo

Shows detailed graphics information: backend type, API version, device name, driver version, and max texture size.

purge

Purges Resources from the ResourceManager.

idlesuspend

Gets and sets MainLoop SuspendWhenIdle. Usage: idlesuspend [0|1]

fpslimit

Sets MainLoop framerate limit. Usage: fpslimit [fps]

profcats

Sets all Profiling Categories enabled state. Usage: profcats [0|1]

quit

Shuts down the Kanzi Engine.

nodetreeinfo

Shows Node Tree information. Usage: nodetreeinfo [index]

The following commands are available when the Application instance is registered. See Enabling features that depend on the Application instance.

Command

Description

appquit

Quits the application.

appfpsinfo

Shows Application performance information.

perfinfolevel

Gets and sets the application PerformanceInfo level. Usage: perfinfolevel [0|1|2]

See also

Using the Overwatch service

Using the Monitor Web UI

Configuring Kanzi Monitor