python-mister-fpga 0.2.0__tar.gz → 0.3.1__tar.gz

python_mister_fpga-0.3.1/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## 0.3.1
+- Import `asyncssh` at module load. The lazy import inside `MisterSSH._ensure` ran on the event loop and made Home Assistant report blocking calls (liboqs/fido2 file reads) on the first SSH connection.
+
+## 0.3.0
+
+Findings from reverse-engineering mrext Remote 0.4/0.5 and odelot's Main_MiSTer on a real device.
+
+**Fixes**
+- `async_search_games` sent `data`; the server reads `query`, so every search returned the whole index. Adds `page` (Remote 0.5 paginates). Response is `{data, total, pageSize, page}`.
+- `async_set_background_mode` used `/settings/core/menu` (answered by the web UI); the route is `/settings/cores/menu`, and only modes 0, 2, 4 … 14 are valid (`BACKGROUND_MODES`). Invalid modes now raise `ValueError`.
+- `async_launch_token` now base64url-encodes the token as `/l/` requires; pass plain text such as `**random:snes`.
+- Unknown routes (Remote answers them with `200 text/html`) raise `MisterUnsupportedError` instead of "invalid JSON".
+- `async_get_screenshots` returns `[]` when the server sends `null`.
+- Path segments (screenshots, wallpapers, scripts, playlists) are URL-quoted.
+- `MisterStatus` disk fields come from the `/media/fat` entry, not just the first disk.
+- WebSocket reducer: `menuNavigation:FULL:CURRENT` is split and joined into one path; arcade `gameRunning:<core>` keeps the name; a new `coreRunning` clears the stale system/game.
+- Docstrings: `game` is `<system>/<file>`, not a path; `dns` is the mDNS name; raw keyboard codes are Linux evdev codes.
+
+**New**
+- Main health over SSH: `parse_ssh_probe` adds `cmd_fifo_pending` (bytes Main has not read from `/dev/MiSTer_cmd` — non-zero on two probes means Main is hung), `main_open_fds`, `volume`/`muted`, `game_id`, `sam_active`, `sam_game`.
+- `MisterSSH.async_send_command` writes the command FIFO non-blocking and raises `MisterMainUnresponsiveError` instead of hanging; `async_set_volume`, `async_set_mute`.
+- `MisterGamepad`: virtual controller/keyboard through the MiSTer Companion Remote daemon (port 9191).
+- `parse_ra_log` / `MisterRA.async_read_log` / `MisterRA.async_set_debug`: RetroAchievements login, game identified, achievement, leaderboard, game-completed events from odelot's debug log.
+- `parse_index_status` / `MisterIndexStatus` (index progress), `split_menu_navigation`, `MisterWebSocketClient.async_send` (e.g. `kbdRawDown:`/`kbdRawUp:`).
+- REST: `async_delete_screenshot`, `async_get_search_systems`, `async_browse_games`, `async_browse_menu` (rejects `..`), `async_get_remote_log`, and for Remote 0.5 `async_get_screen`, `async_get_playlog_status/summary/games/sessions`; `MisterStatus.core_session_time`/`game_session_time`, `disks`.
+- `MDNS_SERVICE_TYPE` for zeroconf discovery.
+
+## 0.2.0
+- Add `MisterRAWeb` — async client for the [RetroAchievements.org Web API](https://api.docs.retroachievements.org/) to pull cloud player stats (points, rank, recently-played games, latest unlocked achievement) without SSH.
+- New dataclasses `MisterRAWebStats`, `RAGameProgress`, `RAAchievement` for aggregated cloud-stats snapshots.
+- New exception `MisterRAWebError` raised on network, HTTP, or API-level failures (including bad credentials).
+
+## 0.1.2
+- Add online documentation (MkDocs Material) at https://hudsonbrendon.github.io/python-mister-fpga/ and enrich public-API docstrings.
+
+## 0.1.1
+- Export `DEFAULT_SSH_PORT`, `DEFAULT_SSH_USERNAME` and `SSH_PROBE_CMD` from the top-level package so consumers can reuse them without duplicating.
+
+## 0.1.0
+- Initial release: async REST client (`MisterClient`/`MisterStatus`/`MisterConnectionError`), WebSocket reducer + client (`apply_ws_message`/`MisterWebSocketClient`), and SSH telemetry (`parse_ssh_probe`/`MisterSSH`) for the MiSTer FPGA mrext Remote API.

{python_mister_fpga-0.2.0 → python_mister_fpga-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-mister-fpga
-Version: 0.2.0
+Version: 0.3.1
 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/
@@ -108,6 +108,34 @@ async def main():
 asyncio.run(main())
 ```
 
+### Main health, volume and Super Attract Mode (SSH)
+
+```python
+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)
+
+```python
+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`)
+
+```python
+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](https://api.docs.retroachievements.org/) 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](https://retroachievements.org/settings).

{python_mister_fpga-0.2.0 → python_mister_fpga-0.3.1}/README.md

@@ -76,6 +76,34 @@ async def main():
 asyncio.run(main())
 ```
 
+### Main health, volume and Super Attract Mode (SSH)
+
+```python
+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)
+
+```python
+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`)
+
+```python
+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](https://api.docs.retroachievements.org/) 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](https://retroachievements.org/settings).

{python_mister_fpga-0.2.0 → python_mister_fpga-0.3.1}/docs/api.md

@@ -14,6 +14,26 @@
 
 ::: mister_fpga.MisterConnectionError
 
+::: mister_fpga.MisterUnsupportedError
+
+::: mister_fpga.MisterMainUnresponsiveError
+
+::: mister_fpga.MisterGamepad
+
+::: mister_fpga.MisterGamepadError
+
+::: mister_fpga.MisterIndexStatus
+
+::: mister_fpga.parse_index_status
+
+::: mister_fpga.split_menu_navigation
+
+::: mister_fpga.parse_volume
+
+::: mister_fpga.parse_ra_log
+
+::: mister_fpga.MisterRA
+
 ::: mister_fpga.MisterRAWeb
 
 ::: mister_fpga.MisterRAWebStats

python_mister_fpga-0.3.1/docs/changelog.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.3.1
+- Import `asyncssh` at module load. The lazy import inside `MisterSSH._ensure` ran on the event loop and made Home Assistant report blocking calls (liboqs/fido2 file reads) on the first SSH connection.
+
+## 0.3.0
+
+Findings from reverse-engineering mrext Remote 0.4/0.5 and odelot's Main_MiSTer on a real device.
+
+**Fixes**
+- `async_search_games` sent `data`; the server reads `query`, so every search returned the whole index. Adds `page` (Remote 0.5 paginates). Response is `{data, total, pageSize, page}`.
+- `async_set_background_mode` used `/settings/core/menu` (answered by the web UI); the route is `/settings/cores/menu`, and only modes 0, 2, 4 … 14 are valid (`BACKGROUND_MODES`). Invalid modes now raise `ValueError`.
+- `async_launch_token` now base64url-encodes the token as `/l/` requires; pass plain text such as `**random:snes`.
+- Unknown routes (Remote answers them with `200 text/html`) raise `MisterUnsupportedError` instead of "invalid JSON".
+- `async_get_screenshots` returns `[]` when the server sends `null`.
+- Path segments (screenshots, wallpapers, scripts, playlists) are URL-quoted.
+- `MisterStatus` disk fields come from the `/media/fat` entry, not just the first disk.
+- WebSocket reducer: `menuNavigation:FULL:CURRENT` is split and joined into one path; arcade `gameRunning:<core>` keeps the name; a new `coreRunning` clears the stale system/game.
+- Docstrings: `game` is `<system>/<file>`, not a path; `dns` is the mDNS name; raw keyboard codes are Linux evdev codes.
+
+**New**
+- Main health over SSH: `parse_ssh_probe` adds `cmd_fifo_pending` (bytes Main has not read from `/dev/MiSTer_cmd` — non-zero on two probes means Main is hung), `main_open_fds`, `volume`/`muted`, `game_id`, `sam_active`, `sam_game`.
+- `MisterSSH.async_send_command` writes the command FIFO non-blocking and raises `MisterMainUnresponsiveError` instead of hanging; `async_set_volume`, `async_set_mute`.
+- `MisterGamepad`: virtual controller/keyboard through the MiSTer Companion Remote daemon (port 9191).
+- `parse_ra_log` / `MisterRA.async_read_log` / `MisterRA.async_set_debug`: RetroAchievements login, game identified, achievement, leaderboard, game-completed events from odelot's debug log.
+- `parse_index_status` / `MisterIndexStatus` (index progress), `split_menu_navigation`, `MisterWebSocketClient.async_send` (e.g. `kbdRawDown:`/`kbdRawUp:`).
+- REST: `async_delete_screenshot`, `async_get_search_systems`, `async_browse_games`, `async_browse_menu` (rejects `..`), `async_get_remote_log`, and for Remote 0.5 `async_get_screen`, `async_get_playlog_status/summary/games/sessions`; `MisterStatus.core_session_time`/`game_session_time`, `disks`.
+- `MDNS_SERVICE_TYPE` for zeroconf discovery.
+
+## 0.1.2
+
+- Add online documentation (MkDocs Material) at <https://hudsonbrendon.github.io/python-mister-fpga/> and enrich public-API docstrings.
+
+## 0.1.1
+
+- Export `DEFAULT_SSH_PORT`, `DEFAULT_SSH_USERNAME` and `SSH_PROBE_CMD` from the top-level package so consumers can reuse them without duplicating.
+
+## 0.1.0
+
+- Initial release: async REST client (`MisterClient`/`MisterStatus`/`MisterConnectionError`), WebSocket reducer + client (`apply_ws_message`/`MisterWebSocketClient`), and SSH telemetry (`parse_ssh_probe`/`MisterSSH`) for the MiSTer FPGA mrext Remote API.

{python_mister_fpga-0.2.0 → python_mister_fpga-0.3.1}/docs/usage.md

@@ -90,3 +90,32 @@ async def main():
 
 asyncio.run(main())
 ```
+
+
+## Main health, volume and Super Attract Mode (SSH)
+
+```python
+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)
+
+```python
+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`)
+
+```python
+from mister_fpga import MisterRA
+
+ra = MisterRA(ssh)
+offset, events = await ra.async_read_log(0)   # login / game_identified / achievement / ...
+```

{python_mister_fpga-0.2.0 → python_mister_fpga-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mister-fpga"
-version = "0.2.0"
+version = "0.3.1"
 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.3.1/src/mister_fpga/__init__.py

@@ -0,0 +1,97 @@
+"""Async Python client for the MiSTer FPGA mrext Remote API."""
+from .client import (
+    MisterClient,
+    MisterConnectionError,
+    MisterStatus,
+    MisterUnsupportedError,
+)
+from .const import (
+    BACKGROUND_MODES,
+    CMD_FIFO,
+    DEFAULT_PORT,
+    DEFAULT_SSH_PORT,
+    DEFAULT_SSH_USERNAME,
+    INI_VIDEO_KEYS,
+    KEYBOARD_NAMES,
+    MDNS_SERVICE_TYPE,
+    RA_STATUS_CMD,
+    RA_SUPPORTED_SYSTEMS,
+    RA_USERNAME_PLACEHOLDER,
+    SSH_PROBE_CMD,
+    WS_PATH,
+    MisterRAStatus,
+    MisterRAWebStats,
+    RAAchievement,
+    RAGameProgress,
+)
+from .gamepad import (
+    DEFAULT_GAMEPAD_PATH,
+    DEFAULT_GAMEPAD_PORT,
+    GAMEPAD_ACTIONS,
+    GAMEPAD_BUTTONS,
+    MisterGamepad,
+    MisterGamepadError,
+)
+from .ra import MisterRA, MisterRAError, parse_ra_log, parse_ra_status
+from .ra_web import MisterRAWeb, MisterRAWebError
+from .ssh import (
+    MisterMainUnresponsiveError,
+    MisterSSH,
+    parse_game_id,
+    parse_ssh_probe,
+    parse_volume,
+)
+from .websocket import (
+    MisterIndexStatus,
+    MisterWebSocketClient,
+    apply_ws_message,
+    parse_index_status,
+    split_menu_navigation,
+)
+
+__all__ = [
+    "BACKGROUND_MODES",
+    "CMD_FIFO",
+    "DEFAULT_GAMEPAD_PATH",
+    "DEFAULT_GAMEPAD_PORT",
+    "GAMEPAD_ACTIONS",
+    "GAMEPAD_BUTTONS",
+    "MDNS_SERVICE_TYPE",
+    "MisterGamepad",
+    "MisterGamepadError",
+    "MisterIndexStatus",
+    "MisterMainUnresponsiveError",
+    "MisterUnsupportedError",
+    "parse_game_id",
+    "parse_index_status",
+    "parse_ra_log",
+    "parse_volume",
+    "split_menu_navigation",
+    "MisterClient",
+    "MisterStatus",
+    "MisterConnectionError",
+    "MisterRA",
+    "MisterRAError",
+    "MisterRAStatus",
+    "MisterRAWeb",
+    "MisterRAWebError",
+    "MisterRAWebStats",
+    "MisterWebSocketClient",
+    "apply_ws_message",
+    "MisterSSH",
+    "parse_ra_status",
+    "parse_ssh_probe",
+    "RAAchievement",
+    "RAGameProgress",
+    "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.3.1"