From 6665e14e1daf0750b1dfbcdf6b89fbd26a5a2b4b Mon Sep 17 00:00:00 2001
From: Robert <mail@rbeekman.nl>
Date: Mon, 26 Apr 2021 22:58:52 +0200
Subject: [PATCH] ASUS - Explain what is going on with LED tagging

---
 .../Keyboard/AsusKeyboardRGBDevice.cs         | 65 ++++++++++++++-----
 1 file changed, 48 insertions(+), 17 deletions(-)

diff --git a/RGB.NET.Devices.Asus/Keyboard/AsusKeyboardRGBDevice.cs b/RGB.NET.Devices.Asus/Keyboard/AsusKeyboardRGBDevice.cs
index 319b3b5..b4af3a4 100644
--- a/RGB.NET.Devices.Asus/Keyboard/AsusKeyboardRGBDevice.cs
+++ b/RGB.NET.Devices.Asus/Keyboard/AsusKeyboardRGBDevice.cs
@@ -1,4 +1,5 @@
 using System.Collections.Generic;
+using System.Threading;
 using AuraServiceLib;
 using RGB.NET.Core;
 
@@ -43,6 +44,10 @@ namespace RGB.NET.Devices.Asus
                 int pos = 0;
                 int unknownLed = (int)LedId.Unknown1;
 
+                // A device can have more lights than keys, a space bar with 4 lights per example but only the middle light is represented as a key
+                // This means we want all lights but keys contain more information (a LED ID) so first pick up all keys and 'tag' them by giving them a color of 0x000001
+
+                // Clear tags to make sure no device is already at 0x000001
                 ClearTags();
                 foreach (IAuraRgbKey key in ((IAuraSyncKeyboard)DeviceInfo.Device).Keys)
                 {
@@ -57,6 +62,11 @@ namespace RGB.NET.Devices.Asus
                     TagAsusLed(key);
                 }
 
+                // Give the ASUS SDK some time to catch up
+                Thread.Sleep(100);
+
+                // With keys iterated, add any light that was not tagged, these are lights that aren't represented by keys
+                // Because there's no way to tell which light is which, they're all added as Unknown LEDs
                 for (int index = 0; index < ((IAuraSyncKeyboard)DeviceInfo.Device).Lights.Count; index++)
                 {
                     IAuraRgbLight light = ((IAuraSyncKeyboard)DeviceInfo.Device).Lights[index];
@@ -66,6 +76,8 @@ namespace RGB.NET.Devices.Asus
                     AddAsusLed(index, (LedId)unknownLed, new Point(pos++ * 19, 0), new Size(19, 19));
                     unknownLed++;
                 }
+
+                // Clear tags when done, the info is no longer relevant
                 ClearTags();
             }
             else
@@ -76,22 +88,6 @@ namespace RGB.NET.Devices.Asus
             }
         }
 
-        private void AddAsusLed(AsusLedId asusLedId, LedId ledId, Point position, Size size)
-        {
-            if (this._ledAsusLed.TryGetValue(ledId, out AsusLedId firstAsusLed))
-                throw new
-                    RGBDeviceException($"Got LED '{ledId}' twice, first ASUS LED '{firstAsusLed}' second ASUS LED '{asusLedId}' on device '{DeviceInfo.DeviceName}'");
-
-            this._ledAsusLed.Add(ledId, asusLedId);
-            AddLed(ledId, position, size);
-        }
-
-        private void AddAsusLed(int index, LedId ledId, Point position, Size size)
-        {
-            this._ledAsusLights.Add(ledId, index);
-            AddLed(ledId, position, size);
-        }
-
         /// <inheritdoc />
         protected override object? GetLedCustomData(LedId ledId)
         {
@@ -102,17 +98,52 @@ namespace RGB.NET.Devices.Asus
             return null;
         }
 
+
+        /// <summary>
+        /// Add an ASUS LED by its LED ID
+        /// </summary>
+        private void AddAsusLed(AsusLedId asusLedId, LedId ledId, Point position, Size size)
+        {
+            if (this._ledAsusLed.TryGetValue(ledId, out AsusLedId firstAsusLed))
+                throw new RGBDeviceException($"Got LED '{ledId}' twice, first ASUS LED '{firstAsusLed}' "
+                                             + $"second ASUS LED '{asusLedId}' on device '{DeviceInfo.DeviceName}'");
+
+            this._ledAsusLed.Add(ledId, asusLedId);
+            AddLed(ledId, position, size);
+        }
+
+        /// <summary>
+        /// Add an asus LED by its light index
+        /// </summary>
+        private void AddAsusLed(int index, LedId ledId, Point position, Size size)
+        {
+            this._ledAsusLights.Add(ledId, index);
+            AddLed(ledId, position, size);
+        }
+
+        /// <summary>
+        /// Clears the tags off all keys by setting their color to 0x000000
+        /// </summary>
         private void ClearTags()
         {
-            foreach (IAuraRgbLight light in ((IAuraSyncKeyboard)DeviceInfo.Device).Lights) 
+            foreach (IAuraRgbLight light in ((IAuraSyncKeyboard)DeviceInfo.Device).Lights)
                 light.Color = 0x000000;
         }
 
+        /// <summary>
+        /// Tags a LED by its key by setting its color to 0x000001
+        /// </summary>
+        /// <param name="key"></param>
         private void TagAsusLed(IAuraRgbKey key)
         {
             key.Color = 0x000001;
         }
 
+        /// <summary>
+        /// Determines whether a LED is tagged by its light
+        /// </summary>
+        /// <param name="light"></param>
+        /// <returns></returns>
         private bool IsAsusLedTagged(IAuraRgbLight light)
         {
             return light.Color == 0x000001;