RDK Window Manager

RDK Window Manager (rdkwindowmanager) is responsible for creating Wayland displays, compositing application surfaces, managing window properties, and handling input routing and focus on RDK video and entertainment devices. It depends on Westeros for Wayland compositor creation and Essos for display context management, and exposes its control surface as a Thunder plugin that clients reach through the Firebolt API layer.

RDK Window Manager is the display and input management layer within the RDK Core Middleware stack. It initialises a Westeros-backed Wayland compositor, allocates per-application display surfaces, composites those surfaces onto the screen using OpenGL ES 2.0, and routes key and pointer input from Linux input devices to the correct application. Window properties — position, size, opacity, z-order, visibility, and crop — are managed at runtime. An inactivity-detection mechanism monitors the elapsed time since the last key event and notifies subscribers when the device becomes idle.

The component ships three Wayland protocol extensions (firebolt_shell, firebolt_surface, firebolt_wm) that give Wayland clients direct access to surface creation and property control without requiring a Thunder round-trip. When enabled at build time, a VNC server provides remote frame-buffer access over a TCP connection.

From a device perspective the component acts as the single Wayland display server for all applications — native, HTML, and Lightning — and arbitrates which application receives keyboard focus at any given moment. It is consumed by the Thunder plugin that bridges higher-level Firebolt API calls down to the compositor.

flowchart LR

%% Styles
classDef Apps stroke:#00B9F1,fill:#E6F7FD,stroke-width:2px;
classDef RDKMW stroke:#75D701,fill:#F1FFE6,stroke-width:2px;
classDef VL stroke:#808080,fill:#F2F2F2,stroke-width:2px;

    subgraph Apps["Apps & Runtimes"]
        NativeApp["Native App"]
        HTMLApp["HTML / WPE App"]
        LightningApp["Lightning App"]
    end

    subgraph RDKMW["RDK Core Middleware"]
        Thunder["WPEFramework (Thunder)"]
        RDKWM["RDK Window Manager\n(librdkwindowmanager.so)"]
        Westeros["Westeros Compositor"]
        Essos["Essos Display Context"]
    end

    subgraph VL["Vendor Layer"]
        EGL["EGL / OpenGL ES 2.0"]
        LinuxInput["Linux Input Devices"]
    end

    Apps -->|Wayland / Firebolt WM Protocol| RDKWM
    Thunder -->|JSON-RPC / Thunder API| RDKWM
    RDKWM --> Westeros
    RDKWM --> Essos
    RDKWM -->|HAL APIs| VL

Key Features & Responsibilities:

• Wayland Display Creation: Creates and manages per-application embedded Westeros compositor instances, assigns display names, and tracks client connection and disconnection lifecycle.
• Surface Composition: Composites multiple application surfaces onto the display each frame using OpenGL ES 2.0, respecting z-order, opacity, position, size, and crop parameters for each surface.
• Input Routing and Focus Management: Receives key and pointer events from Essos, maps Linux/Wayland key codes to RDK virtual key codes, and dispatches events to the focused application or to registered key intercept and listener handlers.
• Key Intercept and Listener Registration: Allows applications to register intercepts for specific key codes — with optional focus-only and propagation modes — and listeners that can activate or suppress key propagation.
• Inactivity Reporting: Tracks elapsed time since the last key event and fires an inactivity notification to registered listeners once the configurable threshold is exceeded.
• Firebolt Wayland Extensions: Provides firebolt_shell, firebolt_surface, and firebolt_wm Westeros protocol plugins that give Wayland clients fine-grained surface management without a Thunder round-trip.
• VNC Remote Access: Optionally starts a TCP-based VNC server that captures the current frame buffer and serves it to remote clients (enabled at build time via RDK_WINDOW_MANAGER_VNC_SERVER).
• Input Device Classification: Reads a JSON configuration file to classify attached Linux input devices by vendor, product, and device type, allowing key metadata to carry device-type information to applications.
• Memory Threshold Configuration (not currently enforced): Parses RAM/swap threshold environment variables (RDK_WINDOW_MANAGER_LOW_MEMORY_THRESHOLD, RDK_WINDOW_MANAGER_CRITICALLY_LOW_MEMORY_THRESHOLD, RDK_WINDOW_MANAGER_SWAP_MEMORY_INCREASE_THRESHOLD), but does not currently emit notifications because memory monitoring is not started in the main loop.

Design

RDK Window Manager is built as a shared library (librdkwindowmanager.so) that typically runs inside a Thunder plugin; the repository also provides a standalone rdkwindowmanager executable that links the same code for direct execution/testing. Its architecture separates concerns across five focused layers: initialisation and lifecycle (RdkWindowManager namespace), Essos context and input ingestion (EssosInstance), compositor creation and per-client surface management (RdkCompositor / RdkCompositorNested), the orchestration and routing logic that operates across all active compositors (CompositorController), and the Wayland extension plugins (firebolt_shell, firebolt_surface, firebolt_wm). Each layer communicates through well-defined C++ interfaces, and the component exposes its full north-bound API via this shared library.

Northbound interaction is through the Thunder JSON-RPC interface exposed by the companion Thunder plugin. That plugin forwards calls directly to CompositorController static methods. The Wayland extension layer provides an orthogonal northbound path: Wayland clients load the extension protocols and communicate directly with the window manager process over the existing Wayland socket, bypassing Thunder entirely for performance-sensitive surface property updates.

Southbound, the component binds to Essos for display context initialisation and key/pointer event delivery, and to Westeros for embedded compositor creation (WstCompositorCreate, WstCompositorStart, and associated callbacks). OpenGL ES 2.0 is used directly for off-screen frame buffer rendering and final composition. Linux input devices are enumerated and classified through a JSON configuration file parsed by RdkWindowManagerJson, and raw Wayland key codes are translated to RDK virtual key codes by linuxkeys.

The Thunder plugin calls into the window manager in-process via the shared library interface (librdkwindowmanager.so). Communication between the window manager and Wayland client applications is through the standard Wayland socket protocol, extended by the three Firebolt Westeros protocol plugins.

Runtime state — including window property changes, focus assignments, and key intercept registrations — is held in process memory for the duration of the session.

graph TD
    subgraph RDKWindowManagerProcess["rdkwindowmanager process"]

        subgraph Lifecycle["Lifecycle"]
            Init["initialize()"]
            RunLoop["run() / draw() / update()"]
        end

        subgraph EssosLayer["Essos Integration"]
            EssCtx["EssosInstance"]
            KeyEvt["Key / Pointer Callbacks"]
        end

        subgraph CtrlLayer["Compositor Controller"]
            CompCtrl["CompositorController (static)"]
            KeyIntercept["Key Intercept Table"]
            KeyListener["Key Listener Table"]
            InactivityTimer["Inactivity Timer"]
            VNCServer["VNC Server (optional)"]
        end

        subgraph CompositorLayer["Per-App Compositors"]
            RdkComp["RdkCompositor (base)"]
            NestedComp["RdkCompositorNested"]
            FrameBuf["FrameBuffer / FrameBufferRenderer"]
            CursorMgr["Cursor"]
        end

        subgraph ExtensionLayer["Wayland Extensions"]
            FBShell["firebolt_shell plugin"]
            FBSurface["firebolt_surface plugin"]
            FBWM["firebolt_wm plugin"]
        end

        subgraph InputLayer["Input Handling"]
            LinuxInput["linuxinput (device config)"]
            LinuxKeys["linuxkeys (key mapping)"]
        end

    end

    Init --> EssCtx
    Init --> CompCtrl
    RunLoop --> CompCtrl
    EssCtx --> KeyEvt
    KeyEvt --> CompCtrl
    CompCtrl --> KeyIntercept
    CompCtrl --> KeyListener
    CompCtrl --> InactivityTimer
    CompCtrl --> NestedComp
    NestedComp --> RdkComp
    RdkComp --> FrameBuf
    NestedComp --> FBShell
    NestedComp --> FBSurface
    NestedComp --> FBWM
    CompCtrl --> CursorMgr
    CompCtrl --> VNCServer
    LinuxInput --> EssCtx
    LinuxKeys --> CompCtrl

Threading Model

• Threading Architecture: Multi-threaded.
• Main Thread: Runs the RdkWindowManager::run() loop, calling EssosInstance::update(), CompositorController::update(), and CompositorController::draw() at the configured frame rate (default 40 fps, overridable via RDK_WINDOW_MANAGER_FRAMERATE). All Westeros callbacks and key-event processing also execute on this thread.
• Worker Threads:
• Application launch thread: Each RdkCompositor can spawn a background thread via launchApplicationInBackground() to start the associated application process without blocking the main loop.
• VNC GMainLoop thread (when RDK_WINDOW_MANAGER_VNC_SERVER is enabled): VncServer runs a GLib main loop on a dedicated thread to serve VNC TCP connections.
• Synchronization: A std::mutex (gFireboltExtensionListenerMapMutex) guards the Firebolt extension event listener map. RdkCompositor uses mInputLock and mStateChangeLock mutexes to protect its input-listener and state-change-listener maps. FireboltWindowManager and FireboltShell each hold a mContextLock mutex protecting their per-compositor client maps.
• Async / Event Dispatch: Essos delivers key and pointer callbacks synchronously on the main thread. Application lifecycle events (connect, disconnect, terminate) are dispatched from Westeros WstClient_* status callbacks, also on the main thread, and forwarded to registered RdkWindowManagerEventListener implementations.

Platform and Integration Requirements

• Build Dependencies: westeros, wayland, essos, virtual/egl, rapidjson, jpeg, libpng. For the rdkwmtest test executable: additionally curl. When RDK_WINDOW_MANAGER_VNC_SERVER=ON: additionally libsoup-2.4, boost, libsyswrapper. When BUILD_ENABLE_ERM: additionally essos-resmgr.
• Wayland Protocol Extensions: firebolt_shell, firebolt_surface, and firebolt_wm protocol XML files are compiled into server-side Westeros plugins (libwstplugin_rdkwmfirebolt*.so) and client-side shared libraries (librdkwmext*.so). Extensions are loaded from the compiled-in path defined by RDK_WINDOW_MANAGER_WESTEROS_PLUGIN_DIRECTORY (set via CMake RDK_WINDOW_MANAGER_WESTEROS_PLUGIN_FOLDER; default /usr/lib/plugins/westeros/).
• Configuration Files: Input device type configuration file path supplied through RDK_WINDOW_MANAGER_INPUT_DEVICES_CONFIG. Splash screen suppression: presence of /tmp/.rdkwindowmanagersplash controls splash rendering.
• Startup Order: The rdkwindowmanager executable must be started before any Wayland client applications attempt to connect.

Component State Flow

Initialization to Active State

The component progresses from system start through Essos and Westeros initialisation before entering its render and event loop.

The component transitions through the following states during its lifecycle: Initializing (configure logging, read key mappings, read input device config, apply environment-variable overrides) → DisplaySetup (initialise Essos context at target resolution) → CompositorReady (CompositorController::initialize() called, OpenGL blend state configured) → Active (frame-rate render loop running, key and pointer events dispatched) → Shutdown (loop exits, resources released).

sequenceDiagram
    participant Main as main()
    participant WM as RdkWindowManager
    participant Essos as EssosInstance
    participant CC as CompositorController

    Main->>WM: initialize()
    WM->>WM: mapNativeKeyCodes() / mapVirtualKeyCodes()
    WM->>WM: readInputDevicesConfiguration()
    WM->>WM: Apply env-var overrides (framerate, memory thresholds, key delays)
    WM->>Essos: instance()->initialize(false, width, height)
    Essos-->>WM: Essos context ready
    WM->>WM: glEnable(GL_BLEND)
    WM->>CC: initialize()
    CC-->>WM: CompositorController ready
    WM-->>Main: initialize() returns

    Main->>WM: run()
    loop Frame loop (40 fps default)
        WM->>Essos: update()
        WM->>CC: update()
        WM->>CC: draw()
    end

    WM-->>Main: run() returns (on shutdown)

Runtime State Changes

Application connection and disconnection events arrive through Westeros WstClient_* callbacks and are forwarded to registered RdkWindowManagerEventListener instances. Focus changes are driven by explicit CompositorController::setFocus() calls from the Thunder plugin. Inactivity detection runs inside CompositorController::update(): when gEnableInactivityReporting is true and the time since the last key event exceeds gInactivityIntervalInSeconds, onUserInactive is fired on the registered listener.

State Change Triggers:

• A new Wayland client connecting fires onApplicationConnected; disconnection fires onApplicationDisconnected.
• Receipt of the first rendered frame from a client fires onReady.
• Time elapsed without key input exceeding gInactivityIntervalInSeconds fires onUserInactive.
• Visibility changes (set via CompositorController::setVisibility()) fire onApplicationVisible or onApplicationHidden.
• Focus assignment via CompositorController::setFocus() fires onApplicationFocus on the newly focused client and onApplicationBlur on the previously focused one.

Context Switching Scenarios:

• When ignoreKeyInputs(true) is active, all key events are dropped before reaching the intercept or listener evaluation logic.
• Key intercept entries marked focusOnly=true suppress delivery to non-focused applications.
• Topmost compositor entries (stored in gTopmostCompositorList) are evaluated independently from the standard compositor list, allowing system overlays to receive input regardless of normal focus order.

Call Flows

Initialization Call Flow

sequenceDiagram
    participant Main as main()
    participant WM as RdkWindowManager::initialize()
    participant Essos as EssosInstance
    participant Keys as linuxkeys / linuxinput
    participant CC as CompositorController

    Main->>WM: initialize()
    WM->>Keys: mapNativeKeyCodes()
    WM->>Keys: mapVirtualKeyCodes()
    WM->>Keys: readInputDevicesConfiguration()
    WM->>WM: Read env vars (log level, framerate, memory thresholds, key delays)
    WM->>Essos: configureKeyInput(initialDelay, repeatInterval)
    WM->>Essos: initialize(false, width, height)
    Essos-->>WM: EssContext created and started
    WM->>WM: glEnable / glBlendFunc
    WM->>CC: initialize()
    CC-->>WM: Done
    WM-->>Main: returns

Request Processing Call Flow

The following illustrates CreateDisplay — the most common setup call — flowing from the Thunder plugin down through CompositorController to the Westeros-backed nested compositor. The component validates the provided parameters before forwarding the request, and propagates the Westeros API result back to the caller as a boolean response.

sequenceDiagram
    participant Client as Thunder Plugin
    participant CC as CompositorController
    participant Nested as RdkCompositorNested
    participant Wst as WstCompositor (Westeros)

    Client->>CC: createDisplay(client, displayName, width, height, ...)
    CC->>Nested: new RdkCompositorNested
    Nested->>Wst: WstCompositorCreate()
    Nested->>Wst: WstCompositorSetIsEmbedded(true)
    Nested->>Wst: WstCompositorSetOutputSize(width, height)
    Nested->>Wst: WstCompositorSetDisplayName(displayName)
    Nested->>Nested: loadExtensions() / loadfireboltExtensions()
    Nested->>Wst: WstCompositorStart()
    Wst-->>Nested: compositor started
    Nested-->>CC: createDisplay returns true
    CC-->>Client: true

Internal Modules

Component Interactions

Interaction Matrix

Events Published

IPC Flow Patterns

Primary Request / Response Flow (Thunder JSON-RPC to CompositorController):

The Thunder plugin receives a JSON-RPC request, validates parameters, and calls the corresponding CompositorController static method directly through the shared library interface. The method return value or output parameter is converted back to a JSON-RPC response.

sequenceDiagram
    participant Client as Client Application
    participant Thunder as WPEFramework (Thunder)
    participant Plugin as RDK WM Thunder Plugin
    participant CC as CompositorController

    Client->>Thunder: JSON-RPC request (e.g., setFocus)
    Thunder->>Plugin: Dispatch to plugin handler
    Plugin->>CC: CompositorController::setFocus(client)
    CC-->>Plugin: true / false
    Plugin-->>Thunder: JSON-RPC response
    Thunder-->>Client: JSON-RPC response

Key Event Flow (Essos to CompositorController to Application):

sequenceDiagram
    participant HW as Linux Input Device
    participant Essos as EssosInstance
    participant CC as CompositorController
    participant App as Focused Wayland App

    HW->>Essos: Key event (Essos callback)
    Essos->>Essos: Translate modifiers, process metadata
    Essos->>CC: onKeyPress(keyCode, flags, metadata)
    CC->>CC: Check ignoreKeyInputs flag
    CC->>CC: Evaluate key intercepts
    CC->>CC: Evaluate key listeners
    CC->>App: compositor->onKeyPress(keyCode, flags, metadata)
    App-->>CC: (processed)

Event Notification Flow (Westeros client lifecycle to Thunder plugin):

sequenceDiagram
    participant Wst as Westeros
    participant Comp as RdkCompositor
    participant CC as CompositorController
    participant Plugin as Thunder Plugin

    Wst->>Comp: clientStatus(WstClient_connected, pid, ...)
    Comp->>CC: onEvent(compositor, "onApplicationConnected")
    CC->>Plugin: listener->onApplicationConnected(client)
    Plugin->>Plugin: Fire JSON-RPC OnConnected event

Implementation Details

Major HAL APIs Integration

Key Implementation Logic

• State / Lifecycle Management: Application state per compositor (Unknown, Running, Suspended, Stopped) is tracked in RdkCompositor::mApplicationState. Transitions are driven by WstClient_* status codes received in RdkCompositor::onClientStatus(). The global flag gRdkWindowManagerIsRunning controls the main frame loop.
• Core lifecycle: src/rdkwindowmanager.cpp
• Per-compositor state: src/rdkcompositor.cpp
• Event Processing: Essos key callbacks (processKeyEvent in essosinstance.cpp) translate raw Wayland key codes using keyCodeFromWayland(), pack modifier flags, and call CompositorController::onKeyPress / onKeyRelease. CompositorController first checks gIgnoreKeyInputEnabled, then evaluates the key-intercept map (gKeyInterceptInfoMap), and finally dispatches to the focused compositor or evaluates the key-listener table for each matching compositor. Key-repeat generation is handled in CompositorController::update() using gKeyRepeatConfig.
• Error Handling Strategy: Westeros API failures are logged at Information level and propagate as bool return values from createDisplay(). A failure at any Westeros setup step sets a local error flag that causes createDisplay to return false, which the caller (Thunder plugin) maps to a JSON-RPC error response.
• Logging & Diagnostics: Log output uses the RdkWindowManager::Logger class. Log levels: Debug, Information, Warn, Error, Fatal. Runtime log level is set via the RDK_WINDOW_MANAGER_LOG_LEVEL environment variable. When built with RDK_WINDOW_MANAGER_LOGGER, log output is written to /opt/logs/rdkwindowmanager.log.

Configuration

Key Configuration Files

Key Configuration Parameters

Runtime Configuration

The render frame rate and memory thresholds are configured through environment variables read at process startup. Key-intercept and key-listener registrations, focus assignments, visibility, opacity, z-order, and bounds are adjustable at runtime through the CompositorController API, surfaced via the Thunder plugin JSON-RPC interface.

Build-Time Configuration Flags

The following flags are defined in CMakeLists.txt and control compiled-in feature availability: