glkvm

Files (2)

• SKILL.md
• glkvm.py · scripts/

SKILL.md (first lines)

# GLKVM Control Skill

## Fixed setup

- GLKVM: `https://kvm.home.drewcouncil.com`
- Deterministic CLI: `{{skillDir}}/scripts/glkvm.py`

Do not ask for the address, username, or password, and do not use the curl examples below for real interactions. The CLI has the setup embedded, never prints the password, and caches only GLKVM session cookies. Always invoke it by the home-relative path shown here; never resolve `scripts/glkvm.py` relative to the session's working directory.

## Initialization

First try a read-only command, which reuses the cached session:

```bash
{{skillDir}}/scripts/glkvm.py status
```

Only if it says the session is missing or expired, run this once:

```bash
{{skillDir}}/scripts/glkvm.py login
```

Do not run it again while the cached session works.

## Required interaction workflow

The session can have any working directory. Invoke the CLI with its home-relative path. Start by observing, perform the smallest action needed, then observe again:

```bash
{{skillDir}}/scripts/glkvm.py snapshot
# Read /tmp/glkvm_snapshot.jpg with the read tool.
{{skillDir}}/scripts/glkvm.py --help
```

Common deterministic commands (set `GLKVM={{skillDir}}/scripts/glkvm.py` to shorten repeated calls):

```bash
$GLKVM status
$GLKVM snapshot [--full] [--ocr]
$GLKVM key KEY_ENTER
$GLKVM shortcut 'ControlLeft,KeyC'
$GLKVM type 'literal text' [--slow]
$GLKVM move-pixel X Y --width W --height H
$GLKVM click [--button left|right|middle]
$GLKVM relative DX DY
$GLKVM scroll DY
$GLKVM reset
$GLKVM fingerbot status
```

- Always view a fresh screenshot before deciding coordinates and after an action to verify it.
- Do not type or click unless the current screenshot makes the target and effect clear.
- Treat Fingerbot presses, PC power operations, KVM reboot, firmware operations, and remote-media operations as destructive/high-impact. Obtain explicit user confirmation immediately before them. The CLI also confirms Fingerbot presses interactively.
- The remainder of this document is the original skill's API reference. It explains behavior and key names, but its generic `<IP>` curl snippets are reference-only. Use the home-relative CLI path above, never raw curl, for this installation.

---

## Feature 1: Screenshot / View Current Screen

**Capture and save a screenshot:**
```bash
curl -sk -b /tmp/glkvm_cookies.txt \
  "https://<IP>/api/streamer/snapshot" \
  --output /tmp/glkvm_snapshot.jpg
```
Then use the Read tool to read `/tmp/glkvm_snapshot.jpg` to view the image content.

**Get thumbnail (recommended for quick preview):**
```bash
curl -sk -b /tmp/glkvm_cookies.txt \
  "https://<IP>/api/streamer/snapshot?preview=true&preview_max_width=1280&preview_max_height=720&preview_quality=80" \
  --output /tmp/glkvm_snapshot.jpg
```

**Screenshot with OCR recognition (returns text):**
```bash
curl -sk -b /tmp/glkvm_cookies.txt \
  "https://<IP>/api/streamer/snapshot?ocr=true&ocr_langs=chi_sim,eng"
```

**Parameter description:**
- `save=true`: Save screenshot to device disk
- `load=true`: Load previously saved screenshot without re-capturing
- `allow_offline=true`: Allow response even when video stream is offline
- `ocr_left/ocr_top/ocr_right/ocr_bottom`: OCR region coordinates (-1 = no crop)

**Working principle: After taking a screenshot, you must use the Read tool to view the image, understand the current screen state, then decide the next action.**

---

## Feature 2: Keyboard Control

### 2a. Send Single Key

```bash
# Full click (press + release)
curl -sk -b /tmp/glkvm_cookies.txt -X POST \
  "https://<IP>/api/hid/events/send_key?key=KEY_A"

# Press only
curl -sk -b /tmp/glkvm_cookies.txt -X POST \
  "https://<IP>/api/hid/events/send_key?key=KEY_A&state=true"

# Release only
curl -sk -b /tmp/glkvm_cookies.txt -X POST \
  "https://<IP>/api/hid/events/send_key?key=KEY_A&state=false"
```

Common key names (USB HID keycodes):
- Letters: `KEY_A` ~ `KEY_Z`
- Numbers: `KEY_1` ~ `KEY_0`
- Function keys: `KEY_F1` ~ `KEY_F12`
- Special keys: `KEY_ENTER`, `KEY_BACKSPACE`, `KEY_TAB`, `KEY_ESC`, `KEY_SPACE`
- Arrow keys: `KEY_UP`, `KEY_DOWN`, `KEY_LEFT`, `KEY_RIGHT`
- Modifier keys: `KEY_LEFTCTRL`, `KEY_LEFTSHIFT`, `KEY_LEFTALT`, `KEY_LEFTMETA`
- Others: `KEY_DELETE`, `KEY_HOME`, `KEY_END`, `KEY_PAGEUP`, `KEY_PAGEDOWN`, `KEY_INSERT`

### 2b. Send Keyboard Shortcuts

From drew-council/pi-config, MIT.

More from drew-council/pi-config