{"id":31574069,"url":"https://github.com/jiahaoxiang2000/mouse-gesture","last_synced_at":"2025-10-05T15:42:33.680Z","repository":{"id":296001477,"uuid":"991843822","full_name":"jiahaoxiang2000/mouse-gesture","owner":"jiahaoxiang2000","description":"A Rust-based gesture recognition tool for Apple Magic Mouse on Linux, specifically designed for the Magic Mouse 2 USB-C 2024 model.","archived":false,"fork":false,"pushed_at":"2025-07-16T09:13:48.000Z","size":111,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-02T21:38:59.884Z","etag":null,"topics":["apple","magic-mouse","mouse-gestures"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jiahaoxiang2000.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-28T08:27:14.000Z","updated_at":"2025-07-16T09:13:52.000Z","dependencies_parsed_at":"2025-06-03T00:17:46.266Z","dependency_job_id":null,"html_url":"https://github.com/jiahaoxiang2000/mouse-gesture","commit_stats":null,"previous_names":["jiahaoxiang2000/mouse-gesture"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jiahaoxiang2000/mouse-gesture","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiahaoxiang2000%2Fmouse-gesture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiahaoxiang2000%2Fmouse-gesture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiahaoxiang2000%2Fmouse-gesture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiahaoxiang2000%2Fmouse-gesture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jiahaoxiang2000","download_url":"https://codeload.github.com/jiahaoxiang2000/mouse-gesture/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiahaoxiang2000%2Fmouse-gesture/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278477817,"owners_count":25993540,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple","magic-mouse","mouse-gestures"],"created_at":"2025-10-05T15:42:32.074Z","updated_at":"2025-10-05T15:42:33.674Z","avatar_url":"https://github.com/jiahaoxiang2000.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Magic Mouse Gesture Recognition\n\nA Rust-based gesture recognition tool for Apple Magic Mouse on Linux, specifically designed for the Magic Mouse 2 USB-C 2024 model.\n\n## Features\n\n- **Multi-touch gesture recognition**: Detects swipes, scrolls, taps, and pinch gestures\n- **Two-finger tap recognition**: Advanced two-finger tap detection based on Linux Multi-Touch Protocol\n- **Configurable actions**: Execute custom commands for each gesture\n- **Direct input handling**: Works with raw input events from evdev\n- **Async processing**: Non-blocking event processing using Tokio\n- **Customizable configuration**: JSON-based configuration system\n\n## Supported Gestures\n\n- **2-finger swipes**: Navigate browser history, open/close tabs\n- **Scrolling**: Vertical and horizontal scrolling\n- **Taps**: Single and double-finger taps for click simulation\n- **Pinch**: Zoom in/out functionality\n- **Button clicks**: Standard mouse button support\n\n## Prerequisites\n\n### Hardware Requirements\n\n- Apple Magic Mouse 2 USB-C 2024\n- Linux system with evdev support\n\n### Software Requirements\n\n- Rust 1.70+ (for building)\n- `hid-magicmouse` kernel module (see [setup guide](docs/apple.md))\n- `xdotool` (for executing actions)\n\n### Installation of Dependencies\n\nOn Arch Linux:\n\n```bash\nsudo pacman -S xdotool\n```\n\nOn Ubuntu/Debian:\n\n```bash\nsudo apt install xdotool\n```\n\n## Installation\n\n### Automated Installation (Recommended)\n\nThe easiest way to install Magic Mouse Gesture Recognition is using the automated installation script:\n\n```bash\ngit clone \u003crepository-url\u003e\ncd mouse-gesture\n\n# Run the installation script\n./scripts/install.sh\n```\n\nThe installation script will:\n- Install Rust dependencies and build the project\n- Copy the binary to `/usr/local/bin`\n- Set up configuration in `~/.config/mouse-gesture/`\n- Create udev rules for device access\n- Add your user to the `input` group\n- Install and configure a systemd user service\n- Set up automatic startup\n\nAfter installation:\n```bash\n# Start the service immediately\nsystemctl --user start mouse-gesture.service\n\n# Enable automatic startup on login\nsystemctl --user enable mouse-gesture.service\n```\n\n### Manual Installation\n\nIf you prefer to build and configure manually:\n\n1. Clone the repository:\n\n```bash\ngit clone \u003crepository-url\u003e\ncd mouse-gesture\n```\n\n2. Build the project:\n\n```bash\ncargo build --release\n```\n\n### Uninstallation\n\nTo completely remove the application:\n\n```bash\n./scripts/uninstall.sh\n```\n\n## Configuration\n\nThe application will create a default configuration file `config.json` on first run. You can customize gestures and actions by editing this file.\n\n### Example Configuration\n\n```json\n{\n  \"device\": {\n    \"path\": null,\n    \"auto_detect\": true,\n    \"name_pattern\": \"Magic Mouse\"\n  },\n  \"gesture\": {\n    \"scroll_threshold\": 2.0,\n    \"swipe_threshold\": 12.0,\n    \"pinch_threshold\": 0.1,\n    \"tap_timeout_ms\": 300,\n    \"debounce_ms\": 100\n  },\n  \"actions\": {\n    \"swipe_left_2finger\": \"xdotool key alt+Right\",\n    \"swipe_right_2finger\": \"xdotool key alt+Left\",\n    \"swipe_up_2finger\": \"xdotool key ctrl+t\",\n    \"swipe_down_2finger\": \"xdotool key ctrl+w\",\n    \"scroll_vertical\": \"scroll_vertical\",\n    \"scroll_horizontal\": \"scroll_horizontal\",\n    \"tap_1finger\": \"click\",\n    \"tap_2finger\": \"right_click\",\n    \"pinch_in\": \"xdotool key ctrl+minus\",\n    \"pinch_out\": \"xdotool key ctrl+plus\"\n  }\n}\n```\n\n## Usage\n\n### Basic Usage\n\nAfter installation, the service runs automatically. For manual testing or development:\n\n```bash\n# Check system dependencies and device detection\nmouse-gesture-recognition --check-deps\n\n# Run manually with auto-detection (for testing)\nmouse-gesture-recognition\n\n# Specify device path explicitly\nmouse-gesture-recognition -d /dev/input/event26\n\n# Enable verbose logging for debugging\nmouse-gesture-recognition -v\n\n# Run directly from build directory (before installation)\nsudo ./target/release/mouse-gesture-recognition --check-deps\n```\n\n**Note**: After installation, no `sudo` is required as the application runs with user permissions and accesses devices through proper group membership.\n\n### Finding Your Device\n\nUse `evtest` to find your Magic Mouse device:\n\n```bash\nsudo evtest\n```\n\nLook for a device with \"Magic Mouse\" in the name and note its event number.\n\n### Finding Your Device Event Number\n\nTo find out which `/dev/input/eventX` device corresponds to your Magic Mouse:\n\n1. Run the following command:\n\n```fish\nsudo evtest\n```\n\n2. You will see a list of input devices. Look for one with \"Magic Mouse\" in the name. Note the event number (e.g., `/dev/input/event27`).\n\n3. Select that number when prompted, or use it directly:\n\n```fish\nevtest /dev/input/event27\n```\n\n4. Move or tap your Magic Mouse. If you see events appear, you have found the correct device.\n\nIf you want to check without root, add your user to the `input` group and log out/in:\n\n```fish\nsudo usermod -aG input (whoami)\n```\n\nIf you do not want to log out, you can use `newgrp input` to start a new shell with the new group applied immediately:\n\n```fish\nnewgrp input\n```\n\nThen use `evtest` without `sudo` in that shell.\n\n### Running as a Service\n\nThe installation script automatically sets up a systemd user service. After installation:\n\n```bash\n# Enable the service to start automatically\nsystemctl --user enable mouse-gesture.service\n\n# Start the service\nsystemctl --user start mouse-gesture.service\n\n# Check service status\nsystemctl --user status mouse-gesture.service\n\n# View service logs\njournalctl --user -u mouse-gesture.service -f\n```\n\nThe service is configured to:\n- Start automatically when you log in\n- Restart automatically if it crashes\n- Run with your user permissions (no root required)\n- Access the configuration in `~/.config/mouse-gesture/config.json`\n\nYou can also use the provided service management script:\n\n```bash\n# Service management\n./scripts/service.sh start      # Start the service\n./scripts/service.sh stop       # Stop the service\n./scripts/service.sh restart    # Restart the service\n./scripts/service.sh status     # Check service status\n./scripts/service.sh enable     # Enable automatic startup\n./scripts/service.sh disable    # Disable automatic startup\n\n# Monitoring and configuration\n./scripts/service.sh logs       # View service logs\n./scripts/service.sh edit-config # Edit configuration file\n```\n\n### Additional Management Scripts\n\nThe project includes several utility scripts:\n\n```bash\n# Development helpers\n./scripts/dev.sh build          # Build project\n./scripts/dev.sh run            # Run directly (not as service)\n./scripts/dev.sh test           # Run tests\n./scripts/dev.sh clean          # Clean build artifacts\n\n# Build system\nmake install                    # Same as ./scripts/install.sh\nmake uninstall                  # Same as ./scripts/uninstall.sh\nmake build                      # Build project\nmake run                        # Run project\n```\n\n## Permissions\n\nThe application runs with user privileges and accesses input devices through proper group membership. The installation script:\n\n1. Adds your user to the `input` group for device access\n2. Sets up udev rules for Magic Mouse devices\n3. Configures appropriate file permissions\n\nNo root privileges are required for normal operation. The service runs as your user account with access to:\n- Input devices (via `input` group membership)\n- Your desktop environment for executing actions\n- User configuration directory (`~/.config/mouse-gesture/`)\n\n## Troubleshooting\n\n### Device Not Found\n\n- Ensure the Magic Mouse is connected and paired\n- Check that the `hid-magicmouse` module is loaded\n- Verify the device path with `ls /dev/input/event*`\n\n### Gestures Not Recognized\n\n- Enable verbose logging with `-v` flag\n- Check the gesture thresholds in configuration\n- Ensure multi-touch events are being generated\n\n### Actions Not Executing\n\n- Run `--check-deps` to verify system dependencies\n- Check that `xdotool` is installed and working\n- Verify the command syntax in configuration\n\n## Development\n\n### Project Structure\n\n```\nsrc/\n├── main.rs           # Application entry point\n├── device.rs         # Magic Mouse device handling\n├── gesture.rs        # Gesture recognition algorithms\n├── config.rs         # Configuration management\n└── event_handler.rs  # Action execution\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT OR Apache-2.0 license.\n\n## Acknowledgments\n\n- [Linux Magic Trackpad 2 USB-C Driver](https://github.com/mr-cal/Linux-Magic-Trackpad-2-USB-C-Driver) for the kernel module\n- The evdev and Rust community for excellent libraries\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiahaoxiang2000%2Fmouse-gesture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjiahaoxiang2000%2Fmouse-gesture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiahaoxiang2000%2Fmouse-gesture/lists"}