Mouser — Logitech Mouse Remapper

• Mouser — Logitech Mouse Remapper: Detailed Description

• Mouser logo

1) Overview

• Mouser is a lightweight, open-source, fully local alternative to Logitech Options+ for remapping Logitech HID++ mice. It focuses on delivering a robust remapping experience without telemetry, cloud services, or requiring a Logitech account.
• The best experience is currently with the MX Master family, where the UI provides a dedicated overlay and responsive per-device mapping. For other Logitech models, Mouser detects devices and offers a generic or experimental layout with an aim to improve as overlays are added.
• The project emphasizes privacy, local processing, and cross-platform compatibility, targeting Windows, macOS, and Linux with native hooks and device-aware behaviors.
• The project artwork and practical UI elements are designed to be responsive and visually informative, including a device diagram for MX Master devices and clear visual indicators of connection state.

2) Featured Capabilities

• Button Remapping
• Remap any programmable button, including middle click, gesture button, back, forward, mode shift, and horizontal scroll.
• Per-application profiles automatically switch mappings when you switch apps (e.g., Chrome vs. VS Code).
• Custom keyboard shortcuts allow defining arbitrary key combinations (for example, Ctrl+Shift+P) as button actions.
• A suite of 30+ built-in actions spans navigation, browser, editing, media, and desktop shortcuts that adapt per platform.
• Device Control
• DPI / pointer speed control via a slider from 200–8000 DPI, with quick presets and live synchronization via HID++.
• Smart Shift toggle enables or disables Logitech’s ratchet-to-free-spin scroll mode switching.
• Scroll direction inversion with independent toggles for vertical and horizontal scroll.
• Gesture button plus swipe actions support: tap for a single action and directional swipes for others.
• Cross-Platform Support
• Native hooks on Windows (WHMOUSELL), macOS (CGEventTap), and Linux (evdev/uinput) ensure broad compatibility.
• Start at login on Windows (registry) and macOS (LaunchAgent), including a “Start minimized” tray-only option.
• Single instance guard ensures launching a second copy simply brings the existing window to the front.
• Smart Connectivity
• Works with both Bluetooth and Logi Bolt USB receivers; the connection type is shown in the UI.
• Auto-reconnection detects power cycles and restores full functionality without needing a restart.
• Live connection status badges in the UI show “Connected” or “Not Connected” in real time.
• Device-aware UI presents an MX Master diagram with clickable hotspots for supported devices; a generic fallback is used for others.
• Multi-Language UI
• Localized interfaces in English, Simplified Chinese, and Traditional Chinese, switchable on the fly without restart.
• Language preference is saved to config.json and restored on subsequent launches.
• Privacy-First Philosophy
• Fully local operation: all configuration data lives as a JSON file on the user’s machine.
• System tray / menu bar access remains quiet in the background with quick access from the tray.
• Zero telemetry, zero cloud, zero Logitech account required to use Mouser.

3) Screenshots and Visuals

• Mouser — Logo and Interface — The Mouse & Profiles page, showing the device-aware view with MX Master overlays for supported devices.
• Mouser — Settings Page — The Point & Scroll settings view, highlighting the DPI controls, inversion toggles, and Smart Shift options.
• The app also ships with various icons and device diagrams to help users recognize their hardware context and current state.

4) Device Coverage At a Glance

• Current device coverage highlights:
• MX Master 4 / 3S / 3 / 2S / MX Master: Yes for HID++ probing with a dedicated interactive mx_master layout.
• MX Anywhere 3S / 3 / 2S: Yes, with a generic fallback card and an experimental override option.
• MX Vertical: Yes, with a generic fallback card.
• Unknown Logitech HID++ mice: Best effort by PID/name with a generic fallback card.
• Note: Only the MX Master family currently has a dedicated visual overlay. Other devices will be detected with their model names shown in the UI and may use the experimental layout override picker, but precise overlay alignment will await additional artwork.

5) Default Mappings (Illustrative)

• Back button → Alt + Tab (Switch Windows)
• Forward button → Alt + Tab (Switch Windows)
• Middle click → Pass-through (unmapped by default to a neutral action)
• Gesture button → Pass-through (unmapped by default)
• Mode shift (scroll click) → Pass-through
• Horizontal scroll left → Browser Back
• Horizontal scroll right → Browser Forward

6) Available Actions (Adaptive by Platform)

• Navigation
• Windows: Alt+Tab, Alt+Shift+Tab, Show Desktop, Previous Desktop, Next Desktop, Task View
• macOS: Mission Control, Show Desktop, App Expose, Launchpad
• Browser
• Back, Forward, Close Tab (Ctrl+W), New Tab (Ctrl+T), Next Tab (Ctrl+Tab), Previous Tab (Ctrl+Shift+Tab)
• Editing
• Copy, Paste, Cut, Undo, Select All, Save, Find
• Media
• Volume Up, Volume Down, Volume Mute, Play/Pause, Next Track, Previous Track
• Custom
• User-defined keyboard shortcuts (any key combination)
• Other
• Do Nothing (pass-through)

7) Download & Run: Quick Start

• No install required. Just download, extract, and run.
• Windows, macOS, and Linux builds are provided:
• Windows: Mouser-Windows.zip
• macOS (Apple Silicon): Mouser-macOS.zip
• macOS (Intel): Mouser-macOS-intel.zip
• Linux: Mouser-Linux.zip
• After download, extract the ZIP and run the appropriate executable:
• Windows: Mouser.exe
• macOS: Mouser.app
• Linux: ./Mouser
• The app should open and start remapping your mouse buttons immediately. For macOS, see the macOS Setup Guide for Accessibility permissions and login-item notes.
• Screenshots and status indicators show the current device page, system tray presence, and immediate activation of mappings.
• First-time notes:
• Windows SmartScreen may warn initially; choose “More info” and then “Run anyway.”
• Logitech Options+ must not be running, or it may conflict with HID++ access.
• Configurations are saved automatically to the user’s app data directory per platform (Windows, macOS, Linux).
• How to quit:
• The window can be closed without quitting – Mouser runs in the system tray. To fully quit, right-click the tray icon and select Quit Mouser.
• Additional download guidance and per-platform nuances are described in the project’s guidance pages and setup notes.

8) Installation (From Source)

• Prerequisites
• Supported OSes: Windows 10/11, macOS 12+ (Monterey), Linux (experimental; X11 plus KDE Wayland app detection)
• Python 3.10+ (tested with 3.14)
• A supported Logitech HID++ mouse paired via Bluetooth or USB
• Logitech Options+ must not be running
• macOS: Accessibility permission required
• Linux: xdotool enables per-app profile switching on X11; kdotool enables KDE Wayland detection; Linux requires read access to /dev/input/event* and write access to /dev/uinput
• Steps to set up
• Clone the repository
• Create and activate a virtual environment
• Install dependencies from requirements.txt
• Key dependencies
• PySide6 for the UI (Qt Quick / QML)
• hidapi for HID++ communication
• Pillow for image processing (icon generation)
• macOS Quartz and Cocoa bindings for event and app support
• evdev for Linux input handling and uinput for virtual devices
• Running locally
• Run main_qml.py directly
• Optional: run in tray mode with --start-hidden
• On macOS, override HID backend debugging with --hid-backend options if needed
• Building artifacts (high level)
• Windows: use build scripts with PyInstaller; ensure hidapi is importable
• macOS: use a PyInstaller-based build and sign the bundle
• Linux: PyInstaller with Linux-specific spec file
• Desktop shortcuts
• A Mouser.lnk shortcut is included; you can create one manually with a short PowerShell script for convenience
• Notes
• Linux permissions can require udev rules to access HID devices
• Automated releases trigger builds across Windows, macOS, and Linux

9) How It Works: Architectural View

• High-level architecture

• Logitech mouse (HID++ device) communicates with Mouser’s Engine

• A central Backend routes input events through a Button Simulator to the App UI (QML) and triggers the Key Simulator

• The UI (QML) presents a device-aware layout with an MX Master diagram or a generic fallback

• A Detector determines the active foreground application and applies per-app mappings

• Core paths

• Mouse Hook intercepts button presses, wheel events, and gestures

• HID++ gesture listener diverts gesture-related controls when supported

• A device catalog resolves device IDs and associates layouts

• The Engine coordinates profile switches on app changes without restarting hooks

• Device reconnection

• HID++ layer monitors device health and attempts reconnection upon disconnection

• The Hook layer reinstalls the low-level mouse hook on device changes

• The UI reflects connection state and current device identity in real time

• Per-device and per-profile configuration

• Configurations live in an OS-specific path (Windows, macOS, Linux)

• Profiles can be named and associated with particular applications

• Global settings include DPI, inversion, gesture tuning, startup preferences, and appearance

10) App Detector, Engine, and Reconnection

• App Detector
• Periodically polls the foreground window to determine the active application
• Special handling for UWP apps to resolve the real child process
• Engine
• The central conductor that wires the hooks, simulator, and UI
• On app change, performs a lightweight profile switch to minimize latency
• Keeps the UI synchronized with the detected device identity and active layout
• Device Reconnection
• HID++ layer detects disconnection and uses a retry loop to reconnect
• Hook layer listens for device-change notifications and reinstalls hooks as needed
• UI shows up-to-date connection status and device identity

11) Configuration and Data Management

• Location
• Windows: %APPDATA%\Mouser\config.json
• macOS: ~/Library/Application Support/Mouser/config.json
• Linux: ~/.config/Mouser/config.json
• Content
• Multiple named profiles with per-profile button mappings
• Per-profile app associations (list of executable names)
• Global settings: DPI, inversion, gesture tuning, appearance, debug flags, Smart Shift, startup preferences
• Per-device layout overrides for devices lacking dedicated overlays
• Automatic migration utilities for older config versions
• Data safety
• All configuration is local; there is no cloud dependency or telemetry

12) Project Structure (High-Level View)

• mouser/
• main_qml.py – Application entry point (PySide6 + QML)
• Mouser.bat – Quick-launch batch file
• Mouser-mac.spec – Native macOS app-bundle spec
• Mouser-linux.spec – Linux PyInstaller spec
• buildmacOSapp.sh – macOS bundle build, icon handling, and signing flow
• .github/workflows/ci.yml – CI checks: compile, tests, QML lint
• .github/workflows/release.yml – Automated release builds
• readmemacosx.md – macOS-specific instructions
• requirements.txt – Python dependencies
• mouser/ – Core backend and UI bridge
  • core/ – Backend logic
  • accessibility.py – macOS accessibility checks
  • engine.py – Core engine
  • mouse_hook.py – Low-level mouse hook + HID++ gesture listening
  • hid_gesture.py – HID++ 2.0 gesture diversion
  • logi_devices.py – Logitech device catalog
  • device_layouts.py – Layout registry for overlays
  • key_simulator.py – Platform-specific action simulation
  • startup.py – Cross-platform login startup
  • config.py – Config management
  • app_detector.py – Foreground app polling
  • ui/ – UI layer
  • backend.py – QML ↔ Python bridge
  • qml/ – QML app shell, pages, and components
    • Main.qml – App shell (sidebar + page stack + tray toast)
    • MousePage.qml – Device-aware layout and profile manager
    • ScrollPage.qml – DPI and inversion controls
    • HotspotDot.qml – Interactive overlay for MX Master hotspots
    • ActionChip.qml – Action pills
    • Theme.js – Shared colors and constants
  • images/ – App icons; logo; device diagrams
    • AppIcon.icns
    • mouse.png
    • icons/mouse-simple.svg
    • logo.png
    • logo.ico
    • logo_icon.png
    • chrom.png
    • VSCODE.png
    • VLC.png
    • media.webp
• Licensing and acknowledgments
• MIT License
• Not affiliated with or endorsed by Logitech

13) User Interface Overview

• UI pages and navigation
• Mouse & Profiles (Page 1)
  • Left panel: Profiles list, with Default (All Apps) always present
  • Right panel: Device-aware mouse view; MX Master devices show clickable hotspot overlays
  • Add profile: A bottom combo box lists known apps (Chrome, Edge, VS Code, VLC, etc.); click the plus icon to create a per-app profile
• Point & Scroll (Page 2)
  • DPI slider with presets (200–8000 DPI) and a live read of the device’s current DPI
  • Independent vertical and horizontal scroll inversion toggles
  • Smart Shift toggle for the ratchet-to-free-spin feature
  • Startup controls: Start at login and Start minimized options to launch at startup or minimized to tray
• Device overlays and fallback
• MX Master devices feature a dedicated interactive overlay
• Other devices use a generic device card with an experimental map override picker
• The UI shows the device name when a model overlay is not available

14) Known Limitations

• Early multi-device support
• Only MX Master family has a dedicated interactive overlay; others use a generic fallback
• Per-device mappings vs. per-profile scoping
• Layout overrides are per device; profile mappings are global, not fully per-device
• HID++ and connection compatibility
• Works with Bluetooth and Logi Bolt; conflict with Logitech Options+ may occur if both are running
• Scroll inversion
• Inversion is experimental and may not work perfectly in all apps due to injection latency
• Admin rights
• Elevated windows or certain games may not receive injected keystrokes
• Linux validation
• X11 using xdotool and KDE Wayland via kdotool; GNOME/Wayland may require fallback behavior
• Per-device remapping requires device permissions to /dev/input/event* and /dev/uinput; HID++ features additionally require access to /dev/hidraw*
• Practical udev setup
• Linux users may need to create a udev rule to allow HID++ access without root

15) Future Work and Roadmap

• [ ] Dedicated overlays for more devices (MX Anywhere, MX Vertical, and others)
• [ ] True per-device config separation (multi-mouse usage on a single machine)
• [ ] Dynamic button inventory (discover REPROGCONTROLSV4 controls dynamically)
• [x] Custom key combos (arbitrary key sequences)
• [x] Windows login item support (cross-platform startup)
• [ ] Improved scroll inversion solutions (driver-level or interception-based approaches)
• [ ] Gesture swipe tuning for reliability across more devices
• [ ] Per-app profile auto-creation prompts
• [ ] Export/import of configurations for cross-machine sharing
• [x] macOS support via CGEventTap, Quartz, and NSWorkspace
• [ ] Broader Wayland support and Linux validation across more distros
• [ ] Plugin system for third-party action providers

16) How to Contribute

• Contributions are welcome. To get involved:
• Fork the repository and create a feature branch
• Set up the development environment as described in Installation
• Implement changes and test with a supported Logitech HID++ mouse (MX Master family preferred)
• Submit a pull request with a clear description
• Areas where help is needed
• Testing with other Logitech HID++ devices
• Scroll inversion improvements
• Broader Linux/Wayland validation
• UI/UX polishing and accessibility enhancements

17) Support and Community

• If Mouser helps you avoid installing Logitech Options+, consider supporting development:
• Sponsor badge: Sponsor
• Your sponsorship supports ongoing maintenance and feature development

18) Licensing

• This project is licensed under the MIT License.

• Acknowledgments

• [@andrew-sz] — macOS port: CGEventTap mouse hooking, Quartz key simulation, NSWorkspace app detection

• [@thisislvca] — major expansion including multi-device support, new UI features, and issue triage

• [@awkure] — login startup, single-instance guard, start minimized, MX Master 4 detection

• [@hieshima] — Linux support, LCD gestures, and reliability improvements; macOS CGEventTap improvements

• [@pavelzaichyk] — Next Tab/Previous Tab actions, persistent rotating log storage, HID++ enhancements

• [@nellwhoami] — Multi-language UI and navigation actions

• [@guilamu] — per-mouse button remapping improvements and HID++ stability fixes

• Legal note

• Mouser is not affiliated with or endorsed by Logitech. Logitech, MX Master, and Options+ are trademarks of Logitech International S.A.

• Visual references from the input are incorporated above to reflect the real UI and branding, ensuring that the description remains faithful to the original Mouser project materials.