aiopikvm

Async Python client for the PiKVM API.

Targets kvmd 4.206 or later — see PiKVM version.

Key features

• Full async/await API built on httpx
• 11 API resources: ATX, HID, MSD, GPIO, Streamer, Media, Switch, Redfish, Prometheus, System, Auth
• WebSocket client for realtime events and low-latency HID input
• Live video: the MJPEG stream, H.264 frames off the media daemon, and WebRTC through Janus with the webrtc extra
• Pydantic v2 response models with full type safety
• PEP 561 compatible — works with mypy strict mode
• TOTP two-factor authentication support

Quick example

import asyncio
from aiopikvm import PiKVM

async def main():
    async with PiKVM("https://pikvm.local", user="admin", passwd="admin") as kvm:
        # Check host power state
        state = await kvm.atx.get_state()
        if not state.leds.power:
            await kvm.atx.power_on()

        # Type text via HID
        await kvm.hid.type_text("Hello from aiopikvm!")

        # Take a screenshot
        screen = await kvm.streamer.snapshot()
        with open("screen.jpeg", "wb") as f:
            f.write(screen.data)

asyncio.run(main())

Getting started

New to aiopikvm? Start here:

• Installation — install the package
• Quick Start — first steps with every resource
• Configuration — constructor parameters and client lifecycle

User guide

Detailed guides for each API resource:

• ATX Power Control — power on/off, reset, status LEDs
• HID Keyboard & Mouse — typing, key events, mouse control
• Mass Storage (MSD) — virtual drives and image upload
• GPIO Channels — read/write GPIO state
• Streamer & OCR — screenshots and text recognition
• Live Video — the MJPEG stream and H.264 over the media socket
• WebRTC Video — the low-latency path, through Janus
• KVM Switch — multi-port switching and EDID management
• Redfish BMC — DMTF Redfish compatibility
• Prometheus Metrics — metrics export
• System Info & Logs — device info and log streaming
• WebSocket — realtime events and HID input
• Error Handling — exception hierarchy and patterns

API reference

Auto-generated from source code docstrings:

• PiKVM Client — main client class
• WebSocket — WebSocket client
• Media WebSocket — the video socket
• WebRTC Session — the Janus signalling session
• Models — Pydantic response models
• Exceptions — exception hierarchy
• Resources — all API resource classes