feat: add PiKVM module #247

llogen · 2025-12-08T10:09:29Z

The PiKVM module provides comprehensive control of a DUT via a PiKVM device. It offers power management through ATX control, keyboard input simulation, and virtual media mounting capabilities.

Power management commands: on, off, force-off, reset, force-reset,
and status. Keyboard control commands: type, key, combo, and paste.
Virtual media commands: mount, mount-url, unmount, and media-status.

The module connects to a PiKVM device using HTTP/HTTPS with configurable host, user, password, and timeout. It supports both short and long ATX button presses for power and reset control, allows sending keyboard input and key combinations, and enables mounting ISO images from local files or URLs.

resolves #246

RiSKeD

Nice changes, looks pretty clean overall. Just some thoughts:

Maybe separate the power,virtual-media,keyboard functionalities into separate files for better readability
'combo' -> key-combo

Tell me what you think 😄

llogen · 2025-12-17T10:28:00Z

Nice changes, looks pretty clean overall. Just some thoughts:

Maybe separate the power,virtual-media,keyboard functionalities into separate files for better readability

'combo' -> key-combo

Tell me what you think 😄

I think thats a good idea :)

The PiKVM module provides comprehensive control of a DUT via a PiKVM device. It offers power management through ATX control, keyboard input simulation, and virtual media mounting capabilities. Power management commands: on, off, force-off, reset, force-reset, and status. Keyboard control commands: type, key, combo, and paste. Virtual media commands: mount, mount-url, unmount, and media-status. The module connects to a PiKVM device using HTTP/HTTPS with configurable host, user, password, and timeout. It supports both short and long ATX button presses for power and reset control, allows sending keyboard input and key combinations, and enables mounting ISO images from local files or URLs. Signed-off-by: llogen <[email protected]>

jenstopp

Wow, full KVM feature set implemented 🚀 :)

jenstopp · 2026-01-06T15:28:00Z

pkg/module/pikvm/README.md

@@ -0,0 +1,167 @@
+# PiKVM
+
+This module provides comprehensive control of a DUT via a PiKVM device. It offers power management through ATX control, keyboard input simulation, and virtual media mounting capabilities.


Can you add a link to PiKVM for further info? In case someone does not know this device. Also ist is desinged to support a special PiKVM device?

jenstopp · 2026-01-06T15:29:52Z

pkg/module/pikvm/README.md

+  key <keyname>        Send a single key (e.g., Enter, Escape, F12)
+  key-combo <keys>     Send key combination (e.g., Ctrl+Alt+Delete)


Write or refer to a full list of available 'key strings'

jenstopp · 2026-01-06T17:01:55Z

pkg/module/pikvm/README.md

+This module interacts with the following PiKVM API endpoints:
+
+- `/api/atx` - Get ATX power status
+- `/api/atx/power` - Intelligent power management (on/off/off_hard/reset_hard)
+- `/api/atx/click` - ATX button control (reset)
+- `/api/hid/print` - Type text input
+- `/api/hid/events/send_key` - Send keyboard keys and combinations
+- `/api/msd` - Mass Storage Device (virtual media) status
+- `/api/msd/write` - Upload images to PiKVM storage
+- `/api/msd/write_remote` - Download images from URL to PiKVM
+- `/api/msd/set_params` - Configure virtual media parameters
+- `/api/msd/set_connected` - Mount/unmount media
+- `/api/msd/remove` - Delete images from storage
+- `/api/streamer/snapshot` - Capture screenshot


What would a user need this info for?

jenstopp · 2026-01-06T17:02:55Z

pkg/module/pikvm/README.md

+| user     | string | admin   | Username for authentication                                          |
+| password | string | -       | Password for authentication                                          |
+| timeout  | string | 10s     | Timeout for HTTP requests (e.g., "10s", "30s")                      |
+| command  | string | -       | **Required**: Command type ("power", "keyboard", "media", "screenshot") |


Is only one supported at a time?

yes you can only define one command per command. @RiSKeD and I talked about making the command parameter optional to also allow full control just via arguments.

jenstopp · 2026-01-06T17:04:01Z

pkg/module/pikvm/README.md

+### Basic Power Control
+
+```yaml
+version: 0
+devices:
+  my-server:
+    desc: "Server controlled via PiKVM"
+    cmds:
+      power:
+        desc: "Power management: on|off|force-off|reset|force-reset|status"
+        modules:
+          - module: pikvm
+            main: true
+            options:
+              host: https://pikvm.local
+              user: admin
+              password: admin
+              command: power
+```
+
+### Boot Menu Access
+
+```yaml
+keyboard:
+  desc: "Keyboard control: type <text>|key <keyname>|key-combo <combo>"
+  modules:
+    - module: pikvm
+      main: true
+      options:
+        host: https://pikvm.local
+        user: admin
+        password: admin
+        command: keyboard
+
+# Usage: dutctl my-server keyboard key F12
+```
+
+### ISO Mounting
+
+```yaml
+media:
+  desc: "Virtual media control: mount <path>|mount-url <url>|unmount|media-status"
+  modules:
+    - module: pikvm
+      main: true
+      options:
+        host: https://pikvm.local
+        user: admin
+        password: admin
+        command: media
+
+# Usage: dutctl my-server media mount-url https://releases.ubuntu.com/22.04/ubuntu-22.04-live-server-amd64.iso
+```
+
+### Screenshot Capture
+
+```yaml
+screenshot:
+  desc: "Capture a screenshot from PiKVM"
+  modules:
+    - module: pikvm
+      main: true
+      options:
+        host: https://pikvm.local
+        user: admin
+        password: admin
+        command: screenshot
+
+# Usage: dutctl my-server screenshot
+# The screenshot will be saved to the current directory
+```


Put all examples in YAML files and link them here for better overview

jenstopp · 2026-01-06T17:32:20Z

pkg/module/pikvm/pikvm.go

+	if p.Command == "" {
+		return fmt.Errorf("pikvm: command option is required (must be: %s, %s, %s, or %s)",
+			cmdTypePower, cmdTypeKeyboard, cmdTypeMedia, cmdTypeScreenshot)
+	}
+
+	if !isValidCommand(p.Command) {
+		return fmt.Errorf("pikvm: invalid command %q (must be: %s, %s, %s, or %s)",
+			p.Command, cmdTypePower, cmdTypeKeyboard, cmdTypeMedia, cmdTypeScreenshot)
+	}


Combine in one function

jenstopp · 2026-01-06T17:35:17Z

pkg/module/pikvm/pikvm.go

+	host := strings.TrimSpace(p.Host)
+	if !strings.HasPrefix(host, "http://") && !strings.HasPrefix(host, "https://") {
+		host = "https://" + host
+	}


Combine with the host validation part from above

jenstopp · 2026-01-06T17:38:38Z

pkg/module/pikvm/pikvm.go

+	case cmdTypeScreenshot:
+		return p.handleScreenshot(ctx, s)
+	default:
+		return fmt.Errorf("pikvm: unknown command type %q", p.Command)


try to show that it is not the users fault:

Suggested change

return fmt.Errorf("pikvm: unknown command type %q", p.Command)

return fmt.Errorf("pikvm: misconfigured: unknown command type %q", p.Command)

Suggested change

return fmt.Errorf("pikvm: unknown command type %q", p.Command)

return fmt.Errorf("pikvm: invalid configuration: unknown command type %q", p.Command)

jenstopp · 2026-01-06T17:40:41Z

pkg/module/pikvm/pikvm.go

+func (p *PiKVM) doRequest(ctx context.Context, method, urlPath string, body io.Reader, contentType string) (*http.Response, error) {
+	return p.doRequestWithOptions(ctx, method, urlPath, body, contentType, requestOptions{})
+}


Is this for testing purposes?

this is for the purpose of not having 3 different methods and combine them within one with the requestOptions input

jenstopp · 2026-01-06T17:42:01Z

pkg/module/pikvm/pikvm.go

+func (p *PiKVM) buildRequestURL(urlPath string) (string, error) {
+	targetURL := *p.baseURL
+
+	parsedPath, err := url.Parse(urlPath)
+	if err != nil {
+		return "", fmt.Errorf("invalid URL path: %v", err)
+	}
+
+	targetURL.Path = path.Join(targetURL.Path, parsedPath.Path)
+	targetURL.RawQuery = parsedPath.RawQuery
+
+	return targetURL.String(), nil
+}


Isn't this done during init?

RiSKeD · 2026-01-07T10:44:22Z

pkg/module/pikvm/keyboard.go

+)
+
+const (
+	keyDelay           = 500 * time.Millisecond


maybe default this and make the delay an option instead?

RiSKeD · 2026-01-07T10:46:49Z

pkg/module/pikvm/keyboard.go

+	}
+
+	// Check for invalid characters
+	for _, c := range []string{invalidCharNul, invalidCharNewline, invalidCharReturn} {


i would maybe suggest to use a precompiled regex instead

or an array of values

RiSKeD · 2026-01-07T12:07:13Z

pkg/module/pikvm/pikvm.go

+	contentType string,
+) (*http.Response, error) {
+	return p.doRequestWithOptions(ctx, method, urlPath, body, contentType, requestOptions{noTimeout: true})
+}


instead of this wrappers, just call the function with options directly

llogen force-pushed the feat/addPiKVModule branch 2 times, most recently from 9dbc7d7 to ad77246 Compare December 8, 2025 10:22

RiSKeD reviewed Dec 8, 2025

View reviewed changes

llogen force-pushed the feat/addPiKVModule branch from ad77246 to ae564e7 Compare December 17, 2025 10:27

llogen force-pushed the feat/addPiKVModule branch from ae564e7 to 4e04fe1 Compare December 17, 2025 12:26

llogen force-pushed the feat/addPiKVModule branch 3 times, most recently from 441f7ee to 2183a74 Compare January 6, 2026 14:53

llogen force-pushed the feat/addPiKVModule branch from 2183a74 to 9454670 Compare January 6, 2026 14:55

jenstopp reviewed Jan 6, 2026

View reviewed changes

RiSKeD reviewed Jan 7, 2026

View reviewed changes

		@@ -0,0 +1,167 @@
		# PiKVM

		This module provides comprehensive control of a DUT via a PiKVM device. It offers power management through ATX control, keyboard input simulation, and virtual media mounting capabilities.

		key <keyname> Send a single key (e.g., Enter, Escape, F12)
		key-combo <keys> Send key combination (e.g., Ctrl+Alt+Delete)

	return fmt.Errorf("pikvm: unknown command type %q", p.Command)
	return fmt.Errorf("pikvm: misconfigured: unknown command type %q", p.Command)

	return fmt.Errorf("pikvm: unknown command type %q", p.Command)
	return fmt.Errorf("pikvm: invalid configuration: unknown command type %q", p.Command)

feat: add PiKVM module #247

Are you sure you want to change the base?

feat: add PiKVM module #247

Conversation

llogen commented Dec 8, 2025

Uh oh!

RiSKeD left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

llogen commented Dec 17, 2025

Uh oh!

jenstopp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

RiSKeD left a comment •

edited

Loading