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

python_mister_fpga-0.3.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 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.1.3 → python_mister_fpga-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-mister-fpga
-Version: 0.1.3
+Version: 0.3.0
 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/
@@ -23,6 +23,7 @@ Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
 Provides-Extra: test
+Requires-Dist: aiohttp<3.10; extra == 'test'
 Requires-Dist: aioresponses>=0.7; extra == 'test'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
 Requires-Dist: pytest>=8; extra == 'test'
@@ -107,6 +108,102 @@ 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
+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.
+
+| Method | Description |
+|---|---|
+| `await async_fetch_stats() -> MisterRAWebStats` | Fire all three API calls concurrently and return an aggregated stats snapshot. |
+| `await async_validate()` | Lightweight credential check — raises `MisterRAWebError` if the username or API key is wrong. |
+| `await async_get_badge_image(url) -> bytes` | Fetch a badge or icon image by absolute URL (e.g. `stats.last_achievement.badge_url`). |
+| `await async_close()` | Close the session if this client created it. |
+
+### Dataclasses
+
+**`MisterRAWebStats`** — aggregated snapshot returned by `async_fetch_stats()`:
+
+| Field | Type | Description |
+|---|---|---|
+| `hardcore_points` | `int` | Total hardcore score. |
+| `softcore_points` | `int` | Total softcore score. |
+| `rank` | `int \| None` | Global hardcore rank (None if unranked). |
+| `total_ranked` | `int \| None` | Total number of ranked players. |
+| `current_game` | `RAGameProgress \| None` | Most recently played game (first entry in the recent-games list). |
+| `recent_games` | `list[RAGameProgress]` | Up to 10 recently played games, most-recent first. |
+| `last_achievement` | `RAAchievement \| None` | Most recently unlocked achievement (within the last 7 days). |
+
+**`RAGameProgress`** — per-game achievement progress:
+
+| Field | Type | Description |
+|---|---|---|
+| `game_id` | `int` | RA game ID. |
+| `title` | `str` | Game title. |
+| `console` | `str` | Console name (e.g. `"SNES"`). |
+| `num_achieved` | `int` | Achievements unlocked by the player. |
+| `num_possible` | `int` | Total achievements in the set. |
+| `percent` | `float` | Completion percentage (0–100). |
+| `last_played` | `str \| None` | ISO-ish timestamp of last session. |
+| `icon_url` | `str \| None` | Absolute URL of the game icon. |
+
+**`RAAchievement`** — a single unlocked achievement:
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | `str` | Achievement title. |
+| `description` | `str` | Achievement description. |
+| `points` | `int` | Point value. |
+| `game_title` | `str` | Title of the game it belongs to. |
+| `date` | `str \| None` | Unlock timestamp. |
+| `badge_url` | `str \| None` | Absolute URL of the badge image. |
+
+**`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`.
@@ -116,6 +213,9 @@ asyncio.run(main())
 - **`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

python_mister_fpga-0.3.0/README.md

@@ -0,0 +1,199 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/dark_logo.png" width="420">
+    <img src="assets/logo.png" alt="python-mister-fpga" width="420">
+  </picture>
+</p>
+
+# python-mister-fpga
+
+[![Tests](https://github.com/hudsonbrendon/python-mister-fpga/actions/workflows/tests.yml/badge.svg)](https://github.com/hudsonbrendon/python-mister-fpga/actions/workflows/tests.yml)
+[![PyPI version](https://img.shields.io/pypi/v/python-mister-fpga)](https://pypi.org/project/python-mister-fpga/)
+[![Python versions](https://img.shields.io/pypi/pyversions/python-mister-fpga)](https://pypi.org/project/python-mister-fpga/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://hudsonbrendon.github.io/python-mister-fpga/)
+
+Async Python client for the [mrext Remote API](https://github.com/wizzomafizzo/mrext) (REST + WebSocket) and optional SSH telemetry for the MiSTer FPGA. Zero Home Assistant dependency — use it in any Python project.
+
+## Install
+
+```bash
+pip install python-mister-fpga
+```
+
+## Usage
+
+### REST client
+
+```python
+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)
+
+```python
+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
+
+```python
+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)
+
+```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
+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.
+
+| Method | Description |
+|---|---|
+| `await async_fetch_stats() -> MisterRAWebStats` | Fire all three API calls concurrently and return an aggregated stats snapshot. |
+| `await async_validate()` | Lightweight credential check — raises `MisterRAWebError` if the username or API key is wrong. |
+| `await async_get_badge_image(url) -> bytes` | Fetch a badge or icon image by absolute URL (e.g. `stats.last_achievement.badge_url`). |
+| `await async_close()` | Close the session if this client created it. |
+
+### Dataclasses
+
+**`MisterRAWebStats`** — aggregated snapshot returned by `async_fetch_stats()`:
+
+| Field | Type | Description |
+|---|---|---|
+| `hardcore_points` | `int` | Total hardcore score. |
+| `softcore_points` | `int` | Total softcore score. |
+| `rank` | `int \| None` | Global hardcore rank (None if unranked). |
+| `total_ranked` | `int \| None` | Total number of ranked players. |
+| `current_game` | `RAGameProgress \| None` | Most recently played game (first entry in the recent-games list). |
+| `recent_games` | `list[RAGameProgress]` | Up to 10 recently played games, most-recent first. |
+| `last_achievement` | `RAAchievement \| None` | Most recently unlocked achievement (within the last 7 days). |
+
+**`RAGameProgress`** — per-game achievement progress:
+
+| Field | Type | Description |
+|---|---|---|
+| `game_id` | `int` | RA game ID. |
+| `title` | `str` | Game title. |
+| `console` | `str` | Console name (e.g. `"SNES"`). |
+| `num_achieved` | `int` | Achievements unlocked by the player. |
+| `num_possible` | `int` | Total achievements in the set. |
+| `percent` | `float` | Completion percentage (0–100). |
+| `last_played` | `str \| None` | ISO-ish timestamp of last session. |
+| `icon_url` | `str \| None` | Absolute URL of the game icon. |
+
+**`RAAchievement`** — a single unlocked achievement:
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | `str` | Achievement title. |
+| `description` | `str` | Achievement description. |
+| `points` | `int` | Point value. |
+| `game_title` | `str` | Title of the game it belongs to. |
+| `date` | `str \| None` | Unlock timestamp. |
+| `badge_url` | `str \| None` | Absolute URL of the badge image. |
+
+**`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](https://github.com/wizzomafizzo/mrext). MiSTer-kun logo by the MiSTer-devel project. Author [@hudsonbrendon](https://github.com/hudsonbrendon).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

python_mister_fpga-0.3.0/docs/api.md

@@ -0,0 +1,45 @@
+# API reference
+
+::: mister_fpga.MisterClient
+
+::: mister_fpga.MisterStatus
+
+::: mister_fpga.MisterWebSocketClient
+
+::: mister_fpga.apply_ws_message
+
+::: mister_fpga.MisterSSH
+
+::: mister_fpga.parse_ssh_probe
+
+::: 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
+
+::: mister_fpga.RAGameProgress
+
+::: mister_fpga.RAAchievement
+
+::: mister_fpga.MisterRAWebError

python_mister_fpga-0.3.0/docs/changelog.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 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.1.3 → python_mister_fpga-0.3.0}/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.1.3 → python_mister_fpga-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mister-fpga"
-version = "0.1.3"
+version = "0.3.0"
 description = "Async Python client for the MiSTer FPGA mrext Remote API (REST + WebSocket) and SSH telemetry"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -28,7 +28,14 @@ Documentation = "https://hudsonbrendon.github.io/python-mister-fpga/"
 Issues = "https://github.com/hudsonbrendon/python-mister-fpga/issues"
 
 [project.optional-dependencies]
-test = ["pytest>=8", "pytest-asyncio>=0.23", "aioresponses>=0.7", "ruff"]
+test = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "aioresponses>=0.7",
+  # aiohttp<3.10: aioresponses 0.7.8 uses the removed loop= param in StreamReader
+  "aiohttp<3.10",
+  "ruff",
+]
 docs = ["mkdocs-material>=9.5", "mkdocstrings[python]>=0.25"]
 
 [tool.hatch.build.targets.wheel]

python_mister_fpga-0.3.0/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.0"