From c11d585578754fdac22b2f5c9cbc0b221edd376a Mon Sep 17 00:00:00 2001
From: "Peter F. Patel-Schneider" <pfpschneider@gmail.com>
Date: Tue, 30 Jan 2024 00:06:41 -0500
Subject: [PATCH] device: support backlight levels and duration

---
 lib/logitech_receiver/device.py             |   8 ++
 lib/logitech_receiver/hidpp20.py            |  29 ++++
 lib/logitech_receiver/settings.py           |   1 +
 lib/logitech_receiver/settings_templates.py | 141 +++++++++++++++++++-
 4 files changed, 178 insertions(+), 1 deletion(-)

diff --git a/lib/logitech_receiver/device.py b/lib/logitech_receiver/device.py
index dc21c1781..cb029c596 100644
--- a/lib/logitech_receiver/device.py
+++ b/lib/logitech_receiver/device.py
@@ -79,6 +79,7 @@ def __init__(
         self._remap_keys = None
         self._gestures = None
         self._gestures_lock = _threading.Lock()
+        self._backlight = None
         self._registers = None
         self._settings = None
         self._feature_settings_checked = False
@@ -315,6 +316,13 @@ def gestures(self):
                         self._gestures = _hidpp20.get_gestures(self) or ()
         return self._gestures
 
+    @property
+    def backlight(self):
+        if self._backlight is None:
+            if self.online and self.protocol >= 2.0:
+                self._backlight = _hidpp20.get_backlight(self)
+        return self._backlight
+
     @property
     def registers(self):
         if not self._registers:
diff --git a/lib/logitech_receiver/hidpp20.py b/lib/logitech_receiver/hidpp20.py
index 076dbc4d4..ed47fdb74 100644
--- a/lib/logitech_receiver/hidpp20.py
+++ b/lib/logitech_receiver/hidpp20.py
@@ -1117,6 +1117,28 @@ def set_param(self, param, value):
         return g.set(self.device, value) if g else None
 
 
+class Backlight:
+    """Information about the current settings of x1982 Backlight2 v3, but also works for previous versions"""
+
+    def __init__(self, device):
+        response = device.feature_request(FEATURE.BACKLIGHT2, 0x00)
+        if not response:
+            raise FeatureCallError(msg='No reply from device.')
+        self.device = device
+        self.enabled, self.options, supported, self.effects, self.level, self.dho, self.dhi, self.dpow = _unpack(
+            '<BBBHBHHH', response[:12]
+        )
+        self.auto_supported = supported & 0x08
+        self.temp_supported = supported & 0x10
+        self.perm_supported = supported & 0x20
+        self.mode = (self.options >> 3) & 0x03
+
+    def write(self):
+        self.options = (self.options & 0x03) | (self.mode << 3)
+        data_bytes = _pack('<BBBBHHH', self.enabled, self.options, self.effects, self.level, self.dho, self.dhi, self.dpow)
+        self.device.feature_request(FEATURE.BACKLIGHT2, 0x10, data_bytes)
+
+
 #
 #
 #
@@ -1402,6 +1424,13 @@ def get_gestures(device):
         return Gestures(device)
 
 
+def get_backlight(device):
+    if getattr(device, '_backlight', None) is not None:
+        return device._backlight
+    if FEATURE.BACKLIGHT2 in device.features:
+        return Backlight(device)
+
+
 def get_mouse_pointer_info(device):
     pointer_info = feature_request(device, FEATURE.MOUSE_POINTER)
     if pointer_info:
diff --git a/lib/logitech_receiver/settings.py b/lib/logitech_receiver/settings.py
index 6e7956c34..aa81c144b 100644
--- a/lib/logitech_receiver/settings.py
+++ b/lib/logitech_receiver/settings.py
@@ -207,6 +207,7 @@ class Setting:
     """A setting descriptor. Needs to be instantiated for each specific device."""
     name = label = description = ''
     feature = register = kind = None
+    min_version = 0
     persist = True
     rw_options = {}
     validator_class = BooleanValidator
diff --git a/lib/logitech_receiver/settings_templates.py b/lib/logitech_receiver/settings_templates.py
index 3a2ced3de..f72ea618f 100644
--- a/lib/logitech_receiver/settings_templates.py
+++ b/lib/logitech_receiver/settings_templates.py
@@ -215,7 +215,7 @@ class Backlight(_Setting):
 
 # MX Keys S requires some extra values, as in 11 02 0c1a 000dff000b000b003c00000000000000
 # on/off options (from current) effect (FF-no change) level (from current) durations[6] (from current)
-class Backlight2(_Setting):
+class Backlight2X(_Setting):
     name = 'backlight'
     label = _('Backlight')
     description = _('Turn illumination on or off on keyboard.')
@@ -231,6 +231,139 @@ def write(self, device, data_bytes):
             return super().write(device, data_bytes + self.trail)
 
 
+# MX Keys S requires some extra values, as in 11 02 0c1a 000dff000b000b003c00000000000000
+# on/off options (from current) effect (FF-no change) level (from current) durations[6] (from current)
+class Backlight2(_Setting):
+    name = 'backlight'
+    label = _('Backlight')
+    description = _('Control illumination on keyboard.')
+    feature = _F.BACKLIGHT2
+    min_version = 0
+
+    class rw_class:
+
+        def __init__(self, feature):
+            self.feature = feature
+            self.kind = _FeatureRW.kind
+
+        def read(self, device):
+            backlight = device.backlight
+            if not backlight.enabled:
+                return 0xFF
+            else:
+                return backlight.mode
+
+        def write(self, device, data_bytes):
+            backlight = device.backlight
+            backlight.enabled = data_bytes[0] != 0xFF
+            if data_bytes[0] != 0xFF:
+                self.mode = data_bytes[0]
+            backlight.write()
+            return True
+
+    class validator_class(_ChoicesV):
+
+        @classmethod
+        def build(cls, setting_class, device):
+            backlight = device.backlight
+            choices = _NamedInts(Disabled=0xFF)
+            if backlight.auto_supported:
+                choices[0x1] = 'Auto'
+            if backlight.temp_supported:
+                choices[0x2] = 'Manual'
+            if backlight.perm_supported:
+                choices[0x3] = 'Software'
+            if not (backlight.auto_supported or backlight.temp_supported or backlight.perm_supported):
+                choices[0x0] = 'Enabled'
+            return cls(choices=choices, byte_count=1)
+
+
+class Backlight2Level(_Setting):
+    name = 'backlight_level'
+    label = _('Backlight Level')
+    description = _('Illumination level on keyboard in Software mode.')
+    feature = _F.BACKLIGHT2
+    min_version = 3
+
+    class rw_class:
+
+        def __init__(self, feature):
+            self.feature = feature
+            self.kind = _FeatureRW.kind
+
+        def read(self, device):
+            backlight = device.backlight
+            print('READ LEVEL', backlight.level)
+            return _int2bytes(backlight.level, 1)
+
+        def write(self, device, data_bytes):
+            print('WRITE LEVEL', data_bytes)
+            device.backlight.level = _bytes2int(data_bytes)
+            device.backlight.write()
+            return True
+
+    class validator_class(_RangeV):
+
+        @classmethod
+        def build(cls, setting_class, device):
+            reply = device.feature_request(_F.BACKLIGHT2, 0x20)
+            assert reply, 'Oops, backlight range cannot be retrieved!'
+            return cls(min_value=0, max_value=reply[0], byte_count=1)
+
+
+class Backlight2Duration(_Setting):
+    feature = _F.BACKLIGHT2
+    min_version = 3
+    validator_class = _RangeV
+    min_value = 0  # 1 # 5 seconds
+    max_value = 120  # actual maximum is 0x5A0 or 2 hours
+    validator_options = {'byte_count': 2}
+
+    class rw_class:
+
+        def __init__(self, feature, field):
+            self.feature = feature
+            self.kind = _FeatureRW.kind
+            self.field = field
+
+        def read(self, device):
+            backlight = device.backlight
+            return _int2bytes(getattr(backlight, self.field), 2) * 5  # use seconds instead of 5-second units
+
+        def write(self, device, data_bytes):
+            backlight = device.backlight
+            setattr(backlight, self.field, (int.from_bytes(data_bytes) + 4) // 5)  # use ceiling in 5-second units
+            backlight.write()
+            return True
+
+
+class Backlight2DurationHandsOut(Backlight2Duration):
+    name = 'backlight_duration_hands_out'
+    label = _('Backlight Delay Hands Out')
+    description = _('Delay in seconds until backlight fades out with hands away from keyboard.')
+    feature = _F.BACKLIGHT2
+    validator_class = _RangeV
+    rw_options = {'field': 'dho'}
+
+
+class Backlight2DurationHandsIn(Backlight2Duration):
+    name = 'backlight_duration_hands_in'
+    label = _('Backlight Delay Hands In')
+    description = _('Delay in seconds until backlight fades out with hands near keyboard.')
+    feature = _F.BACKLIGHT2
+    validator_class = _RangeV
+    rw_options = {'field': 'dhi'}
+
+
+class Backlight2DurationPowered(Backlight2Duration):
+    name = 'backlight_duration_powered'
+    label = _('Backlight Delay Powered')
+    description = _('Delay in seconds until backlight fades out with external power.')
+    feature = _F.BACKLIGHT2
+    validator_class = _RangeV
+    rw_options = {'field': 'dpow'}
+
+
 class Backlight3(_Setting):
     name = 'backlight-timed'
     label = _('Backlight')
@@ -1238,6 +1371,10 @@ class ADCPower(_Setting):
     SpeedChange,
     #    Backlight,  # not working - disabled temporarily
     Backlight2,  # working
+    Backlight2Level,
+    Backlight2DurationHandsOut,
+    Backlight2DurationHandsIn,
+    Backlight2DurationPowered,
     Backlight3,
     FnSwap,  # simple
     NewFnSwap,  # simple
@@ -1270,6 +1407,8 @@ class ADCPower(_Setting):
 def check_feature(device, sclass):
     if sclass.feature not in device.features:
         return
+    if sclass.min_version > device.features.get_feature_version(sclass.feature):
+        return
     try:
         detected = sclass.build(device)
         if _log.isEnabledFor(_DEBUG):