Command Line Interface

The Makcu Python Library provides several command-line tools for testing, debugging, and development. These tools are accessible through Python’s module execution syntax.

Overview

All command-line tools are accessed via:

python -m makcu [OPTION]

Available Options

--debug

Launches an interactive debug console where you can send raw commands directly to your Makcu device and see live responses.

Usage:

python -m makcu --debug

Features: - Real-time command execution - Live response monitoring - Connection status display - Error handling and reporting - Exit with quit or exit

Example Session:

🔧 Makcu Debug Console
Type a raw command (e.g., km.version()) and press Enter.
Type 'exit' or 'quit' to leave

> km.version()
Response: km.MAKCU

> km.move(100,50)
Response: km.move(100,50)

> km.click(1)
Response: km.click(1)

> quit
Disconnecting...

--testPort

Tests connection to a specific COM port and reports success or failure.

Usage:

python -m makcu --testPort COM3
python -m makcu --testPort /dev/ttyUSB0  # Linux/macOS

Output Examples:

Successful connection:

Trying to connect to COM1...
✅ Successfully connected to COM1.

Failed connection:

Testing connection to COM2...
❌ Port COM2 does not exist. Please check the port name.

Use Cases: - Verify device connectivity - Troubleshoot connection issues - Identify correct COM port - Automated testing scripts

--runtest

Executes the complete test suite using pytest and generates a detailed HTML report.

Usage:

python -m makcu --runtest

What it does: 1. Runs test_suite.py with pytest 2. Generates latest_pytest.html report 3. Automatically opens the report in your default browser 4. Provides comprehensive test results

Test Categories: - Port connection tests - Mouse movement accuracy - Button control verification - Locking mechanism tests - Performance benchmarks

Example Output:

Running Makcu Test Suite...
============================

test_suite.py::test_connect_to_port PASSED          [ 10%]
test_suite.py::test_firmware_version PASSED         [ 20%]
test_suite.py::test_mouse_movement PASSED           [ 30%]
test_suite.py::test_button_control PASSED           [ 40%]
test_suite.py::test_button_locking PASSED           [ 50%]
test_suite.py::test_performance_timing PASSED       [ 60%]
test_suite.py::test_batch_commands PASSED           [ 70%]
test_suite.py::test_human_like_clicking PASSED      [ 80%]
test_suite.py::test_auto_reconnection PASSED        [ 90%]
test_suite.py::test_async_operations PASSED         [100%]

==================== 10 passed, 0 failed ====================

HTML report generated: latest_pytest.html
Opening report in browser...

Error Handling

All command-line tools include comprehensive error handling:

Device Not Found:

Error: No Makcu device found
Solutions:
- Check USB connection
- Verify device is powered on
- Try different USB port
- Check device manager (Windows)
- Install device drivers (Makcu Discord Server)

Permission Errors:

Error: Permission denied accessing COM port
Solutions:
- Run as administrator (Windows)
- Add user to dialout group (Linux)
- Check port permissions

Invalid Arguments:

Unknown command: --invalid

Usage: python -m makcu [OPTION]
Options:
  --debug      Interactive debug console
  --testPort   Test specific port connection
  --runtest    Run complete test suite

Integration with Scripts

The command-line tools can be integrated into automated workflows:

Batch Testing:

#!/bin/bash
# test_makcu.sh

echo "Testing Makcu device..."
python -m makcu --testPort COM3

if [ $? -eq 0 ]; then
    echo "Running full test suite..."
    python -m makcu --runtest
else
    echo "Device not ready, skipping tests"
fi

CI/CD Integration:

# .github/workflows/test.yml
name: Test Makcu Library

steps:
  - name: Install dependencies
    run: pip install makcu pytest

  - name: Test device connection
    run: python -m makcu --testPort COM3

  - name: Run test suite
    run: python -m makcu --runtest

Python Script Integration:

import subprocess
import sys

def test_device_ready():
    """Test if Makcu device is ready"""
    result = subprocess.run([
        sys.executable, '-m', 'makcu', '--testPort', 'COM3'
    ], capture_output=True, text=True)

    return result.returncode == 0

if test_device_ready():
    print("Device ready")
else:
    print("Device not available")

Advanced Usage

Debug Console with Logging:

python -m makcu --debug

Automated Port Testing:

# Test multiple ports
for port in COM3 COM4 COM5; do
    echo "Testing $port..."
    python -m makcu --testPort $port
done

Performance Monitoring

The command-line tools provide performance insights:

Test Suite Benchmarks:

The --runtest option includes performance benchmarks that compare current performance against baseline metrics, helping identify performance regressions.

Port Testing:

The --testPort option measures connection establishment, useful for optimizing connection parameters.

Troubleshooting

Common Issues:

1. “Module not found” error:

   pip install makcu
   

2. “No device found” repeatedly:

   • Check device manager

   • Try different USB ports

   • Restart device

   • Update drivers

3. Permission denied on Linux/macOS:

   sudo usermod -a -G dialout $USER
   # Then log out and back in
   

4. Tests fail intermittently:

   • Check USB cable quality

   • Reduce USB hub usage

   • Close other serial applications

Exit Codes

All command-line tools return standard exit codes:

• 0: Success

• 1: General error

• 2: Device not found

• 3: Permission denied

• 4: Timeout

• 5: Invalid arguments