Skip to content

feat: USB CDC ACM virtual serial console#819

Draft
deasmi wants to merge 1 commit into
sipeed:mainfrom
deasmi:main
Draft

feat: USB CDC ACM virtual serial console#819
deasmi wants to merge 1 commit into
sipeed:mainfrom
deasmi:main

Conversation

@deasmi

@deasmi deasmi commented Jun 16, 2026

Copy link
Copy Markdown

This PR adds support for exposing a virtual serial port to the host, that can be used as a serial console tty. This was done as a POC as it seemed like it should be possible and it was interesting.

It is 100% written by Claude. please bear that in mind.

It includes some things that Claude used to run the development process, like the deploy.sh script.

Therefore I am not suggesting this is merged directly, I am providing it as a POC to prove it is possible as this would be a nice feature to add.


Exposes a CDC ACM virtual serial port to the attached host via a /boot/usb.acm boot flag, providing an out-of-band text console for OPNsense/FreeBSD/Linux servers over the existing NanoKVM USB cable. Host enumerates /dev/ttyACM0 (Linux) or /dev/cuaU0 (FreeBSD).

The SG2002/dwc2 USB controller's FIFO budget only fits keyboard + mouse + ACM simultaneously. The toggle therefore implies HID-Only mode and additionally suppresses the touchpad. The UI warns of the trade-off and reboots to apply.

Components:

  • kvmapp/system/init.d/S03usbhid: when /boot/usb.acm exists, skip hid.GS2 (touchpad) and link functions/acm.GS0 into configs/c.1/. Standard-mode S03usbdev is untouched.
  • server/service/vm/virtual-device.go: USB Serial toggle dispatched via existing POST /api/vm/device/virtual (device:"serial"). Enable forces the hid-only script over /etc/init.d/S03usbdev, writes /boot/usb.acm, removes firmware's acm::respawn getty from /etc/inittab (so web terminal has exclusive ttyGS0 access), and reboots. Disable removes the flag, restores the getty line, and reboots.
  • server/service/hid/status.go: exports CopyModeFile so vm package can force the script swap, bypassing the bcdDevice-based short-circuit in SwitchMode.
  • server/proto/vm.go: GetVirtualDeviceRsp gains Serial bool.
  • web Settings -> Device: third Switch + warning modal.
  • web Terminal -> Serial Port: /dev/ttyGS0 radio option when enabled.
  • web Terminal -> terminal/index.tsx: picocom with --imap lfcrlf (fixes diagonal output) and --noreset (avoids ENOTTY on exit).
  • Makefile + docker/Dockerfile: fix make app on Apple Silicon / arm64 Linux.
  • deploy.sh: dev workflow helper (build + deploy over SSH).
  • i18n: real English strings; placeholder stubs in 23 other locales.

Tested on NanoKVM Lite (SG2002) against OPNsense/FreeBSD.

Exposes a CDC ACM virtual serial port to the attached host via a
/boot/usb.acm boot flag, providing an out-of-band text console
for OPNsense/FreeBSD/Linux servers over the existing NanoKVM USB
cable. Host enumerates /dev/ttyACM0 (Linux) or /dev/cuaU0 (FreeBSD).

The SG2002/dwc2 USB controller's FIFO budget only fits keyboard +
mouse + ACM simultaneously. The toggle therefore implies HID-Only
mode and additionally suppresses the touchpad. The UI warns of the
trade-off and reboots to apply.

Components:
- kvmapp/system/init.d/S03usbhid: when /boot/usb.acm exists, skip
  hid.GS2 (touchpad) and link functions/acm.GS0 into configs/c.1/.
  Standard-mode S03usbdev is untouched.
- server/service/vm/virtual-device.go: USB Serial toggle dispatched
  via existing POST /api/vm/device/virtual (device:"serial"). Enable
  forces the hid-only script over /etc/init.d/S03usbdev, writes
  /boot/usb.acm, removes firmware's acm::respawn getty from
  /etc/inittab (so web terminal has exclusive ttyGS0 access), and
  reboots. Disable removes the flag, restores the getty line, and
  reboots.
- server/service/hid/status.go: exports CopyModeFile so vm package
  can force the script swap, bypassing the bcdDevice-based
  short-circuit in SwitchMode.
- server/proto/vm.go: GetVirtualDeviceRsp gains Serial bool.
- web Settings -> Device: third Switch + warning modal.
- web Terminal -> Serial Port: /dev/ttyGS0 radio option when enabled.
- web Terminal -> terminal/index.tsx: picocom with --imap lfcrlf
  (fixes diagonal output) and --noreset (avoids ENOTTY on exit).
- Makefile + docker/Dockerfile: fix make app on Apple Silicon /
  arm64 Linux.
- deploy.sh: dev workflow helper (build + deploy over SSH).
- i18n: real English strings; placeholder stubs in 23 other locales.

Tested on NanoKVM Lite (SG2002) against OPNsense/FreeBSD.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant