blueretro-ble 0.1.0__tar.gz

blueretro_ble-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hudson Brendon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blueretro_ble-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: blueretro-ble
+Version: 0.1.0
+Summary: BLE library for the BlueRetro retro-console Bluetooth adapter
+Author-email: Hudson Brendon <contato.hudsonbrendon@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hudsonbrendon/blueretro-homeassistant
+Project-URL: Repository, https://github.com/hudsonbrendon/blueretro-homeassistant
+Project-URL: Issues, https://github.com/hudsonbrendon/blueretro-homeassistant/issues
+Keywords: bluetooth,ble,blueretro,home-assistant,retro-gaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.22.0
+Requires-Dist: bleak-retry-connector>=3.5.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: pytest-homeassistant-custom-component>=0.13; extra == "test"
+Requires-Dist: pyserial>=3.5; extra == "test"
+Requires-Dist: dbus-fast>=2.0; extra == "test"
+Dynamic: license-file
+
+# BlueRetro for Home Assistant
+
+Autodiscovers a [BlueRetro](https://github.com/darthcloud/BlueRetro) adapter over Bluetooth
+and exposes read-only sensors plus reboot/deep-sleep controls.
+
+## Limits
+
+- Works only while the adapter is **idle** (no controller connected). During gameplay the
+  config BLE is unavailable, so entities show `unavailable` — by design, to protect gameplay.
+- No battery or live controller input (the hardware does not expose them).
+
+## Install
+
+1. Add this repo as a HACS custom repository (category: Integration).
+2. Install **BlueRetro** and restart Home Assistant.
+3. Power the BlueRetro with no controller connected; Home Assistant discovers it automatically.
+
+## Entities
+
+- Sensors: Firmware, Game ID, Game, Config source, ABI version (diag), BD address (diag).
+- Binary sensor: Config available (connectivity).
+- Buttons: Reboot, Deep sleep.

blueretro_ble-0.1.0/README.md

@@ -0,0 +1,22 @@
+# BlueRetro for Home Assistant
+
+Autodiscovers a [BlueRetro](https://github.com/darthcloud/BlueRetro) adapter over Bluetooth
+and exposes read-only sensors plus reboot/deep-sleep controls.
+
+## Limits
+
+- Works only while the adapter is **idle** (no controller connected). During gameplay the
+  config BLE is unavailable, so entities show `unavailable` — by design, to protect gameplay.
+- No battery or live controller input (the hardware does not expose them).
+
+## Install
+
+1. Add this repo as a HACS custom repository (category: Integration).
+2. Install **BlueRetro** and restart Home Assistant.
+3. Power the BlueRetro with no controller connected; Home Assistant discovers it automatically.
+
+## Entities
+
+- Sensors: Firmware, Game ID, Game, Config source, ABI version (diag), BD address (diag).
+- Binary sensor: Config available (connectivity).
+- Buttons: Reboot, Deep sleep.

blueretro_ble-0.1.0/blueretro_ble/__init__.py

@@ -0,0 +1,16 @@
+"""BlueRetro BLE library."""
+
+from .const import SERVICE_UUID
+from .device import BlueRetroDevice
+from .discovery import supports
+from .models import BlueRetroState
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SERVICE_UUID",
+    "BlueRetroDevice",
+    "BlueRetroState",
+    "supports",
+    "__version__",
+]

blueretro_ble-0.1.0/blueretro_ble/const.py

@@ -0,0 +1,18 @@
+"""BlueRetro BLE protocol constants (from darthcloud/BlueRetroWebCfg)."""
+
+SERVICE_UUID = "56830f56-5180-fab0-314b-2fa176799a00"
+
+# Directly readable characteristics
+CHAR_ABI = "56830f56-5180-fab0-314b-2fa176799a06"
+CHAR_CMD = "56830f56-5180-fab0-314b-2fa176799a07"
+CHAR_APP = "56830f56-5180-fab0-314b-2fa176799a09"
+CHAR_BDADDR = "56830f56-5180-fab0-314b-2fa176799a0c"
+
+# Command bytes written to CHAR_CMD, response read back from CHAR_CMD
+CMD_GET_GAMEID = 0x04
+CMD_GET_CFG_SRC = 0x05
+CMD_SYS_DEEP_SLEEP = 0x37
+CMD_SYS_RESET = 0x38
+
+# Advertised BLE name prefix used for discovery
+NAME_PREFIX = "BlueRetro"

blueretro_ble-0.1.0/blueretro_ble/device.py

@@ -0,0 +1,89 @@
+"""High-level BlueRetro device operations over BLE."""
+
+from __future__ import annotations
+
+import logging
+
+from bleak import BleakClient
+from bleak.backends.device import BLEDevice
+from bleak.exc import BleakError
+from bleak_retry_connector import establish_connection
+
+from . import const
+from .gameid import lookup_game_name
+from .models import BlueRetroState
+from .parser import decode_abi, decode_bdaddr, decode_string
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class BlueRetroDevice:
+    """Connects to a BlueRetro adapter to read state and send commands."""
+
+    def __init__(self) -> None:
+        self.last_state = BlueRetroState()
+
+    async def _connect(self, ble_device: BLEDevice) -> BleakClient:
+        return await establish_connection(
+            BleakClient, ble_device, ble_device.address
+        )
+
+    async def async_update(self, ble_device: BLEDevice) -> BlueRetroState:
+        """Connect, read all fields, disconnect. Never raises."""
+        try:
+            client = await self._connect(ble_device)
+        except (BleakError, TimeoutError, OSError) as err:
+            _LOGGER.debug("BlueRetro connect failed: %s", err)
+            self.last_state = BlueRetroState(available=False)
+            return self.last_state
+
+        try:
+            abi = decode_abi(await client.read_gatt_char(const.CHAR_ABI))
+            fw = decode_string(await client.read_gatt_char(const.CHAR_APP))
+            bdaddr = decode_bdaddr(await client.read_gatt_char(const.CHAR_BDADDR))
+            game_id = decode_string(
+                await self._command(client, const.CMD_GET_GAMEID)
+            )
+            cfg_src = decode_abi(
+                await self._command(client, const.CMD_GET_CFG_SRC)
+            )
+        except (BleakError, TimeoutError, OSError, Exception) as err:  # noqa: BLE001
+            _LOGGER.debug("BlueRetro read failed: %s", err)
+            self.last_state = BlueRetroState(available=False)
+            return self.last_state
+        finally:
+            await client.disconnect()
+
+        state = BlueRetroState(
+            available=True,
+            fw_version=fw,
+            abi_version=abi,
+            bdaddr=bdaddr,
+            game_id=game_id,
+            cfg_src=cfg_src,
+            game_name=lookup_game_name(game_id),
+        )
+        self.last_state = state
+        return state
+
+    async def _command(self, client: BleakClient, command: int) -> bytes:
+        """Write a command byte to CHAR_CMD then read the response."""
+        await client.write_gatt_char(const.CHAR_CMD, bytes([command]), response=True)
+        return await client.read_gatt_char(const.CHAR_CMD)
+
+    async def async_reboot(self, ble_device: BLEDevice) -> None:
+        """Reboot the adapter."""
+        await self._send_command(ble_device, const.CMD_SYS_RESET)
+
+    async def async_deep_sleep(self, ble_device: BLEDevice) -> None:
+        """Put the adapter into deep sleep."""
+        await self._send_command(ble_device, const.CMD_SYS_DEEP_SLEEP)
+
+    async def _send_command(self, ble_device: BLEDevice, command: int) -> None:
+        client = await self._connect(ble_device)
+        try:
+            await client.write_gatt_char(
+                const.CHAR_CMD, bytes([command]), response=True
+            )
+        finally:
+            await client.disconnect()

blueretro_ble-0.1.0/blueretro_ble/discovery.py

@@ -0,0 +1,20 @@
+"""Detect a BlueRetro device from its BLE advertisement."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from .const import NAME_PREFIX, SERVICE_UUID
+
+
+class _AdvertisementLike(Protocol):
+    name: str | None
+    service_uuids: list[str]
+
+
+def supports(info: _AdvertisementLike) -> bool:
+    """True if the advertisement looks like a BlueRetro adapter."""
+    name = info.name or ""
+    if name.startswith(NAME_PREFIX):
+        return True
+    return SERVICE_UUID.lower() in {u.lower() for u in info.service_uuids}

blueretro_ble-0.1.0/blueretro_ble/gameid.py

@@ -0,0 +1,32 @@
+"""Resolve a BlueRetro Game ID to a human-readable game name."""
+
+from __future__ import annotations
+
+import sqlite3
+from importlib import resources
+from pathlib import Path
+
+
+def _bundled_db_path() -> Path:
+    return Path(str(resources.files("blueretro_ble") / "gameid.db"))
+
+
+def lookup_game_name(game_id: str | None, db_path: Path | None = None) -> str | None:
+    """Look up a game name in the SQLite game database.
+
+    Returns None for unknown IDs, missing DB, or any read error.
+    """
+    if not game_id:
+        return None
+    path = db_path or _bundled_db_path()
+    if not Path(path).exists():
+        return None
+    try:
+        uri = f"file:{path}?mode=ro"
+        with sqlite3.connect(uri, uri=True) as conn:
+            row = conn.execute(
+                "SELECT name FROM games WHERE id = ? LIMIT 1", (game_id,)
+            ).fetchone()
+    except sqlite3.Error:
+        return None
+    return row[0] if row else None

blueretro_ble-0.1.0/blueretro_ble/models.py

@@ -0,0 +1,18 @@
+"""State container for a BlueRetro device."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class BlueRetroState:
+    """Snapshot of a BlueRetro adapter read over BLE."""
+
+    available: bool = False
+    fw_version: str | None = None
+    abi_version: int | None = None
+    bdaddr: str | None = None
+    game_id: str | None = None
+    game_name: str | None = None
+    cfg_src: int | None = None

blueretro_ble-0.1.0/blueretro_ble/parser.py

@@ -0,0 +1,23 @@
+"""Pure decoders for BlueRetro characteristic payloads."""
+
+from __future__ import annotations
+
+
+def decode_bdaddr(raw: bytes) -> str | None:
+    """Decode a 6-byte BD address (little-endian, byte 5 first)."""
+    if len(raw) < 6:
+        return None
+    return ":".join(f"{raw[i]:02x}" for i in range(5, -1, -1))
+
+
+def decode_string(raw: bytes) -> str | None:
+    """Decode a UTF-8 string, stripping trailing NULs. Empty -> None."""
+    text = raw.decode("utf-8", errors="replace").rstrip("\x00").strip()
+    return text or None
+
+
+def decode_abi(raw: bytes) -> int | None:
+    """Decode a small integer carried in the first byte."""
+    if not raw:
+        return None
+    return raw[0]

blueretro_ble-0.1.0/blueretro_ble.egg-info/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: blueretro-ble
+Version: 0.1.0
+Summary: BLE library for the BlueRetro retro-console Bluetooth adapter
+Author-email: Hudson Brendon <contato.hudsonbrendon@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hudsonbrendon/blueretro-homeassistant
+Project-URL: Repository, https://github.com/hudsonbrendon/blueretro-homeassistant
+Project-URL: Issues, https://github.com/hudsonbrendon/blueretro-homeassistant/issues
+Keywords: bluetooth,ble,blueretro,home-assistant,retro-gaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.22.0
+Requires-Dist: bleak-retry-connector>=3.5.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: pytest-homeassistant-custom-component>=0.13; extra == "test"
+Requires-Dist: pyserial>=3.5; extra == "test"
+Requires-Dist: dbus-fast>=2.0; extra == "test"
+Dynamic: license-file
+
+# BlueRetro for Home Assistant
+
+Autodiscovers a [BlueRetro](https://github.com/darthcloud/BlueRetro) adapter over Bluetooth
+and exposes read-only sensors plus reboot/deep-sleep controls.
+
+## Limits
+
+- Works only while the adapter is **idle** (no controller connected). During gameplay the
+  config BLE is unavailable, so entities show `unavailable` — by design, to protect gameplay.
+- No battery or live controller input (the hardware does not expose them).
+
+## Install
+
+1. Add this repo as a HACS custom repository (category: Integration).
+2. Install **BlueRetro** and restart Home Assistant.
+3. Power the BlueRetro with no controller connected; Home Assistant discovers it automatically.
+
+## Entities
+
+- Sensors: Firmware, Game ID, Game, Config source, ABI version (diag), BD address (diag).
+- Binary sensor: Config available (connectivity).
+- Buttons: Reboot, Deep sleep.

blueretro_ble-0.1.0/blueretro_ble.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+blueretro_ble/__init__.py
+blueretro_ble/const.py
+blueretro_ble/device.py
+blueretro_ble/discovery.py
+blueretro_ble/gameid.db
+blueretro_ble/gameid.py
+blueretro_ble/models.py
+blueretro_ble/parser.py
+blueretro_ble.egg-info/PKG-INFO
+blueretro_ble.egg-info/SOURCES.txt
+blueretro_ble.egg-info/dependency_links.txt
+blueretro_ble.egg-info/requires.txt
+blueretro_ble.egg-info/top_level.txt

blueretro_ble-0.1.0/blueretro_ble.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

blueretro_ble-0.1.0/blueretro_ble.egg-info/requires.txt

@@ -0,0 +1,9 @@
+bleak>=0.22.0
+bleak-retry-connector>=3.5.0
+
+[test]
+pytest>=8.0
+pytest-asyncio>=0.23
+pytest-homeassistant-custom-component>=0.13
+pyserial>=3.5
+dbus-fast>=2.0

blueretro_ble-0.1.0/blueretro_ble.egg-info/top_level.txt

@@ -0,0 +1 @@
+blueretro_ble

blueretro_ble-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "blueretro-ble"
+version = "0.1.0"
+description = "BLE library for the BlueRetro retro-console Bluetooth adapter"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+authors = [{ name = "Hudson Brendon", email = "contato.hudsonbrendon@gmail.com" }]
+keywords = ["bluetooth", "ble", "blueretro", "home-assistant", "retro-gaming"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Home Automation",
+]
+dependencies = [
+    "bleak>=0.22.0",
+    "bleak-retry-connector>=3.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/hudsonbrendon/blueretro-homeassistant"
+Repository = "https://github.com/hudsonbrendon/blueretro-homeassistant"
+Issues = "https://github.com/hudsonbrendon/blueretro-homeassistant/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-homeassistant-custom-component>=0.13",
+    # Pulled in transitively by Home Assistant's bluetooth stack on Linux, but
+    # required explicitly to run the HA bluetooth integration under tests on macOS.
+    "pyserial>=3.5",
+    "dbus-fast>=2.0",
+]
+
+[tool.setuptools]
+packages = ["blueretro_ble"]
+
+[tool.setuptools.package-data]
+blueretro_ble = ["gameid.db"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

blueretro_ble-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+