feat: add multi-device Logitech support and fallback layouts

Author: thisislvca

README.md

@@ -53,7 +53,7 @@
 }
 
 DEFAULT_CONFIG = {
-    "version": 3,
+    "version": 4,
     "active_profile": "default",
     "profiles": {
         "default": {
@@ -86,6 +86,7 @@
         "gesture_cooldown_ms": 500,
         "appearance_mode": "system",
         "debug_mode": False,
+        "device_layout_overrides": {},
     },
 }
 
@@ -230,9 +231,15 @@ def _migrate(cfg):
                 mappings.setdefault(key, "none")
         cfg["version"] = 3
 
+    if version < 4:
+        settings = cfg.setdefault("settings", {})
+        settings.setdefault("device_layout_overrides", {})
+        cfg["version"] = 4
+
     cfg.setdefault("settings", {})
     cfg["settings"].setdefault("appearance_mode", "system")
     cfg["settings"].setdefault("debug_mode", False)
+    cfg["settings"].setdefault("device_layout_overrides", {})
 
     # Always migrate old wmplayer.exe → Microsoft.Media.Player.exe in profile apps
     for pdata in cfg.get("profiles", {}).values():

core/config.py

@@ -0,0 +1,134 @@
+"""
+Device-layout registry for Mouser's interactive mouse view.
+
+The goal is to keep device-specific visual layout data out of QML so adding a
+new Logitech family becomes a data change instead of a UI rewrite.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+
+
+MX_MASTER_LAYOUT = {
+    "key": "mx_master",
+    "label": "MX Master family",
+    "image_asset": "mouse.png",
+    "image_width": 460,
+    "image_height": 360,
+    "interactive": True,
+    "manual_selectable": True,
+    "note": "",
+    "hotspots": [
+        {
+            "buttonKey": "middle",
+            "label": "Middle button",
+            "summaryType": "mapping",
+            "normX": 0.35,
+            "normY": 0.40,
+            "labelSide": "right",
+            "labelOffX": 100,
+            "labelOffY": -160,
+        },
+        {
+            "buttonKey": "gesture",
+            "label": "Gesture button",
+            "summaryType": "gesture",
+            "normX": 0.70,
+            "normY": 0.63,
+            "labelSide": "left",
+            "labelOffX": -200,
+            "labelOffY": 60,
+        },
+        {
+            "buttonKey": "xbutton2",
+            "label": "Forward button",
+            "summaryType": "mapping",
+            "normX": 0.60,
+            "normY": 0.48,
+            "labelSide": "left",
+            "labelOffX": -300,
+            "labelOffY": 0,
+        },
+        {
+            "buttonKey": "xbutton1",
+            "label": "Back button",
+            "summaryType": "mapping",
+            "normX": 0.65,
+            "normY": 0.40,
+            "labelSide": "right",
+            "labelOffX": 200,
+            "labelOffY": 50,
+        },
+        {
+            "buttonKey": "hscroll_left",
+            "label": "Horizontal scroll",
+            "summaryType": "hscroll",
+            "isHScroll": True,
+            "normX": 0.60,
+            "normY": 0.375,
+            "labelSide": "right",
+            "labelOffX": 200,
+            "labelOffY": -50,
+        },
+    ],
+}
+
+GENERIC_MOUSE_LAYOUT = {
+    "key": "generic_mouse",
+    "label": "Generic mouse",
+    "image_asset": "icons/mouse-simple.svg",
+    "image_width": 220,
+    "image_height": 220,
+    "interactive": False,
+    "manual_selectable": False,
+    "note": (
+        "This device is detected and the backend can still probe HID++ features, "
+        "but Mouser does not have a dedicated visual overlay for it yet."
+    ),
+    "hotspots": [],
+}
+
+MX_ANYWHERE_LAYOUT = {
+    **GENERIC_MOUSE_LAYOUT,
+    "key": "mx_anywhere",
+    "label": "MX Anywhere family",
+    "note": (
+        "MX Anywhere support is wired for device detection and HID++ probing. "
+        "A dedicated overlay image and hotspot map still need to be added."
+    ),
+}
+
+MX_VERTICAL_LAYOUT = {
+    **GENERIC_MOUSE_LAYOUT,
+    "key": "mx_vertical",
+    "label": "MX Vertical family",
+    "note": (
+        "MX Vertical uses a different physical shape, so Mouser falls back to a "
+        "generic device card until a dedicated overlay is added."
+    ),
+}
+
+
+DEVICE_LAYOUTS = {
+    "mx_master": MX_MASTER_LAYOUT,
+    "mx_anywhere": MX_ANYWHERE_LAYOUT,
+    "mx_vertical": MX_VERTICAL_LAYOUT,
+    "generic_mouse": GENERIC_MOUSE_LAYOUT,
+}
+
+
+def get_device_layout(layout_key=None):
+    layout = DEVICE_LAYOUTS.get(layout_key or "", DEVICE_LAYOUTS["generic_mouse"])
+    return deepcopy(layout)
+
+
+def get_manual_layout_choices():
+    choices = [{"key": "", "label": "Auto-detect"}]
+    for layout in DEVICE_LAYOUTS.values():
+        if layout.get("manual_selectable"):
+            choices.append({
+                "key": layout["key"],
+                "label": layout.get("label", layout["key"]),
+            })
+    return choices

core/device_layouts.py

@@ -12,6 +12,7 @@
     BUTTON_TO_EVENTS, GESTURE_DIRECTION_BUTTONS, save_config,
 )
 from core.app_detector import AppDetector
+from core.logi_devices import clamp_dpi
 
 
 class Engine:
@@ -253,6 +254,10 @@ def set_connection_change_callback(self, cb):
     def device_connected(self):
         return self.hook.device_connected
 
+    @property
+    def connected_device(self):
+        return getattr(self.hook, "connected_device", None)
+
     @property
     def enabled(self):
         return self._enabled
@@ -262,12 +267,13 @@ def enabled(self):
     # ------------------------------------------------------------------
     def set_dpi(self, dpi_value):
         """Send DPI change to the mouse via HID++."""
-        self.cfg.setdefault("settings", {})["dpi"] = dpi_value
+        dpi = clamp_dpi(dpi_value, self.connected_device)
+        self.cfg.setdefault("settings", {})["dpi"] = dpi
         save_config(self.cfg)
         # Try via the hook's HidGestureListener
         hg = self.hook._hid_gesture
         if hg:
-            return hg.set_dpi(dpi_value)
+            return hg.set_dpi(dpi)
         print("[Engine] No HID++ connection — DPI not applied")
         return False
 

core/engine.py

@@ -1,14 +1,11 @@
 """
-hid_gesture.py — Detect MX Master 3S gesture button via Logitech HID++.
+hid_gesture.py — Detect Logitech HID++ gesture controls and device features.
 
-The gesture button on a Bluetooth-connected MX Master 3S (without Logi Options+)
-often produces NO standard OS-level mouse event.  This module uses the HID++
-protocol (over hidapi) to:
-
-  1. Open the Logitech vendor-specific HID collection (UP 0xFF43).
-  2. Discover the REPROG_CONTROLS_V4 (0x1B04) feature via IRoot.
-  3. Divert the gesture button (CID 0x00C3) so we receive notifications.
-  4. Fire callbacks on gesture press / release.
+Many Logitech mice expose their gesture button and DPI/battery controls only
+through the HID++ vendor channel instead of standard OS mouse events. This
+module opens the Logitech HID interface, discovers REPROG_CONTROLS_V4 and
+related features, diverts the best gesture candidate it can find, and reports
+press/release or RawXY movement back to Mouser.
 
 Requires:  pip install hidapi
 Falls back gracefully if the package or device are unavailable.
@@ -19,6 +16,13 @@
 import threading
 import time
 
+from core.logi_devices import (
+    DEFAULT_GESTURE_CIDS,
+    build_connected_device_info,
+    clamp_dpi,
+    resolve_device,
+)
+
 try:
     import hid as _hid
     HIDAPI_OK = True
@@ -439,8 +443,7 @@ def read(self, _size, timeout_ms=0):
 FEAT_ADJ_DPI   = 0x2201      # Adjustable DPI
 FEAT_UNIFIED_BATT   = 0x1004      # Unified Battery (preferred)
 FEAT_BATTERY_STATUS = 0x1000      # Battery Status (fallback)
-DEFAULT_GESTURE_CID = 0x00C3      # "Mouse Gesture Button"
-FALLBACK_GESTURE_CIDS = (0x00D7,)
+DEFAULT_GESTURE_CID = DEFAULT_GESTURE_CIDS[0]
 
 MY_SW          = 0x0A        # arbitrary software-id used in our requests
 
@@ -548,14 +551,15 @@ def __init__(self, on_down=None, on_up=None, on_move=None,
         self._battery_feature_id = None
         self._dev_idx   = BT_DEV_IDX
         self._gesture_cid = DEFAULT_GESTURE_CID
-        self._gesture_candidates = [DEFAULT_GESTURE_CID]
+        self._gesture_candidates = list(DEFAULT_GESTURE_CIDS)
         self._held      = False
         self._connected = False         # True while HID++ device is open
         self._rawxy_enabled = False
         self._pending_dpi = None        # set by set_dpi(), applied in loop
         self._dpi_result  = None        # True/False after apply
         self._pending_battery = None
         self._battery_result = None
+        self._connected_device_info = None
 
     # ── public API ────────────────────────────────────────────────
 
@@ -580,9 +584,14 @@ def stop(self):
             except Exception:
                 pass
             self._dev = None
+        self._connected_device_info = None
         if self._thread:
             self._thread.join(timeout=3)
 
+    @property
+    def connected_device(self):
+        return self._connected_device_info
+
     # ── device discovery ──────────────────────────────────────────
 
     @staticmethod
@@ -777,13 +786,38 @@ def _discover_reprog_controls(self):
             )
         return controls
 
-    def _choose_gesture_candidates(self, controls):
+    def _choose_gesture_candidates(self, controls, device_spec=None):
         present = {c["cid"] for c in controls}
         ordered = []
-        for cid in (DEFAULT_GESTURE_CID,) + FALLBACK_GESTURE_CIDS:
+        preferred = tuple(
+            getattr(device_spec, "gesture_cids", ()) or DEFAULT_GESTURE_CIDS
+        )
+
+        def add_candidate(cid):
             if cid in present and cid not in ordered:
                 ordered.append(cid)
-        return ordered or [DEFAULT_GESTURE_CID]
+
+        for cid in preferred:
+            add_candidate(cid)
+
+        for control in controls:
+            cid = control["cid"]
+            flags = int(control.get("flags", 0) or 0)
+            mapping_flags = int(control.get("mapping_flags", 0) or 0)
+            raw_xy_capable = bool(
+                flags & 0x0100
+                or flags & 0x0200
+                or mapping_flags & 0x0010
+                or mapping_flags & 0x0040
+            )
+            virtual_or_named = bool(
+                flags & 0x0080
+                or "gesture" in KNOWN_CID_NAMES.get(cid, "").lower()
+            )
+            if raw_xy_capable and virtual_or_named and flags & 0x0020:
+                add_candidate(cid)
+
+        return ordered or list(preferred)
 
     def _divert(self):
         """Divert the selected gesture control and enable raw XY when supported."""
@@ -825,7 +859,7 @@ def _undivert(self):
     def set_dpi(self, dpi_value):
         """Queue a DPI change — will be applied on the listener thread.
         Can be called from any thread.  Returns True on success."""
-        dpi = max(200, min(8200, int(dpi_value)))  # MX Master 3S max is 8000
+        dpi = clamp_dpi(dpi_value, self._connected_device_info)
         self._dpi_result = None
         self._pending_dpi = dpi
         # Wait up to 3s for the listener thread to apply it
@@ -1027,12 +1061,17 @@ def _try_connect(self):
             pid = info.get("product_id", 0)
             up = info.get("usage_page", 0)
             usage = info.get("usage", 0)
+            product = info.get("product_string")
+            source = info.get("source", "unknown")
+            device_spec = resolve_device(product_id=pid, product_name=product)
             self._feat_idx = None
             self._dpi_idx = None
             self._battery_idx = None
             self._battery_feature_id = None
             self._gesture_cid = DEFAULT_GESTURE_CID
-            self._gesture_candidates = [DEFAULT_GESTURE_CID]
+            self._gesture_candidates = list(
+                getattr(device_spec, "gesture_cids", ()) or DEFAULT_GESTURE_CIDS
+            )
             self._rawxy_enabled = False
             open_attempts = []
             if _BACKEND_PREFERENCE in ("auto", "hidapi") and info.get("path"):
@@ -1089,7 +1128,10 @@ def _try_connect(self):
                     print(f"[HidGesture] Found REPROG_V4 @0x{fi:02X}  "
                           f"PID=0x{pid:04X} devIdx=0x{idx:02X}")
                     controls = self._discover_reprog_controls()
-                    self._gesture_candidates = self._choose_gesture_candidates(controls)
+                    self._gesture_candidates = self._choose_gesture_candidates(
+                        controls,
+                        device_spec=device_spec,
+                    )
                     print("[HidGesture] Gesture CID candidates: "
                           + ", ".join(_format_cid(cid) for cid in self._gesture_candidates))
                     # Also discover ADJUSTABLE_DPI
@@ -1109,6 +1151,13 @@ def _try_connect(self):
                             self._battery_feature_id = FEAT_BATTERY_STATUS
                             print(f"[HidGesture] Found BATTERY_STATUS @0x{batt_fi:02X}")
                     if self._divert():
+                        self._connected_device_info = build_connected_device_info(
+                            product_id=pid,
+                            product_name=product,
+                            transport=open_info.get("transport") or transport,
+                            source=source,
+                            gesture_cids=self._gesture_candidates,
+                        )
                         return True
                     break        # right device but divert failed
 
@@ -1170,8 +1219,9 @@ def _main_loop(self):
             self._pending_battery = None
             self._held = False
             self._gesture_cid = DEFAULT_GESTURE_CID
-            self._gesture_candidates = [DEFAULT_GESTURE_CID]
+            self._gesture_candidates = list(DEFAULT_GESTURE_CIDS)
             self._rawxy_enabled = False
+            self._connected_device_info = None
             if self._connected:
                 self._connected = False
                 if self._on_disconnect: