zeropykvm

A KVM-over-IP solution running on Raspberry Pi Zero 2 W — rewritten from Zig to Python.

Attribution: This project is a Python port of darkyzhou/mykvm, originally written in Zig. All credit for the architecture and design goes to the original author.

Features

• Zero-copy video pipeline: Uses Linux DMA-BUF to share buffers between capture device (TC358743) and hardware H.264 encoder (bcm2835-codec)
• USB HID gadget: Emulates USB keyboard and mouse via Linux ConfigFS, with Boot Protocol support for BIOS compatibility
• HTTPS + WebSocket: Serves a web frontend over HTTPS with WebSocket for real-time video streaming and HID control
• E-Paper display: Optional status display on Waveshare EPD 2in13 V4
• HDMI passthrough: Optionally mirror the captured HDMI input to the RPi's own HDMI output via the Linux framebuffer

Demo hardware

• Raspberry Pi Zero 2 W (Archive)
• Waveshare HDMI-CSI Adapter (Archive)
• Raspberry Pi Zero Camera Cable (38 cm) (Archive)

Screenshots

Architecture

The Python rewrite mirrors the original Zig project's architecture:

Requirements

• Python >= 3.12
• Linux with V4L2 support (Raspberry Pi OS recommended)
• TC358743 HDMI capture device
• bcm2835-codec hardware encoder
• USB gadget support (dwc2 overlay)
• uv (recommended for dependency management)

Installation

# Install from PyPI using uv (recommended)
uv tool install zeropykvm

# Or with pip
pip install zeropykvm

# With e-Paper display support (on Raspberry Pi)
pip install zeropykvm[epaper]

Development setup

git clone https://github.com/esoadamo/zeropykvm.git
cd zeropykvm
uv sync

# With development tools
uv sync --extra dev

# With e-Paper display support (on Raspberry Pi)
uv sync --extra epaper

Usage

# Generate a self-signed TLS certificate (no openssl required)
zeropykvm gencrt --cert cert.pem --key key.pem

# Run zeropykvm
zeropykvm --cert cert.pem --key key.pem

# With custom settings
zeropykvm --cert cert.pem --key key.pem --port 443 --bitrate 2000000

# Enable HDMI passthrough (mirror input to the RPi HDMI output)
zeropykvm --cert cert.pem --key key.pem --hdmi-passthrough

# Use an alternate framebuffer device
zeropykvm --cert cert.pem --key key.pem --hdmi-passthrough --hdmi-passthrough-device /dev/fb1

Then open https://<pi-ip>:8443/ in a browser (or whatever port you chose) and accept the self-signed certificate.

HDMI passthrough

When --hdmi-passthrough is given, each captured frame is also written to the Linux framebuffer device (default /dev/fb0). This lets a locally-connected HDMI monitor display the source content in real time while the stream is simultaneously encoded and served over the network.

Supported framebuffer colour depths: 16-bit (RGB565) and 32-bit (ARGB8888). Supported capture pixel formats: YUYV, UYVY, and BGR24 (produced by the TC358743).

Performance note: The pixel format conversion is handled by a dynamically compiled C-extension directly between memory-mapped DMA buffers, achieving absolute zero-copy latency (literally 0 frames of software delay). Requirement: You MUST have gcc installed on the host device for this feature to function properly, as the extension is compiled at runtime to perfectly match the active hardware memory layout.

Systemd service

zeropykvm install-service automates the full setup on a Raspberry Pi OS host:

• creates /etc/zeropykvm/ (mode 0755)
• generates a self-signed TLS certificate there if one does not already exist
• writes /etc/systemd/system/zeropykvm.service and runs daemon-reload → enable → start

# Install with defaults (port 8443, data dir /etc/zeropykvm) — runs as root
sudo zeropykvm install-service

# Custom port and data directory
sudo zeropykvm install-service --port 443 --data-dir /opt/zeropykvm

# Install with HDMI passthrough enabled by default
sudo zeropykvm install-service --hdmi-passthrough

# Install without starting the service immediately
sudo zeropykvm install-service --no-start

# Full option list
zeropykvm install-service --help

Testing

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test module
uv run pytest tests/test_usb.py -v

License

This project follows the same license as the original mykvm.