USBDisplayStack

English | 简体中文

USBDisplayStack is a GPL-2.0-only Linux display stack for USB display adapters that use vendor-specific transport protocols. Applications render to normal framebuffer or DRM/KMS devices; protocol, compression, and USB details stay in replaceable userspace backends.

Alpha status: the virtual DRM/fbdev frontend and userspace frame path are working on Linux 4.15. The Actions Micro 185b:2d1d live backend is implemented but remains experimental and is not enabled by default.

Architecture

LVGL or another application
          |
          +----> /dev/fbN (fixed XRGB8888 framebuffer)
          |
          +----> /dev/dri/cardN (DRM/KMS virtual connector)
                         |
                         v
                usbdisplay kernel module
                triple-buffer snapshot ABI
                         |
                  /dev/usbdisplay0
                         |
                         v
                    usb-displayd
                         |
             dynamically loaded backend
                         |
             codec / HID / USB transport

The module never falls back to /dev/fb0. If the USB transport or backend is missing, the secondary display stops while the primary display remains untouched.

See architecture, ABI, and compatibility for the contracts between layers.

Components

• kernel/usbdisplay_drv.c: virtual DRM/KMS device, independent fbdev, and read-only triple-buffer stream.
• userspace/usb-displayd.c: single-consumer frame dispatcher.
• backends/null: diagnostics and throughput testing.
• backends/ppm: writes the latest frame as a PPM image.
• backends/actions-micro: initialization, heartbeat, FFmpeg H.264, and HID video transport for Actions Micro 185b:2d1d.
• tools/fb-test-pattern: writes a color pattern through /dev/fbN.
• tools/drm-probe: checks connectors and modes using DRM ioctls without requiring libdrm.
• tools/actions-micro-replay: validates and explicitly replays captured 185b:2d1d HID reports for protocol research.
• examples/lvgl: LVGL 9 applications for fbdev and DRM/KMS.
• examples/csharp: .NET 8 applications for fbdev and DRM/KMS.

Requirements

The current kernel implementation targets the TinyDRM API present in Linux 4.15. It requires these kernel options:

CONFIG_DRM
CONFIG_DRM_KMS_HELPER
CONFIG_DRM_TINYDRM
CONFIG_FB
CONFIG_FB_DEFERRED_IO

Install the compiler, make, and headers matching the running kernel before building.

The experimental Actions Micro backend requires ffmpeg built with the libx264 encoder. The optional examples require LVGL 9/libdrm or .NET 8 as described in their local READMEs.

Build

make userspace
make module
# Optional, when LVGL 9 and libdrm development files are installed:
make examples-lvgl

The userspace binaries are written to build/; the module is kernel/usbdisplay.ko.

Manual smoke test

The example uses a small mode to keep the test output compact:

sudo modprobe tinydrm
sudo insmod kernel/usbdisplay.ko width=640 height=360

build/drm-probe /dev/dri/card1 640 360
build/usb-displayd \
  --backend build/usbdisplay-ppm.so \
  --backend-option /tmp/usbdisplay.ppm &
daemon_pid=$!

sudo build/fb-test-pattern /dev/fb1
sleep 1
kill "$daemon_pid"
sudo rmmod usbdisplay

Do not assume the secondary nodes are always numbered 1; discover them by the usbdisplay framebuffer name and DRM driver name in production scripts.

Application examples

Run only one producer at a time. Both LVGL examples render the same dashboard:

make -C examples/lvgl
sudo build/examples/lvgl-fbdev-example /dev/fb1
sudo build/examples/lvgl-drm-example /dev/dri/card1

The C# examples render animated XRGB8888 patterns and refuse devices that are not owned by USBDisplayStack:

dotnet run --project examples/csharp/Fbdev -- /dev/fb1
dotnet run --project examples/csharp/Drm -- /dev/dri/card1

Install

scripts/install.sh installs the module built for the running kernel, userspace binaries, backends, udev rules, and systemd files. It deliberately does not load the module or enable the service.

sudo ./scripts/install.sh
sudo systemctl enable --now usb-displayd.service

Set the virtual resolution in /etc/modprobe.d/usbdisplay.conf and select a backend in /etc/default/usb-displayd before enabling the service.

Actions Micro activation

The live backend requires an authorized DPRPL001 replay template containing the adapter's initialization and heartbeat commands. Captured video is ignored by default; bootstrap=full explicitly sends it once on firmware that requires a full captured stream to leave its waiting page. Replay data is never distributed by this project. Configure the reference adapter with:

USBDISPLAY_BACKEND=/usr/lib/usbdisplay/usbdisplay-actions-micro.so
USBDISPLAY_BACKEND_ARGS=--backend-option template=/var/lib/usbdisplay/actions-micro.replay,bootstrap=full

The backend discovers and verifies both 185b:2d1d hidraw interfaces, sends initialization, maintains heartbeats while idle, and converts new fbdev or DRM frames into baseline H.264 and vendor HID reports. With the module and service running, an LVGL write to the USBDisplayStack framebuffer automatically enters that pipeline. See the supported device list and Actions Micro 185b:2d1d for the matching USB identity, options, and current validation limits.

Experimental hardware work

The Actions Micro research notes and replay safety rules are documented in the link above. Both captured Windows output and live generated LVGL output have displayed successfully on the reference unit. The backend remains experimental until repeated reconnect and long-running tests are complete.

License

USBDisplayStack is licensed under GPL-2.0-only. See LICENSE.