jetkvm-ezcoo

Integration of JetKVM with Ezcoo HDMI KVM switches to enable multi-device management from a single JetKVM unit.

This project is similar to what Techno Tim did with PiKVM, but adapted for the JetKVM platform and Ezcoo KVM hardware.

Features

Multi-Device Control

• Switch between 4+ computers via a single web interface
• Seamless switching with keyboard shortcuts or mouse gestures
• Real-time device status monitoring

Serial Control

• Ezcoo KVM switch control via USB serial commands
• Support for EZ-SW41HA-KVMU3P and compatible models
• Automatic port detection and configuration

Web Interface

• Modern React-based UI for device management
• Responsive design for desktop and mobile access
• Keyboard and mouse passthrough with low latency

MQTT Integration

• Home Assistant compatible via MQTT
• Publish device status and receive control commands
• Automate switching based on time, events, or sensors

Power Management

• Wake-on-LAN (WoL) support for remote power control
• Power on/off/reboot individual devices
• Scheduled power operations

Virtual Media

• Mount ISO images to target devices
• Support for CD/DVD and USB drive emulation
• Persistent mount across reboots (see Bug Fixes below)

Bug Fixes

This project addresses three known JetKVM issues:

• Windows color space fix - Resolves green/pink screen issue
• HP USB enumeration fix - Fixes USB not working until boot completes
• ISO persistence - Maintains mount state across device reboots

Architecture

┌─────────────┐     ┌─────────────────┐     ┌─────────────┐     ┌─────────────┐
│  Computer 1  │────▶│                 │     │             │     │             │
├─────────────┤     │   Ezcoo KVM     │     │   JetKVM    │     │   Network   │
│  Computer 2  │────▶│   Switch        │────▶│   Device    │────▶│   Switch    │
├─────────────┤     │  (EZ-SW41HA)    │     │  (RK3566)   │     │             │
│  Computer 3  │────▶│                 │     │             │     │             │
├─────────────┤     │  Serial Control │     │  Web Server │     │             │
│  Computer 4  │────▶│  via USB Serial │     │  MQTT Client│     │             │
└─────────────┘     └─────────────────┘     └─────────────┘     └──────┬──────┘
                                                                      │
                                                                      ▼
                                                               ┌─────────────┐
                                                               │   Web       │
                                                               │   Browser   │
                                                               └─────────────┘

Component Overview

Component	Description
JetKVM Hardware	RK3566-based KVM device with HDMI capture and USB HID
Ezcoo Switch	EZ-SW41HA-KVMU3P HDMI KVM switch (4-port recommended)
Serial Connection	USB-A to Micro-USB cable for switch control
Web Interface	React application running on JetKVM
MQTT Broker	Optional, for Home Assistant integration

Hardware Requirements

Required

• JetKVM device (RK3566-based) - jetkvm/kvm
• Ezcoo HDMI KVM switch - Model EZ-SW41HA-KVMU3P recommended
• USB-A to Micro-USB cable - For serial control connection
• HDMI cables - One per computer (4+ cables for multi-device)
• USB cables - One per computer (USB 3.0 recommended for full speed)

Optional

• Network switch - For remote access from multiple devices
• USB hub - If connecting more than 4 devices
• PS/2 adapter - For HP BIOS access workarounds

Installation

Prerequisites

• Node.js 18+ and npm
• Python 3.8+
• Docker (optional, for containerized deployment)
• Access to the Ezcoo KVM switch via USB serial

Clone Repository

git clone https://git.crashmedia.ca/crashmedia/jetkvm-ezcoo.git
cd jetkvm-ezcoo

Install Dependencies

# Frontend dependencies
cd frontend
npm install

# Backend dependencies
cd ../backend
pip install -r requirements.txt

Configure Ezcoo Connection

1. Connect the Ezcoo switch to the JetKVM device using the USB-A to Micro-USB cable
2. Identify the serial port:

   ls /dev/ttyUSB* /dev/ttyACM*
   

3. Update configuration:

   cp config.example.json config.json
   # Edit config.json with your serial port and device mappings
   

Build and Deploy

# Build frontend
cd frontend
npm run build

# Start the application
cd ../backend
python app.py

First-Time Setup

1. Access the web interface at http://<jetkvm-ip>:8080
2. Navigate to Settings > KVM Configuration
3. Configure serial port and device mappings
4. Test switching between devices
5. Configure MQTT (optional) for Home Assistant integration

Configuration

Serial Port Configuration

Edit config.json:

{
  "serial": {
    "port": "/dev/ttyUSB0",
    "baud_rate": 9600,
    "timeout": 1000
  }
}

Device Mapping

Map physical KVM ports to logical device names:

{
  "devices": {
    "1": {
      "name": "Workstation",
      "ip": "192.168.1.100",
      "mac": "AA:BB:CC:DD:EE:FF",
      "wake_on_lan": true
    },
    "2": {
      "name": "Media Server",
      "ip": "192.168.1.101",
      "mac": "11:22:33:44:55:66",
      "wake_on_lan": true
    }
  }
}

MQTT Settings

{
  "mqtt": {
    "enabled": true,
    "broker": "192.168.1.50",
    "port": 1883,
    "topic_prefix": "jetkvm",
    "username": "",
    "password": ""
  }
}

Wake-on-LAN Setup

1. Enable WoL on target devices in BIOS/UEFI
2. Configure MAC addresses in device mapping
3. Use the web interface or MQTT to send WoL packets

EDID Configuration

Custom EDID profiles can be configured for specific display requirements:

{
  "edid": {
    "enabled": true,
    "profile": "custom",
    "resolution": "1920x1080",
    "refresh_rate": 60
  }
}

Usage

Switching Between Devices

1. Web Interface: Click on device cards or use the dropdown menu
2. Keyboard Shortcuts: Ctrl+Alt+1 through Ctrl+Alt+4 for quick switching
3. MQTT: Publish to jetkvm/switch topic with device number

Mounting ISO Images

1. Navigate to the Virtual Media section
2. Click "Mount ISO" and select your image file
3. Select the target device
4. The ISO will persist across reboots (see Bug Fixes below)

Power Management

• Power On: Click the power button or send MQTT command
• Power Off: Long press or use scheduled shutdown
• Reboot: Use the reboot button for graceful restart

Keyboard/Mouse Control

• Keyboard and mouse are automatically captured when the web interface is focused
• Use Ctrl+Alt+Esc to release mouse capture
• Clipboard sharing is supported for text (copy/paste between devices)

Troubleshooting

Issue 1: Green/Pink Screen in Windows

Symptoms: After switching to a Windows device, the screen displays green or pink colors.

Cause: Color space conversion (CSC) mismatch between HDMI capture and encoding pipeline. The Ezcoo switch may output a different color space than what JetKVM expects.

Solution:

# Force YUYV color space in JetKVM configuration
# Edit /etc/jetkvm/config.yaml:
video:
  force_yuyv: true
  disable_hw_csc: true

Workaround: Open any Windows program (like Notepad) to trigger a display reset, which forces the correct color space negotiation.

Issue 2: HP USB Not Working Until Boot

Symptoms: Keyboard and mouse don't work during HP BIOS/UEFI until the operating system boots.

Cause: HP BIOS delays USB enumeration until POST (Power-On Self-Test) is complete, preventing HID devices from being recognized during early boot.

Solution:

# Enable USB re-enumeration script
# This script periodically re-enumerates USB devices
sudo systemctl enable jetkvm-usb-enum
sudo systemctl start jetkvm-usb-enum

Workaround: Use a PS/2 adapter for initial BIOS access, then switch to USB after boot.

Issue 3: ISO Mount Loses on Reboot

Symptoms: Virtual media (ISO) mounts are lost when the target device reboots.

Cause: Virtual media state is not persisted across device reboots. When the HDMI signal is lost during reboot, the mount is cleared.

Solution: The persistent mount daemon automatically remounts ISOs when the HDMI signal is restored:

# Enable persistent mount daemon
sudo systemctl enable jetkvm-persistent-mount
sudo systemctl start jetkvm-persistent-mount

Implementation Details:

• Mount state is stored in /var/lib/jetkvm/mounts.json
• Daemon monitors HDMI signal status
• Auto-remount triggers when signal is restored after reboot
• State survives JetKVM device reboots as well

Development Roadmap

Phase 1: Basic Ezcoo Integration

• Serial communication with Ezcoo switch
• Basic switching functionality
• Command protocol implementation

Phase 2: Multi-Device UI

• React-based web interface
• Device cards and status display
• Keyboard/mouse passthrough

Phase 3: Bug Fixes

• Windows color space fix (green/pink screen)
• HP USB enumeration fix
• ISO persistence across reboots

Phase 4: Advanced Features

• Macro support for automated sequences
• Scheduling for time-based switching
• Integration with home automation systems
• Multi-user access control

Contributing

How to Contribute

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Setup

# Clone your fork
git clone https://git.crashmedia.ca/<your-username>/jetkvm-ezcoo.git
cd jetkvm-ezcoo

# Install development dependencies
cd frontend && npm install
cd ../backend && pip install -r requirements.txt

# Start development server
npm run dev  # Frontend
python app.py  # Backend

Code Style

• Frontend: Follow ESLint configuration, use Prettier for formatting
• Backend: Follow PEP 8 for Python code
• Commits: Use conventional commits format (feat:, fix:, docs:)

Testing

# Run frontend tests
cd frontend && npm test

# Run backend tests
cd backend && python -m pytest

# Run integration tests
./scripts/integration-test.sh

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• JetKVM Project - For the amazing KVM hardware platform
• PiKVM Project - Inspiration for multi-device management
• Techno Tim - PiKVM at scale documentation
• Ezcoo - For the HDMI KVM switch hardware (EZ-SW41HA-KVMU3P)

---

Note: This project is not officially affiliated with JetKVM or Ezcoo. It is a community-driven integration project.