go-zerokvm

日本語の説明

This project is a Go port of the original ZeroKVM by doominator42. Go-zerokvm is a low-cost, easy-to-build KVM-over-IP device. It presents itself to the target host as a DisplayLink monitor and a standard USB keyboard/mouse. We would like to express our gratitude to doominator42 for their incredible work on the original project.

Features

• DisplayLink Protocol Implementation: Captures screen signals from the host and displays them in a web browser.
• USB HID Emulation: Emulates keyboard, absolute mouse, and relative mouse.
• Web Console: Intuitive remote operation directly from your browser.
• Multi-Architecture Support: Works on ARM-based Linux devices such as Raspberry Pi Zero/2/3/4/5.
• No CGO Required: Pure Go implementation makes cross-compilation extremely easy.

Screen Shots

Requirements

• Hardware: Linux device with USB OTG (USB 2.0 Device/Gadget mode) support (e.g., Raspberry Pi Zero, 4, 5).
• OS: Linux with ConfigFS and FunctionFS enabled.

Setup (ZeroKVM Device Side)

For Raspberry Pi users, the following configuration is required:

1. Enable Kernel Overlays

Add the following line to /boot/config.txt (or /boot/firmware/config.txt):

dtoverlay=dwc2

2. Load Kernel Modules

Add these lines to /etc/modules and reboot, or load them manually via modprobe:

dwc2
libcomposite

3. Permissions

Since this program configures USB gadgets (ConfigFS) and manipulates FunctionFS endpoints, it must be run with root privileges (sudo).

Host PC (Target) Requirements

The target PC connected to ZeroKVM requires DisplayLink drivers.

• Linux: Mainline udl driver is included in kernels 3.4+. Check with lsmod | grep udl if not recognized.
• Windows: Drivers are typically installed automatically via Windows Update.
• macOS / Android: "DisplayLink Manager" (or DisplayLink Presenter) must be installed from the official website.

Configuration

You can specify the following arguments at runtime:

Argument	Description	Default
-udc	Name of the USB controller (Required)	(none)
-name	Gadget name	zerokvm
-listen	Listen address for the Web UI	:8080

Identifying the UDC Name

ls /sys/class/udc
# Example: fe980000.usb

Operation

1. Build: Using mise:

   mise run build:all

   Manual build (e.g., for ARM64):

   GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o go-zerokvm

2. Run:

   sudo ./go-zerokvm -udc <your-udc-name>

3. Usage: Connect the ZeroKVM device's USB OTG port to the host PC's USB port, and access http://<device-ip>:8080 in your web browser.

Testing

Unit Tests

To run the internal logic tests (DisplayLink decoding, HID protocol, etc.):

go test ./...

E2E Web UI Testing (Maestro)

We use Maestro for end-to-end testing of the web interface.

1. Start the Mock Server: You can run the application in "mock" mode on any OS (including macOS/Windows) to test the UI without real hardware:

   go run main.go -mock -listen :8081

2. Run Maestro:

   # Smoke test
   maestro test e2e/viewer_smoke_test.yaml
   # Interaction test
   maestro test e2e/toolbar_interactions.yaml

License

This project is licensed under the Apache License 2.0.