makcu 0.1.1__py3-none-any.whl

makcu/__init__.py

@@ -0,0 +1,16 @@
+from .controller import MakcuController
+from .enums import MouseButton
+from .errors import MakcuError, MakcuConnectionError
+
+def create_controller(debug=False, send_init=True):
+    makcu = MakcuController(debug=debug, send_init=send_init)
+    makcu.connect()
+    return makcu
+
+__all__ = [
+    "MakcuController",
+    "MouseButton",
+    "MakcuError",
+    "MakcuConnectionError",
+    "create_controller",
+]

makcu/__main__.py

@@ -0,0 +1,80 @@
+# makcu/__main__.py
+
+import sys
+import subprocess
+import webbrowser
+import os
+from makcu import create_controller, MakcuConnectionError
+
+def debug_console():
+    controller = create_controller()
+    transport = controller.transport
+
+    print("🔧 Makcu Debug Console")
+    print("Type a raw command (e.g., km.version()) and press Enter.")
+    print("Type 'exit' or 'quit' to leave.")
+
+    while True:
+        try:
+            cmd = input(">>> ").strip()
+            if cmd.lower() in {"exit", "quit"}:
+                break
+            if not cmd:
+                continue
+
+            response = transport.send_command(cmd, expect_response=True)
+            print(f"{response or '(no response)'}")
+
+        except Exception as e:
+            print(f"⚠️ Error: {e}")
+
+    controller.disconnect()
+    print("Disconnected.")
+
+def test_port(port):
+    try:
+        print(f"Trying to connect to {port} (without init command)...")
+        controller = create_controller(send_init=False)
+        print(f"✅ Successfully connected to {port}")
+        controller.disconnect()
+    except MakcuConnectionError as e:
+        print(f"❌ Failed to connect to {port}: {e}")
+    except Exception as e:
+        print(f"❌ Unexpected error: {e}")
+
+def run_tests():
+    print("🧪 Running Pytest Suite...")
+    subprocess.run([
+        sys.executable, "-m", "pytest",
+        "--html=latest_pytest.html", "--self-contained-html"
+    ])
+
+    report_path = os.path.abspath("latest_pytest.html")
+    print(f"📄 Opening test report: {report_path}")
+    webbrowser.open(f"file://{report_path}")
+
+def main():
+    args = sys.argv[1:]
+
+    if not args:
+        print("Usage:")
+        print("  python -m makcu --debug")
+        print("  python -m makcu --testPort COM3")
+        print("  python -m makcu --runtest")
+        return
+
+    if args[0] == "--debug":
+        debug_console()
+    elif args[0] == "--testPort" and len(args) == 2:
+        test_port(args[1])
+    elif args[0] == "--runtest":
+        run_tests()
+    else:
+        print(f"Unknown command: {' '.join(args)}")
+        print("Usage:")
+        print("  python -m makcu --debug")
+        print("  python -m makcu --testPort COM3")
+        print("  python -m makcu --runtest")
+
+if __name__ == "__main__":
+    main()

makcu/connection.py

@@ -0,0 +1,277 @@
+import serial
+import threading
+import time
+from serial.tools import list_ports
+from .errors import MakcuConnectionError, MakcuTimeoutError
+from .enums import MouseButton
+
+class SerialTransport:
+    global fallback_com_port
+    baud_change_command = bytearray([0xDE, 0xAD, 0x05, 0x00, 0xA5, 0x00, 0x09, 0x3D, 0x00])
+
+    button_map = {
+        0: 'left',
+        1: 'right',
+        2: 'middle',
+        3: 'mouse4',
+        4: 'mouse5'
+    }
+
+    def __init__(self, debug=False, send_init=True):        
+        self._log_messages = []
+        self.debug = debug
+        self.send_init = send_init
+        self._button_callback = None
+        self._last_mask = 0
+        self._lock = threading.Lock()
+        self._is_connected = False
+        self._stop_event = threading.Event()
+        self._listener_thread = None
+        self._button_states = {btn: False for btn in self.button_map.values()}
+        self._debounce_time_ms = 50
+        self._last_callback_time = {bit: 0 for bit in self.button_map}
+        self._pause_listener = False
+
+        self._button_enum_map = {
+            0: MouseButton.LEFT,
+            1: MouseButton.RIGHT,
+            2: MouseButton.MIDDLE,
+            3: MouseButton.MOUSE4,
+            4: MouseButton.MOUSE5,
+        }
+
+        self.port = self.find_com_port()
+        if not self.port:
+            raise MakcuConnectionError("Makcu device not found. Please specify a port explicitly.")
+
+        self.baudrate = 115200
+        self.serial = None
+        self._current_baud = None
+
+    def receive_response(self, max_bytes=1024, max_lines=3, sent_command: str = "") -> str:
+        lines = []
+        try:
+            for _ in range(max_lines):
+                line = self.serial.readline(max_bytes)
+                if not line:
+                    break
+                decoded = line.decode(errors="ignore").strip()
+                if decoded:
+                    lines.append(decoded)
+        except Exception as e:
+            print(f"[RECV ERROR] {e}")
+            return ""
+
+        command_clean = sent_command.strip()
+        if lines:
+            lines.pop(-1)
+        if command_clean in lines and len(lines) > 1:
+            lines.remove(command_clean)
+        return "\n".join(lines)
+
+    def set_debounce_time(self, ms: int):
+        self._debounce_time_ms = ms
+
+    def set_button_callback(self, callback):
+        self._button_callback = callback
+
+    def _log(self, message):
+        timestamp = time.strftime("%H:%M:%S")
+        entry = f"[{timestamp}] {message}"
+        self._log_messages.append(entry)
+        if len(self._log_messages) > 20:
+            self._log_messages.pop(0)
+        print(entry, flush=True)
+
+    def find_com_port(self):
+        global fallback_com_port
+        self._log("Searching for CH343 device...")
+
+        for port in list_ports.comports():
+            if "USB-Enhanced-SERIAL CH343" in port.description:
+                self._log(f"Device found: {port.device}")
+                return port.device
+
+        if fallback_com_port and "COM" in fallback_com_port:
+            self._log(f"CH343 not found. Falling back to specified port: {fallback_com_port}")
+            return fallback_com_port
+        else:
+            self._log("Fallback port is not valid.")
+            return None
+
+
+    def _open_serial_port(self, port, baud_rate):
+        try:
+            self._log(f"Trying to open {port} at {baud_rate} baud.")
+            return serial.Serial(port, baud_rate, timeout=0.05)
+        except serial.SerialException:
+            self._log(f"Failed to open {port} at {baud_rate} baud.")
+            return None
+
+    def _change_baud_to_4M(self):
+        if self.serial and self.serial.is_open:
+            self._log("Sending baud rate switch command to 4M.")
+            self.serial.write(self.baud_change_command)
+            self.serial.flush()
+            port = self.serial.name
+            self.serial.close()
+            time.sleep(0.1)
+            self.serial = self._open_serial_port(port, 4000000)
+            if self.serial:
+                self._current_baud = 4000000
+                self._log("Switched to 4M baud successfully.")
+                return True
+            else:
+                self._log("Failed to reopen port at 4M baud.")
+        return False
+
+    def connect(self):
+        if self._is_connected:
+            self._log("Already connected.")
+            return
+        self.serial = self._open_serial_port(self.port, 115200)
+        if not self.serial:
+            raise MakcuConnectionError(f"Failed to connect to {self.port} at 115200.")
+        self._log(f"Connected to {self.port} at 115200.")
+        if not self._change_baud_to_4M():
+            raise MakcuConnectionError("Failed to switch to 4M baud.")
+        self._is_connected = True
+        if self.send_init:
+            with self._lock:
+                self.serial.write(b"km.buttons(1)\r")
+                self.serial.flush()
+                self._log("Sent init command: km.buttons(1)")
+
+            self._stop_event.clear()
+            self._listener_thread = threading.Thread(target=self._listen, kwargs={"debug": self.debug}, daemon=True)
+            self._listener_thread.start()
+
+    def disconnect(self):
+        if self.send_init:
+            self._stop_event.set()
+            if self._listener_thread:
+                self._listener_thread.join()
+        with self._lock:
+            if self.serial and self.serial.is_open:
+                self.serial.close()
+            self.serial = None
+            self._is_connected = False
+            self._log("Disconnected.")
+
+    def is_connected(self):
+        return self._is_connected
+
+    def send_command(self, command, expect_response=False):
+        time.sleep(0.06)
+        if not self._is_connected or not self.serial or not self.serial.is_open:
+            raise MakcuConnectionError("Serial connection not open.")
+        with self._lock:
+            try:
+                self._pause_listener = True
+                self.serial.reset_input_buffer()
+                self.serial.write(command.encode("ascii") + b"\r\n")
+                self.serial.flush()
+                if expect_response:
+                    response = self.receive_response(sent_command=command)
+                    if not response:
+                        raise MakcuTimeoutError(f"No response from device for command: {command}")
+                    return response
+            finally:
+                self._pause_listener = False
+
+    def get_button_states(self):
+        return dict(self._button_states)
+
+    def get_button_mask(self) -> int:
+        mask = 0
+        for i, name in self.button_map.items():
+            if self._button_states.get(name, False):
+                mask |= (1 << i)
+        return mask
+
+    def enable_button_monitoring(self, enable: bool = True):
+        self.send_command("km.buttons(1)" if enable else "km.buttons(0)")
+
+    def catch_button(self, button: str):
+        command = {
+            "LEFT": "km.catch_ml(0)",
+            "RIGHT": "km.catch_mr(0)",
+            "MIDDLE": "km.catch_mm(0)",
+            "MOUSE4": "km.catch_ms1(0)",
+            "MOUSE5": "km.catch_ms2(0)",
+        }.get(button.upper())
+        if command:
+            self.send_command(command)
+        else:
+            raise ValueError(f"Unsupported button: {button}")
+
+    def read_captured_clicks(self, button: str) -> int:
+        command = {
+            "LEFT": "km.catch_ml()",
+            "RIGHT": "km.catch_mr()",
+            "MIDDLE": "km.catch_mm()",
+            "MOUSE4": "km.catch_ms1()",
+            "MOUSE5": "km.catch_ms2()",
+        }.get(button.upper())
+        if command:
+            result = self.send_command(command, expect_response=True)
+            try:
+                return int(result.strip())
+            except Exception:
+                return 0
+        else:
+            raise ValueError(f"Unsupported button: {button}")
+
+    def _listen(self, debug=False):
+        self._log("Started listener thread")
+        last_value = None
+        button_states = {i: False for i in self.button_map}
+        self._last_mask = 0
+
+        while self._is_connected and not self._stop_event.is_set():
+            if self._pause_listener:
+                time.sleep(0.001)
+                continue
+            try:
+                byte = self.serial.read(1)
+                if byte:
+                    value = byte[0]
+                    mask = 0
+                    for bit, name in self.button_map.items():
+                        is_pressed = bool(value & (1 << bit))
+                        if is_pressed != button_states[bit]:
+                            button_states[bit] = is_pressed
+                        if is_pressed:
+                            mask |= (1 << bit)
+
+                    for bit, name in self.button_map.items():
+                        self._button_states[name] = button_states[bit]
+
+                    now = time.time() * 1000 
+                    if self._button_callback and mask != self._last_mask:
+                        for bit, name in self.button_map.items():
+                            previous = bool(self._last_mask & (1 << bit))
+                            current = bool(mask & (1 << bit))
+                            if previous != current:
+                                last_time = self._last_callback_time.get(bit, 0)
+                                if now - last_time >= self._debounce_time_ms:
+                                    button_enum = self._button_enum_map.get(bit)
+                                    if button_enum:
+                                        self._button_callback(button_enum, current)
+                                        self._last_callback_time[bit] = now
+
+                    self._last_mask = mask
+
+                    if debug:
+                        pressed = [name for bit, name in self.button_map.items() if button_states[bit]]
+                        button_str = ", ".join(pressed) if pressed else "No buttons pressed"
+                        self._log(f"Byte: {value} (0x{value:02X}) -> {button_str}")
+
+                    last_value = value
+            except serial.SerialException as e:
+                if "ClearCommError failed" not in str(e):
+                    self._log(f"Serial error during listening: {e}")
+                    break
+            time.sleep(0.0001)
+
+        self._log("Listener thread exiting")

makcu/controller.py

@@ -0,0 +1,197 @@
+import random
+import time
+from .mouse import Mouse
+from .connection import SerialTransport
+from .errors import MakcuConnectionError
+from .enums import MouseButton
+
+class MakcuController:
+    def __init__(self, debug=False, send_init=True):
+        self.transport = SerialTransport(debug=debug, send_init=send_init)
+        self.mouse = Mouse(self.transport)
+
+    def connect(self):
+        self.transport.connect()
+
+    def disconnect(self):
+        self.transport.disconnect()
+
+    def is_connected(self):
+        return self.transport.is_connected()
+
+    def _check_connection(self):
+        if not self.transport.serial or not self.transport.serial.is_open:
+            raise MakcuConnectionError("Not connected")
+
+    def click(self, button: MouseButton):
+        self._check_connection()
+        self.mouse.press(button)
+        self.mouse.release(button)
+
+    def move(self, dx: int, dy: int):
+        self._check_connection()
+        self.mouse.move(dx, dy)
+
+    def scroll(self, delta: int):
+        self._check_connection()
+        self.mouse.scroll(delta)
+
+    def move_smooth(self, dx: int, dy: int, segments: int):
+        self._check_connection()
+        self.mouse.move_smooth(dx, dy, segments)
+
+    def move_bezier(self, dx: int, dy: int, segments: int, ctrl_x: int, ctrl_y: int):
+        self._check_connection()
+        self.mouse.move_bezier(dx, dy, segments, ctrl_x, ctrl_y)
+
+    def lock_mouse_x(self, lock: bool):
+        self._check_connection()
+        self.mouse.lock_x(lock)
+
+    def lock_mouse_y(self, lock: bool):
+        self._check_connection()
+        self.mouse.lock_y(lock)
+
+    def lock_left(self, lock: bool):
+        self._check_connection()
+        self.mouse.lock_left(lock)
+
+    def lock_middle(self, lock: bool):
+        self._check_connection()
+        self.mouse.lock_middle(lock)
+
+    def lock_right(self, lock: bool):
+        self._check_connection()
+        self.mouse.lock_right(lock)
+
+    def lock_side1(self, lock: bool):
+        self._check_connection()
+        self.mouse.lock_side1(lock)
+
+    def lock_side2(self, lock: bool):
+        self._check_connection()
+        self.mouse.lock_side2(lock)
+
+    def spoof_serial(self, serial: str):
+        self._check_connection()
+        self.mouse.spoof_serial(serial)
+
+    def reset_serial(self):
+        self._check_connection()
+        self.mouse.reset_serial()
+
+    def get_device_info(self):
+        self._check_connection()
+        return self.mouse.get_device_info()
+
+    def get_firmware_version(self):
+        self._check_connection()
+        return self.mouse.get_firmware_version()
+
+    def get_button_mask(self) -> int:
+        self._check_connection()
+        return self.transport.get_button_mask()
+
+    def is_locked(self, target: str) -> bool:
+        self._check_connection()
+        return self.mouse.is_locked(target)
+
+    def is_button_locked(self, button: MouseButton) -> bool:
+        self._check_connection()
+        return self.mouse.is_button_locked(button)
+
+    def capture(self, button: MouseButton):
+        self._check_connection()
+        self.mouse.begin_capture(button.name)
+
+    def get_captured_clicks(self, button: MouseButton) -> int:
+        self._check_connection()
+        return self.mouse.stop_capturing_clicks(button.name)
+
+
+    def click_human_like(self, button: MouseButton, count: int = 1,
+        profile: str = "normal", jitter: int = 0):
+        self._check_connection()
+
+        timing_profiles = {
+            "normal": {"min_down": 60,  "max_down": 120, "min_wait": 100, "max_wait": 180},
+            "fast":   {"min_down": 30,  "max_down": 60,  "min_wait": 50,  "max_wait": 100},
+            "slow":   {"min_down": 100, "max_down": 180, "min_wait": 150, "max_wait": 300},
+        }
+
+        if profile not in timing_profiles:
+            raise ValueError(f"Invalid profile: {profile}. Choose from {list(timing_profiles.keys())}")
+
+        t = timing_profiles[profile]
+
+        for _ in range(count):
+            if jitter > 0:
+                dx = random.randint(-jitter, jitter)
+                dy = random.randint(-jitter, jitter)
+                self.mouse.move(dx, dy)
+
+            self.mouse.press(button)
+            time.sleep(random.uniform(t["min_down"], t["max_down"]) / 1000.0)
+            self.mouse.release(button)
+            time.sleep(random.uniform(t["min_wait"], t["max_wait"]) / 1000.0)
+    
+    def enable_button_monitoring(self, enable: bool = True):
+        self._check_connection()
+        self.transport.enable_button_monitoring(enable)
+
+    def set_button_callback(self, callback):
+        self._check_connection()
+        self.transport.set_button_callback(callback)
+
+    def get_all_lock_states(self) -> dict:
+        self._check_connection()
+        return self.mouse.get_all_lock_states()
+    
+    def set_callback_debounce_time(self, ms: int):
+        self._check_connection()
+        self.transport.set_debounce_time(ms)
+
+    def start_capturing_clicks(self, button: str):
+        self._check_connection()
+        self.transport._capture_counts[button] = 0
+        self.transport._capture_active[button] = True
+        self.transport._capture_last_state[button] = None
+        self.mouse.begin_capture(button)
+
+    def stop_capturing_clicks(self, button: str) -> int:
+        self._check_connection()
+        self.transport._capture_active[button] = False
+        return self.mouse.stop_capturing_clicks(button)
+
+    def press(self, button: MouseButton):
+        self._check_connection()
+        self.mouse.press(button)
+
+    def release(self, button: MouseButton):
+        self._check_connection()
+        self.mouse.release(button)
+
+    def set_port(self, port: str):
+        import makcu.connection
+        makcu.connection.fallback_com_port = port
+    
+    def get_button_states(self) -> dict:
+        self._check_connection()
+        return self.transport.get_button_states()
+
+    def is_button_pressed(self, button: MouseButton) -> bool:
+        self._check_connection()
+        return self.transport.get_button_states().get(button.name.lower(), False)
+
+    def get_raw_mask(self) -> int:
+        self._check_connection()
+        return self.transport.get_button_mask()
+
+    def get_virtual_bit_mapping(self) -> dict:
+        return {
+            "LEFT": 0,
+            "RIGHT": 1,
+            "MIDDLE": 2,
+            "MOUSE4": 3,
+            "MOUSE5": 4
+        }

makcu/enums.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+class MouseButton(Enum):
+    LEFT = 0
+    RIGHT = 1
+    MIDDLE = 2
+    MOUSE4 = 3
+    MOUSE5 = 4

makcu/errors.py

@@ -0,0 +1,19 @@
+class MakcuError(Exception):
+    """Base exception for all Makcu-related errors."""
+    pass
+
+class MakcuConnectionError(MakcuError):
+    """Raised when the device connection fails."""
+    pass
+
+class MakcuCommandError(MakcuError):
+    """Raised when a device command is invalid, rejected, or fails."""
+    pass
+
+class MakcuTimeoutError(MakcuError):
+    """Raised when the device does not respond in time."""
+    pass
+
+class MakcuResponseError(MakcuError):
+    """Raised when the response from the device is malformed or unexpected."""
+    pass