python-mister-fpga 0.1.2__tar.gz → 0.1.3__tar.gz

{python_mister_fpga-0.1.2 → python_mister_fpga-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mister-fpga
-Version: 0.1.2
+Version: 0.1.3
 Summary: Async Python client for the MiSTer FPGA mrext Remote API (REST + WebSocket) and SSH telemetry
 Project-URL: Homepage, https://github.com/hudsonbrendon/python-mister-fpga
 Project-URL: Documentation, https://hudsonbrendon.github.io/python-mister-fpga/

{python_mister_fpga-0.1.2 → python_mister_fpga-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mister-fpga"
-version = "0.1.2"
+version = "0.1.3"
 description = "Async Python client for the MiSTer FPGA mrext Remote API (REST + WebSocket) and SSH telemetry"
 readme = "README.md"
 requires-python = ">=3.11"

{python_mister_fpga-0.1.2 → python_mister_fpga-0.1.3}/src/mister_fpga/__init__.py

@@ -6,9 +6,14 @@ from .const import (
     DEFAULT_SSH_USERNAME,
     INI_VIDEO_KEYS,
     KEYBOARD_NAMES,
+    RA_STATUS_CMD,
+    RA_SUPPORTED_SYSTEMS,
+    RA_USERNAME_PLACEHOLDER,
     SSH_PROBE_CMD,
     WS_PATH,
+    MisterRAStatus,
 )
+from .ra import MisterRA, MisterRAError, parse_ra_status
 from .ssh import MisterSSH, parse_ssh_probe
 from .websocket import MisterWebSocketClient, apply_ws_message
 
@@ -16,16 +21,23 @@ __all__ = [
     "MisterClient",
     "MisterStatus",
     "MisterConnectionError",
+    "MisterRA",
+    "MisterRAError",
+    "MisterRAStatus",
     "MisterWebSocketClient",
     "apply_ws_message",
     "MisterSSH",
+    "parse_ra_status",
     "parse_ssh_probe",
     "KEYBOARD_NAMES",
     "INI_VIDEO_KEYS",
+    "RA_STATUS_CMD",
+    "RA_SUPPORTED_SYSTEMS",
+    "RA_USERNAME_PLACEHOLDER",
     "WS_PATH",
     "DEFAULT_PORT",
     "DEFAULT_SSH_PORT",
     "DEFAULT_SSH_USERNAME",
     "SSH_PROBE_CMD",
 ]
-__version__ = "0.1.2"
+__version__ = "0.1.3"

{python_mister_fpga-0.1.2 → python_mister_fpga-0.1.3}/src/mister_fpga/const.py

@@ -1,6 +1,8 @@
 """Protocol constants for the MiSTer FPGA mrext Remote API."""
 from __future__ import annotations
 
+from dataclasses import dataclass
+
 DEFAULT_PORT = 8182
 HTTP_TIMEOUT = 10
 
@@ -60,3 +62,37 @@ KEYBOARD_NAMES = (
     "reset", "screenshot", "raw_screenshot", "console", "exit_console",
     "computer_osd", "change_background", "pair_bluetooth", "toggle_core_dates",
 )
+
+# RetroAchievements (local, via SSH helper scripts) ------------------------
+
+# mrext system keys for cores with odelot RA-modified builds.
+RA_SUPPORTED_SYSTEMS = (
+    "NES", "FDS", "SNES", "MegaDrive", "SMS", "Gameboy", "N64", "PSX",
+    "GBA", "MegaCD", "NeoGeo", "TurboGrafx16", "Atari2600", "Atari7800", "S32X",
+)
+
+# Placeholder written by the RA installer before the user fills credentials.
+RA_USERNAME_PLACEHOLDER = "YOUR_RA_USERNAME"
+
+# One-shot SSH command emitting parseable RA state. Combines an install probe,
+# the username from the cfg, and ra_status.sh output.
+RA_STATUS_CMD = (
+    "if [ -d /media/fat/_RA_Cores ]; then echo installed=1; "
+    "else echo installed=0; fi; "
+    "echo \"username=$(sed -n 's/^username=//p' "
+    "/media/fat/retroachievements.cfg 2>/dev/null | head -1)\"; "
+    "bash /media/fat/Scripts/.ra/ra_status.sh 2>/dev/null"
+)
+
+
+@dataclass
+class MisterRAStatus:
+    """Parsed RetroAchievements local state."""
+
+    installed: bool = False
+    cores_on: bool = False
+    binary_ra: bool = False
+    hardcore: bool = False
+    username: str | None = None
+    cores_active: int = 0
+    cores_total: int = 0

python_mister_fpga-0.1.3/src/mister_fpga/ra.py

@@ -0,0 +1,82 @@
+"""RetroAchievements local control over SSH (best-effort)."""
+from __future__ import annotations
+
+import logging
+import re
+
+from .const import RA_STATUS_CMD, RA_USERNAME_PLACEHOLDER, MisterRAStatus
+
+_LOGGER = logging.getLogger(__name__)
+
+# Matches a per-core table row: "NES   RA  -> ..." or "PSX   STOCK  ...".
+_CORE_ROW = re.compile(r"^\S+\s+(RA|STOCK)\b")
+
+
+def parse_ra_status(raw: str) -> MisterRAStatus:
+    """Parse RA_STATUS_CMD output into a MisterRAStatus.
+
+    Tolerant of format drift: matches stable prefixes, ignores unknown lines,
+    and never raises.
+    """
+    status = MisterRAStatus()
+    total = 0
+    active = 0
+    for line in raw.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("installed="):
+            status.installed = stripped.split("=", 1)[1].strip() == "1"
+        elif stripped.startswith("username="):
+            value = stripped.split("=", 1)[1].strip()
+            status.username = (
+                value if value and value != RA_USERNAME_PLACEHOLDER else None
+            )
+        elif stripped.startswith("Mode flag:"):
+            status.cores_on = "ON" in stripped.split(":", 1)[1]
+        elif stripped.startswith("Hardcore"):
+            status.hardcore = "ON" in stripped.split(":", 1)[1]
+        elif stripped.startswith("/media/fat/MiSTer"):
+            status.binary_ra = "RA" in stripped.split(":", 1)[1]
+        else:
+            match = _CORE_ROW.match(line)
+            if match:
+                total += 1
+                if match.group(1) == "RA":
+                    active += 1
+    status.cores_total = total
+    status.cores_active = active
+    return status
+
+
+class MisterRAError(Exception):
+    """A RetroAchievements control command failed."""
+
+
+class MisterRA:
+    """RetroAchievements local control sharing a MisterSSH connection."""
+
+    def __init__(self, ssh) -> None:
+        self._ssh = ssh
+
+    async def async_status(self) -> MisterRAStatus | None:
+        """Probe RA state. Returns None only on SSH failure (best-effort)."""
+        try:
+            _rc, out = await self._ssh.async_run(RA_STATUS_CMD, timeout=15)
+        except Exception as err:  # noqa: BLE001 - best-effort; never break the integration
+            _LOGGER.debug("RA status probe failed: %s", err)
+            return None
+        return parse_ra_status(out)
+
+    async def async_cores_on(self) -> None:
+        await self._run_checked("bash /media/fat/Scripts/.ra/ra_on.sh")
+
+    async def async_cores_off(self) -> None:
+        await self._run_checked("bash /media/fat/Scripts/.ra/ra_off.sh")
+
+    async def async_set_hardcore(self, enabled: bool) -> None:
+        arg = "on" if enabled else "off"
+        await self._run_checked(f"bash /media/fat/Scripts/.ra/ra_hardcore.sh {arg}")
+
+    async def _run_checked(self, command: str) -> None:
+        rc, out = await self._ssh.async_run(command, timeout=30)
+        if rc != 0:
+            raise MisterRAError(f"command failed (rc={rc}): {command}\n{out}")

{python_mister_fpga-0.1.2 → python_mister_fpga-0.1.3}/src/mister_fpga/ssh.py

@@ -1,6 +1,7 @@
 """Optional SSH telemetry client for the MiSTer FPGA."""
 from __future__ import annotations
 
+import asyncio
 import logging
 
 from .const import SSH_PROBE_CMD
@@ -86,6 +87,7 @@ class MisterSSH:
         self.username = username
         self.password = password
         self._conn = None
+        self._lock = asyncio.Lock()
 
     async def _ensure(self) -> None:
         if self._conn is not None:
@@ -100,20 +102,28 @@ class MisterSSH:
             known_hosts=None,
         )
 
-    async def async_probe(self) -> dict:
-        """Run the SSH probe command and return parsed telemetry.
+    async def async_run(self, command: str, timeout: int = 15) -> tuple[int, str]:
+        """Run a command over the shared SSH connection.
 
-        Returns:
-            Telemetry dict as returned by :func:`parse_ssh_probe`, or ``{}``
-            if the SSH connection or command fails.
+        Returns ``(exit_status, stdout)``. Raises on connection/transport
+        failure (callers that need best-effort behaviour must catch).
         """
+        async with self._lock:
+            try:
+                await self._ensure()
+                result = await self._conn.run(command, check=False, timeout=timeout)
+            except Exception:
+                self._conn = None
+                raise
+            return result.exit_status or 0, result.stdout or ""
+
+    async def async_probe(self) -> dict:
+        """Run the SSH probe command and return parsed telemetry."""
         try:
-            await self._ensure()
-            result = await self._conn.run(SSH_PROBE_CMD, check=False, timeout=10)
-            return parse_ssh_probe(result.stdout or "")
-        except Exception as err:  # noqa: BLE001 - asyncssh raises many types; SSH is best-effort and must never break the HTTP integration
+            _rc, out = await self.async_run(SSH_PROBE_CMD, timeout=10)
+            return parse_ssh_probe(out)
+        except Exception as err:  # noqa: BLE001 - SSH is best-effort; never break the HTTP integration
             _LOGGER.debug("MiSTer SSH probe failed: %s", err)
-            self._conn = None
             return {}
 
     async def async_close(self) -> None:

python_mister_fpga-0.1.3/tests/test_ra.py

@@ -0,0 +1,163 @@
+"""Tests for the RetroAchievements local module."""
+import pytest
+
+from mister_fpga.const import RA_SUPPORTED_SYSTEMS, MisterRAStatus
+from mister_fpga.ra import MisterRA, MisterRAError, parse_ra_status
+
+
+def test_ra_status_defaults():
+    status = MisterRAStatus()
+    assert status.installed is False
+    assert status.cores_on is False
+    assert status.binary_ra is False
+    assert status.hardcore is False
+    assert status.username is None
+    assert status.cores_active == 0
+    assert status.cores_total == 0
+
+
+def test_supported_systems_contains_core_keys():
+    assert "NES" in RA_SUPPORTED_SYSTEMS
+    assert "SNES" in RA_SUPPORTED_SYSTEMS
+    assert "PSX" in RA_SUPPORTED_SYSTEMS
+
+
+_STATUS_ON = """installed=1
+username=hudsonbrendon
+ra_status v0.4.0
+Mode flag: ON
+Hardcore : OFF
+/media/fat/MiSTer : RA (odelot)
+
+CORE         STATE   DETAILS
+----         -----   -------
+NES          RA      -> NES.rbf (1 symlink(s), 1 stashed)
+SNES         RA      -> SNES.rbf (1 symlink(s), 1 stashed)
+PSX          STOCK   PSX_20260411.rbf
+"""
+
+_STATUS_OFF = """installed=1
+username=YOUR_RA_USERNAME
+Mode flag: never toggled
+Hardcore : OFF
+/media/fat/MiSTer : STOCK
+NES          STOCK   NES_20260603.rbf
+"""
+
+_NOT_INSTALLED = "installed=0\nusername=\n"
+
+
+def test_parse_status_on():
+    s = parse_ra_status(_STATUS_ON)
+    assert s.installed is True
+    assert s.cores_on is True
+    assert s.binary_ra is True
+    assert s.hardcore is False
+    assert s.username == "hudsonbrendon"
+    assert s.cores_total == 3
+    assert s.cores_active == 2
+
+
+def test_parse_status_off_treats_placeholder_username_as_none():
+    s = parse_ra_status(_STATUS_OFF)
+    assert s.installed is True
+    assert s.cores_on is False
+    assert s.binary_ra is False
+    assert s.username is None
+    assert s.cores_total == 1
+    assert s.cores_active == 0
+
+
+def test_parse_not_installed():
+    s = parse_ra_status(_NOT_INSTALLED)
+    assert s.installed is False
+    assert s.username is None
+    assert s.cores_total == 0
+
+
+def test_parse_hardcore_on_with_trailing_note():
+    s = parse_ra_status(
+        "installed=1\nMode flag: ON\n"
+        "Hardcore : ON  (NES/FDS only enforced upstream)\n"
+        "/media/fat/MiSTer : RA (odelot)\n"
+    )
+    assert s.hardcore is True
+
+
+def test_parse_malformed_does_not_crash():
+    s = parse_ra_status("garbage\n\nnonsense line")
+    assert s.installed is False
+    assert s.cores_total == 0
+
+
+class _FakeSSH:
+    def __init__(self, rc=0, out=""):
+        self._rc = rc
+        self._out = out
+        self.commands = []
+
+    async def async_run(self, command, timeout=15):
+        self.commands.append(command)
+        return self._rc, self._out
+
+
+class _RaisingSSH:
+    async def async_run(self, command, timeout=15):
+        raise OSError("ssh down")
+
+
+@pytest.mark.asyncio
+async def test_async_status_parses():
+    ssh = _FakeSSH(out=_STATUS_ON)
+    ra = MisterRA(ssh)
+    status = await ra.async_status()
+    assert status is not None
+    assert status.cores_on is True
+    assert status.username == "hudsonbrendon"
+
+
+@pytest.mark.asyncio
+async def test_async_status_none_on_ssh_failure():
+    ra = MisterRA(_RaisingSSH())
+    assert await ra.async_status() is None
+
+
+@pytest.mark.asyncio
+async def test_cores_on_off_commands():
+    ssh = _FakeSSH()
+    ra = MisterRA(ssh)
+    await ra.async_cores_on()
+    await ra.async_cores_off()
+    assert ssh.commands == [
+        "bash /media/fat/Scripts/.ra/ra_on.sh",
+        "bash /media/fat/Scripts/.ra/ra_off.sh",
+    ]
+
+
+@pytest.mark.asyncio
+async def test_set_hardcore_arg():
+    ssh = _FakeSSH()
+    ra = MisterRA(ssh)
+    await ra.async_set_hardcore(True)
+    await ra.async_set_hardcore(False)
+    assert ssh.commands == [
+        "bash /media/fat/Scripts/.ra/ra_hardcore.sh on",
+        "bash /media/fat/Scripts/.ra/ra_hardcore.sh off",
+    ]
+
+
+@pytest.mark.asyncio
+async def test_control_raises_on_nonzero():
+    ra = MisterRA(_FakeSSH(rc=1, out="fail"))
+    with pytest.raises(MisterRAError):
+        await ra.async_cores_on()
+
+
+def test_public_exports():
+    import mister_fpga
+
+    assert hasattr(mister_fpga, "MisterRA")
+    assert hasattr(mister_fpga, "MisterRAStatus")
+    assert hasattr(mister_fpga, "MisterRAError")
+    assert hasattr(mister_fpga, "RA_SUPPORTED_SYSTEMS")
+    assert mister_fpga.__version__ == "0.1.3"

python_mister_fpga-0.1.3/tests/test_ssh.py

@@ -0,0 +1,82 @@
+"""Tests for the optional SSH telemetry parsing."""
+from __future__ import annotations
+
+import pytest
+
+from mister_fpga.ssh import MisterSSH, parse_ssh_probe
+
+
+def test_parse_ssh_probe_full():
+    raw = (
+        "SNES\n|||\n123456.78 100.0\n|||\n0.50 0.40 0.30 1/98 1234"
+        "\n|||\n1048576\n524288\n|||\n1742860800"
+    )
+    data = parse_ssh_probe(raw)
+    assert data["active_core"] == "SNES"
+    assert data["uptime_seconds"] == 123456
+    assert data["cpu_load_1m"] == 0.50
+    assert data["memory_used_percent"] == 50.0
+    assert data["firmware_timestamp"] == 1742860800
+
+
+def test_parse_ssh_probe_partial_is_tolerant():
+    raw = "MENU\n|||\n\n|||\n\n|||\n\n|||\n"
+    data = parse_ssh_probe(raw)
+    assert data["active_core"] == "MENU"
+    assert data["uptime_seconds"] is None
+    assert data["memory_used_percent"] is None
+
+
+class _FakeResult:
+    def __init__(self, stdout="", exit_status=0):
+        self.stdout = stdout
+        self.exit_status = exit_status
+
+
+class _FakeConn:
+    def __init__(self, result):
+        self._result = result
+        self.commands = []
+
+    async def run(self, command, check=False, timeout=10):
+        self.commands.append(command)
+        return self._result
+
+    def close(self):
+        pass
+
+
+@pytest.mark.asyncio
+async def test_async_run_returns_rc_and_stdout(monkeypatch):
+    ssh = MisterSSH("h", 22, "root", "1")
+    ssh._conn = _FakeConn(_FakeResult(stdout="hello", exit_status=0))
+    rc, out = await ssh.async_run("echo hello")
+    assert rc == 0
+    assert out == "hello"
+    assert ssh._conn.commands == ["echo hello"]
+
+
+@pytest.mark.asyncio
+async def test_async_run_propagates_nonzero(monkeypatch):
+    ssh = MisterSSH("h", 22, "root", "1")
+    ssh._conn = _FakeConn(_FakeResult(stdout="boom", exit_status=3))
+    rc, out = await ssh.async_run("false")
+    assert rc == 3
+    assert out == "boom"
+
+
+@pytest.mark.asyncio
+async def test_async_run_raises_and_drops_conn_on_error():
+    ssh = MisterSSH("h", 22, "root", "1")
+
+    class _BoomConn:
+        async def run(self, *a, **k):
+            raise OSError("down")
+
+        def close(self):
+            pass
+
+    ssh._conn = _BoomConn()
+    with pytest.raises(OSError):
+        await ssh.async_run("x")
+    assert ssh._conn is None

python_mister_fpga-0.1.2/tests/test_ssh.py

@@ -1,25 +0,0 @@
-"""Tests for the optional SSH telemetry parsing."""
-from __future__ import annotations
-
-from mister_fpga.ssh import parse_ssh_probe
-
-
-def test_parse_ssh_probe_full():
-    raw = (
-        "SNES\n|||\n123456.78 100.0\n|||\n0.50 0.40 0.30 1/98 1234"
-        "\n|||\n1048576\n524288\n|||\n1742860800"
-    )
-    data = parse_ssh_probe(raw)
-    assert data["active_core"] == "SNES"
-    assert data["uptime_seconds"] == 123456
-    assert data["cpu_load_1m"] == 0.50
-    assert data["memory_used_percent"] == 50.0
-    assert data["firmware_timestamp"] == 1742860800
-
-
-def test_parse_ssh_probe_partial_is_tolerant():
-    raw = "MENU\n|||\n\n|||\n\n|||\n\n|||\n"
-    data = parse_ssh_probe(raw)
-    assert data["active_core"] == "MENU"
-    assert data["uptime_seconds"] is None
-    assert data["memory_used_percent"] is None