python-mister-fpga

Async Python client for the mrext Remote API (REST + WebSocket) and optional SSH telemetry for the MiSTer FPGA. Zero Home Assistant dependency — use it in any Python project.

Install

pip install python-mister-fpga

Usage

REST client

import asyncio
from mister_fpga import MisterClient

async def main():
    client = MisterClient("192.168.1.50")
    status = await client.async_get_status()
    print(status.core, status.game)
    await client.async_launch_game("/media/fat/games/SNES/Chrono.sfc")
    await client.async_close()

asyncio.run(main())

WebSocket (real-time updates)

import asyncio
from mister_fpga import MisterWebSocketClient, MisterStatus, apply_ws_message

state = MisterStatus(online=True)
menu_path = None
index_state = (False, False)

def on_message(text: str) -> None:
    global state, menu_path, index_state
    state, menu_path, index_state = apply_ws_message(text, state, menu_path, index_state)
    print(state.core, state.game)

async def main():
    ws = MisterWebSocketClient("192.168.1.50")
    await ws.listen(on_message)

asyncio.run(main())

SSH telemetry

import asyncio
from mister_fpga import MisterSSH

async def main():
    ssh = MisterSSH("192.168.1.50", 22, "root", "1")
    data = await ssh.async_probe()
    print(data)
    await ssh.async_close()

asyncio.run(main())

Main health, volume and Super Attract Mode (SSH)

data = await ssh.async_probe()
data["cmd_fifo_pending"]  # >0 on two probes in a row: Main is hung
data["volume"], data["muted"], data["game_id"], data["sam_game"]
await ssh.async_set_volume(5)          # 0-7, never blocks on a hung Main
await ssh.async_send_command("load_core /media/fat/menu.rbf")

Virtual gamepad (MiSTer Companion Remote daemon, port 9191)

from mister_fpga import MisterGamepad

pad = MisterGamepad("192.168.1.50")
await pad.async_press("start")         # a real controller press: works in cores, menu, SAM

RetroAchievements events (odelot Main with debug=1)

from mister_fpga import MisterRA

ra = MisterRA(ssh)
offset, events = await ra.async_read_log(0)   # login / game_identified / achievement / ...

RetroAchievements cloud stats

MisterRAWeb queries the public RetroAchievements.org Web API to pull a player's points, rank, recently-played games, and latest unlocked achievement — no SSH required. You need a Web API key from retroachievements.org/settings.

import asyncio
from mister_fpga import MisterRAWeb

async def main():
    web = MisterRAWeb("myuser", "my_api_key")
    stats = await web.async_fetch_stats()
    print(stats.hardcore_points, stats.rank, stats.current_game)
    await web.async_close()

asyncio.run(main())

MisterRAWeb(username, api_key, *, session=None, timeout=15)

Async HTTPS client for the RA Web API. When session is None the client creates its own aiohttp.ClientSession; call await web.async_close() to release it. Pass a shared session to manage its lifetime yourself.

Dataclasses

MisterRAWebStats — aggregated snapshot returned by async_fetch_stats():

RAGameProgress — per-game achievement progress:

RAAchievement — a single unlocked achievement:

MisterRAWebError — raised by MisterRAWeb on network failures, HTTP errors, or API-level errors (including bad credentials).

API

• MisterClient(host, port=8182, *, session=None, timeout=10) — async REST client; call await client.async_close() when done, or inject your own aiohttp.ClientSession.
• MisterStatus — dataclass snapshot: online, core, system, game, hostname, version, ip, ips, dns, disk_total/used/free. Property is_running_game.
• MisterConnectionError — raised on network/HTTP errors.
• MisterWebSocketClient(host, port=8182, *, session=None, reconnect_delay=5) — reconnecting WS loop; await ws.listen(callback), call ws.stop() to exit.
• apply_ws_message(message, status, menu_path, index_state) — pure reducer; apply a single WS text frame and return updated (status, menu_path, index_state).
• MisterSSH(host, port, username, password) — persistent asyncssh connection; await ssh.async_probe() returns telemetry dict.
• parse_ssh_probe(raw) — parse the raw batched SSH output into a telemetry dict.
• MisterRAWeb(username, api_key, *, session=None, timeout=15) — async RA Web API client; await web.async_fetch_stats() returns MisterRAWebStats.
• MisterRAWebStats, RAGameProgress, RAAchievement — cloud-stats dataclasses (see section above).
• MisterRAWebError — raised on RA Web API failures.
• KEYBOARD_NAMES, INI_VIDEO_KEYS, WS_PATH, DEFAULT_PORT — protocol constants.

Documentation

Full documentation is available at https://hudsonbrendon.github.io/python-mister-fpga/ — usage guide, runnable examples, and auto-generated API reference.

Credits

REST/WebSocket API by wizzomafizzo/mrext. MiSTer-kun logo by the MiSTer-devel project. Author @hudsonbrendon.

License

MIT — see LICENSE.