Overview

Available window managers:

How Window Managers Work

The kernel's display server defines the display_server_wm_t vtable interface. Every window manager — whether compiled-in or loaded from a .wm.elf file — must implement this vtable:

typedef struct {
    const char *name;
    esp_err_t (*init)(void);
    esp_err_t (*render)(lv_obj_t *screen);
    esp_err_t (*on_input)(input_event_t *event);
    esp_err_t (*on_app_launch)(const char *app_id);
    esp_err_t (*on_app_close)(const char *app_id);
    esp_err_t (*on_surface_create)(surface_t *surface);
    esp_err_t (*on_surface_destroy)(surface_t *surface);
    void (*shutdown)(void);
} display_server_wm_t;

The display server calls into these functions at the appropriate lifecycle points. The WM owns the screen layout: it decides where the status bar goes, how the app drawer looks, how surfaces are arranged, and how input events are routed to the focused app.

Switching Window Managers

The active window manager is configured in config/system.json on the SD card or SPIFFS:

{
  "window_manager": "thistle-tk",
  "theme": "dark",
  "wifi_ssid": "...",
  "wifi_pass": "..."
}

Change the "window_manager" value to the name of any installed WM and reboot. The kernel will load the matching .wm.elf from storage, or fall back to the compiled-in WM if no file is found.

Building a Custom Window Manager

1. Implement the display_server_wm_t vtable — at minimum init, render, on_input, and shutdown.
2. Build as a .wm.elf using the driver SDK toolchain, or compile-in via display_server_register_wm().
3. Place the .wm.elf file in the wm/ directory on SPIFFS or SD card.
4. Create a manifest.json alongside the ELF with name, version, and description.
5. Set "window_manager" in system.json to your WM's name and reboot.