Other Commands

def set_fun_mode(enable : bool = False):
    """
    Enable or disable fun mode.

    Args:
        enable: Boolean or equivalent, enables (True) or disables (False) fun mode.
    """

    # Convert bool
    if isinstance(enable, str):
        enable = enable.lower() in ("true", "1", "yes", "on")

    # Build payload using bytes
    payload = bytes([
        5,                        # Command length
        0,                        # Reserved
        4,                        # Command ID
        1,                        # Command type ID
        1 if bool(enable) else 0  # Fun mode value
    ])

    return single_window_plan("set_fun_mode", payload)

def set_pixel(x: int, y: int, color: str, device_info: Optional[DeviceInfo] = None):
    """
    Defines the color of a specific pixel.

    Args:
        x: X coordinate of the pixel (0-...).
        y: Y coordinate of the pixel (0-...).
        color: Color in hexadecimal format (e.g., 'FF0000' for red).
    """

    # Validate coordinates range if device info is provided
    if device_info and not (0 <= int(x) <= device_info.width - 1 and 0 <= int(y) <= device_info.height - 1):
            raise ValueError(f"Invalid coordinates range. Range are x[0:{device_info.width-1}] y[0:{device_info.height-1}]")

    # Validate color format
    if (not (isinstance(color, str)) 
        and len(color) == 6 
        and all(c in '0123456789abcdefABCDEF' for c in color)):
            raise ValueError("Color must be a 6-character hexadecimal string.")

    # Build payload using bytes
    payload = bytes([
        10,                       # Command length
        0,                        # Reserved
        5,                        # Command ID
        1,                        # Command type ID
        0,                        # Reserved
        int(color[0:2], 16),      # Red
        int(color[2:4], 16),      # Green
        int(color[4:6], 16),      # Blue
        int(x),                   # X coordinate
        int(y)                    # Y coordinate
    ])

    return single_window_plan("set_pixel", payload, requires_ack=False)

def set_rhythm_mode(style=0, l1 : int = 0, l2 : int = 0, l3 : int = 0, l4 : int = 0, l5 : int = 0, l6 : int = 0, l7 : int = 0, l8 : int = 0, l9 : int = 0, l10 : int = 0, l11 : int = 0):
    """Set the rhythm mode of the device.

    Args:
        style (int): The style of the rhythm mode (0-4).
        l1 (int): Level 1 (0-15).
        l2 (int): Level 2 (0-15).
        l3 (int): Level 3 (0-15).
        l4 (int): Level 4 (0-15).
        l5 (int): Level 5 (0-15).
        l6 (int): Level 6 (0-15).
        l7 (int): Level 7 (0-15).
        l8 (int): Level 8 (0-15).
        l9 (int): Level 9 (0-15).
        l10 (int): Level 10 (0-15).
        l11 (int): Level 11 (0-15).

    Raises:
        ValueError: If ``style`` is not in 0..4 or any level is not in 0..15.
    """

    # Validation
    if not (0 <= int(style) <= 4):
        raise ValueError(f"rhythm mode style must be between 0 and 4, got {style}")

    levels = [int(v) for v in [l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11]]
    for idx, lv in enumerate(levels, start=1):
        if not (0 <= lv <= 15):
            raise ValueError(f"level {idx} must be between 0 and 15, got {lv}")

    # Build payload
    payload = bytes([
        16,     # Command length
        0,      # Reserved
        1,      # Command ID
        2,      # Command type ID
        int(style),
    ])
    payload += bytes(levels)

    return single_window_plan("set_rhythm_mode", payload, requires_ack=True)

def set_rhythm_mode_2(style: int = 0, t: int = 0):
    """Set the rhythm mode of the device (alternative version).

    Args:
        style (int): The style of the rhythm mode. Allowed values are 0 or 1.
        t (int): Animation time (0-7).

    Returns:
        bytes: Byte sequence for the command payload used to set the rhythm mode.

    Raises:
        ValueError: If ``style`` is not in 0..1 or ``t`` is not in 0..7.
    """

    # Validation
    if not (0 <= int(style) <= 1):
        raise ValueError(f"rhythm mode style must be between 0 and 1, got {style}")

    if not (0 <= int(t) <= 7):
        raise ValueError(f"Level (t) must be between 0 and 7, got {t}")

    # Build payload using bytes
    payload = bytes([
        6,              # Command length
        0,              # Reserved
        0,              # Command ID
        2,              # Command type ID
        int(t),         # Animation time
        int(style)      # Style
    ])

    return single_window_plan("set_rhythm_mode_2", payload)

def set_timer(action: Union[TimerAction, str, int]) -> SendPlan:
    """
    Set timer action (start, pause, stop).

    Args:
        action (Union[TimerAction, str, int]): TimerAction enum, string ('start', 'pause', 'stop'),
            or integer (0 = stop, 1 = start, 2 = pause).

    Returns:
        SendPlan: The single window send plan for this command.
    """
    timer_action = _parse_action(action)

    payload = bytes([
        5,                  # Command length
        0,                  # Reserved
        9,                  # Command ID
        0x80,               # Command type ID
        timer_action.value  # Value: 0 = stop, 1 = start, 2 = pause
    ])
    return single_window_plan("set_timer", payload)

def set_scores(score_p1: Union[int, str] = 0, score_p2: Union[int, str] = 0) -> SendPlan:
    """
    Set scoreboard scores for player 1 and player 2.

    Args:
        score_p1 (Union[int, str]): Score for player 1 (0-99). Defaults to 0.
        score_p2 (Union[int, str]): Score for player 2 (0-99). Defaults to 0.

    Returns:
        SendPlan: The single window send plan for this command.
    """
    p1 = _parse_score(score_p1, "score_p1")
    p2 = _parse_score(score_p2, "score_p2")

    payload = bytes([
        8,      # Command length
        0,      # Reserved
        0x0A,   # Command ID
        0x80,   # Command type ID
        p1,     # Player 1 score
        0,      # Padding
        p2,     # Player 2 score
        0       # Padding
    ])
    return single_window_plan("set_scores", payload)