Enums and Constants

This section documents the enumerations and constants used in the Makcu library, aligned with the current API as shown in the main documentation.

MouseButton

The MouseButton enum defines the available mouse buttons that can be controlled by Makcu devices.

class MouseButton

An enumeration of mouse buttons supported by Makcu devices.

LEFT: MouseButton = 0

Left mouse button (primary button for most users)

RIGHT: MouseButton = 1

Right mouse button (secondary button, typically context menu)

MIDDLE: MouseButton = 2

Middle mouse button (typically scroll wheel click)

MOUSE4: MouseButton = 3

Side button 1 (typically “back” button on gaming mice)

MOUSE5: MouseButton = 4

Side button 2 (typically “forward” button on gaming mice)

Usage Examples:

from makcu import MouseButton

# Synchronous API
makcu.click(MouseButton.LEFT)
makcu.click(MouseButton.RIGHT)
makcu.click(MouseButton.MIDDLE)

# Gaming mouse side buttons
makcu.click(MouseButton.MOUSE4)
makcu.click(MouseButton.MOUSE5)

# Asynchronous API
await makcu.click(MouseButton.LEFT)
await makcu.click(MouseButton.RIGHT)

# Get button properties
button = MouseButton.LEFT
print(button.name)   # "LEFT"
print(button.value)  # 0

Button Values:

MouseButton Values and Usage

Button	Value	Typical Use
LEFT	0	Primary clicking, selection, dragging
RIGHT	1	Context menus, secondary actions
MIDDLE	2	Scroll wheel click, special functions
MOUSE4	3	Back/previous navigation, gaming macros
MOUSE5	4	Forward/next navigation, gaming macros

Human-Like Profiles

The library supports string-based timing profiles for human-like mouse interactions, used with the click_human_like() method.

Available Profiles:

GAMING_PROFILE: str = "gaming"

Ultra-fast profile optimized for competitive gaming (1-5ms delays)

FAST_PROFILE: str = "fast"

Fast clicking profile (10-30ms delays)

NORMAL_PROFILE: str = "normal"

Natural human-like timing (50-150ms delays, default)

SLOW_PROFILE: str = "slow"

Slow, deliberate timing (200-500ms delays)

VARIABLE_PROFILE: str = "variable"

Highly variable timing to avoid detection (50-300ms delays)

Usage Examples:

# Synchronous API
makcu.click_human_like(MouseButton.LEFT, count=3, profile="gaming")
makcu.click_human_like(MouseButton.RIGHT, count=5, profile="normal", jitter=5)

# Asynchronous API
await makcu.click_human_like(MouseButton.LEFT, count=2, profile="gaming", jitter=3)
await makcu.click_human_like(MouseButton.RIGHT, count=3, profile="variable")

Profile Characteristics:

Human-Like Profile Timing

Profile	Min Delay	Max Delay	Best For
"gaming"	1ms	5ms	Competitive gaming, maximum speed
"fast"	10ms	30ms	Productivity automation, quick tasks
"normal"	50ms	150ms	General automation, natural feel
"slow"	200ms	500ms	Careful automation, older systems
"variable"	50ms	300ms	Anti-detection, randomized patterns

Lock Targets

The locking system accepts string identifiers for buttons and axes that can be locked to prevent input.

Button Lock Targets:

LOCK_LEFT: str = "LEFT"

Lock left mouse button

LOCK_RIGHT: str = "RIGHT"

Lock right mouse button

LOCK_MIDDLE: str = "MIDDLE"

Lock middle mouse button

Axis Lock Targets:

LOCK_X_AXIS: str = "X"

Lock X-axis movement (horizontal)

LOCK_Y_AXIS: str = "Y"

Lock Y-axis movement (vertical)

Usage Examples:

# Lock buttons (synchronous)
makcu.lock(MouseButton.LEFT)    # Using enum
makcu.lock("RIGHT")             # Using string
makcu.lock("MIDDLE")

# Lock movement axes
makcu.lock("X")    # Lock horizontal movement
makcu.lock("Y")    # Lock vertical movement

# Asynchronous API
await makcu.lock(MouseButton.LEFT)
await makcu.lock("X")
await makcu.unlock("Y")

# Check lock status
is_locked = makcu.is_locked(MouseButton.LEFT)
all_locks = makcu.get_all_lock_states()
# Returns: {"LEFT": True, "RIGHT": False, "X": True, "Y": False, ...}

Constants and Default Values

Serial Communication

DEFAULT_BAUDRATE: int = 4000000

Default serial communication speed (4 Mbps)

DEFAULT_TIMEOUT: float = 0.1

Default timeout for device operations (100ms, optimized for gaming)

VID_PID: tuple = (0x1a86, 0x55d3)

USB Vendor ID and Product ID for auto-detection (CH343 chipset)

Usage Examples:

# Custom timeout (synchronous)
makcu = create_controller(timeout=0.05)  # 50ms timeout

# Custom timeout (asynchronous)
makcu = await create_async_controller(timeout=0.05)

Device Limits

MAX_MOVE_DISTANCE: int = 32767

Maximum single movement distance in pixels

MIN_MOVE_DISTANCE: int = -32768

Minimum single movement distance in pixels

MAX_SCROLL_STEPS: int = 127

Maximum scroll steps in single operation

Usage Examples:

# Large movements are automatically clamped
makcu.move(50000, 25000)  # Clamped to MAX_MOVE_DISTANCE

# Asynchronous version
await makcu.move(50000, 25000)

# Maximum scroll
makcu.scroll(MAX_SCROLL_STEPS)
await makcu.scroll(-MAX_SCROLL_STEPS)  # Scroll down maximum

Performance Constants

GAMING_REFRESH_RATES: dict = {"60Hz": 16.7, "144Hz": 7.0, "240Hz": 4.2, "360Hz": 2.8}

Common gaming refresh rates and their frame times in milliseconds

PERFORMANCE_TARGETS: dict = {"excellent": 1, "good": 3, "acceptable": 5}

Performance targets in milliseconds per operation (v2.0 benchmarks)

Usage Examples:

# Performance-aware gaming code
import time

# Benchmark operation timing
start = time.perf_counter()
makcu.click(MouseButton.LEFT)
operation_time = (time.perf_counter() - start) * 1000  # Convert to ms

if operation_time < PERFORMANCE_TARGETS["excellent"]:
    print(f"Excellent performance: {operation_time:.2f}ms (suitable for 360Hz gaming)")
elif operation_time < GAMING_REFRESH_RATES["144Hz"]:
    print(f"Good for 144Hz gaming: {operation_time:.2f}ms")

Error Handling Constants

The library defines specific error types for different failure conditions.

ERROR_TYPES: tuple = (MakcuError, MakcuConnectionError, MakcuTimeoutError)

Main exception types used by the library

Usage Examples:

from makcu import MakcuError, MakcuConnectionError, MakcuTimeoutError

# Synchronous error handling
try:
    makcu = create_controller()
    makcu.click(MouseButton.LEFT)
except MakcuConnectionError as e:
    print(f"Connection failed: {e}")
except MakcuTimeoutError as e:
    print(f"Operation timed out: {e}")
except MakcuError as e:
    print(f"General error: {e}")

# Asynchronous error handling
try:
    makcu = await create_async_controller()
    await makcu.click(MouseButton.LEFT)
except MakcuConnectionError as e:
    print(f"Connection failed: {e}")

Version Information

LIBRARY_VERSION: str = "2.3.1"

Current library version

Usage Examples:

# Check library version
import makcu
print(f"Makcu library version: {makcu.__version__}")

# Version-specific feature usage
if makcu.__version__ >= "2.0":
    # Use new async features
    makcu = await create_async_controller()
else:
    # Fall back to sync only
    makcu = create_controller()

Type Hints and Validation

The library provides flexible input types while maintaining type safety.

Acceptable Button Types:

• MouseButton enum values (recommended)

• Integer values (0-4, mapped to buttons)

• String names (“LEFT”, “RIGHT”, etc., case-insensitive)

Acceptable Profile Types:

• String literals (“gaming”, “fast”, “normal”, “slow”, “variable”)

Acceptable Lock Target Types:

• MouseButton enum values for button locks

• String identifiers (“X”, “Y” for axes; “LEFT”, “RIGHT”, etc. for buttons)

Usage Examples:

# All of these work (flexible input types):

# Using enums (recommended for type safety)
makcu.click(MouseButton.LEFT)

# Using integers
makcu.click(0)  # Same as MouseButton.LEFT

# Using strings (case-insensitive)
makcu.click("left")
makcu.click("LEFT")
makcu.click("Left")

# Profile flexibility
makcu.click_human_like(MouseButton.LEFT, profile="gaming")
makcu.click_human_like(MouseButton.LEFT, profile="GAMING")

# Lock target flexibility
makcu.lock(MouseButton.LEFT)  # Enum
makcu.lock("LEFT")            # String
makcu.lock("x")               # Axis (case-insensitive)

Best Practices

1. Use MouseButton Enum for Type Safety:

   # Recommended: Clear and type-safe
   await makcu.click(MouseButton.LEFT)
   
   # Avoid: Magic numbers
   await makcu.click(0)
   

2. Consistent Profile Usage:

   # Consistent profile strings
   GAMING_PROFILE = "gaming"
   await makcu.click_human_like(MouseButton.LEFT, profile=GAMING_PROFILE)
   

3. Error Handling:

   # Always handle connection errors
   try:
       async with await create_async_controller() as makcu:
           await makcu.click(MouseButton.LEFT)
   except MakcuConnectionError:
       print("Could not connect to Makcu device")
   

4. Performance-Aware Code:

   # Check performance for gaming applications
   if operation_time < GAMING_REFRESH_RATES["240Hz"]:
       print("Suitable for 240Hz gaming!")
   

5. Use Context Managers:

   # Automatic connection management
   async with await create_async_controller() as makcu:
       await makcu.click(MouseButton.LEFT)
   # Automatically disconnects
   

Integration with Main API

These enums and constants integrate seamlessly with both synchronous and asynchronous APIs:

from makcu import create_controller, create_async_controller, MouseButton
import asyncio

# Synchronous usage
def sync_example():
    with create_controller() as makcu:
        makcu.click(MouseButton.LEFT)
        makcu.move(100, 50)
        makcu.click_human_like(MouseButton.RIGHT, count=3, profile="gaming")

# Asynchronous usage
async def async_example():
    async with await create_async_controller() as makcu:
        await makcu.click(MouseButton.LEFT)
        await makcu.move(100, 50)
        await makcu.click_human_like(MouseButton.RIGHT, count=3, profile="gaming")

# Run async version
asyncio.run(async_example())

See Also

• MakcuController API Reference - Main synchronous controller API

• async_controller - Asynchronous controller API

• Getting Started with Makcu Python Library - Basic usage tutorial

• Examples - More code examples with enums

• Async Usage - Async/await patterns