🖱️ Remote Mouse Pro

A professional, production-ready remote mouse and keyboard controller for cross-platform use.

Transform your smartphone into a wireless mouse, keyboard, and presentation remote. Control your computer seamlessly over WiFi with a beautiful, intuitive interface.

✨ Features

🎯 Core Functionality

• Wireless Mouse Control - Smooth, responsive cursor movement
• Virtual Keyboard - Type text directly from your phone
• Multi-touch Gestures - Tap, long-press, and drag support
• Scroll Support - Vertical and horizontal scrolling
• Right-click Context Menu - Full mouse button support

🚀 Professional Features

• Auto-Discovery - Automatically finds servers on your network
• Manual Connection - Connect by IP for advanced setups
• Secure PIN Authentication - Password protection
• Cross-Platform - Works on Windows, macOS, and Linux
• Modern UI - Material Design 3 with dark/light themes
• Haptic Feedback - Tactile response for better user experience
• Connection Management - Auto-reconnect with smart retry logic

⚡ Advanced Controls

• Common Hotkeys - Copy, Paste, Undo, Redo, Alt+Tab
• System Shortcuts - Search, Close, Fullscreen toggles
• Custom Key Combinations - Extensible hotkey system
• OS-Specific Mapping - Proper Cmd/Ctrl key handling

📱 Screenshots

Discovery Screen	Connected Control	Settings

🛠️ Quick Start

Prerequisites

• Python 3.8+ on your computer
• Flutter development environment for mobile app
• Both devices connected to the same WiFi network

1. Server Setup (Computer)

# Clone the repository
git clone https://github.com/yourusername/remote-mouse-pro.git
cd remote-mouse-pro

# Install Python dependencies
pip install -r requirements.txt

# Run the server
python3 remote_mouse_server.py

2. Mobile App Setup

# Navigate to Flutter app directory
cd flutter_app

# Install dependencies
flutter pub get

# Run on connected device
flutter run

# Or build APK for Android
flutter build apk --release

3. Connect and Control!

1. Open the app on your phone
2. Wait for auto-discovery or connect manually
3. Enter the PIN shown in server console
4. Start controlling your computer!

🔧 Configuration

Server Configuration

Edit the CONFIG section in remote_mouse_server.py:

CONFIG = {
    "pin": "123456",              # Change this for security
    "ws_port": 8765,              # WebSocket port
    "discovery_port": 9876,       # UDP discovery port  
    "server_name": "My Computer", # Display name
    "max_connections": 10,        # Max simultaneous clients
}

Network Setup

Firewall Ports:

• 8765 - WebSocket communication
• 9876 - UDP device discovery

Windows Firewall:

netsh advfirewall firewall add rule name="Remote Mouse WS" dir=in action=allow protocol=TCP localport=8765
netsh advfirewall firewall add rule name="Remote Mouse Discovery" dir=in action=allow protocol=UDP localport=9876

Linux/macOS:

sudo ufw allow 8765/tcp
sudo ufw allow 9876/udp

🏗️ Architecture

┌─────────────────┐    WiFi Network    ┌──────────────────┐
│   Flutter App   │◄──────────────────►│  Python Server  │
│  (Mobile/Web)   │                    │   (Computer)     │
├─────────────────┤                    ├──────────────────┤
│ • UI/UX Layer   │    WebSocket       │ • Mouse Control  │
│ • Auto Discovery│◄──────────────────►│ • Keyboard Input │
│ • Connection    │                    │ • OS Integration │
│   Management    │    UDP Broadcast   │ • Multi-client   │
│ • Input Capture │◄──────────────────►│ • Authentication │
└─────────────────┘                    └──────────────────┘

Technology Stack

Backend (Python):

• websockets - Real-time WebSocket communication
• pynput - Cross-platform input control
• asyncio - Asynchronous server architecture

Frontend (Flutter):

• web_socket_channel - WebSocket client
• shared_preferences - Settings persistence
• Material Design 3 - Modern UI framework

📋 API Reference

WebSocket Message Protocol

Authentication:

{
  "t": "hello",
  "pin": "123456"
}

Mouse Movement:

{
  "t": "move", 
  "dx": 10.5,
  "dy": -5.2
}

Mouse Click:

{
  "t": "click",
  "btn": "left|right|middle",
  "down": true|false  // Optional: press/release
}

Keyboard Input:

{
  "t": "key",
  "text": "Hello World"
}

Hotkey Combination:

{
  "t": "hotkey",
  "keys": ["cmd", "c"]
}

Scroll Wheel:

{
  "t": "scroll",
  "dx": 0,
  "dy": 1
}

🔍 Troubleshooting

Common Issues

❌ "No servers found"

• Ensure both devices are on same WiFi network
• Check firewall settings allow ports 8765 and 9876
• Try manual connection with computer's IP address

❌ "Connection failed"

• Verify PIN matches server console output
• Confirm server is running and accessible
• Check network connectivity between devices

❌ "Permission denied" (Linux/macOS)

• Run server with appropriate permissions for input control
• Some distributions require additional setup for input devices

❌ Server suspended on Ctrl+Z

• Fixed in latest version with OS-specific key mapping
• Server maps hotkeys appropriately for each operating system

Manual Connection

1. Find your computer's IP address:

   # Windows
   ipconfig
   
   # macOS/Linux  
   ifconfig

2. In the app, tap the "+" icon and enter IP manually

Getting Help

• Issues: Open a GitHub issue with detailed logs
• Features: Submit feature requests via GitHub
• Security: Report vulnerabilities privately

🧪 Development

Project Structure

remote-mouse-pro/
├── remote_mouse_server.py    # Python WebSocket server
├── requirements.txt          # Python dependencies  
├── flutter_app/              # Flutter mobile application
│   ├── lib/
│   │   └── main.dart        # Main Flutter code
│   ├── pubspec.yaml         # Flutter dependencies
│   └── android/             # Android-specific files
├── screenshots/             # App screenshots
└── docs/                   # Additional documentation

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Commit changes: git commit -am 'Add feature'
4. Push to branch: git push origin feature-name
5. Submit a Pull Request

Testing

Server Testing:

python -m pytest tests/

Flutter Testing:

flutter test

📊 Performance

• Latency: < 50ms on local networks
• Battery Usage: Optimized for extended use
• Memory Footprint:
  • Server: ~15MB RAM
  • Mobile App: ~25MB RAM
• Network Usage: Minimal bandwidth requirements

🔐 Security

• PIN Authentication - Secure connection establishment
• Local Network Only - No internet communication required
• No Data Storage - No sensitive information stored
• Open Source - Full code transparency

Security Best Practices:

• Change default PIN in production environments
• Use on trusted networks only
• Keep software updated
• Monitor server logs for suspicious activity

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2024 Remote Mouse Pro

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🤝 Acknowledgments

• pynput - Cross-platform input control library
• websockets - Robust WebSocket implementation
• Flutter - Beautiful cross-platform UI framework
• Material Design - Google's design system
• Open Source Community - For tools and inspiration

🚀 Roadmap

v2.1.0 (Next Release)

• Presentation Mode - Slide navigation controls
• Media Controls - Volume, play/pause, skip
• File Transfer - Drag and drop support
• Multi-Monitor - Screen selection support

v2.2.0 (Future)

• Voice Commands - Speech-to-text input
• Gesture Customization - User-defined actions
• Remote Desktop - Screen viewing capability
• Cloud Sync - Settings synchronization

v3.0.0 (Long-term)

• Direct WiFi - Connection without router
• Bluetooth Support - Alternative connectivity
• AR Integration - Augmented reality controls
• Team Collaboration - Multi-user sessions

---

⭐ Star this project if you find it useful!

Report Bug • Request Feature • Documentation

Built with ❤️ for the developer community