# ESP-KVM

> An open-source IP-KVM: firmware that turns a ~$40 ESP32-P4 board and a TC358743
> HDMI bridge into a KVM-over-IP. It captures a target machine's HDMI, presents
> itself to that machine as a USB keyboard and mouse, and serves both to a browser
> over HTTPS - enough to reach a machine with no working OS (a BIOS screen, a boot
> menu, a kernel that will not come up). Free and open source, Apache-2.0.

Key facts:

- Hardware: an ESP32-P4 plus a TC358743 HDMI-to-MIPI-CSI-2 bridge. Reference build
  is a Waveshare ESP32-P4-ETH with a Geekworm C790; it also builds for the
  Espressif ESP32-P4 Function EV Board.
- Video: follows the target's resolution automatically (a 640x480 BIOS through a
  1080p desktop); MJPEG or hardware H.264.
- Input: a composite USB HID device - keyboard, absolute and relative pointer,
  media keys.
- Text screens can be read back as characters: a BIOS, a boot loader or a console
  can be selected with the mouse and copied, or copied whole. Not OCR - the
  characters are read from the character grid the firmware draws them on, so a
  reading is either exact or refused. Graphical UEFI setups have no grid and are
  not read.
- The device can watch a text screen while nobody is connected: give it phrases
  (`no boot device`, `kernel panic`) and it raises an alert, in its log and in
  Home Assistant, when one appears. Off by default.
- Pasting text types it out as keystrokes, so it follows the target's keyboard
  layout: US English, Russian, Czech, Ukrainian and Lithuanian. A character the
  layout cannot type is reported rather than guessed at.
- Virtual media: boot the target from a disk image on a microSD card or from a
  small image in the device's own flash.
- Networking: Ethernet, or WiFi on boards with an ESP32-C6 (the Function EV Board) -
  station or the device's own access point, one link at a time. A rescue hotspot and
  a captive portal keep a device reachable, and set up from a phone, when its network
  is out of range. mDNS (espkvm.local), DHCP or static addressing, and IPv6
  alongside IPv4 (autoconfigured from the router, nothing to fill in).
- An optional status screen on the device (I2C OLED, or a round SPI LCD) shows the
  link, address, capture state and health with no browser. The round one also shows
  a code a phone scans to join the rescue hotspot, and fills a ring while the
  recovery button is held.
- Security: HTTPS with a certificate the device issues itself, plus a login. It is
  not meant for the public internet - keep it on a trusted network, or reach it over
  the built-in WireGuard client (split-tunnel, generates its own key).
- Updates install over the network into a spare slot, with rollback. The console
  shows the version and state of both slots and can boot the other one on demand.
  The device never reaches the internet on its own.
- It builds on jrowny/p4kvm, which brought up the TC358743 on the ESP32-P4 first.

## Links

- [Website](https://espkvm.io/)
- [Flash from the browser](https://espkvm.io/flash/)
- [Serial monitor in the browser](https://espkvm.io/serial/)
- [Tools: read a firmware image, decode a panic, inspect an EDID](https://espkvm.io/tools/)
- [Interactive demo, no hardware needed](https://demo.espkvm.io/)
- [Blog: what each release changed, and how](https://espkvm.io/blog/)
- [Source code on GitHub](https://github.com/espkvm/espkvm)
- [README](https://github.com/espkvm/espkvm/blob/main/README.md)
- [Releases](https://github.com/espkvm/espkvm/releases)
- [Discussions](https://github.com/espkvm/espkvm/discussions)
- [Telegram channel](https://t.me/espkvm)
- [X / Twitter](https://x.com/espkvm)
- [YouTube channel](https://youtube.com/@espkvm)