Surface QMK discovery results to the user (v4.1.43)

Previously: enabling the QMK Keyboards toggle with no boards plugged in
flashed the button on and then back off with no console output, no
dialog — looking exactly like a bug.

Now:
- QmkRawHidDiscovery logs the full enumeration breakdown to the console
  (HID device count, Raw HID candidates found, open-failures, handshake
  misses, final usable count). When a candidate fails handshake the log
  includes the reason — most usefully, "could not open the Raw HID
  interface (likely held exclusively by another app — close VIA / Vial
  / OpenRGB and try again)".
- SettingsViewModel's enable handler now logs "Scanning..." before
  discovery, and pops a localised "No QMK Keyboards Found" dialog when
  discovery returns empty so the user can see exactly why the toggle
  didn't take. Strings routed through LocalizationService.Instance per
  the localization rule; en.json + the six non-EN locales updated via
  translate.py.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: logicallysynced

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to Chromatics are documented here.
 
-## 4.1.42
+## 4.1.43
 
 - **New:** QMK Raw HID keyboard support (Beta). Covers custom keyboards from NovelKeys, KBDFans, Drop, GMMK, Glorious and any other brand running QMK firmware with Raw HID enabled. Enable it from Settings → Device Providers, or pick it on the first-run device selector. Chromatics auto-detects compatible boards on USB and adopts them — no firmware flashing or extra software required. Per-key lighting is driven via the OpenRGB-QMK plugin when the firmware has it installed; otherwise Chromatics drives the firmware's built-in RGB matrix base colour and effect mode (VIA). For per-key LED boards, Chromatics looks up the physical key layout from the via-keyboards database automatically on first connect so the Highlight / Keybind layers line up with the right keys out of the box.
 - Updated dependency libraries to latest version

Chromatics/Chromatics.csproj

@@ -4,7 +4,7 @@
     <OutputType>WinExe</OutputType>
     <TargetFramework>net10.0-windows7.0</TargetFramework>
     <StartupObject>Chromatics.Program</StartupObject>
-    <Version>4.1.42.0</Version>
+    <Version>4.1.43.0</Version>
     <Authors>Danielle Thompson</Authors>
     <ApplicationManifest>app.manifest</ApplicationManifest>
     <Copyright>logicallysynced 2026</Copyright>

Chromatics/Extensions/RGB.NET/Devices/QmkRawHid/Protocol/QmkRawHidDiscovery.cs

@@ -1,3 +1,5 @@
+using Chromatics.Core;
+using Chromatics.Enums;
 using HidSharp;
 using HidSharp.Reports;
 using System;
@@ -44,17 +46,48 @@ public static IReadOnlyList<Candidate> Discover()
             var results = new List<Candidate>();
             HidDevice[] all;
             try { all = DeviceList.Local.GetHidDevices() as HidDevice[] ?? new List<HidDevice>(DeviceList.Local.GetHidDevices()).ToArray(); }
-            catch { return results; }
+            catch (Exception ex)
+            {
+                Logger.WriteConsole(LoggerTypes.Devices,
+                    $"[QMK] HID enumeration failed: {ex.Message}",
+                    forwardToSentry: false);
+                return results;
+            }
+
+            Logger.WriteConsole(LoggerTypes.Devices,
+                $"[QMK] Enumerated {all.Length} HID device(s) on the USB bus; scanning for the Raw HID interface (usage page 0x{QmkRawHidConstants.RawHidUsagePage:X4}, usage 0x{QmkRawHidConstants.RawHidUsage:X2})...");
+
+            int rawHidCandidates = 0;
+            int openFailures = 0;
+            int handshakeMisses = 0;
 
             foreach (HidDevice hid in all)
             {
                 if (!ExposesRawHidUsage(hid)) continue;
+                rawHidCandidates++;
+
+                Logger.WriteConsole(LoggerTypes.Devices,
+                    $"[QMK] Candidate: VID=0x{hid.VendorID:X4} PID=0x{hid.ProductID:X4} ({SafeProductName(hid)} / {SafeManufacturer(hid)})");
 
-                if (!TryHandshake(hid, out var protocol, out int ledCount, out byte cols, out byte rows, out string fwName))
+                if (!TryHandshake(hid, out var protocol, out int ledCount, out byte cols, out byte rows, out string fwName, out string failureReason))
+                {
+                    openFailures++;
+                    Logger.WriteConsole(LoggerTypes.Devices,
+                        $"[QMK]   handshake skipped — {failureReason}",
+                        forwardToSentry: false);
                     continue;
+                }
 
-                if (protocol == ProtocolSupport.None) continue;
+                if (protocol == ProtocolSupport.None)
+                {
+                    handshakeMisses++;
+                    Logger.WriteConsole(LoggerTypes.Devices,
+                        "[QMK]   neither VIA nor OpenRGB-QMK responded; firmware probably doesn't have Raw HID enabled.");
+                    continue;
+                }
 
+                Logger.WriteConsole(LoggerTypes.Devices,
+                    $"[QMK]   handshake OK — protocol: {protocol}, LEDs: {ledCount}, matrix: {cols}x{rows}");
                 results.Add(new Candidate(hid, protocol, ledCount, cols, rows, fwName));
             }
 
@@ -65,9 +98,18 @@ public static IReadOnlyList<Candidate> Discover()
                 return a.Hid.ProductID.CompareTo(b.Hid.ProductID);
             });
 
+            Logger.WriteConsole(LoggerTypes.Devices,
+                $"[QMK] Discovery done: {all.Length} HID devices total, {rawHidCandidates} with Raw HID interface, " +
+                $"{openFailures} could not be opened, {handshakeMisses} did not respond to handshake, {results.Count} usable.");
+
             return results;
         }
 
+        private static string SafeManufacturer(HidDevice hid)
+        { try { return hid.GetManufacturer() ?? ""; } catch { return "?"; } }
+        private static string SafeProductName(HidDevice hid)
+        { try { return hid.GetProductName() ?? ""; } catch { return "?"; } }
+
         // Returns true if any of the HidDevice's top-level collections
         // declares usage page 0xFF60, usage 0x61. Multi-interface USB
         // devices expose each interface as a separate HidDevice, so
@@ -97,17 +139,26 @@ private static bool ExposesRawHidUsage(HidDevice hid)
         // strictly more capable protocol. Stream is disposed before
         // we return; the provider will reopen it for the device's
         // permanent UpdateQueue.
-        private static bool TryHandshake(HidDevice hid, out ProtocolSupport protocol, out int ledCount, out byte cols, out byte rows, out string firmwareDeviceName)
+        private static bool TryHandshake(HidDevice hid, out ProtocolSupport protocol, out int ledCount, out byte cols, out byte rows, out string firmwareDeviceName, out string failureReason)
         {
             protocol = ProtocolSupport.None;
             ledCount = 0; cols = 0; rows = 0; firmwareDeviceName = string.Empty;
+            failureReason = string.Empty;
 
             HidStream stream;
             try
             {
-                if (!hid.TryOpen(out stream)) return false;
+                if (!hid.TryOpen(out stream))
+                {
+                    failureReason = "could not open the Raw HID interface (likely held exclusively by another app — close VIA / Vial / OpenRGB and try again)";
+                    return false;
+                }
+            }
+            catch (Exception ex)
+            {
+                failureReason = $"open threw: {ex.Message}";
+                return false;
             }
-            catch { return false; }
 
             try
             {

Chromatics/ViewModels/SettingsViewModel.cs

@@ -10,6 +10,7 @@
 using Chromatics.Models;
 using Chromatics.Helpers;
 using Chromatics.Views;
+using Chromatics.Views.Dialogs;
 using Microsoft.VisualBasic.FileIO;
 using Microsoft.Win32;
 using RGB.NET.Devices.Asus;
@@ -281,15 +282,18 @@ private void BuildDeviceToggles(Models.SettingsModel s)
                 "QMK Keyboards (Beta)",
                 "[BETA] Enable/disable QMK Raw HID keyboard support. Auto-adopts any QMK-compatible keyboard with Raw HID enabled (covers NovelKeys, KBDFans, Drop, GMMK, Glorious, and other custom QMK boards). Default: Disabled",
                 s.deviceQmkRawHidEnabled,
-                () =>
+                async () =>
                 {
                     var cur = AppSettings.GetSettings();
 
+                    Logger.WriteConsole(LoggerTypes.Devices,
+                        "[QMK] Scanning for QMK-compatible keyboards on the USB bus...");
+
                     // Discovery + auto-adopt: run on a background thread to
                     // keep the Settings dialog responsive — per-device VIA
                     // handshakes can take 200-500ms each on a sluggish USB
                     // stack, and discovery + handshake of 5+ boards adds up.
-                    return Task.Run(() =>
+                    bool result = await Task.Run(() =>
                     {
                         var discovered = Chromatics.Extensions.RGB.NET.Devices.QmkRawHid.Protocol.QmkRawHidDiscovery.Discover();
                         if (discovered.Count == 0)
@@ -334,6 +338,22 @@ private void BuildDeviceToggles(Models.SettingsModel s)
                             Chromatics.Extensions.RGB.NET.Devices.QmkRawHid.QmkRawHidRGBDeviceProvider.Instance);
                         return true;
                     });
+
+                    if (!result)
+                    {
+                        // The "no boards found" path. Logger.WriteConsole has
+                        // already written the detailed enumeration breakdown
+                        // (count of HID devices seen, candidates with the
+                        // Raw HID interface, open-failures, etc.). Surface a
+                        // short user-facing dialog too so it's obvious why
+                        // the toggle didn't take — without this the toggle
+                        // flashes on then back off with no visible feedback.
+                        await DialogService.ShowAsync(
+                            LocalizationService.Instance["No QMK Keyboards Found"],
+                            LocalizationService.Instance["Chromatics didn't detect any QMK keyboards on this PC. Make sure your keyboard is plugged in over USB and that its firmware has Raw HID enabled (this is the default for any VIA-compatible build). If you have VIA, Vial, or OpenRGB running, close it before enabling this provider — they hold the Raw HID interface exclusively. See the console for a detailed breakdown of which HID devices were enumerated."]);
+                    }
+
+                    return result;
                 },
                 () =>
                 {

Chromatics/locale/de.json

@@ -840,5 +840,7 @@
   "Couldn't read lights from the bridge: {0}": "Lampen konnten nicht von der Bridge gelesen werden: {0}",
   "QMK Keyboards (Beta)": "QMK-Tastaturen (Beta)",
   "QMK keyboards over Raw HID. Covers NovelKeys, KBDFans, Drop, GMMK, Glorious and any other custom keyboard running QMK with Raw HID enabled.": "QMK-Tastaturen über Raw HID. Umfasst NovelKeys, KBDFans, Drop, GMMK, Glorious und jede andere benutzerdefinierte Tastatur, auf der QMK mit aktiviertem Raw HID läuft.",
-  "[BETA] Enable/disable QMK Raw HID keyboard support. Auto-adopts any QMK-compatible keyboard with Raw HID enabled (covers NovelKeys, KBDFans, Drop, GMMK, Glorious, and other custom QMK boards). Default: Disabled": "[BETA] QMK-Raw-HID-Tastaturunterstützung aktivieren/deaktivieren. Übernimmt automatisch jede QMK-kompatible Tastatur mit aktiviertem Raw HID (umfasst NovelKeys, KBDFans, Drop, GMMK, Glorious und andere benutzerdefinierte QMK-Boards). Standard: Deaktiviert"
+  "[BETA] Enable/disable QMK Raw HID keyboard support. Auto-adopts any QMK-compatible keyboard with Raw HID enabled (covers NovelKeys, KBDFans, Drop, GMMK, Glorious, and other custom QMK boards). Default: Disabled": "[BETA] QMK-Raw-HID-Tastaturunterstützung aktivieren/deaktivieren. Übernimmt automatisch jede QMK-kompatible Tastatur mit aktiviertem Raw HID (umfasst NovelKeys, KBDFans, Drop, GMMK, Glorious und andere benutzerdefinierte QMK-Boards). Standard: Deaktiviert",
+  "No QMK Keyboards Found": "Keine QMK-Tastaturen gefunden",
+  "Chromatics didn't detect any QMK keyboards on this PC. Make sure your keyboard is plugged in over USB and that its firmware has Raw HID enabled (this is the default for any VIA-compatible build). If you have VIA, Vial, or OpenRGB running, close it before enabling this provider — they hold the Raw HID interface exclusively. See the console for a detailed breakdown of which HID devices were enumerated.": "Chromatics hat auf diesem PC keine QMK-Tastaturen erkannt. Stelle sicher, dass deine Tastatur über USB angeschlossen ist und dass in ihrer Firmware Raw HID aktiviert ist (dies ist die Standardeinstellung für jeden VIA-kompatiblen Build). Falls VIA, Vial oder OpenRGB ausgeführt wird, schließe es, bevor du diesen Anbieter aktivierst — sie belegen die Raw-HID-Schnittstelle exklusiv. In der Konsole findest du eine detaillierte Aufschlüsselung, welche HID-Geräte aufgelistet wurden."
 }

Chromatics/locale/en.json

@@ -621,6 +621,8 @@
     "PlayStation (Beta)":  "PlayStation (Beta)",
     "QMK Keyboards (Beta)":  "QMK Keyboards (Beta)",
     "QMK keyboards over Raw HID. Covers NovelKeys, KBDFans, Drop, GMMK, Glorious and any other custom keyboard running QMK with Raw HID enabled.":  "QMK keyboards over Raw HID. Covers NovelKeys, KBDFans, Drop, GMMK, Glorious and any other custom keyboard running QMK with Raw HID enabled.",
+    "No QMK Keyboards Found":  "No QMK Keyboards Found",
+    "Chromatics didn't detect any QMK keyboards on this PC. Make sure your keyboard is plugged in over USB and that its firmware has Raw HID enabled (this is the default for any VIA-compatible build). If you have VIA, Vial, or OpenRGB running, close it before enabling this provider — they hold the Raw HID interface exclusively. See the console for a detailed breakdown of which HID devices were enumerated.":  "Chromatics didn't detect any QMK keyboards on this PC. Make sure your keyboard is plugged in over USB and that its firmware has Raw HID enabled (this is the default for any VIA-compatible build). If you have VIA, Vial, or OpenRGB running, close it before enabling this provider — they hold the Raw HID interface exclusively. See the console for a detailed breakdown of which HID devices were enumerated.",
     "[BETA] Enable/disable QMK Raw HID keyboard support. Auto-adopts any QMK-compatible keyboard with Raw HID enabled (covers NovelKeys, KBDFans, Drop, GMMK, Glorious, and other custom QMK boards). Default: Disabled":  "[BETA] Enable/disable QMK Raw HID keyboard support. Auto-adopts any QMK-compatible keyboard with Raw HID enabled (covers NovelKeys, KBDFans, Drop, GMMK, Glorious, and other custom QMK boards). Default: Disabled",
     "Enable/disable Razer device library. Default: Enabled":  "Enable/disable Razer device library. Default: Enabled",
     "Enable/disable Logitech device library. Default: Enabled":  "Enable/disable Logitech device library. Default: Enabled",

Chromatics/locale/es.json

@@ -840,5 +840,7 @@
   "Couldn't read lights from the bridge: {0}": "No se pudieron leer las luces del puente: {0}",
   "QMK Keyboards (Beta)": "Teclados QMK (Beta)",
   "QMK keyboards over Raw HID. Covers NovelKeys, KBDFans, Drop, GMMK, Glorious and any other custom keyboard running QMK with Raw HID enabled.": "Teclados QMK mediante Raw HID. Cubre NovelKeys, KBDFans, Drop, GMMK, Glorious y cualquier otro teclado personalizado que ejecute QMK con Raw HID habilitado.",
-  "[BETA] Enable/disable QMK Raw HID keyboard support. Auto-adopts any QMK-compatible keyboard with Raw HID enabled (covers NovelKeys, KBDFans, Drop, GMMK, Glorious, and other custom QMK boards). Default: Disabled": "[BETA] Activa/desactiva la compatibilidad con teclados QMK Raw HID. Adopta automáticamente cualquier teclado compatible con QMK que tenga Raw HID habilitado (cubre NovelKeys, KBDFans, Drop, GMMK, Glorious y otros teclados QMK personalizados). Valor predeterminado: Desactivado"
+  "[BETA] Enable/disable QMK Raw HID keyboard support. Auto-adopts any QMK-compatible keyboard with Raw HID enabled (covers NovelKeys, KBDFans, Drop, GMMK, Glorious, and other custom QMK boards). Default: Disabled": "[BETA] Activa/desactiva la compatibilidad con teclados QMK Raw HID. Adopta automáticamente cualquier teclado compatible con QMK que tenga Raw HID habilitado (cubre NovelKeys, KBDFans, Drop, GMMK, Glorious y otros teclados QMK personalizados). Valor predeterminado: Desactivado",
+  "No QMK Keyboards Found": "No se encontraron teclados QMK",
+  "Chromatics didn't detect any QMK keyboards on this PC. Make sure your keyboard is plugged in over USB and that its firmware has Raw HID enabled (this is the default for any VIA-compatible build). If you have VIA, Vial, or OpenRGB running, close it before enabling this provider — they hold the Raw HID interface exclusively. See the console for a detailed breakdown of which HID devices were enumerated.": "Chromatics no detectó ningún teclado QMK en este PC. Asegúrate de que el teclado esté conectado por USB y de que su firmware tenga habilitado Raw HID (esto es lo predeterminado en cualquier compilación compatible con VIA). Si tienes VIA, Vial u OpenRGB en ejecución, ciérralo antes de habilitar este proveedor, ya que mantienen la interfaz Raw HID en exclusiva. Consulta la consola para ver un desglose detallado de los dispositivos HID que se enumeraron."
 }

Chromatics/locale/fr.json

@@ -840,5 +840,7 @@
   "Couldn't read lights from the bridge: {0}": "Impossible de lire les lumières depuis le pont : {0}",
   "QMK Keyboards (Beta)": "Claviers QMK (bêta)",
   "QMK keyboards over Raw HID. Covers NovelKeys, KBDFans, Drop, GMMK, Glorious and any other custom keyboard running QMK with Raw HID enabled.": "Claviers QMK via Raw HID. Couvre NovelKeys, KBDFans, Drop, GMMK, Glorious et tout autre clavier personnalisé exécutant QMK avec Raw HID activé.",
-  "[BETA] Enable/disable QMK Raw HID keyboard support. Auto-adopts any QMK-compatible keyboard with Raw HID enabled (covers NovelKeys, KBDFans, Drop, GMMK, Glorious, and other custom QMK boards). Default: Disabled": "[BÊTA] Activer/désactiver la prise en charge des claviers QMK Raw HID. Adopte automatiquement tout clavier compatible QMK avec Raw HID activé (couvre NovelKeys, KBDFans, Drop, GMMK, Glorious et autres claviers QMK personnalisés). Par défaut : désactivé"
+  "[BETA] Enable/disable QMK Raw HID keyboard support. Auto-adopts any QMK-compatible keyboard with Raw HID enabled (covers NovelKeys, KBDFans, Drop, GMMK, Glorious, and other custom QMK boards). Default: Disabled": "[BÊTA] Activer/désactiver la prise en charge des claviers QMK Raw HID. Adopte automatiquement tout clavier compatible QMK avec Raw HID activé (couvre NovelKeys, KBDFans, Drop, GMMK, Glorious et autres claviers QMK personnalisés). Par défaut : désactivé",
+  "No QMK Keyboards Found": "Aucun clavier QMK trouvé",
+  "Chromatics didn't detect any QMK keyboards on this PC. Make sure your keyboard is plugged in over USB and that its firmware has Raw HID enabled (this is the default for any VIA-compatible build). If you have VIA, Vial, or OpenRGB running, close it before enabling this provider — they hold the Raw HID interface exclusively. See the console for a detailed breakdown of which HID devices were enumerated.": "Chromatics n’a détecté aucun clavier QMK sur ce PC. Assurez-vous que votre clavier est branché en USB et que le Raw HID est activé dans son firmware (c’est le réglage par défaut pour toute version compatible VIA). Si VIA, Vial ou OpenRGB est en cours d’exécution, fermez-le avant d’activer ce fournisseur — ils monopolisent l’interface Raw HID. Consultez la console pour obtenir le détail des périphériques HID qui ont été énumérés."
 }