blueretro-ble 0.4.0

BLE library for the BlueRetro retro-console Bluetooth adapter

blueretro-ble

Pure-Python BLE library for the BlueRetro retro-console Bluetooth adapter. Talks to the BlueRetro GATT server via bleak + bleak-retry-connector (connect → read/write → disconnect).

Powers the BlueRetro Home Assistant integration.

Install

pip install blueretro-ble

Usage

from blueretro_ble import BlueRetroDevice, supports

# `supports(advertisement)` is a discovery predicate: True if a BLE
# advertisement (anything exposing `.name` and `.service_uuids`) looks
# like a BlueRetro adapter.

device = BlueRetroDevice()
state = await device.async_update(ble_device)  # a bleak BLEDevice
print(state.fw_version, state.game_id, state.game_name)

await device.async_reboot(ble_device)
await device.async_deep_sleep(ble_device)

async_update connects, reads ABI/firmware/BD-address directly, runs the command-then-read cycles (game id, config source, firmware name), reads the global config (system/multitap/inquiry/card bank), resolves the game name from the bundled gameid.db, always disconnects, and never raises — on failure it returns a BlueRetroState(available=False).

CLI

Installing the package provides a blueretro command (also python -m blueretro_ble):

blueretro scan                       # list nearby adapters
blueretro info AA:BB:CC:DD:EE:FF     # connect and print the full state
blueretro reboot AA:BB:CC:DD:EE:FF
blueretro sleep AA:BB:CC:DD:EE:FF

Notes

• The adapter only accepts connections while idle (no controller connected). During gameplay, connections fail and async_update returns an unavailable state.
• gameid.db is a SQLite database (games(id TEXT, name TEXT)) bundled with the package, sourced from darthcloud/BlueRetroWebCfg.
• The BLE protocol is reverse-engineered from the official web config; verify cfg_src (0x05) against real hardware.

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[test]"
pytest

License

MIT