openkvm

README

OpenKVM

Make an old laptop or a single board computer into a KVM device to control a computer remotely. KVM stands for Keyboard & Video & Mouse instead of Linux Kernel Virtual Machine.

Unlike the IP-KVM, this project respects VNC protocol.

Just like the MIT license says, no warranty or guarantee.

My dev walkthrough is in WALKTHROUGH.md.

And do NOT use for any illegal purposes.

TODO

• Remove OpenCV, see WALKTHROUGH.md for the reason of removal
• Installation script
  • Register as a system service
  • Start on boot
• VNC authentication
  • DES encryption in Golang can NOT directly apply to VNC Authentication
  • Http Basic Auth in web page and API
• More effective to calculate the difference between frames
  • Balance between the power of SBC and the network efficiency
  • Or achieve more support for noVNC, beyond rfc6143
• OTG as keyboard and mouse, see Linux USB Gadget API
• Using a single command to get the frame for Video, like

  v4l2-ctl --device=/dev/video0 --stream-mmap --stream-count=1 --stream-to=- --set-fmt-video="width=640,height=480,pixelformat=MJPG"
  

Dev Environment

Hardware

NONE of them is sponsored, use them at your own risk!

Essential hardware are:

• A device that can run Golang
  • A personal computer or a laptop
  • SBC
    • RaspberryPi
    • OrangePi
    • BTT-Pi
    • etc...
• HDMI Recorder, see WALKTHROUGH.md for more details.
  • Or a webcam pointing to an always-on monitor.
• Keyboard & Mouse Emulator
  • ESP32-S3
  • Some other device that supports USB HID output.
    • HID over BLE is not recommended, because it may not work in BIOS.
• Relay and/or delayed relay

My Setup

• SBC: OrangePi 3 LTS
  • ¥241 RMB ≈ $34 USD
• HDMI Recorder: UGREEN CM716
  • ¥84 RMB ≈ $12 USD
• Keyboard & Mouse: ESP32-S3
  • I bought a third-party one of WeAct ESP32 S3 (A) DevKitC 1.
  • ¥52 RMB ≈ $7.5 USD
• 5V relay * 2, 5V delayed relay * 1
  • ¥15 RMB ≈ $2 USD

Others

• Test Device:
  • RaspberryPi 2B
  • A Windows computer
  • Ubuntu 24.04 x86_64
• Some SD cards.
• Some USB Type-C2C/C2A cables.
• A HDMI cable.
• Some power supplies.

Price is for reference only, the actual price may vary.

Software

• GO
• Arduino
• noVNC

Diagram

飞书文档, FeiShu Doc

Installation

Debian ARM64

1. Install GO dev kit

   sudo apt-get update
   sudo apt-get install -y wget curl ffmpeg v4l-utils
   GO_ZIP="go1.23.3.linux-arm64.tar.gz"
   wget "https://go.dev/dl/$GO_ZIP"
   sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf "$GO_ZIP"
   export PATH=$PATH:/usr/local/go/bin
   

2. Pull this repo

   sudo apt-get update
   sudo apt-get install -y git
   git clone --depth 1 https://github.com/allape/openkvm.git
   

3. Get noNVC

   git clone --depth 1 https://github.com/novnc/noVNC.git
   
   # [Optional] You can run noVNC separately
   python3 -m http.server --directory noVNC/ 8081
   

4. Flash ESP32-S3
   • PIO: See WALKTHROUGH.md for the reason of removal
   • Arduino
     • Open Perferences -> Additional Board Manager URLs -> Add https://espressif.github.io/arduino-esp32/package_esp32_dev_index.json
       • Click HERE for more details
     • Open km/esp32s3-arduino/main/main.ino with Arduino IDE
     • Select board ESP32S3 Dev Module and corresponding port
     • Click Upload
       • For deployed device, use Arduino CLI to compile and upload firmware
       • Here is an example on Debian with an ESP32-S3 connected to /dev/ttyACM0

         cd ~
         # Command below will install `arduino-cli` at ~/bin
         curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
         echo "export PATH=\$PATH:$HOME/bin" >> ./.bashrc
         source ./.bashrc
         arduino-cli config init
         arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_dev_index.json
         arduino-cli config set network.proxy "http://localhost:1080" # Optional, because arduino-cli may NOT respect http_proxy or https_proxy environment variables
         arduino-cli core update-index
         arduino-cli core install esp32:esp32 # This will takes a while...
         cd openkvm # Change to the directory where the project located
         cd ./km/esp32s3-arduino/main/
         arduino-cli compile -b esp32:esp32:esp32s3 .
         # sudo chmod 777 /dev/ttyACM0
         arduino-cli upload . --fqbn esp32:esp32:esp32s3 -p /dev/ttyACM0
         # screen /dev/ttyACM0 921600 # ctrl + a + k to exit
         

5. Run or build repo

   export PATH=$PATH:/usr/local/go/bin
   
   cd openkvm
   
   go mod download
   
   cp kvm.new.toml kvm.toml
   
   # Find out serial port
   dmesg | grep tty
   
   # Edit this file to apply your settings
   vim kvm.toml # kvm.onragepi.ugreen_25854.toml for example
   
   # Should run with super user privilege
   sudo /usr/local/go/bin/go run .
   
   #/usr/local/go/bin/go build -o openkvm .
   #sudo ./openkvm
   

6. Open browser and go to http://ip:8080/vnc.html, then click Connect
   • Hostname and port may vary depending on your settings
   • Clipboard Usage
     • For now, only host to client is supported
     • Example on Debian
       • USB CDC / USB Serial with device /dev/ttyACM0

         sudo screen /dev/ttyACM0
         # Or
         sudo cat /dev/ttyACM0 # FIXME: In some cases, this command only works after you run `screen`
         

       • USB MSC / USB Pen with device /dev/sda, use lsblk to find out

         mkdir openkvm
         # Commands below need to be run every time you used clipboard
         sudo umount /dev/sda
         sudo mount /dev/sda ./openkvm
         cat ./openkvm/data.txt
         

7. Open http://ip:8080/ui/button.html to control the relay

Credits

• Listed in go.mod
• Roboto Font
• noVNC
• ESP-IDF
• ESP32-Arduino
• Raspberry Pi Imager
• KeyMap