From cff0110f81e7097aa2ad6ffd94e3d434e1feb082 Mon Sep 17 00:00:00 2001
From: "Peter F. Patel-Schneider" <pfpschneider@gmail.com>
Date: Thu, 30 Oct 2025 06:01:51 -0400
Subject: [PATCH] settings: add scroll ratchet force setting

---
 docs/devices/MX Master 4.text               | Bin 0 -> 7969 bytes
 lib/logitech_receiver/settings_templates.py |  36 ++++++++++++++++++++
 lib/logitech_receiver/settings_validator.py |   9 ++---
 3 files changed, 41 insertions(+), 4 deletions(-)
 create mode 100644 docs/devices/MX Master 4.text

diff --git a/docs/devices/MX Master 4.text b/docs/devices/MX Master 4.text
new file mode 100644
index 0000000000000000000000000000000000000000..aedfc34ae2d0430cbad0fb903dea635068a66f99
GIT binary patch
literal 7969
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
G$@~jyM<_S|

literal 0
HcmV?d00001

diff --git a/lib/logitech_receiver/settings_templates.py b/lib/logitech_receiver/settings_templates.py
index 9c8c4d6d..9f1616e0 100644
--- a/lib/logitech_receiver/settings_templates.py
+++ b/lib/logitech_receiver/settings_templates.py
@@ -99,8 +99,11 @@ class State(enum.Enum):
 #   mask is used to keep only some bits from a sequence of bits, this can be an integer or a byte string,
 #   read_skip_byte_count is the number of bytes to ignore at the beginning of the read value (default 0),
 #   write_prefix_bytes is a byte string to write before the value (default empty).
+
 # RangeValidator is for an integer in a range.  It takes
 #   byte_count is number of bytes that the value is stored in (defaults to size of max_value).
+#   read_skip_byte_count is as for BooleanV
+#   write_prefix_bytes is as for BooleanV
 # RangeValidator uses min_value and max_value from the setting class as minimum and maximum.
 
 # ChoicesValidator is for symbolic choices.  It takes one positional and three keyword arguments:
@@ -698,6 +701,38 @@ class ScrollRatchetEnhanced(ScrollRatchet):
     rw_options = {"read_fnid": 0x10, "write_fnid": 0x20}
 
 
+class ScrollRatchetTorque(settings.Setting):
+    name = "scroll-ratchet-torque"
+    label = _("Scroll Wheel Ratchet Torque")
+    description = _("Change the torque needed to overcome the ratchet.")
+    feature = _F.SMART_SHIFT_ENHANCED
+    min_value = 1
+    max_value = 100
+    rw_options = {"read_fnid": 0x10, "write_fnid": 0x20}
+
+    class rw_class(settings.FeatureRW):
+        def write(self, device, data_bytes):
+            ratchetSetting = next(filter(lambda s: s.name == "scroll-ratchet", device.settings), None)
+            if ratchetSetting:  # for MX Master 4, the ratchet setting needs to be written for changes to take effect
+                ratchet_value = ratchetSetting.read(True)
+                data_bytes = ratchet_value.to_bytes(1, "big") + data_bytes[1:]
+            result = super().write(device, data_bytes)
+            return result
+
+    class validator_class(settings_validator.RangeValidator):
+        @classmethod
+        def build(cls, setting_class, device):
+            reply = device.feature_request(_F.SMART_SHIFT_ENHANCED, 0x00)
+            if reply[0] & 0x01:  # device supports tunable torque
+                return cls(
+                    min_value=setting_class.min_value,
+                    max_value=setting_class.max_value,
+                    byte_count=1,
+                    write_prefix_bytes=b"\x00\x00",  # don't change mode or disengage, but see above
+                    read_skip_byte_count=2,
+                )
+
+
 # the keys for the choice map are Logitech controls (from special_keys)
 # each choice value is a NamedInt with the string from a task (to be shown to the user)
 # and the integer being the control number for that task (to be written to the device)
@@ -1756,6 +1791,7 @@ SETTINGS: list[settings.Setting] = [
     HiresSmoothResolution,  # working
     HiresMode,  # simple
     ScrollRatchet,  # simple
+    ScrollRatchetTorque,
     SmartShift,  # working
     ScrollRatchetEnhanced,
     SmartShiftEnhanced,  # simple
diff --git a/lib/logitech_receiver/settings_validator.py b/lib/logitech_receiver/settings_validator.py
index cd241d4d..ddc164ff 100644
--- a/lib/logitech_receiver/settings_validator.py
+++ b/lib/logitech_receiver/settings_validator.py
@@ -531,12 +531,13 @@ class RangeValidator(Validator):
         kwargs["max_value"] = setting_class.max_value
         return cls(**kwargs)
 
-    def __init__(self, min_value=0, max_value=255, byte_count=1):
+    def __init__(self, min_value=0, max_value=255, byte_count=1, read_skip_byte_count=0, write_prefix_bytes=b""):
         assert max_value > min_value
         self.min_value = min_value
         self.max_value = max_value
+        self.read_skip_byte_count = read_skip_byte_count
+        self.write_prefix_bytes = write_prefix_bytes
         self.needs_current_value = True  # read and check before write (needed for ADC power and probably a good idea anyway)
-
         self._byte_count = math.ceil(math.log(max_value + 1, 256))
         if byte_count:
             assert self._byte_count <= byte_count
@@ -544,7 +545,7 @@ class RangeValidator(Validator):
         assert self._byte_count < 8
 
     def validate_read(self, reply_bytes):
-        reply_value = common.bytes2int(reply_bytes[: self._byte_count])
+        reply_value = common.bytes2int(reply_bytes[self.read_skip_byte_count : self.read_skip_byte_count + self._byte_count])
         assert reply_value >= self.min_value, f"{self.__class__.__name__}: failed to validate read value {reply_value:02X}"
         assert reply_value <= self.max_value, f"{self.__class__.__name__}: failed to validate read value {reply_value:02X}"
         return reply_value
@@ -553,7 +554,7 @@ class RangeValidator(Validator):
         if new_value < self.min_value or new_value > self.max_value:
             raise ValueError(f"invalid choice {new_value!r}")
         current_value = self.validate_read(current_value) if current_value is not None else None
-        to_write = common.int2bytes(new_value, self._byte_count)
+        to_write = self.write_prefix_bytes + common.int2bytes(new_value, self._byte_count)
         # current value is known and same as value to be written return None to signal not to write it
         return None if current_value is not None and current_value == new_value else to_write