Skip to content

Async Client

pypixelcolor.client.AsyncClient

Asynchronous client for controlling the LED matrix via BLE.

Source code in src/pypixelcolor/client.py 
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
class AsyncClient:
    """Asynchronous client for controlling the LED matrix via BLE."""

    @staticmethod
    async def scan(timeout: float = 5.0):
        """Scan for compatible LED devices asynchronously."""
        return await scan_devices(timeout=timeout)

    def __init__(self, address: str):
        """Initialize the AsyncClient.

        Args:
            address: Bluetooth device address (e.g., "1D:6B:5E:B5:A5:54")
        """
        self._session = DeviceSession(address)
        self._connected = False

    async def connect(self) -> None:
        """Connect to the BLE device and retrieve device info."""
        if self._connected:
            logger.warning("Already connected")
            return

        await self._session.connect()
        self._connected = True

    async def disconnect(self) -> None:
        """Disconnect from the BLE device."""
        if not self._connected:
            logger.warning("Not connected")
            return

        await self._session.disconnect()
        self._connected = False

    def version(self) -> str:
        """Get the client library version."""
        return VERSION

    def get_device_info(self) -> DeviceInfo:
        """
        Get cached device information.

        Device info is automatically retrieved during connect().
        This is a simple getter for the cached data.

        Returns:
            DeviceInfo object with device specifications.

        Raises:
            RuntimeError: If not connected.
        """
        return self._session.get_device_info()

    async def _ensure_connected(self) -> None:
        """Ensure the client is connected."""
        if not self._connected:
            raise RuntimeError("Client not connected. Call connect() first")

    async def __aenter__(self):
        """Async context manager entry."""
        await self.connect()
        return self

    async def __aexit__(self, exc_type, exc_val, exc_tb):
        """Async context manager exit."""
        await self.disconnect()

__aenter__() async

Async context manager entry.

Source code in src/pypixelcolor/client.py 
111
112
113
114
async def __aenter__(self):
    """Async context manager entry."""
    await self.connect()
    return self

__aexit__(exc_type, exc_val, exc_tb) async

Async context manager exit.

Source code in src/pypixelcolor/client.py 
116
117
118
async def __aexit__(self, exc_type, exc_val, exc_tb):
    """Async context manager exit."""
    await self.disconnect()

__init__(address)

Initialize the AsyncClient.

Parameters:

Name Type Description Default
address str

Bluetooth device address (e.g., "1D:6B:5E:B5:A5:54")

 required
Source code in src/pypixelcolor/client.py 
60
61
62
63
64
65
66
67
def __init__(self, address: str):
    """Initialize the AsyncClient.

    Args:
        address: Bluetooth device address (e.g., "1D:6B:5E:B5:A5:54")
    """
    self._session = DeviceSession(address)
    self._connected = False

clear() async

Clears the ROM data on the device.

Source code in src/pypixelcolor/client.py 
36
37
38
if result.data is None:
    logger.info(f"Command '{command_name}' executed successfully")
else:

connect() async

Connect to the BLE device and retrieve device info.

Source code in src/pypixelcolor/client.py 
69
70
71
72
73
74
75
76
async def connect(self) -> None:
    """Connect to the BLE device and retrieve device info."""
    if self._connected:
        logger.warning("Already connected")
        return

    await self._session.connect()
    self._connected = True

delete(n) async

Delete a specific slot by its index.

Source code in src/pypixelcolor/client.py 
39
40
41
    logger.debug(f"Command '{command_name}' executed successfully with data")

# Return the data directly (not the CommandResult wrapper)

disconnect() async

Disconnect from the BLE device.

Source code in src/pypixelcolor/client.py 
78
79
80
81
82
83
84
85
async def disconnect(self) -> None:
    """Disconnect from the BLE device."""
    if not self._connected:
        logger.warning("Not connected")
        return

    await self._session.disconnect()
    self._connected = False

get_device_info()

Get cached device information.

Device info is automatically retrieved during connect(). This is a simple getter for the cached data.

Returns:

Type Description
DeviceInfo

DeviceInfo object with device specifications.

Raises:

Type Description
RuntimeError

If not connected.
Source code in src/pypixelcolor/client.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def get_device_info(self) -> DeviceInfo:
    """
    Get cached device information.

    Device info is automatically retrieved during connect().
    This is a simple getter for the cached data.

    Returns:
        DeviceInfo object with device specifications.

    Raises:
        RuntimeError: If not connected.
    """
    return self._session.get_device_info()

scan(timeout=5.0) async staticmethod

Scan for compatible LED devices asynchronously.

Source code in src/pypixelcolor/client.py 
55
56
57
58
@staticmethod
async def scan(timeout: float = 5.0):
    """Scan for compatible LED devices asynchronously."""
    return await scan_devices(timeout=timeout)

send_image(path, resize_method=ResizeMethod.CROP, device_info=None, save_slot=0) async

Send an image or animation.

Source code in src/pypixelcolor/client.py 
42
43
# This makes the API cleaner: client.get_device_info() returns DeviceInfo, not CommandResult
return result.data

send_image_hex(hex_string, file_extension, resize_method=ResizeMethod.CROP, device_info=None, save_slot=0) async

Send an image or animation from a hexadecimal string.

Source code in src/pypixelcolor/client.py 
45
46
47
# Preserve the original function's metadata for better introspection
method.__name__ = command_name
method.__doc__ = command_func.__doc__

send_text(text, rainbow_mode=0, animation=0, save_slot=0, speed=80, color='ffffff', bg_color=None, font='UNIFONT', char_height=None, device_info=None) async

Send a text to the device with configurable parameters.

Source code in src/pypixelcolor/client.py 
48
return method

set_brightness(level) async

Set the brightness of the device.

Source code in src/pypixelcolor/client.py 
51
52
class AsyncClient:
    """Asynchronous client for controlling the LED matrix via BLE."""

set_clock_mode(style=1, date='', show_date=True, format_24=True) async

Set the clock mode of the device.

Source code in src/pypixelcolor/client.py 
54
55
@staticmethod
async def scan(timeout: float = 5.0):

set_fun_mode(enable=False) async

Enable or disable fun mode.

Source code in src/pypixelcolor/client.py 
57
58
"""Scan for compatible LED devices asynchronously."""
return await scan_devices(timeout=timeout)

set_orientation(orientation=0) async

Set the orientation of the device.

Source code in src/pypixelcolor/client.py 
60
61
def __init__(self, address: str):
    """Initialize the AsyncClient.

set_pixel(x, y, color, device_info=None) async

Defines the color of a specific pixel.

Source code in src/pypixelcolor/client.py 
63
64
65
Args:
    address: Bluetooth device address (e.g., "1D:6B:5E:B5:A5:54")
"""

set_power(on=True) async

Set the power state of the device.

Source code in src/pypixelcolor/client.py 
66
67
self._session = DeviceSession(address)
self._connected = False

set_rhythm_mode(style=0, l1=0, l2=0, l3=0, l4=0, l5=0, l6=0, l7=0, l8=0, l9=0, l10=0, l11=0) async

Set the rhythm mode of the device.

Source code in src/pypixelcolor/client.py 
69
70
71
async def connect(self) -> None:
    """Connect to the BLE device and retrieve device info."""
    if self._connected:

set_rhythm_mode_2(style=0, t=0) async

Set the rhythm mode of the device (alternative version).

Source code in src/pypixelcolor/client.py 
72
73
logger.warning("Already connected")
return

set_schedule(hour, minute, on, days=None, slot=0) async

Set an automated on/off schedule by time and day of week.

Source code in src/pypixelcolor/client.py 
75
76
await self._session.connect()
self._connected = True

set_scores(score_p1=0, score_p2=0) async

Set scoreboard scores for player 1 and player 2.

Source code in src/pypixelcolor/client.py 
78
79
80
async def disconnect(self) -> None:
    """Disconnect from the BLE device."""
    if not self._connected:

set_time(hour=None, minute=None, second=None) async

Set the device time.

Source code in src/pypixelcolor/client.py 
81
82
logger.warning("Not connected")
return

set_timer(action) async

Set timer action (start, pause, stop).

Source code in src/pypixelcolor/client.py 
84
85
await self._session.disconnect()
self._connected = False

show_slot(number) async

Shows the specified slot on the device.

Source code in src/pypixelcolor/client.py 
87
88
89
def version(self) -> str:
    """Get the client library version."""
    return VERSION

version()

Get the client library version.

Source code in src/pypixelcolor/client.py 
87
88
89
def version(self) -> str:
    """Get the client library version."""
    return VERSION