Installation Guide

This guide covers all the ways to install the Makcu Python library and get started with controlling your Makcu device.

Requirements

System Requirements:

Python 3.7 or higher
Windows, macOS, or Linux
USB port for device connection

Python Dependencies:

The Makcu library automatically installs these dependencies:

pyserial - Serial communication
asyncio - Async support (Python 3.7+)

Installation Methods

PyPI Installation (Recommended)

The easiest way to install Makcu is from PyPI using pip:

pip install makcu

This installs the latest stable version with all dependencies.

Verify Installation:

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

Install Specific Version

To install a specific version:

# Install latest v2.x
pip install "makcu>=2.0.0,<3.0.0"

# Install exact version
pip install makcu==2.3.1

From Source (Development)

For development or the latest features:

# Clone the repository
git clone https://github.com/SleepyTotem/makcu-py-lib
cd makcu-py-lib

# Install in development mode
pip install -e .

Development Installation with Dependencies:

# Install with development dependencies
pip install -e .[dev]

# Or install test dependencies
pip install -e .[test]

Virtual Environment Setup

Using venv (Recommended)

# Create virtual environment
python -m venv makcu-env

# Activate (Windows)
makcu-env\Scripts\activate

# Activate (macOS/Linux)
source makcu-env/bin/activate

# Install makcu
pip install makcu

Using conda

# Create conda environment
conda create -n makcu-env python=3.9
conda activate makcu-env

# Install makcu
pip install makcu

Docker Installation

For containerized applications:

FROM python:3.9-slim

# Install makcu
RUN pip install makcu

# Your application code
COPY . /app
WORKDIR /app

CMD ["python", "your_app.py"]

Note: USB device access in Docker requires additional configuration:

# Run with device access
docker run --device=/dev/ttyUSB0 your-image

Post-Installation Setup

Device Connection

After installation, connect your Makcu device:

Plug in your Makcu device via USB
Windows will automatically install drivers
The device appears as a COM port (Windows) or /dev/tty* (Linux/macOS)

Verify Device Connection:

from makcu import create_controller

try:
    makcu = create_controller()
    print("✅ Device connected successfully!")
    print(f"Device info: {makcu.get_device_info()}")
    makcu.disconnect()
except Exception as e:
    print(f"❌ Connection failed: {e}")

Command-Line Tools

Test your installation with built-in tools:

# Interactive debug console
python -m makcu --debug

# Test specific port
python -m makcu --testPort COM3

# Run test suite
python -m makcu --runtest

Troubleshooting Installation

Common Issues

Permission Errors (Linux/macOS):

# Add user to dialout group (Linux)
sudo usermod -a -G dialout $USER

# Log out and back in, or run:
sudo chmod 666 /dev/ttyUSB0

Driver Issues (Windows):

Download CH343 drivers from manufacturer
Install drivers manually if Windows doesn’t auto-install
Check Device Manager for COM port assignment

Python Version Issues:

# Check Python version
python --version

# Must be 3.7 or higher
# Upgrade if needed
python -m pip install --upgrade pip

Dependency Conflicts

If you encounter dependency conflicts:

# Create clean environment
python -m venv clean-env
source clean-env/bin/activate  # or activate.bat on Windows

# Install only makcu
pip install makcu

Specific Conflict Resolution:

# Force reinstall
pip install --force-reinstall makcu

# Install with no dependencies (advanced)
pip install --no-deps makcu
pip install pyserial  # Install dependencies manually

Offline Installation

For systems without internet access:

Download Packages:

# On internet-connected machine
pip download makcu -d makcu-packages/

# Transfer makcu-packages/ to offline machine

# Install offline
pip install makcu --find-links makcu-packages/ --no-index

Verification Tests

Quick Test

#!/usr/bin/env python3
"""Quick installation test"""

import sys
import makcu
from makcu import create_controller, MouseButton

def test_installation():
    print(f"✅ Makcu imported successfully")
    print(f"📦 Version: {makcu.__version__}")

    try:
        # Test controller creation
        controller = create_controller()
        print(f"✅ Controller created")

        # Test device info
        info = controller.get_device_info()
        print(f"📱 Device: {info}")

        controller.disconnect()
        print(f"✅ All tests passed!")

    except Exception as e:
        print(f"❌ Test failed: {e}")
        return False

    return True

if __name__ == "__main__":
    success = test_installation()
    sys.exit(0 if success else 1)

Full Test Suite

Run the comprehensive test suite:

# Run all tests
python -m makcu --runtest

# This will:
# 1. Test device connection
# 2. Verify all mouse functions
# 3. Check button states and locking
# 4. Generate HTML report

Upgrading

Upgrade to Latest Version

# Upgrade to latest
pip install --upgrade makcu

# Check new version
python -c "import makcu; print(makcu.__version__)"

Migration Between Versions

From v1.x to v2.x:

Most code remains compatible, but v2.x adds async support:

# v1.x code (still works)
from makcu import create_controller
makcu = create_controller()
makcu.click(MouseButton.LEFT)

# v2.x async code (new)
import asyncio
from makcu import create_async_controller

async def main():
    async with await create_async_controller() as makcu:
        await makcu.click(MouseButton.LEFT)

asyncio.run(main())

Uninstallation

To remove Makcu completely:

# Uninstall makcu
pip uninstall makcu

# Remove configuration (if any)
# Location varies by OS

Getting Help

If installation fails:

Check Requirements: Python 3.7+, pip up-to-date
Try Virtual Environment: Isolate from other packages
Update pip: python -m pip install --upgrade pip
Check Issues: GitHub Issues
Ask for Help: GitHub Discussions

System Information for Bug Reports:

import sys
import platform

print(f"Python: {sys.version}")
print(f"Platform: {platform.platform()}")
print(f"Architecture: {platform.architecture()}")

try:
    import makcu
    print(f"Makcu: {makcu.__version__}")
except ImportError as e:
    print(f"Makcu import failed: {e}")

Next Steps

After successful installation:

📖 Read the Getting Started with Makcu Python Library guide
🚀 Try the Async Usage examples
📚 Explore the api/index reference
🎮 Check out examples/index for your use case