makcu 0.1.1__py3-none-any.whl

makcu/mouse.py

@@ -0,0 +1,134 @@
+from .enums import MouseButton
+from .errors import MakcuCommandError
+from serial.tools import list_ports
+
+class Mouse:
+    def __init__(self, transport):
+        self.transport = transport
+
+    def press(self, button: MouseButton):
+        cmd = {
+            MouseButton.LEFT: "km.left(1)",
+            MouseButton.RIGHT: "km.right(1)",
+            MouseButton.MIDDLE: "km.middle(1)"
+        }.get(button)
+        if cmd:
+            self.transport.send_command(cmd)
+        else:
+            raise MakcuCommandError(f"Unsupported button for press(): {button}")
+
+    def release(self, button: MouseButton):
+        cmd = {
+            MouseButton.LEFT: "km.left(0)",
+            MouseButton.RIGHT: "km.right(0)",
+            MouseButton.MIDDLE: "km.middle(0)"
+        }.get(button)
+        if cmd:
+            self.transport.send_command(cmd)
+        else:
+            raise MakcuCommandError(f"Unsupported button for release(): {button}")
+
+    def move(self, x: int, y: int):
+        self.transport.send_command(f"km.move({x},{y})")
+
+    def move_smooth(self, x: int, y: int, segments: int):
+        self.transport.send_command(f"km.move({x},{y},{segments})")
+
+    def move_bezier(self, x: int, y: int, segments: int, ctrl_x: int, ctrl_y: int):
+        self.transport.send_command(f"km.move({x},{y},{segments},{ctrl_x},{ctrl_y})")
+
+    def scroll(self, delta: int):
+        self.transport.send_command(f"km.wheel({delta})")
+
+    def lock_left(self, lock: bool): self.transport.send_command(f"km.lock_ml({int(lock)})")
+    def lock_middle(self, lock: bool): self.transport.send_command(f"km.lock_mm({int(lock)})")
+    def lock_right(self, lock: bool): self.transport.send_command(f"km.lock_mr({int(lock)})")
+    def lock_side1(self, lock: bool): self.transport.send_command(f"km.lock_ms1({int(lock)})")
+    def lock_side2(self, lock: bool): self.transport.send_command(f"km.lock_ms2({int(lock)})")
+    def lock_x(self, lock: bool): self.transport.send_command(f"km.lock_mx({int(lock)})")
+    def lock_y(self, lock: bool): self.transport.send_command(f"km.lock_my({int(lock)})")
+
+    def spoof_serial(self, serial: str): self.transport.send_command(f"km.serial('{serial}')")
+    def reset_serial(self): self.transport.send_command("km.serial(0)")
+
+    def get_device_info(self) -> dict:
+        port_name = self.transport.port
+        is_connected = self.transport.is_connected()
+        info = {
+            "port": port_name,
+            "description": "Unknown",
+            "vid": "Unknown",
+            "pid": "Unknown",
+            "isConnected": is_connected
+        }
+        for port in list_ports.comports():
+            if port.device == port_name:
+                info.update({
+                    "description": port.description,
+                    "vid": hex(port.vid) if port.vid is not None else "Unknown",
+                    "pid": hex(port.pid) if port.pid is not None else "Unknown"
+                })
+                break
+        return info
+
+    def get_firmware_version(self) -> str:
+        return self.transport.send_command("km.version()", expect_response=True)
+
+    def is_locked(self, target: str) -> bool:
+        target = target.upper()
+        commands = {
+            "X": "km.lock_mx()",
+            "Y": "km.lock_my()",
+            "LEFT": "km.lock_ml()",
+            "MIDDLE": "km.lock_mm()",
+            "RIGHT": "km.lock_mr()",
+            "MOUSE4": "km.lock_ms1()",
+            "MOUSE5": "km.lock_ms2()",
+        }
+        if target not in commands:
+            raise ValueError(f"Unsupported lock target: {target}")
+        try:
+            result = self.transport.send_command(commands[target], expect_response=True)
+            return result.strip() == "1"
+        except Exception:
+            return False
+
+    def is_button_locked(self, button: MouseButton) -> bool:
+        name_map = {
+            MouseButton.LEFT: "LEFT",
+            MouseButton.RIGHT: "RIGHT",
+            MouseButton.MIDDLE: "MIDDLE",
+            MouseButton.MOUSE4: "MOUSE4",
+            MouseButton.MOUSE5: "MOUSE5"
+        }
+        return self.is_locked(name_map[button])
+
+    def begin_capture(self, button: str):
+        """
+        Assumes lock_<button>(1) has already been called.
+        Sends catch_<button>(0) to begin capturing click cycles.
+        """
+        self.transport.catch_button(button)
+
+    def stop_capturing_clicks(self, button: str) -> int:
+        """
+        Assumes lock_<button>(0) has already been called.
+        Returns the total number of clicks since begin_capture.
+        """
+        return self.transport.read_captured_clicks(button)
+
+    def get_captured_clicks_enum(self, button: MouseButton) -> int:
+        mapping = {
+            MouseButton.LEFT: "LEFT",
+            MouseButton.RIGHT: "RIGHT",
+            MouseButton.MIDDLE: "MIDDLE",
+            MouseButton.MOUSE4: "MOUSE4",
+            MouseButton.MOUSE5: "MOUSE5",
+        }
+        return self.stop_capturing_clicks(mapping[button])
+
+    def get_all_lock_states(self) -> dict:
+        return {
+            target: self.is_locked(target)
+            for target in ["X", "Y", "LEFT", "RIGHT", "MIDDLE", "MOUSE4", "MOUSE5"]
+        }

makcu/utils.py

@@ -0,0 +1,7 @@
+from serial.tools import list_ports
+
+def find_makcu_port():
+    for port in list_ports.comports():
+        if "CH343" in port.description:
+            return port.device
+    return None

makcu-0.1.1.dist-info/METADATA

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: makcu
+Version: 0.1.1
+Summary: Python library to interact with Makcu devices.
+Author: SleepyTotem
+License: GPL
+Project-URL: Homepage, https://github.com/SleepyTotem/makcu-py-lib
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🖱️ Makcu Python Library
+
+Makcu Py Lib is a Python library for controlling Makcu devices — enabling software-driven mouse input, movement simulation, locking, monitoring, and more.
+
+---
+
+## 📦 Installation
+
+### ✅ Recommended: PyPI
+
+```bash
+pip install makcu
+```
+
+### 🧪 Alternative: Install from Source
+
+```bash
+git clone https://github.com/SleepyTotem/makcu-py-lib
+cd makcu-py-lib
+pip install .
+```
+
+---
+
+## 🚀 Command-Line Usage
+
+After installation, use:
+
+```bash
+python -m makcu [command]
+```
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `--debug` | Opens interactive console to send raw `km.*` commands |
+| `--testPort COM3` | Tests a specific COM port for connectivity |
+| `--runtest` | Runs all automated tests and opens a test report |
+
+### Examples
+
+```bash
+python -m makcu --debug
+python -m makcu --testPort COM3
+python -m makcu --runtest
+```
+
+---
+
+## 🧠 Quickstart (Python)
+
+```python
+from makcu import create_controller, MouseButton
+
+makcu = create_controller()
+makcu.click(MouseButton.LEFT)
+makcu.move(100, 50)
+makcu.scroll(-1)
+makcu.disconnect()
+```
+
+---
+
+## 🧩 API Reference
+
+### 🔧 Initialization
+
+```python
+makcu = create_controller(debug=True, send_init=True)
+```
+
+#### Set fallback port manually
+
+```python
+makcu.set_port("COM4")  # use before create_controller()
+```
+
+---
+
+### 🎮 Mouse Control
+
+#### Clicks
+
+```python
+makcu.click(MouseButton.LEFT)
+makcu.press(MouseButton.RIGHT)
+makcu.release(MouseButton.RIGHT)
+```
+
+#### Movement
+
+```python
+makcu.move(dx=30, dy=20)
+makcu.move_smooth(100, 40, segments=10)
+makcu.move_bezier(50, 50, 15, ctrl_x=25, ctrl_y=25)
+```
+
+#### Scrolling
+
+```python
+makcu.scroll(-3)  # Scroll down
+makcu.scroll(3)   # Scroll up
+```
+
+---
+
+### 🔒 Locking and Unlocking
+
+```python
+makcu.lock_left(True)
+makcu.lock_right(True)
+makcu.lock_middle(False)
+makcu.lock_side1(True)
+makcu.lock_side2(False)
+makcu.lock_mouse_x(True)
+makcu.lock_mouse_y(False)
+```
+
+#### Lock Status
+
+```python
+makcu.is_button_locked(MouseButton.LEFT)
+makcu.get_all_lock_states()
+```
+
+---
+
+### 👤 Human-like Click Simulation
+
+```python
+makcu.click_human_like(
+    button=MouseButton.LEFT,
+    count=5,
+    profile="normal",  # "fast", "slow" also available
+    jitter=3
+)
+```
+
+---
+
+### 🔍 Device Info & Firmware
+
+```python
+info = makcu.get_device_info()
+print(info)
+
+version = makcu.get_firmware_version()
+print(version)
+```
+
+---
+
+### 🔐 Serial Spoofing
+
+```python
+makcu.spoof_serial("FAKE123456")
+makcu.reset_serial()
+```
+
+---
+
+## 🧪 Button Monitoring & Capture
+
+### Enable Real-time Monitoring
+
+```python
+makcu.enable_button_monitoring(True)
+```
+
+### Set Callback Function
+
+```python
+def on_button_event(button, pressed):
+    print(f"{button.name} is {'pressed' if pressed else 'released'}")
+
+makcu.set_button_callback(on_button_event)
+```
+
+### Configure Debounce
+
+```python
+makcu.set_callback_debounce_time(100)  # milliseconds
+```
+
+---
+
+## Click Capturing
+
+### ❌ **Currently broken (Pending Firmware Update)**
+
+Click capturing will allow you to detect and count click events in software.
+
+```python
+makcu.mouse.lock_right(True)
+makcu.capture(MouseButton.RIGHT)
+
+# User clicks however many times
+
+makcu.mouse.lock_right(False)
+count = makcu.get_captured_clicks(MouseButton.RIGHT)
+print(f"Captured clicks: {count}")
+```
+
+> ⚠️ This feature is currently broken in firmware. Do not rely on it yet.
+
+---
+
+## 🔢 Bitmask & Button States
+
+### Get Bitmask of Active Buttons
+
+```python
+mask = makcu.get_button_mask()
+print(f"Button mask: {mask}")
+```
+
+### Get Raw Button State Map
+
+```python
+states = makcu.get_button_states()
+print(states)  # {'left': False, 'right': True, ...}
+```
+
+### Check if a Specific Button Is Pressed
+
+```python
+if makcu.is_button_pressed(MouseButton.RIGHT):
+    print("Right button is pressed")
+```
+
+---
+
+## ⚙️ Low-Level Command Access
+
+### Send raw serial commands
+
+```python
+response = makcu.transport.send_command("km.version()", expect_response=True)
+print(response)
+```
+
+---
+
+## 🧪 Test Suite
+
+Run all tests and generate HTML report:
+
+```bash
+python -m makcu --runtest
+```
+
+---
+
+## 📚 Enumerations
+
+```python
+from makcu import MouseButton
+
+MouseButton.LEFT
+MouseButton.RIGHT
+MouseButton.MIDDLE
+MouseButton.MOUSE4
+MouseButton.MOUSE5
+```
+
+---
+
+## 🧯 Exception Handling
+
+```python
+from makcu import MakcuError, MakcuConnectionError
+
+try:
+    makcu = create_controller()
+except MakcuConnectionError as e:
+    print("Connection failed:", e)
+```
+
+---
+
+## 🛠️ Developer Notes
+
+- Uses CH343 USB Serial
+- Auto-connects to correct port or fallback
+- Supports baud rate switching to 4M
+- Automatically enables `km.buttons(1)` monitoring if `send_init=True`
+- Supports raw button state polling
+
+---
+
+## 📜 License
+
+GPL License © SleepyTotem
+
+---
+
+## Support
+Please open an issue on the project repository and I will get to it asap
+
+## 🌐 Links
+
+- 🔗 [Project Homepage](https://github.com/SleepyTotem/makcu-py-lib)

makcu-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+makcu/__init__.py,sha256=gBIXKg-TXZg3fTrWeUi97z1ezWF_pleFDbw9f6NpjKs,418
+makcu/__main__.py,sha256=tptSrqmMTrkfe23JsJT_znNXUX2orseCigEnVCeB-B0,2346
+makcu/connection.py,sha256=-lHPzMifqOOhG0ZfYGrM7SNmifBppbWYbdrm1IY5ZBY,10635
+makcu/controller.py,sha256=oFp1qrUW4xqr5FYT3SXTvHIQJxxGF2v5ysqIpZk2Dsk,6542
+makcu/enums.py,sha256=VmvCLmpghVHuTAkvCGMfA14MgWTtFVMfsGQQNnJ58Ts,126
+makcu/errors.py,sha256=4CkQ4gKa7GL5-BO3yOAJMMsy3QlUDDL42S1P1clqV4A,562
+makcu/mouse.py,sha256=KYse0Bm6rEyF8v7ujtRWDXGeUZQU5VAzKO9SxXY_O9g,5284
+makcu/utils.py,sha256=-xr6mkYITpWyAIFxHeTsZQO1V__91Sm0aFho5iWHegc,191
+makcu-0.1.1.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+makcu-0.1.1.dist-info/METADATA,sha256=Z08RUlzyhGdKSoMUrMHpvgfZy0yc_nO7u-_j1meazpU,5563
+makcu-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+makcu-0.1.1.dist-info/top_level.txt,sha256=IRO1UVb5LK_ovjau0g4oObyXQqy00tVEE-yF5lPgw1w,6
+makcu-0.1.1.dist-info/RECORD,,

makcu-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+