picokvm-client 0.1.0__py3-none-any.whl

picokvm_client/__init__.py

@@ -0,0 +1,38 @@
+"""Python client for the Luckfox PicoKVM device.
+
+The PicoKVM exposes a JSON-RPC 2.0 API at ``POST /api/rpc`` (the same
+methods the web UI drives) plus a session-cookie auth endpoint at
+``POST /auth/login-local``.  This package is a thin, synchronous client
+on top of :mod:`httpx` and :mod:`jsonrpcclient` covering both.
+
+The PicoKVM firmware is a Luckfox-Pico-based fork of `JetKVM
+<https://github.com/jetkvm/kvm>`_; the wire protocol is largely shared
+with upstream and other forks today, but **this client makes no
+compatibility commitment** to JetKVM or its other forks.  The PicoKVM
+is the only device this library is tested against.  If you have a
+JetKVM, this library *might* work for the methods that haven't
+diverged — but a separate ``jetkvm-client`` package would be the right
+home for that contract.
+"""
+
+from __future__ import annotations
+
+from picokvm_client.client import PicoKVMClient
+from picokvm_client.exceptions import (
+    AuthError,
+    PicoKVMError,
+    RpcError,
+    TransportError,
+)
+from picokvm_client.methods import KeyboardLedState, UsbState, VideoState
+
+__all__ = [
+    "AuthError",
+    "KeyboardLedState",
+    "PicoKVMClient",
+    "PicoKVMError",
+    "RpcError",
+    "TransportError",
+    "UsbState",
+    "VideoState",
+]

picokvm_client/_cli.py

@@ -0,0 +1,386 @@
+"""Bundled ``picokvm`` CLI tool.
+
+A thin Typer wrapper around :class:`PicoKVMClient` so users can
+exercise the typed surface from the shell without writing a script.
+
+The CLI is intentionally minimal: every verb delegates to a single
+typed method (or to :meth:`PicoKVMClient.rpc` for the ``rpc``
+escape-hatch verb).  The package itself is the contract; this module
+just gives users a fast feedback loop.
+
+Connection details come from ``--url`` / ``--password`` flags or the
+``PICOKVM_URL`` / ``PICOKVM_PASSWORD`` environment variables (flags
+win).  Missing connection info exits non-zero with a clear message --
+no interactive prompts (the CLI is meant to be scriptable).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Annotated, Any
+
+import typer
+
+from picokvm_client.client import (
+    PicoKVMClient,
+    VirtualMediaMode,
+)
+from picokvm_client.exceptions import (
+    AuthError,
+    PicoKVMError,
+    RpcError,
+    TransportError,
+)
+
+ENV_URL = "PICOKVM_URL"
+ENV_PASSWORD = "PICOKVM_PASSWORD"
+
+app = typer.Typer(
+    name="picokvm",
+    help=(
+        "Drive a Luckfox PicoKVM from the shell.\n\n"
+        "Connection details come from --url / --password or the\n"
+        f"{ENV_URL} / {ENV_PASSWORD} environment variables (flags win).\n\n"
+        "See the package README for the full method list."
+    ),
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+
+# ---------------------------------------------------------------------------
+# Shared option types
+# ---------------------------------------------------------------------------
+UrlOpt = Annotated[
+    str | None,
+    typer.Option(
+        "--url",
+        "-u",
+        envvar=ENV_URL,
+        help=f"PicoKVM base URL (or set {ENV_URL}).",
+        show_default=False,
+    ),
+]
+
+PasswordOpt = Annotated[
+    str | None,
+    typer.Option(
+        "--password",
+        "-p",
+        envvar=ENV_PASSWORD,
+        help=f"PicoKVM login password (or set {ENV_PASSWORD}).",
+        show_default=False,
+    ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Connection / error helpers
+# ---------------------------------------------------------------------------
+def _resolve_url(url: str | None) -> str:
+    """Return ``url`` or fail loudly if missing.
+
+    A bare connect to ``localhost:30080`` would only confuse a user who
+    forgot to set ``PICOKVM_URL``; we'd rather raise.
+    """
+    if url is None or url == "":
+        typer.echo(
+            f"error: no PicoKVM URL provided (--url or {ENV_URL})",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+    return url
+
+
+def _open_client(url: str | None, password: str | None) -> PicoKVMClient:
+    resolved = _resolve_url(url)
+    return PicoKVMClient(resolved, password=password)
+
+
+def _run(
+    url: str | None,
+    password: str | None,
+    fn: Any,
+) -> None:
+    """Open a client, call ``fn(client)``, render PicoKVM errors nicely.
+
+    Concentrates the try/except so each verb stays a one-liner.
+    """
+    try:
+        with _open_client(url, password) as client:
+            fn(client)
+    except AuthError as exc:
+        typer.echo(f"auth error: {exc}", err=True)
+        if exc.hint:
+            typer.echo(f"  hint: {exc.hint}", err=True)
+        raise typer.Exit(code=exc.exit_code) from exc
+    except RpcError as exc:
+        typer.echo(f"rpc error: {exc}", err=True)
+        if exc.friendly_hint:
+            typer.echo(f"  hint: {exc.friendly_hint}", err=True)
+        raise typer.Exit(code=exc.exit_code) from exc
+    except TransportError as exc:
+        typer.echo(f"transport error: {exc}", err=True)
+        if exc.hint:
+            typer.echo(f"  hint: {exc.hint}", err=True)
+        raise typer.Exit(code=exc.exit_code) from exc
+    except PicoKVMError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=exc.exit_code) from exc
+
+
+# ---------------------------------------------------------------------------
+# Verbs -- status
+# ---------------------------------------------------------------------------
+@app.command("ping")
+def cmd_ping(url: UrlOpt = None, password: PasswordOpt = None) -> None:
+    """Check that the firmware is responding.
+
+    Exits 0 on ``pong``, 1 otherwise.
+    """
+    resolved = _resolve_url(url)
+    try:
+        with PicoKVMClient(resolved, password=password) as client:
+            ok = client.ping()
+    except PicoKVMError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=exc.exit_code) from exc
+
+    if ok:
+        typer.echo("pong")
+        raise typer.Exit(code=0)
+    typer.echo("no pong", err=True)
+    raise typer.Exit(code=1)
+
+
+@app.command("device-id")
+def cmd_device_id(url: UrlOpt = None, password: PasswordOpt = None) -> None:
+    """Print the device ID (one line)."""
+    _run(url, password, lambda c: typer.echo(c.get_device_id()))
+
+
+@app.command("video-state")
+def cmd_video_state(url: UrlOpt = None, password: PasswordOpt = None) -> None:
+    """Print video input state in a human-readable single line."""
+
+    def _do(c: PicoKVMClient) -> None:
+        s = c.get_video_state()
+        typer.echo(f"{s.width}x{s.height} @ {s.fps:g}fps  ready={str(s.ready).lower()}  error={s.error!r}")
+
+    _run(url, password, _do)
+
+
+@app.command("usb-state")
+def cmd_usb_state(url: UrlOpt = None, password: PasswordOpt = None) -> None:
+    """Print USB gadget state."""
+    _run(
+        url,
+        password,
+        lambda c: typer.echo(f"state={c.get_usb_state().state}"),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Verbs -- HID input
+# ---------------------------------------------------------------------------
+@app.command("type")
+def cmd_type(
+    text: Annotated[str, typer.Argument(help="Text to type into the host.")],
+    url: UrlOpt = None,
+    password: PasswordOpt = None,
+) -> None:
+    """Type a string (US ASCII only)."""
+    _run(url, password, lambda c: c.type_text(text))
+
+
+@app.command("key")
+def cmd_key(
+    key: Annotated[str, typer.Argument(help='Named key, e.g. "F2", "Enter".')],
+    url: UrlOpt = None,
+    password: PasswordOpt = None,
+) -> None:
+    """Press and release a single named key."""
+    _run(url, password, lambda c: c.key_press(key))
+
+
+@app.command("combo")
+def cmd_combo(
+    combo: Annotated[
+        str,
+        typer.Argument(help='Key combo, e.g. "Ctrl+Alt+Del".'),
+    ],
+    url: UrlOpt = None,
+    password: PasswordOpt = None,
+) -> None:
+    """Press a key combination."""
+    _run(url, password, lambda c: c.key_combo(combo))
+
+
+@app.command("click")
+def cmd_click(
+    x: Annotated[int, typer.Argument(help="Absolute X coordinate (0..32767).")],
+    y: Annotated[int, typer.Argument(help="Absolute Y coordinate (0..32767).")],
+    button: Annotated[
+        str,
+        typer.Option(
+            "--button",
+            "-b",
+            help="Mouse button: left/right/middle.",
+        ),
+    ] = "left",
+    url: UrlOpt = None,
+    password: PasswordOpt = None,
+) -> None:
+    """Click at an absolute screen coordinate."""
+    _run(url, password, lambda c: c.click(x, y, button=button))
+
+
+# ---------------------------------------------------------------------------
+# Verbs -- device management
+# ---------------------------------------------------------------------------
+@app.command("reboot")
+def cmd_reboot(
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            "-f",
+            help="Pass -f to the underlying reboot command.",
+        ),
+    ] = False,
+    url: UrlOpt = None,
+    password: PasswordOpt = None,
+) -> None:
+    """Reboot the PicoKVM device itself (not the host)."""
+    _run(url, password, lambda c: c.reboot(force=force))
+
+
+# ---------------------------------------------------------------------------
+# Verbs -- virtual media
+# ---------------------------------------------------------------------------
+@app.command("mount-http")
+def cmd_mount_http(
+    url_arg: Annotated[
+        str,
+        typer.Argument(
+            metavar="URL",
+            help="HTTP/HTTPS URL the firmware will fetch the image from.",
+        ),
+    ],
+    mode: Annotated[
+        VirtualMediaMode,
+        typer.Option(
+            "--mode",
+            "-m",
+            help="cdrom (ISO) or disk (raw image).",
+        ),
+    ] = "cdrom",
+    url: UrlOpt = None,
+    password: PasswordOpt = None,
+) -> None:
+    """Mount a remote image via HTTP."""
+    _run(url, password, lambda c: c.mount_with_http(url_arg, mode=mode))
+
+
+@app.command("unmount")
+def cmd_unmount(url: UrlOpt = None, password: PasswordOpt = None) -> None:
+    """Unmount any currently mounted virtual media."""
+    _run(url, password, lambda c: c.unmount_image())
+
+
+# ---------------------------------------------------------------------------
+# Verbs -- generic JSON-RPC passthrough
+# ---------------------------------------------------------------------------
+_MAX_PARAM_DEPTH = 100
+
+
+def _max_bracket_depth(s: str) -> int:
+    """Largest nesting depth of ``[``/``{`` brackets in ``s``."""
+    depth = peak = 0
+    for ch in s:
+        if ch in "[{":
+            depth += 1
+            peak = max(peak, depth)
+        elif ch in "]}":
+            depth -= 1
+    return peak
+
+
+def _parse_param(spec: str) -> tuple[str, Any]:
+    """Parse a ``key=value`` --param token.
+
+    Values are JSON-decoded when possible (so ``force=true`` becomes
+    the bool ``True`` and ``keys=[4,5]`` becomes ``[4, 5]``); fall
+    back to the raw string when JSON parsing fails (so users do not
+    have to quote ordinary strings).
+    """
+    if "=" not in spec:
+        raise typer.BadParameter(
+            f"--param expects key=value, got {spec!r}",
+        )
+    key, _, raw = spec.partition("=")
+    if not key:
+        raise typer.BadParameter(f"--param key cannot be empty: {spec!r}")
+    # Reject pathologically nested input deterministically instead of relying
+    # on json.loads raising RecursionError -- json's recursion behaviour
+    # differs across Python versions (e.g. 3.13 parses far deeper). Anything
+    # past a sane depth is not a real parameter; treat it as a plain string.
+    if _max_bracket_depth(raw) > _MAX_PARAM_DEPTH:
+        return key, raw
+    try:
+        value: Any = json.loads(raw)
+    except (json.JSONDecodeError, RecursionError, ValueError):
+        # ``json.loads`` raises ``RecursionError`` on deeply nested
+        # input (e.g. ``[[[[...]]]]`` past the interpreter's recursion
+        # limit) and ``ValueError`` for a handful of edge cases (NaN /
+        # Infinity in strict mode, surrogate handling).  Treat all of
+        # these as "not valid JSON, fall back to the raw string" so the
+        # CLI never escapes with a stack trace.
+        value = raw
+    return key, value
+
+
+@app.command("rpc")
+def cmd_rpc(
+    method: Annotated[
+        str,
+        typer.Argument(help="JSON-RPC method name, e.g. 'getJigglerState'."),
+    ],
+    params: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--param",
+            help=("key=value pair (repeatable). Values are JSON-decoded when possible; otherwise treated as strings."),
+        ),
+    ] = None,
+    url: UrlOpt = None,
+    password: PasswordOpt = None,
+) -> None:
+    """Generic JSON-RPC passthrough: call any firmware method.
+
+    The result is printed as JSON on stdout.  Useful for the long tail
+    of methods that don't have a typed wrapper yet.
+    """
+    parsed: dict[str, Any] = {}
+    for spec in params or []:
+        key, value = _parse_param(spec)
+        parsed[key] = value
+
+    def _do(c: PicoKVMClient) -> None:
+        result = c.rpc(method, **parsed)
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+
+    _run(url, password, _do)
+
+
+# ---------------------------------------------------------------------------
+# Module entry point (so `python -m picokvm_client._cli` works too)
+# ---------------------------------------------------------------------------
+def main() -> None:  # pragma: no cover - thin entry point
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

picokvm_client/_hid.py

@@ -0,0 +1,259 @@
+"""USB HID lookup tables for the high-level keyboard / mouse helpers.
+
+The PicoKVM firmware (``kvm/usb.go``) accepts raw USB HID Boot-Protocol
+reports for both the keyboard and mouse channels.  This module owns the
+lookup tables that :meth:`PicoKVMClient.type_text`,
+:meth:`~PicoKVMClient.key_press`, and :meth:`~PicoKVMClient.key_combo`
+use to translate human-friendly Python arguments into the wire bytes:
+
+* :data:`KEYNAME_TO_KEYCODE` -- named keys ("Enter", "F2", arrows, ...)
+  to USB HID Usage IDs.  Source: USB HID Usage Tables 1.22, section 10
+  (Keyboard/Keypad Page, ``0x07``).  See
+  https://usb.org/sites/default/files/hut1_22.pdf .
+
+* :data:`ASCII_TO_HID` -- printable US-ASCII characters to a
+  ``(usage_id, requires_shift)`` tuple.  Layout: the standard US
+  keyboard.  Non-US layouts are out of scope for v0.1.0; pass raw HID
+  reports via :meth:`PicoKVMClient.keyboard_report` if you need them.
+
+* :data:`MODIFIER_BITS` -- modifier-key name to the bit position in the
+  HID modifier byte.  Multiple aliases for the GUI bit (``Win``,
+  ``Meta``, ``Cmd``, ``GUI``) so :meth:`~.key_combo` is forgiving about
+  what users type.
+
+Lookups are intentionally case-insensitive: we lowercase the key/token
+before consulting the table.  The tables themselves store lowercase
+keys.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+# ---------------------------------------------------------------------------
+# Modifier byte (USB HID keyboard report byte 0)
+# ---------------------------------------------------------------------------
+# Bit layout per the HID Usage Tables, Keyboard/Keypad Page:
+#   bit 0: Left Ctrl   bit 4: Right Ctrl
+#   bit 1: Left Shift  bit 5: Right Shift
+#   bit 2: Left Alt    bit 6: Right Alt
+#   bit 3: Left GUI    bit 7: Right GUI
+#
+# We expose the *left*-side bit for each name; combos like "Right Ctrl"
+# are uncommon in practice and can be issued via keyboard_report() with
+# a hand-rolled modifier byte.
+MODIFIER_BITS: Final[dict[str, int]] = {
+    "ctrl": 0x01,
+    "control": 0x01,
+    "shift": 0x02,
+    "alt": 0x04,
+    "option": 0x04,  # macOS naming
+    # GUI bit aliases.  All map to the same bit (Left GUI, 0x08).
+    "win": 0x08,
+    "meta": 0x08,
+    "cmd": 0x08,
+    "command": 0x08,
+    "gui": 0x08,
+    "super": 0x08,
+}
+
+
+# ---------------------------------------------------------------------------
+# Named keys -> USB HID Usage IDs (keyboard/keypad page, 0x07)
+# ---------------------------------------------------------------------------
+# Lowercase keys for case-insensitive lookup.  Names follow common
+# conventions ("Enter" not "Return", "Esc" with "Escape" as alias,
+# arrows as "ArrowUp" / "Up", etc.).
+KEYNAME_TO_KEYCODE: Final[dict[str, int]] = {
+    # Letters (HID 0x04..0x1D)
+    "a": 0x04,
+    "b": 0x05,
+    "c": 0x06,
+    "d": 0x07,
+    "e": 0x08,
+    "f": 0x09,
+    "g": 0x0A,
+    "h": 0x0B,
+    "i": 0x0C,
+    "j": 0x0D,
+    "k": 0x0E,
+    "l": 0x0F,
+    "m": 0x10,
+    "n": 0x11,
+    "o": 0x12,
+    "p": 0x13,
+    "q": 0x14,
+    "r": 0x15,
+    "s": 0x16,
+    "t": 0x17,
+    "u": 0x18,
+    "v": 0x19,
+    "w": 0x1A,
+    "x": 0x1B,
+    "y": 0x1C,
+    "z": 0x1D,
+    # Digit row (HID 0x1E..0x27).  "1".."0" -- note 0 is at the end.
+    "1": 0x1E,
+    "2": 0x1F,
+    "3": 0x20,
+    "4": 0x21,
+    "5": 0x22,
+    "6": 0x23,
+    "7": 0x24,
+    "8": 0x25,
+    "9": 0x26,
+    "0": 0x27,
+    # Whitespace / control
+    "enter": 0x28,
+    "return": 0x28,
+    "esc": 0x29,
+    "escape": 0x29,
+    "backspace": 0x2A,
+    "tab": 0x2B,
+    "space": 0x2C,
+    " ": 0x2C,
+    # Punctuation row (matches ASCII_TO_HID printable mappings)
+    "-": 0x2D,
+    "minus": 0x2D,
+    "=": 0x2E,
+    "equal": 0x2E,
+    "equals": 0x2E,
+    "[": 0x2F,
+    "leftbracket": 0x2F,
+    "]": 0x30,
+    "rightbracket": 0x30,
+    "\\": 0x31,
+    "backslash": 0x31,
+    ";": 0x33,
+    "semicolon": 0x33,
+    "'": 0x34,
+    "apostrophe": 0x34,
+    "quote": 0x34,
+    "`": 0x35,
+    "grave": 0x35,
+    "backtick": 0x35,
+    ",": 0x36,
+    "comma": 0x36,
+    ".": 0x37,
+    "period": 0x37,
+    "dot": 0x37,
+    "/": 0x38,
+    "slash": 0x38,
+    "capslock": 0x39,
+    "caps": 0x39,
+    # Function keys (HID 0x3A..0x45)
+    "f1": 0x3A,
+    "f2": 0x3B,
+    "f3": 0x3C,
+    "f4": 0x3D,
+    "f5": 0x3E,
+    "f6": 0x3F,
+    "f7": 0x40,
+    "f8": 0x41,
+    "f9": 0x42,
+    "f10": 0x43,
+    "f11": 0x44,
+    "f12": 0x45,
+    # Navigation cluster
+    "printscreen": 0x46,
+    "prtsc": 0x46,
+    "scrolllock": 0x47,
+    "pause": 0x48,
+    "break": 0x48,
+    "insert": 0x49,
+    "ins": 0x49,
+    "home": 0x4A,
+    "pageup": 0x4B,
+    "pgup": 0x4B,
+    "delete": 0x4C,
+    "del": 0x4C,
+    "end": 0x4D,
+    "pagedown": 0x4E,
+    "pgdn": 0x4E,
+    # Arrow keys
+    "right": 0x4F,
+    "arrowright": 0x4F,
+    "left": 0x50,
+    "arrowleft": 0x50,
+    "down": 0x51,
+    "arrowdown": 0x51,
+    "up": 0x52,
+    "arrowup": 0x52,
+    # Application keys
+    "menu": 0x65,
+    "app": 0x65,
+}
+
+
+# ---------------------------------------------------------------------------
+# Printable US-ASCII -> (usage_id, requires_shift)
+# ---------------------------------------------------------------------------
+# Built mechanically from KEYNAME_TO_KEYCODE for the unshifted side and
+# from the standard US shift map for the shifted side.  Whitespace is
+# handled here (space, tab, newline) so type_text() can iterate over a
+# single table.
+def _build_ascii_to_hid() -> dict[str, tuple[int, bool]]:
+    table: dict[str, tuple[int, bool]] = {}
+
+    # Letters: lowercase unshifted, uppercase shifted, both share keycode.
+    for ch_low in "abcdefghijklmnopqrstuvwxyz":
+        keycode = KEYNAME_TO_KEYCODE[ch_low]
+        table[ch_low] = (keycode, False)
+        table[ch_low.upper()] = (keycode, True)
+
+    # Digit row: unshifted digits and their shifted symbols.
+    digit_shifted = {
+        "1": "!",
+        "2": "@",
+        "3": "#",
+        "4": "$",
+        "5": "%",
+        "6": "^",
+        "7": "&",
+        "8": "*",
+        "9": "(",
+        "0": ")",
+    }
+    for digit, sym in digit_shifted.items():
+        keycode = KEYNAME_TO_KEYCODE[digit]
+        table[digit] = (keycode, False)
+        table[sym] = (keycode, True)
+
+    # Punctuation pairs: (unshifted, shifted, keycode).
+    # Sourced from the US keyboard layout.
+    punct = [
+        ("-", "_", KEYNAME_TO_KEYCODE["-"]),
+        ("=", "+", KEYNAME_TO_KEYCODE["="]),
+        ("[", "{", KEYNAME_TO_KEYCODE["["]),
+        ("]", "}", KEYNAME_TO_KEYCODE["]"]),
+        ("\\", "|", KEYNAME_TO_KEYCODE["\\"]),
+        (";", ":", KEYNAME_TO_KEYCODE[";"]),
+        ("'", '"', KEYNAME_TO_KEYCODE["'"]),
+        ("`", "~", KEYNAME_TO_KEYCODE["`"]),
+        (",", "<", KEYNAME_TO_KEYCODE[","]),
+        (".", ">", KEYNAME_TO_KEYCODE["."]),
+        ("/", "?", KEYNAME_TO_KEYCODE["/"]),
+    ]
+    for low, high, keycode in punct:
+        table[low] = (keycode, False)
+        table[high] = (keycode, True)
+
+    # Whitespace.  Newline -> Enter; tab -> Tab; space -> Space.
+    table[" "] = (KEYNAME_TO_KEYCODE["space"], False)
+    table["\n"] = (KEYNAME_TO_KEYCODE["enter"], False)
+    table["\t"] = (KEYNAME_TO_KEYCODE["tab"], False)
+
+    return table
+
+
+ASCII_TO_HID: Final[dict[str, tuple[int, bool]]] = _build_ascii_to_hid()
+
+
+# ---------------------------------------------------------------------------
+# Mouse button bitmask (HID mouse report byte 0)
+# ---------------------------------------------------------------------------
+MOUSE_BUTTON_BITS: Final[dict[str, int]] = {
+    "left": 0x01,
+    "right": 0x02,
+    "middle": 0x04,
+}