Skip to content

Commit 9454670

Browse files
llogenllogen
committed
feat: add PiKVM module
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 <christoph.lange@blindspot.software>
1 parent cabf73d commit 9454670

File tree

10 files changed

+1964
-0
lines changed

10 files changed

+1964
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ DUT agent on it. Below you can find the currently supported modules with example
8989
| [GPIO Button](./pkg/module/gpio/README.md) | :white_check_mark: |
9090
| [GPIO Switch](./pkg/module/gpio/README.md) | :white_check_mark: |
9191
| [IPMI Power Control](./pkg/module/gpio/README.md) | :white_check_mark: |
92+
| [PiKVM](./pkg/module/pikvm/README.md) | :white_check_mark: |
9293
| [Power Distribution Unit (Intellinet)](./pkg/module/pdu/README.md) | :white_check_mark: |
9394
| Power Distribution Unit (Delock) | :hourglass_flowing_sand: |
9495
| [SPI Flasher](./pkg/module/flash/README.md) | :white_check_mark: |

‎cmds/dutagent/modules.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import (
1919
_ "github.com/BlindspotSoftware/dutctl/pkg/module/gpio"
2020
_ "github.com/BlindspotSoftware/dutctl/pkg/module/ipmi"
2121
_ "github.com/BlindspotSoftware/dutctl/pkg/module/pdu"
22+
_ "github.com/BlindspotSoftware/dutctl/pkg/module/pikvm"
2223
_ "github.com/BlindspotSoftware/dutctl/pkg/module/serial"
2324
_ "github.com/BlindspotSoftware/dutctl/pkg/module/shell"
2425
_ "github.com/BlindspotSoftware/dutctl/pkg/module/ssh"

‎pkg/module/pikvm/README.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# PiKVM
2+
3+
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.
4+
5+
## Features
6+
7+
### Power Management
8+
Control the DUT's power state via ATX power and reset buttons:
9+
10+
```
11+
COMMANDS:
12+
on Power on (does nothing if already on)
13+
off Graceful shutdown (soft power-off)
14+
force-off Force power off (hard shutdown, 5+ second press)
15+
reset Reset via ATX reset button
16+
force-reset Force reset (hardware hot reset)
17+
status Query current power state
18+
```
19+
20+
### Keyboard Control
21+
Send keyboard input to the DUT:
22+
23+
```
24+
COMMANDS:
25+
type <text> Type a text string
26+
key <keyname> Send a single key (e.g., Enter, Escape, F12)
27+
key-combo <keys> Send key combination (e.g., Ctrl+Alt+Delete)
28+
```
29+
30+
### Virtual Media
31+
Mount ISO images or disk images as virtual USB devices:
32+
33+
```
34+
COMMANDS:
35+
mount <path> Mount an image file from the agent's filesystem
36+
mount-url <url> Mount an image from a URL
37+
unmount Unmount current virtual media
38+
media-status Show mounted media information
39+
```
40+
41+
## Configuration Options
42+
43+
| Option | Type | Default | Description |
44+
| -------- | ------ | ------- | -------------------------------------------------------------------- |
45+
| host | string | - | Address of the PiKVM device (e.g., "192.168.1.100") |
46+
| user | string | admin | Username for authentication |
47+
| password | string | - | Password for authentication |
48+
| timeout | string | 10s | Timeout for HTTP requests (e.g., "10s", "30s") |
49+
| command | string | - | **Required**: Command type ("power", "keyboard", "media", "screenshot") |
50+
51+
⚠️ **Security Warning**: Passwords are stored in plaintext in the configuration file. This should only be used in trusted environments.
52+
53+
## API Endpoints Used
54+
55+
This module interacts with the following PiKVM API endpoints:
56+
57+
- `/api/atx` - Get ATX power status
58+
- `/api/atx/power` - Intelligent power management (on/off/off_hard/reset_hard)
59+
- `/api/atx/click` - ATX button control (reset)
60+
- `/api/hid/print` - Type text input
61+
- `/api/hid/events/send_key` - Send keyboard keys and combinations
62+
- `/api/msd` - Mass Storage Device (virtual media) status
63+
- `/api/msd/write` - Upload images to PiKVM storage
64+
- `/api/msd/write_remote` - Download images from URL to PiKVM
65+
- `/api/msd/set_params` - Configure virtual media parameters
66+
- `/api/msd/set_connected` - Mount/unmount media
67+
- `/api/msd/remove` - Delete images from storage
68+
- `/api/streamer/snapshot` - Capture screenshot
69+
70+
## Usage Examples
71+
72+
See [pikvm-example-cfg.yml](./pikvm-example-cfg.yml) for comprehensive configuration examples.
73+
74+
### Basic Power Control
75+
76+
```yaml
77+
version: 0
78+
devices:
79+
my-server:
80+
desc: "Server controlled via PiKVM"
81+
cmds:
82+
power:
83+
desc: "Power management: on|off|force-off|reset|force-reset|status"
84+
modules:
85+
- module: pikvm
86+
main: true
87+
options:
88+
host: https://pikvm.local
89+
user: admin
90+
password: admin
91+
command: power
92+
```
93+
94+
### Boot Menu Access
95+
96+
```yaml
97+
keyboard:
98+
desc: "Keyboard control: type <text>|key <keyname>|key-combo <combo>"
99+
modules:
100+
- module: pikvm
101+
main: true
102+
options:
103+
host: https://pikvm.local
104+
user: admin
105+
password: admin
106+
command: keyboard
107+
108+
# Usage: dutctl my-server keyboard key F12
109+
```
110+
111+
### ISO Mounting
112+
113+
```yaml
114+
media:
115+
desc: "Virtual media control: mount <path>|mount-url <url>|unmount|media-status"
116+
modules:
117+
- module: pikvm
118+
main: true
119+
options:
120+
host: https://pikvm.local
121+
user: admin
122+
password: admin
123+
command: media
124+
125+
# Usage: dutctl my-server media mount-url https://releases.ubuntu.com/22.04/ubuntu-22.04-live-server-amd64.iso
126+
```
127+
128+
### Screenshot Capture
129+
130+
```yaml
131+
screenshot:
132+
desc: "Capture a screenshot from PiKVM"
133+
modules:
134+
- module: pikvm
135+
main: true
136+
options:
137+
host: https://pikvm.local
138+
user: admin
139+
password: admin
140+
command: screenshot
141+
142+
# Usage: dutctl my-server screenshot
143+
# The screenshot will be saved to the current directory
144+
```
145+
146+
## Requirements
147+
148+
- PiKVM device with API access enabled
149+
- Network connectivity between dutagent and PiKVM
150+
- Valid authentication credentials
151+
152+
## Notes
153+
154+
- The module defaults to HTTPS if no scheme is specified in the host
155+
- HTTP can be used by explicitly specifying `http://` in the host
156+
- Power commands use intelligent API:
157+
- `on` - Does nothing if already powered on (idempotent)
158+
- `off` - Graceful shutdown via power button press
159+
- `force-off` - Hard power off via long press (5+ seconds)
160+
- `reset` - Reset button press
161+
- `force-reset` - Hardware hot reset
162+
- Virtual media:
163+
- `mount` uploads images to PiKVM's storage (with automatic space management)
164+
- `mount-url` instructs PiKVM to download the image directly from the URL
165+
- Old images are automatically deleted when storage space is needed
166+
- SHA256 hashing prevents duplicate uploads
167+
- Screenshot functionality captures the current display output from PiKVM's video stream

0 commit comments

Comments
 (0)