makcu 2.2.0__tar.gz → 2.2.2__tar.gz

{makcu-2.2.0 → makcu-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: makcu
-Version: 2.2.0
+Version: 2.2.2
 Summary: Python library for Makcu hardware device control
 Author: SleepyTotem
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -708,7 +708,7 @@ Requires-Dist: twine>=4.0
 Requires-Dist: rich>=14.0
 Dynamic: license-file
 
-# 🖱️ Makcu Python Library v2.2.0
+# 🖱️ Makcu Python Library v2.2.2
 
 [![PyPI Version](https://img.shields.io/pypi/v/makcu.svg)](https://pypi.org/project/makcu/)
 [![Python Support](https://img.shields.io/pypi/pyversions/makcu.svg)](https://pypi.org/project/makcu/)
@@ -1112,4 +1112,5 @@ GPL License © SleepyTotem
 
 - [GitHub Repository](https://github.com/SleepyTotem/makcu-py-lib)
 - [PyPI Package](https://pypi.org/project/makcu/)
-- [Documentation](https://makcu.readthedocs.io/) *(coming soon)*
+- [Documentation](https://makcu-py-lib.readthedocs.io/)
+- [Changelog](https://makcu-py-lib.readthedocs.io/en/latest/changelog.html)

{makcu-2.2.0 → makcu-2.2.2}/makcu/README.md

@@ -1,405 +1,406 @@
-# 🖱️ Makcu Python Library v2.2.0
-
-[![PyPI Version](https://img.shields.io/pypi/v/makcu.svg)](https://pypi.org/project/makcu/)
-[![Python Support](https://img.shields.io/pypi/pyversions/makcu.svg)](https://pypi.org/project/makcu/)
-[![License](https://img.shields.io/badge/license-GPL-blue.svg)](LICENSE)
-
-Makcu Py Lib is a high-performance Python library for controlling Makcu devices — now with **async/await support**, **zero-delay command execution**, and **automatic reconnection**!
-
----
-
-## 📦 Installation
-
-### Recommended: PyPI
-
-```bash
-pip install makcu
-```
-
-### From Source
-
-```bash
-git clone https://github.com/SleepyTotem/makcu-py-lib
-cd makcu-py-lib
-pip install .
-```
-
----
-
-## 🧠 Quick Start
-
-### Synchronous API (Classic)
-
-```python
-from makcu import create_controller, MouseButton
-
-# Create and connect
-makcu = create_controller(debug=True, auto_reconnect=True)
-
-# Basic operations
-makcu.click(MouseButton.LEFT)
-makcu.move(100, 50)
-makcu.scroll(-1)
-
-# Human-like interaction
-makcu.click_human_like(MouseButton.LEFT, count=2, profile="gaming", jitter=3)
-
-# Clean disconnect
-makcu.disconnect()
-```
-
-### Asynchronous API (New!)
-
-```python
-import asyncio
-from makcu import create_async_controller, MouseButton
-
-async def main():
-    # Auto-connect with context manager
-    async with await create_async_controller(debug=True) as makcu:
-        # Parallel operations
-        await asyncio.gather(
-            makcu.move(100, 0),
-            makcu.click(MouseButton.LEFT),
-            makcu.scroll(-1)
-        )
-        
-        # Human-like clicking
-        await makcu.click_human_like(MouseButton.RIGHT, count=3)
-
-asyncio.run(main())
-```
-
----
-
-## 🎮 Core Features
-
-### Mouse Control
-
-```python
-# Button actions
-await makcu.click(MouseButton.LEFT)
-await makcu.double_click(MouseButton.RIGHT)
-await makcu.press(MouseButton.MIDDLE)
-await makcu.release(MouseButton.MIDDLE)
-
-# Movement
-await makcu.move(100, 50)  # Relative movement
-await makcu.move_smooth(200, 100, segments=20)  # Smooth interpolation
-await makcu.move_bezier(150, 150, segments=30, ctrl_x=75, ctrl_y=200)  # Bezier curve
-
-# Scrolling
-await makcu.scroll(-5)  # Scroll down
-await makcu.scroll(3)   # Scroll up
-
-# Dragging
-await makcu.drag(0, 0, 300, 200, button=MouseButton.LEFT, duration=1.5)
-```
-
-### Button & Axis Locking
-
-```python
-# New unified locking API
-await makcu.lock(MouseButton.LEFT)    # Lock left button
-await makcu.unlock(MouseButton.RIGHT)  # Unlock right button
-await makcu.lock("X")                  # Lock X-axis movement
-await makcu.unlock("Y")                # Unlock Y-axis movement
-
-# Query lock states (no delays!)
-is_locked = await makcu.is_locked(MouseButton.LEFT)
-all_states = await makcu.get_all_lock_states()
-# Returns: {"LEFT": True, "RIGHT": False, "X": True, ...}
-```
-
-### Human-like Interactions
-
-```python
-# Realistic clicking with timing variations
-await makcu.click_human_like(
-    button=MouseButton.LEFT,
-    count=5,
-    profile="gaming",  # "fast", "normal", "slow", "variable", "gaming"
-    jitter=5  # Random mouse movement between clicks
-)
-```
-
-### Button Event Monitoring
-
-```python
-# Real-time button monitoring
-def on_button_event(button: MouseButton, pressed: bool):
-    print(f"{button.name} {'pressed' if pressed else 'released'}")
-
-makcu.set_button_callback(on_button_event)
-await makcu.enable_button_monitoring(True)
-
-# Check current button states
-states = makcu.get_button_states()
-if makcu.is_pressed(MouseButton.RIGHT):
-    print("Right button is pressed")
-```
-
-### Connection Management
-
-```python
-# Auto-reconnection on disconnect
-makcu = await create_async_controller(auto_reconnect=True)
-
-# Connection status callbacks
-@makcu.on_connection_change
-async def handle_connection(connected: bool):
-    if connected:
-        print("Device reconnected!")
-    else:
-        print("Device disconnected!")
-
-# Manual reconnection
-if not makcu.is_connected():
-    await makcu.connect()
-```
-
----
-
-## 🔧 Advanced Features
-
-### Batch Operations
-
-```python
-# Execute multiple commands efficiently
-async def combo_action():
-    await makcu.batch_execute([
-        lambda: makcu.move(50, 0),
-        lambda: makcu.click(MouseButton.LEFT),
-        lambda: makcu.move(-50, 0),
-        lambda: makcu.click(MouseButton.RIGHT)
-    ])
-```
-
-### Device Information
-
-```python
-# Get device details
-info = await makcu.get_device_info()
-# {'port': 'COM3', 'vid': '0x1a86', 'pid': '0x55d3', ...}
-
-# Firmware version
-version = await makcu.get_firmware_version()
-```
-
-### Serial Spoofing
-
-```python
-# Spoof device serial
-await makcu.spoof_serial("CUSTOM123456")
-
-# Reset to default
-await makcu.reset_serial()
-```
-
-### Low-Level Access
-
-```python
-# Send raw commands with tracked responses
-response = await makcu.transport.async_send_command(
-    "km.version()", 
-    expect_response=True,
-    timeout=0.1  # Optimized for gaming
-)
-```
-
----
-
-## 🧪 Command-Line Tools
-
-```bash
-# Interactive debug console
-python -m makcu --debug
-
-# Test specific port
-python -m makcu --testPort COM3
-
-# Run automated tests
-python -m makcu --runtest
-```
-
-### Tool Descriptions
-
-- `--debug`: Launches an interactive console where you can type raw device commands and see live responses.
-- `--testPort COMx`: Attempts to connect to the given COM port and reports success or failure.
-- `--runtest`: Runs `test_suite.py` using `pytest` and opens a detailed HTML test report.
-
----
-
-### Test Suite
-
-- File: `test_suite.py`
-- Run with: `python -m makcu --runtest`
-- Output: `latest_pytest.html`
-
-Includes tests for:
-- Port connection
-- Firmware version check
-- Mouse movement and button control
-- Button masking and locking
-
----
-
-## Test Timings (v1.3 vs v1.4 vs v2.0)
-
-| Test Name                | v1.3   | v1.4  | v2.0  | Improvement (v1.3 → v2.0) |
-|--------------------------|--------|-------|-------|----------------------------|
-| connect_to_port          | ~100ms | ~55ms | **46ms** | ~2.2x faster              |
-| press_and_release        | ~18ms  | ~9ms  | **1ms**  | ~18x faster               |
-| firmware_version         | ~20ms  | ~9ms  | **1ms**  | ~20x faster               |
-| middle_click             | ~18ms  | ~9ms  | **1ms**  | ~18x faster               |
-| device_info              | ~25ms  | ~13ms | **6ms**  | ~4.1x faster              |
-| port_connection          | ~20ms  | ~9ms  | **1ms**  | ~20x faster               |
-| button_mask              | ~17ms  | ~8ms  | **1ms**  | ~17x faster               |
-| get_button_states        | ~18ms  | ~9ms  | **1ms**  | ~18x faster               |
-| lock_state               | ~33ms  | ~10ms | **1ms**  | ~33x faster               |
-| makcu_behavior           | ~20ms  | ~10ms | **1ms**  | ~20x faster               |
-| batch_commands           | ~350ms | ~90ms | **3ms**  | ~117x faster              |
-| rapid_moves              | ~17ms  | ~8ms  | **2ms**  | ~8.5x faster              |
-| button_performance       | ~18ms  | ~9ms  | **2ms**  | ~9x faster                |
-| mixed_operations         | ~22ms  | ~10ms | **2ms**  | ~11x faster               |
-
-Based on the measured test suite, v2.0 is on average **~17× faster** than v1.3 across all core operations.
-
-
-### Gaming Performance Targets (v2.0)
-
-- **144Hz Gaming**: 7ms frame time — ✅ Easily met (avg 1–3ms per operation)
-- **240Hz Gaming**: 4.2ms frame time — ✅ Consistently met (most ops ≤ 2ms)
-- **360Hz Gaming**: 2.8ms frame time — ⚡ Achievable for atomic/single ops
-
----
-
-## 🏎️ Performance Optimization Details
-
-### Version History & Performance
-
-- **v1.3 and earlier**: Original implementation with sleep delays
-- **v1.4**: Initial optimizations, removed some sleep delays
-- **v2.0**: Complete rewrite with zero-delay architecture
-
-### Key Optimizations in v2.0
-
-1. **Pre-computed Commands**: All commands are pre-formatted at initialization
-2. **Bitwise Operations**: Button states use single integer with bit manipulation
-3. **Zero-Copy Buffers**: Pre-allocated buffers for parsing
-4. **Reduced Timeouts**: Gaming-optimized timeouts (100ms default)
-5. **Cache Everything**: Connection states, lock states, and device info cached
-6. **Minimal Allocations**: Reuse objects and avoid string formatting
-7. **Fast Serial Settings**: 1ms read timeout, 10ms write timeout
-8. **Optimized Listener**: Batch processing with minimal overhead
-
-### Tips for Maximum Performance
-
-```python
-# Disable debug mode in production
-makcu = create_controller(debug=False)
-
-# Use cached connection checks
-if makcu.is_connected():  # Cached, no serial check
-    makcu.click(MouseButton.LEFT)
-
-# Batch similar operations
-with makcu:  # Context manager ensures connection
-    for _ in range(10):
-        makcu.move(10, 0)  # No connection check per call
-```
-
----
-
-## 🔍 Debugging
-
-Enable debug mode for detailed logging:
-
-```python
-makcu = await create_async_controller(debug=True)
-
-# View command flow (optimized timestamps)
-# [123.456] [INFO] Sent command #42: km.move(100,50)
-# [123.458] [DEBUG] Command #42 completed in 0.002s
-```
-
----
-
-## 🏗️ Migration from v1.x
-
-Most code works without changes! Key differences:
-
-```python
-# v1.x (still works)
-makcu = create_controller()
-makcu.move(100, 100)
-
-# v2.0 (async)
-makcu = await create_async_controller()
-await makcu.move(100, 100)
-
-# v2.0 context manager (auto cleanup)
-async with await create_async_controller() as makcu:
-    await makcu.click(MouseButton.LEFT)
-```
-
----
-
-## 📚 API Reference
-
-### Enumerations
-
-```python
-from makcu import MouseButton
-
-MouseButton.LEFT    # Left mouse button
-MouseButton.RIGHT   # Right mouse button  
-MouseButton.MIDDLE  # Middle mouse button
-MouseButton.MOUSE4  # Side button 1
-MouseButton.MOUSE5  # Side button 2
-```
-
-### Exception Handling
-
-```python
-from makcu import MakcuError, MakcuConnectionError, MakcuTimeoutError
-
-try:
-    makcu = await create_async_controller()
-except MakcuConnectionError as e:
-    print(f"Connection failed: {e}")
-except MakcuTimeoutError as e:
-    print(f"Command timed out: {e}")
-```
-
----
-
-## 🛠️ Technical Details
-
-- **Protocol**: CH343 USB serial at 4Mbps
-- **Command Format**: ASCII with optional ID tracking (`command#ID`)
-- **Response Format**: `>>> #ID:response` for tracked commands
-- **Threading**: High-priority listener thread with async bridge
-- **Auto-Discovery**: VID:PID=1A86:55D3 detection
-- **Buffer Size**: 4KB read buffer, 256B line buffer
-- **Cleanup Interval**: 50ms for timed-out commands
-
----
-
-## 📜 License
-
-GPL License © SleepyTotem
-
----
-
-## 🙋 Support
-
-- **Issues**: [GitHub Issues](https://github.com/SleepyTotem/makcu-py-lib/issues)
-
----
-
-## 🌐 Links
-
-- [GitHub Repository](https://github.com/SleepyTotem/makcu-py-lib)
-- [PyPI Package](https://pypi.org/project/makcu/)
-- [Documentation](https://makcu.readthedocs.io/) *(coming soon)*
+# 🖱️ Makcu Python Library v2.2.2
+
+[![PyPI Version](https://img.shields.io/pypi/v/makcu.svg)](https://pypi.org/project/makcu/)
+[![Python Support](https://img.shields.io/pypi/pyversions/makcu.svg)](https://pypi.org/project/makcu/)
+[![License](https://img.shields.io/badge/license-GPL-blue.svg)](LICENSE)
+
+Makcu Py Lib is a high-performance Python library for controlling Makcu devices — now with **async/await support**, **zero-delay command execution**, and **automatic reconnection**!
+
+---
+
+## 📦 Installation
+
+### Recommended: PyPI
+
+```bash
+pip install makcu
+```
+
+### From Source
+
+```bash
+git clone https://github.com/SleepyTotem/makcu-py-lib
+cd makcu-py-lib
+pip install .
+```
+
+---
+
+## 🧠 Quick Start
+
+### Synchronous API (Classic)
+
+```python
+from makcu import create_controller, MouseButton
+
+# Create and connect
+makcu = create_controller(debug=True, auto_reconnect=True)
+
+# Basic operations
+makcu.click(MouseButton.LEFT)
+makcu.move(100, 50)
+makcu.scroll(-1)
+
+# Human-like interaction
+makcu.click_human_like(MouseButton.LEFT, count=2, profile="gaming", jitter=3)
+
+# Clean disconnect
+makcu.disconnect()
+```
+
+### Asynchronous API (New!)
+
+```python
+import asyncio
+from makcu import create_async_controller, MouseButton
+
+async def main():
+    # Auto-connect with context manager
+    async with await create_async_controller(debug=True) as makcu:
+        # Parallel operations
+        await asyncio.gather(
+            makcu.move(100, 0),
+            makcu.click(MouseButton.LEFT),
+            makcu.scroll(-1)
+        )
+        
+        # Human-like clicking
+        await makcu.click_human_like(MouseButton.RIGHT, count=3)
+
+asyncio.run(main())
+```
+
+---
+
+## 🎮 Core Features
+
+### Mouse Control
+
+```python
+# Button actions
+await makcu.click(MouseButton.LEFT)
+await makcu.double_click(MouseButton.RIGHT)
+await makcu.press(MouseButton.MIDDLE)
+await makcu.release(MouseButton.MIDDLE)
+
+# Movement
+await makcu.move(100, 50)  # Relative movement
+await makcu.move_smooth(200, 100, segments=20)  # Smooth interpolation
+await makcu.move_bezier(150, 150, segments=30, ctrl_x=75, ctrl_y=200)  # Bezier curve
+
+# Scrolling
+await makcu.scroll(-5)  # Scroll down
+await makcu.scroll(3)   # Scroll up
+
+# Dragging
+await makcu.drag(0, 0, 300, 200, button=MouseButton.LEFT, duration=1.5)
+```
+
+### Button & Axis Locking
+
+```python
+# New unified locking API
+await makcu.lock(MouseButton.LEFT)    # Lock left button
+await makcu.unlock(MouseButton.RIGHT)  # Unlock right button
+await makcu.lock("X")                  # Lock X-axis movement
+await makcu.unlock("Y")                # Unlock Y-axis movement
+
+# Query lock states (no delays!)
+is_locked = await makcu.is_locked(MouseButton.LEFT)
+all_states = await makcu.get_all_lock_states()
+# Returns: {"LEFT": True, "RIGHT": False, "X": True, ...}
+```
+
+### Human-like Interactions
+
+```python
+# Realistic clicking with timing variations
+await makcu.click_human_like(
+    button=MouseButton.LEFT,
+    count=5,
+    profile="gaming",  # "fast", "normal", "slow", "variable", "gaming"
+    jitter=5  # Random mouse movement between clicks
+)
+```
+
+### Button Event Monitoring
+
+```python
+# Real-time button monitoring
+def on_button_event(button: MouseButton, pressed: bool):
+    print(f"{button.name} {'pressed' if pressed else 'released'}")
+
+makcu.set_button_callback(on_button_event)
+await makcu.enable_button_monitoring(True)
+
+# Check current button states
+states = makcu.get_button_states()
+if makcu.is_pressed(MouseButton.RIGHT):
+    print("Right button is pressed")
+```
+
+### Connection Management
+
+```python
+# Auto-reconnection on disconnect
+makcu = await create_async_controller(auto_reconnect=True)
+
+# Connection status callbacks
+@makcu.on_connection_change
+async def handle_connection(connected: bool):
+    if connected:
+        print("Device reconnected!")
+    else:
+        print("Device disconnected!")
+
+# Manual reconnection
+if not makcu.is_connected():
+    await makcu.connect()
+```
+
+---
+
+## 🔧 Advanced Features
+
+### Batch Operations
+
+```python
+# Execute multiple commands efficiently
+async def combo_action():
+    await makcu.batch_execute([
+        lambda: makcu.move(50, 0),
+        lambda: makcu.click(MouseButton.LEFT),
+        lambda: makcu.move(-50, 0),
+        lambda: makcu.click(MouseButton.RIGHT)
+    ])
+```
+
+### Device Information
+
+```python
+# Get device details
+info = await makcu.get_device_info()
+# {'port': 'COM3', 'vid': '0x1a86', 'pid': '0x55d3', ...}
+
+# Firmware version
+version = await makcu.get_firmware_version()
+```
+
+### Serial Spoofing
+
+```python
+# Spoof device serial
+await makcu.spoof_serial("CUSTOM123456")
+
+# Reset to default
+await makcu.reset_serial()
+```
+
+### Low-Level Access
+
+```python
+# Send raw commands with tracked responses
+response = await makcu.transport.async_send_command(
+    "km.version()", 
+    expect_response=True,
+    timeout=0.1  # Optimized for gaming
+)
+```
+
+---
+
+## 🧪 Command-Line Tools
+
+```bash
+# Interactive debug console
+python -m makcu --debug
+
+# Test specific port
+python -m makcu --testPort COM3
+
+# Run automated tests
+python -m makcu --runtest
+```
+
+### Tool Descriptions
+
+- `--debug`: Launches an interactive console where you can type raw device commands and see live responses.
+- `--testPort COMx`: Attempts to connect to the given COM port and reports success or failure.
+- `--runtest`: Runs `test_suite.py` using `pytest` and opens a detailed HTML test report.
+
+---
+
+### Test Suite
+
+- File: `test_suite.py`
+- Run with: `python -m makcu --runtest`
+- Output: `latest_pytest.html`
+
+Includes tests for:
+- Port connection
+- Firmware version check
+- Mouse movement and button control
+- Button masking and locking
+
+---
+
+## Test Timings (v1.3 vs v1.4 vs v2.0)
+
+| Test Name                | v1.3   | v1.4  | v2.0  | Improvement (v1.3 → v2.0) |
+|--------------------------|--------|-------|-------|----------------------------|
+| connect_to_port          | ~100ms | ~55ms | **46ms** | ~2.2x faster              |
+| press_and_release        | ~18ms  | ~9ms  | **1ms**  | ~18x faster               |
+| firmware_version         | ~20ms  | ~9ms  | **1ms**  | ~20x faster               |
+| middle_click             | ~18ms  | ~9ms  | **1ms**  | ~18x faster               |
+| device_info              | ~25ms  | ~13ms | **6ms**  | ~4.1x faster              |
+| port_connection          | ~20ms  | ~9ms  | **1ms**  | ~20x faster               |
+| button_mask              | ~17ms  | ~8ms  | **1ms**  | ~17x faster               |
+| get_button_states        | ~18ms  | ~9ms  | **1ms**  | ~18x faster               |
+| lock_state               | ~33ms  | ~10ms | **1ms**  | ~33x faster               |
+| makcu_behavior           | ~20ms  | ~10ms | **1ms**  | ~20x faster               |
+| batch_commands           | ~350ms | ~90ms | **3ms**  | ~117x faster              |
+| rapid_moves              | ~17ms  | ~8ms  | **2ms**  | ~8.5x faster              |
+| button_performance       | ~18ms  | ~9ms  | **2ms**  | ~9x faster                |
+| mixed_operations         | ~22ms  | ~10ms | **2ms**  | ~11x faster               |
+
+Based on the measured test suite, v2.0 is on average **~17× faster** than v1.3 across all core operations.
+
+
+### Gaming Performance Targets (v2.0)
+
+- **144Hz Gaming**: 7ms frame time — ✅ Easily met (avg 1–3ms per operation)
+- **240Hz Gaming**: 4.2ms frame time — ✅ Consistently met (most ops ≤ 2ms)
+- **360Hz Gaming**: 2.8ms frame time — ⚡ Achievable for atomic/single ops
+
+---
+
+## 🏎️ Performance Optimization Details
+
+### Version History & Performance
+
+- **v1.3 and earlier**: Original implementation with sleep delays
+- **v1.4**: Initial optimizations, removed some sleep delays
+- **v2.0**: Complete rewrite with zero-delay architecture
+
+### Key Optimizations in v2.0
+
+1. **Pre-computed Commands**: All commands are pre-formatted at initialization
+2. **Bitwise Operations**: Button states use single integer with bit manipulation
+3. **Zero-Copy Buffers**: Pre-allocated buffers for parsing
+4. **Reduced Timeouts**: Gaming-optimized timeouts (100ms default)
+5. **Cache Everything**: Connection states, lock states, and device info cached
+6. **Minimal Allocations**: Reuse objects and avoid string formatting
+7. **Fast Serial Settings**: 1ms read timeout, 10ms write timeout
+8. **Optimized Listener**: Batch processing with minimal overhead
+
+### Tips for Maximum Performance
+
+```python
+# Disable debug mode in production
+makcu = create_controller(debug=False)
+
+# Use cached connection checks
+if makcu.is_connected():  # Cached, no serial check
+    makcu.click(MouseButton.LEFT)
+
+# Batch similar operations
+with makcu:  # Context manager ensures connection
+    for _ in range(10):
+        makcu.move(10, 0)  # No connection check per call
+```
+
+---
+
+## 🔍 Debugging
+
+Enable debug mode for detailed logging:
+
+```python
+makcu = await create_async_controller(debug=True)
+
+# View command flow (optimized timestamps)
+# [123.456] [INFO] Sent command #42: km.move(100,50)
+# [123.458] [DEBUG] Command #42 completed in 0.002s
+```
+
+---
+
+## 🏗️ Migration from v1.x
+
+Most code works without changes! Key differences:
+
+```python
+# v1.x (still works)
+makcu = create_controller()
+makcu.move(100, 100)
+
+# v2.0 (async)
+makcu = await create_async_controller()
+await makcu.move(100, 100)
+
+# v2.0 context manager (auto cleanup)
+async with await create_async_controller() as makcu:
+    await makcu.click(MouseButton.LEFT)
+```
+
+---
+
+## 📚 API Reference
+
+### Enumerations
+
+```python
+from makcu import MouseButton
+
+MouseButton.LEFT    # Left mouse button
+MouseButton.RIGHT   # Right mouse button  
+MouseButton.MIDDLE  # Middle mouse button
+MouseButton.MOUSE4  # Side button 1
+MouseButton.MOUSE5  # Side button 2
+```
+
+### Exception Handling
+
+```python
+from makcu import MakcuError, MakcuConnectionError, MakcuTimeoutError
+
+try:
+    makcu = await create_async_controller()
+except MakcuConnectionError as e:
+    print(f"Connection failed: {e}")
+except MakcuTimeoutError as e:
+    print(f"Command timed out: {e}")
+```
+
+---
+
+## 🛠️ Technical Details
+
+- **Protocol**: CH343 USB serial at 4Mbps
+- **Command Format**: ASCII with optional ID tracking (`command#ID`)
+- **Response Format**: `>>> #ID:response` for tracked commands
+- **Threading**: High-priority listener thread with async bridge
+- **Auto-Discovery**: VID:PID=1A86:55D3 detection
+- **Buffer Size**: 4KB read buffer, 256B line buffer
+- **Cleanup Interval**: 50ms for timed-out commands
+
+---
+
+## 📜 License
+
+GPL License © SleepyTotem
+
+---
+
+## 🙋 Support
+
+- **Issues**: [GitHub Issues](https://github.com/SleepyTotem/makcu-py-lib/issues)
+
+---
+
+## 🌐 Links
+
+- [GitHub Repository](https://github.com/SleepyTotem/makcu-py-lib)
+- [PyPI Package](https://pypi.org/project/makcu/)
+- [Documentation](https://makcu-py-lib.readthedocs.io/)
+- [Changelog](https://makcu-py-lib.readthedocs.io/en/latest/changelog.html)

{makcu-2.2.0 → makcu-2.2.2}/makcu/__init__.py

@@ -1,22 +1,22 @@
-from .controller import (
-    MakcuController,
-    create_controller,
-    create_async_controller,
-    maybe_async
-)
-from .enums import MouseButton
-from .errors import MakcuConnectionError
-
-# Version info
-__version__ = "2.2.0"
-__author__ = "SleepyTotem"
-
-# Main exports
-__all__ = [
-    'MakcuController',
-    'MouseButton',
-    'MakcuConnectionError',
-    'create_controller',
-    'create_async_controller',
-    'maybe_async'
+from .controller import (
+    MakcuController,
+    create_controller,
+    create_async_controller,
+    maybe_async
+)
+from .enums import MouseButton
+from .errors import MakcuConnectionError
+
+# Version info
+__version__ = "2.2.1"
+__author__ = "SleepyTotem"
+
+# Main exports
+__all__ = [
+    'MakcuController',
+    'MouseButton',
+    'MakcuConnectionError',
+    'create_controller',
+    'create_async_controller',
+    'maybe_async'
 ]

{makcu-2.2.0 → makcu-2.2.2}/makcu/__main__.py

@@ -91,42 +91,48 @@ def find_writable_directory() -> Path:
 def parse_html_results(html_file: Path) -> Tuple[List[Tuple[str, str, int]], int]:
     if not html_file.exists():
         raise FileNotFoundError(f"HTML report not found: {html_file}")
-    
+   
     with open(html_file, 'r', encoding='utf-8') as f:
         content = f.read()
-    
+   
     match = re.search(r'data-jsonblob="([^"]*)"', content)
     if not match:
         raise ValueError("Could not find JSON data in HTML report")
-    
+   
     json_str = match.group(1)
     json_str = json_str.replace('"', '"').replace(''', "'").replace('&', '&')
-    
+   
     try:
         data = json.loads(json_str)
     except json.JSONDecodeError as e:
         raise ValueError(f"Failed to parse JSON data: {e}")
-    
+   
     test_results = []
     total_ms = 0
-    
+   
     skip_tests = {'test_connect_to_port'}
-    
+   
     for test_id, test_data_list in data.get('tests', {}).items():
         test_name = test_id.split('::')[-1]
+        
+        # Skip tests that are in skip_tests
         if test_name in skip_tests:
             continue
-            
+           
         for test_data in test_data_list:
             status = test_data.get('result', 'UNKNOWN')
             duration_str = test_data.get('duration', '0 ms')
-            
+           
             duration_match = re.search(r'(\d+)\s*ms', duration_str)
             duration_ms = int(duration_match.group(1)) if duration_match else 0
-            total_ms += duration_ms
             
+            # Always add test to results
             test_results.append((test_name, status, duration_ms))
-    
+            
+            # Only add time to total if it's not a cleanup test
+            if 'cleanup' not in test_name.lower():
+                total_ms += duration_ms
+   
     return test_results, total_ms
 
 def run_tests() -> NoReturn:
@@ -244,8 +250,12 @@ def run_tests() -> NoReturn:
             display_name = test_name.replace("test_", "").replace("_", " ").title()
 
             if status.upper() == "PASSED":
-                status_text = "[green]✅ PASSED[/green]"
-                passed += 1
+                if display_name.lower().startswith("cleanup"):
+                    status_text = ""
+                    passed += 1
+                else:
+                    status_text = "[green]✅ PASSED[/green]"
+                    passed += 1
             elif status.upper() == "FAILED":
                 status_text = "[red]❌ FAILED[/red]"
                 failed += 1
@@ -263,7 +273,10 @@ def run_tests() -> NoReturn:
             elif duration_ms <= 10:
                 perf = "[yellow]Good[/yellow]"
             elif duration_ms > 0:
-                perf = "[red]🐌 Needs work[/red]"
+                if display_name.lower().startswith("cleanup"):
+                    perf = ""
+                else:
+                    perf = "[red]🐌 Needs work[/red]"
             else:
                 perf = "-"
 

makcu-2.2.2/makcu/conftest.py

@@ -0,0 +1,8 @@
+import pytest
+import time
+from makcu import MakcuController, MouseButton
+
+@pytest.fixture(scope="session")
+def makcu():
+    ctrl = MakcuController(fallback_com_port="COM1", debug=False)
+    return ctrl

{makcu-2.2.0 → makcu-2.2.2}/makcu/connection.py

@@ -161,31 +161,33 @@ class SerialTransport:
         content = line.decode('ascii', 'ignore').strip()
         return ParsedResponse(None, content, False)
 
+    
     def _handle_button_data(self, byte_val: int) -> None:
         if byte_val == self._last_button_mask:
             return
-            
+
         changed_bits = byte_val ^ self._last_button_mask
+        print("\n", end='')
         self._log(f"Button state changed: 0x{self._last_button_mask:02X} -> 0x{byte_val:02X}")
 
-        for bit in range(5):
+        for bit in range(8):
             if changed_bits & (1 << bit):
                 is_pressed = bool(byte_val & (1 << bit))
                 button_name = self.BUTTON_MAP[bit] if bit < len(self.BUTTON_MAP) else f"bit{bit}"
-                
+            
                 self._log(f"Button {button_name}: {'PRESSED' if is_pressed else 'RELEASED'}")
-
+                print(">>> ", end='', flush=True)
                 if is_pressed:
                     self._button_states |= (1 << bit)
                 else:
                     self._button_states &= ~(1 << bit)
-                
+            
                 if self._button_callback and bit < len(self.BUTTON_ENUM_MAP):
                     try:
                         self._button_callback(self.BUTTON_ENUM_MAP[bit], is_pressed)
                     except Exception as e:
                         self._log(f"Button callback failed: {e}", "ERROR")
-        
+
         self._last_button_mask = byte_val
 
     def _process_pending_commands(self, content: str) -> None:
@@ -234,54 +236,114 @@ class SerialTransport:
 
     def _listen(self) -> None:
         self._log("Starting listener thread")
-
         read_buffer = bytearray(4096)
         line_buffer = bytearray(256)
         line_pos = 0
-        
 
         serial_read = self.serial.read
         serial_in_waiting = lambda: self.serial.in_waiting
         is_connected = lambda: self._is_connected
         stop_requested = self._stop_event.is_set
-        
 
         last_cleanup = time.time()
         cleanup_interval = 0.05
         
+        expecting_text_mode = False
+        last_byte = None
+
         while is_connected() and not stop_requested():
             try:
                 bytes_available = serial_in_waiting()
                 if not bytes_available:
                     time.sleep(0.001)
                     continue
-                
+            
                 bytes_read = serial_read(min(bytes_available, 4096))
-
                 for byte_val in bytes_read:
-                    if byte_val < 32 and byte_val not in (0x0D, 0x0A):
-                        # Button data
-                        self._handle_button_data(byte_val)
-                    else:
-                        if byte_val == 0x0A:  # LF
-                            if line_pos > 0:
+                    
+                    if last_byte == 0x0D and byte_val == 0x0A:
+                        if line_pos > 0:
+                            line = bytes(line_buffer[:line_pos])
+                            line_pos = 0
+                            if line:
+                                response = self._parse_response_line(line)
+                                if response.content:
+                                    self._process_pending_commands(response.content)
+                        expecting_text_mode = False
+                    
+                    elif byte_val >= 32 or byte_val in (0x09,):
+                        expecting_text_mode = True
+                        if line_pos < 256:
+                            line_buffer[line_pos] = byte_val
+                            line_pos += 1
+                    
+                    elif byte_val == 0x0D:
+                        if expecting_text_mode or line_pos > 0:
+                            expecting_text_mode = True
+                        else:
+                            pass
+                    
+                    elif byte_val == 0x0A:
+                        last_byte_str = f"0x{last_byte:02X}" if last_byte is not None else "None"
+                        # self._log(f"LF detected: last_byte={last_byte_str}, expecting_text={expecting_text_mode}, line_pos={line_pos}", "DEBUG")
+                        
+                        button_combination_detected = False
+                        
+                        if (self._last_button_mask != 0 or 
+                            (last_byte is not None and last_byte < 32 and last_byte != 0x0D) or
+                            (line_pos > 0 and not expecting_text_mode)):
+                            
+                            # self._log("LF: Detected as button combination (right + mouse4 = 0x0A)", "DEBUG")
+                            self._handle_button_data(byte_val)
+                            expecting_text_mode = False
+                            button_combination_detected = True
+                            line_pos = 0
+                        
+                        if not button_combination_detected:
+                            if last_byte == 0x0D:
+                                self._log("LF: Completing CRLF sequence", "DEBUG")
+                                if line_pos > 0:
+                                    line = bytes(line_buffer[:line_pos])
+                                    line_pos = 0
+                                    if line:
+                                        response = self._parse_response_line(line)
+                                        if response.content:
+                                            self._process_pending_commands(response.content)
+                                expecting_text_mode = False
+                            elif line_pos > 0 and expecting_text_mode:
+                                self._log("LF: Ending line with text in buffer", "DEBUG")
                                 line = bytes(line_buffer[:line_pos])
                                 line_pos = 0
-                                
                                 if line:
                                     response = self._parse_response_line(line)
                                     if response.content:
                                         self._process_pending_commands(response.content)
-                        elif byte_val != 0x0D:  # Not CR
-                            if line_pos < 256:
-                                line_buffer[line_pos] = byte_val
-                                line_pos += 1
-
+                                expecting_text_mode = False
+                            elif expecting_text_mode:
+                                self._log("LF: Empty line in text mode", "DEBUG")
+                                expecting_text_mode = False
+                            else:
+                                self._log("LF: Treating as button data (no text context)", "DEBUG")
+                                self._handle_button_data(byte_val)
+                                expecting_text_mode = False
+                                line_pos = 0  # Clear any accumulated data
+                    
+                    elif byte_val < 32:
+                        if last_byte == 0x0D:
+                            self._log(f"Processing delayed CR as button data: 0x0D", "DEBUG")
+                            self._handle_button_data(0x0D)
+                        
+                        self._handle_button_data(byte_val)
+                        expecting_text_mode = False
+                        line_pos = 0
+                    
+                    last_byte = byte_val
+                            
                 current_time = time.time()
                 if current_time - last_cleanup > cleanup_interval:
                     self._cleanup_timed_out_commands()
                     last_cleanup = current_time
-                    
+                
             except serial.SerialException as e:
                 self._log(f"Serial exception in listener: {e}", "ERROR")
                 if self.auto_reconnect:
@@ -290,7 +352,7 @@ class SerialTransport:
                     break
             except Exception as e:
                 self._log(f"Unexpected exception in listener: {e}", "ERROR")
-        
+
         self._log("Listener thread ending")
 
     def _attempt_reconnect(self) -> None:
@@ -449,7 +511,7 @@ class SerialTransport:
         self.serial = None
         self._log("Disconnection completed")
 
-    def send_command(self, command: str, expect_response: bool = True, 
+    def send_command(self, command: str, expect_response: bool = False, 
                 timeout: float = DEFAULT_TIMEOUT) -> Optional[str]:
         command_start = time.time()
         
@@ -457,11 +519,10 @@ class SerialTransport:
             raise MakcuConnectionError("Not connected")
         
         if not expect_response:
-            cmd_bytes = f"{command}\r\n".encode('ascii')
-            self.serial.write(cmd_bytes)
+            self.serial.write(f"{command}\r\n".encode('ascii'))
             self.serial.flush()
             send_time = time.time() - command_start
-            self._log(f"Command '{command}' sent in {send_time:.3f}s (no response expected)")
+            self._log(f"Command '{command}' sent in {send_time:.5f}s (no response expected)")
             return command
         
         cmd_id = self._generate_command_id()
@@ -488,7 +549,7 @@ class SerialTransport:
             
             response = result.split('#')[0] if '#' in result else result
             total_time = time.time() - command_start
-            self._log(f"Command '{command}' completed in {total_time:.3f}s total")
+            self._log(f"Command '{command}' completed in {total_time:.5f}s total")
             return response
             
         except TimeoutError:

{makcu-2.2.0 → makcu-2.2.2}/makcu/py.typed

@@ -1,2 +1,2 @@
-# This file is intentionally empty.
+# This file is intentionally empty.
 # It serves as a marker to indicate that this package supports type hints.

{makcu-2.2.0 → makcu-2.2.2}/makcu/test_suite.py

@@ -137,6 +137,23 @@ def test_mixed_operations(makcu):
     assert elapsed_ms < 15
 
 
-@pytest.mark.skip(reason="Capture test disabled until firmware supports tracking clicks from software input")
-def test_capture_right_clicks(makcu):
-    pass
+def test_cleanup(makcu):
+    time.sleep(0.1)
+
+    makcu.lock_left(False)
+    makcu.lock_right(False)
+    makcu.lock_middle(False)
+    makcu.lock_side1(False)
+    makcu.lock_side2(False)
+    makcu.lock_x(False)
+    makcu.lock_y(False)
+
+    makcu.release(MouseButton.LEFT)
+    makcu.release(MouseButton.RIGHT)
+    makcu.release(MouseButton.MIDDLE)
+    makcu.release(MouseButton.MOUSE4)
+    makcu.release(MouseButton.MOUSE5)
+
+    makcu.enable_button_monitoring(False)
+    makcu.disconnect()
+    assert not makcu.is_connected(), "Failed to disconnect from the makcu"

{makcu-2.2.0 → makcu-2.2.2}/makcu.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: makcu
-Version: 2.2.0
+Version: 2.2.2
 Summary: Python library for Makcu hardware device control
 Author: SleepyTotem
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -708,7 +708,7 @@ Requires-Dist: twine>=4.0
 Requires-Dist: rich>=14.0
 Dynamic: license-file
 
-# 🖱️ Makcu Python Library v2.2.0
+# 🖱️ Makcu Python Library v2.2.2
 
 [![PyPI Version](https://img.shields.io/pypi/v/makcu.svg)](https://pypi.org/project/makcu/)
 [![Python Support](https://img.shields.io/pypi/pyversions/makcu.svg)](https://pypi.org/project/makcu/)
@@ -1112,4 +1112,5 @@ GPL License © SleepyTotem
 
 - [GitHub Repository](https://github.com/SleepyTotem/makcu-py-lib)
 - [PyPI Package](https://pypi.org/project/makcu/)
-- [Documentation](https://makcu.readthedocs.io/) *(coming soon)*
+- [Documentation](https://makcu-py-lib.readthedocs.io/)
+- [Changelog](https://makcu-py-lib.readthedocs.io/en/latest/changelog.html)

{makcu-2.2.0 → makcu-2.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "makcu"
-version = "2.2.0"
+version = "2.2.2"
 description = "Python library for Makcu hardware device control"
 readme = "makcu/README.md"
 requires-python = ">=3.7"

makcu-2.2.0/makcu/conftest.py

@@ -1,34 +0,0 @@
-import pytest
-import time
-from makcu import MakcuController, MouseButton
-
-@pytest.fixture(scope="session")
-def makcu(request):
-    ctrl = MakcuController(fallback_com_port="COM1", debug=False)
-
-    def cleanup():
-        if ctrl.is_connected():
-
-            time.sleep(0.1)
-
-            ctrl.lock_left(False)
-            ctrl.lock_right(False)
-            ctrl.lock_middle(False)
-            ctrl.lock_side1(False)
-            ctrl.lock_side2(False)
-            ctrl.lock_x(False)
-            ctrl.lock_y(False)
-
-            ctrl.release(MouseButton.LEFT)
-            ctrl.release(MouseButton.RIGHT)
-            ctrl.release(MouseButton.MIDDLE)
-            ctrl.release(MouseButton.MOUSE4)
-            ctrl.release(MouseButton.MOUSE5)
-
-            ctrl.enable_button_monitoring(False)
-
-        ctrl.disconnect()
-
-    request.addfinalizer(cleanup)
-
-    return ctrl