iobroker.tint 0.3.0

package/io-package.json

@@ -0,0 +1,227 @@
+{
+	"common": {
+		"name": "tint",
+		"version": "0.3.0",
+		"news": {
+			"0.3.0": {
+				"en": "Fix: device tabs no longer trigger a false \"switch host\" warning in admin (React 18 + MUI v6 now shared with admin instead of bundled separately); remove leftover legacy \"tint\" sidebar tab",
+				"de": "Bugfix: Geräte-Tabs lösen keine falsche \"Host wechseln\"-Warnung in Admin mehr aus (React 18 + MUI v6 werden jetzt mit Admin geteilt statt separat gebündelt); veralteten Sidebar-Tab \"tint\" entfernt",
+				"ru": "Исправление: вкладки устройств больше не вызывают ложное предупреждение \"сменить хост\" в админке (React 18 + MUI v6 теперь общие с админкой); удалена устаревшая вкладка \"tint\" в боковой панели",
+				"pt": "Correção: as abas de dispositivos já não geram um aviso falso de \"mudar de host\" no admin (React 18 + MUI v6 agora partilhados com o admin); removida a aba lateral \"tint\" obsoleta",
+				"nl": "Bugfix: apparaattabbladen geven niet langer een onterechte \"host wisselen\"-waarschuwing in admin (React 18 + MUI v6 nu gedeeld met admin); verouderd zijbalktabblad \"tint\" verwijderd",
+				"fr": "Correctif: les onglets d'appareils ne déclenchent plus un faux avertissement \"changer d'hôte\" dans admin (React 18 + MUI v6 désormais partagés avec admin); suppression de l'ancien onglet latéral \"tint\"",
+				"it": "Correzione: le schede dispositivo non generano più un falso avviso \"cambia host\" in admin (React 18 + MUI v6 ora condivisi con admin); rimossa la vecchia scheda laterale \"tint\"",
+				"es": "Corrección: las pestañas de dispositivos ya no generan una falsa advertencia de \"cambiar de host\" en admin (React 18 + MUI v6 ahora compartidos con admin); eliminada la pestaña lateral obsoleta \"tint\"",
+				"pl": "Poprawka: zakładki urządzeń nie wywołują już fałszywego ostrzeżenia \"zmień hosta\" w admin (React 18 + MUI v6 są teraz współdzielone z admin); usunięto przestarzałą zakładkę boczną \"tint\"",
+				"uk": "Виправлення: вкладки пристроїв більше не викликають хибне попередження \"змінити хост\" в admin (React 18 + MUI v6 тепер спільні з admin); видалено застарілу бічну вкладку \"tint\"",
+				"zh-cn": "修复：设备标签页不再在admin中触发错误的“切换主机”警告（React 18 + MUI v6现已与admin共享）；移除遗留的侧边栏“tint”标签"
+			},
+			"0.2.6": {
+				"en": "Fix: replace sendTo button with custom PairButton component for reliable API key retrieval and visual feedback",
+				"de": "Bugfix: sendTo-Button durch eigene PairButton-Komponente ersetzt — zuverlässige API-Schlüssel-Abfrage mit Statusanzeige",
+				"ru": "Исправление: кнопка sendTo заменена собственным компонентом PairButton — надёжное получение API-ключа с визуальной обратной связью",
+				"pt": "Correção: botão sendTo substituído por componente PairButton personalizado — obtenção fiável da chave API com feedback visual",
+				"nl": "Bugfix: sendTo-knop vervangen door eigen PairButton-component — betrouwbaar ophalen van API-sleutel met statusweergave",
+				"fr": "Correctif: bouton sendTo remplacé par un composant PairButton personnalisé — récupération fiable de la clé API avec retour visuel",
+				"it": "Correzione: pulsante sendTo sostituito da componente PairButton personalizzato — recupero affidabile della chiave API con feedback visivo",
+				"es": "Corrección: botón sendTo reemplazado por componente PairButton personalizado — obtención fiable de clave API con feedback visual",
+				"pl": "Poprawka: przycisk sendTo zastąpiony własnym komponentem PairButton — niezawodne pobieranie klucza API z informacją zwrotną",
+				"uk": "Виправлення: кнопку sendTo замінено власним компонентом PairButton — надійне отримання API-ключа з візуальним відгуком",
+				"zh-cn": "修复：将sendTo按钮替换为自定义PairButton组件，可靠获取API密钥并提供视觉反馈"
+			},
+			"0.2.5": {
+				"en": "Fix: pairing button now uses a custom panel (always visible); commit panel bundles to git so GitHub installs work without a build step",
+				"de": "Bugfix: Pairing-Button als Custom-Panel (immer sichtbar); Panel-Bundles in Git eingecheckt, sodass GitHub-Installationen ohne Build-Schritt funktionieren",
+				"ru": "Исправление: кнопка сопряжения теперь использует пользовательский компонент (всегда видима); бандлы панелей добавлены в git",
+				"pt": "Correção: botão de emparelhamento agora usa painel personalizado (sempre visível); bundles de painel adicionados ao git",
+				"nl": "Bugfix: koppelknop gebruikt nu aangepast panel (altijd zichtbaar); panel-bundles in git gezet",
+				"fr": "Correctif: bouton de couplage utilise désormais un panneau personnalisé (toujours visible); bundles de panneau ajoutés à git",
+				"it": "Correzione: il pulsante di pairing ora usa un pannello personalizzato (sempre visibile); bundle panel aggiunti a git",
+				"es": "Corrección: el botón de emparejamiento ahora usa un panel personalizado (siempre visible); bundles de panel añadidos a git",
+				"pl": "Poprawka: przycisk parowania teraz używa niestandardowego panelu (zawsze widoczny); bundle paneli dodane do git",
+				"uk": "Виправлення: кнопка сполучення тепер використовує власну панель (завжди видима); бандли панелей додано до git",
+				"zh-cn": "修复：配对按钮现在使用自定义面板（始终可见）；面板包已提交至git"
+			},
+			"0.2.4": {
+				"en": "Improve pairing UX: click button first, adapter polls deCONZ every 3 s until pairing window opens (up to 60 s) — no more time pressure",
+				"de": "Pairing-UX verbessert: zuerst Button klicken, Adapter prüft alle 3 s ob das Pairing-Fenster offen ist (bis 60 s) — kein Zeitdruck mehr",
+				"ru": "Улучшен UX сопряжения: сначала нажмите кнопку, адаптер опрашивает deCONZ каждые 3 с (до 60 с) — больше нет спешки",
+				"pt": "UX de emparelhamento melhorado: clique primeiro no botão, o adaptador verifica deCONZ a cada 3 s (até 60 s) — sem pressão de tempo",
+				"nl": "Koppel-UX verbeterd: klik eerst op knop, adapter controleert deCONZ elke 3 s (tot 60 s) — geen tijdsdruk meer",
+				"fr": "UX de couplage amélioré: cliquez d'abord sur le bouton, l'adaptateur interroge deCONZ toutes les 3 s (jusqu'à 60 s) — plus de pression temporelle",
+				"it": "UX accoppiamento migliorato: clicca prima il pulsante, l'adattatore controlla deCONZ ogni 3 s (fino a 60 s) — nessuna pressione temporale",
+				"es": "UX de emparejamiento mejorado: haga clic primero en el botón, el adaptador sondea deCONZ cada 3 s (hasta 60 s) — sin presión de tiempo",
+				"pl": "Poprawiony UX parowania: najpierw kliknij przycisk, adapter odpytuje deCONZ co 3 s (do 60 s) — bez presji czasu",
+				"uk": "Покращено UX сполучення: спочатку натисніть кнопку, адаптер опитує deCONZ кожні 3 с (до 60 с) — без поспіху",
+				"zh-cn": "改进配对用户体验：先点击按钮，适配器每3秒轮询deCONZ（最多60秒）——不再有时间压力"
+			},
+			"0.2.3": {
+				"en": "Add automatic API key pairing: button in Settings tab sends a pairing request to deCONZ and fills in the key",
+				"de": "Automatisches API-Schlüssel-Pairing: Button in Einstellungen sendet Pairinganfrage an deCONZ und trägt den Schlüssel automatisch ein",
+				"ru": "Автоматическое сопряжение API-ключа: кнопка в настройках отправляет запрос на сопряжение в deCONZ и заполняет ключ",
+				"pt": "Emparelhamento automático de chave API: botão nas definições envia pedido de emparelhamento ao deCONZ e preenche a chave",
+				"nl": "Automatisch API-sleutel koppelen: knop in instellingen stuurt een koppelingsverzoek naar deCONZ en vult de sleutel in",
+				"fr": "Couplage automatique de clé API: bouton dans les paramètres envoie une demande de couplage à deCONZ et remplit la clé",
+				"it": "Accoppiamento automatico chiave API: il pulsante nelle impostazioni invia una richiesta di accoppiamento a deCONZ e inserisce la chiave",
+				"es": "Emparejamiento automático de clave API: botón en ajustes envía solicitud de emparejamiento a deCONZ y rellena la clave",
+				"pl": "Automatyczne parowanie klucza API: przycisk w ustawieniach wysyła żądanie parowania do deCONZ i wypełnia klucz",
+				"uk": "Автоматичне сполучення API-ключа: кнопка в налаштуваннях надсилає запит на сполучення до deCONZ і заповнює ключ",
+				"zh-cn": "自动API密钥配对：设置中的按钮向deCONZ发送配对请求并自动填写密钥"
+			},
+			"0.2.2": {
+				"en": "Fix tab labels (Lights/Groups), add static descriptions, improve UX with alive-check and sendTo timeout",
+				"de": "Tab-Bezeichnungen korrigiert (Leuchten/Gruppen), statische Beschreibungen ergänzt, UX verbessert mit Alive-Prüfung und sendTo-Timeout",
+				"ru": "Исправлены названия вкладок, добавлены описания, улучшен UX с проверкой alive и таймаутом sendTo",
+				"pt": "Corrigidas etiquetas de separadores, adicionadas descrições estáticas, UX melhorado com verificação alive e timeout sendTo",
+				"nl": "Tablabels gecorrigeerd, statische beschrijvingen toegevoegd, UX verbeterd met alive-check en sendTo-timeout",
+				"fr": "Libellés d'onglets corrigés, descriptions statiques ajoutées, UX amélioré avec vérification alive et délai sendTo",
+				"it": "Corrette etichette delle schede, aggiunte descrizioni statiche, UX migliorato con controllo alive e timeout sendTo",
+				"es": "Corregidas etiquetas de pestañas, añadidas descripciones estáticas, UX mejorado con comprobación alive y timeout sendTo",
+				"pl": "Poprawiono etykiety zakładek, dodano opisy statyczne, poprawiono UX z kontrolą alive i limitem czasu sendTo",
+				"uk": "Виправлено підписи вкладок, додано статичні описи, покращено UX з перевіркою alive та таймаутом sendTo",
+				"zh-cn": "修正选项卡标签，添加静态描述，通过alive检查和sendTo超时改进用户体验"
+			},
+			"0.2.1": {
+				"en": "Fix: panels were empty because window.React is not a global in admin 7",
+				"de": "Bugfix: Panels waren leer, weil window.React in Admin 7 kein Global ist",
+				"ru": "Исправление: панели были пустыми, так как window.React не является глобальным в admin 7",
+				"pt": "Correção: os painéis estavam vazios porque window.React não é global no admin 7",
+				"nl": "Bugfix: panels waren leeg omdat window.React geen global is in admin 7",
+				"fr": "Correctif: les panneaux étaient vides car window.React n'est pas un global dans admin 7",
+				"it": "Correzione: i pannelli erano vuoti perché window.React non è un global in admin 7",
+				"es": "Corrección: los paneles estaban vacíos porque window.React no es un global en admin 7",
+				"pl": "Poprawka: panele były puste, ponieważ window.React nie jest globalnym w admin 7",
+				"uk": "Виправлення: панелі були порожніми, оскільки window.React не є глобальним в admin 7",
+				"zh-cn": "修复：面板为空，因为window.React在admin 7中不是全局变量"
+			},
+			"0.2.0": {
+				"en": "Admin UI: lights and groups tabs in adapter settings; group management (create, edit, delete); Node.js >= 22 required",
+				"de": "Admin-UI: Lampen- und Gruppen-Tabs in den Adaptereinstellungen; Gruppenverwaltung (erstellen, bearbeiten, löschen); Node.js >= 22 erforderlich",
+				"ru": "Admin UI: вкладки светильников и групп в настройках адаптера; управление группами (создание, редактирование, удаление); требуется Node.js >= 22",
+				"pt": "Admin UI: abas de luzes e grupos nas configurações do adaptador; gestão de grupos (criar, editar, eliminar); necessário Node.js >= 22",
+				"nl": "Admin UI: lampen- en groepentabbladen in adapterinstellingen; groepsbeheer (maken, bewerken, verwijderen); Node.js >= 22 vereist",
+				"fr": "Admin UI: onglets lampes et groupes dans les paramètres de l'adaptateur; gestion des groupes (créer, modifier, supprimer); Node.js >= 22 requis",
+				"it": "Admin UI: schede luci e gruppi nelle impostazioni dell'adattatore; gestione gruppi (creare, modificare, eliminare); Node.js >= 22 richiesto",
+				"es": "Admin UI: pestañas de luces y grupos en la configuración del adaptador; gestión de grupos (crear, editar, eliminar); Node.js >= 22 requerido",
+				"pl": "Admin UI: zakładki świateł i grup w ustawieniach adaptera; zarządzanie grupami (tworzenie, edycja, usuwanie); wymagany Node.js >= 22",
+				"uk": "Admin UI: вкладки ламп та груп у налаштуваннях адаптера; керування групами (створення, редагування, видалення); потрібен Node.js >= 22",
+				"zh-cn": "管理界面：适配器设置中的灯具和群组选项卡；群组管理（创建、编辑、删除）；需要Node.js >= 22"
+			},
+			"0.1.0": {
+				"en": "Initial release: lights, groups, scenes, Tint remote with color wheel",
+				"de": "Erstveröffentlichung: Lampen, Gruppen, Szenen, Tint-Fernbedienung mit Farbrad",
+				"ru": "Первый выпуск: лампы, группы, сцены, пульт Tint с цветовым колесом",
+				"pt": "Lançamento inicial: luzes, grupos, cenas, controlo remoto Tint com roda de cores",
+				"nl": "Eerste versie: lampen, groepen, scènes, Tint-afstandsbediening met kleurenwiel",
+				"fr": "Version initiale: lampes, groupes, scènes, télécommande Tint avec roue chromatique",
+				"it": "Versione iniziale: luci, gruppi, scene, telecomando Tint con ruota dei colori",
+				"es": "Versión inicial: luces, grupos, escenas, mando a distancia Tint con rueda de colores",
+				"pl": "Pierwsza wersja: światła, grupy, sceny, pilot Tint z kołem kolorów",
+				"uk": "Перший випуск: лампи, групи, сцени, пульт Tint із колесом кольорів",
+				"zh-cn": "初始版本：灯具、群组、场景、带色轮的Tint遥控器"
+			}
+		},
+		"titleLang": {
+			"en": "Müller Licht tint",
+			"de": "Müller Licht tint",
+			"ru": "Müller Licht tint",
+			"pt": "Müller Licht tint",
+			"nl": "Müller Licht tint",
+			"fr": "Müller Licht tint",
+			"it": "Müller Licht tint",
+			"es": "Müller Licht tint",
+			"pl": "Müller Licht tint",
+			"uk": "Müller Licht tint",
+			"zh-cn": "Müller Licht tint"
+		},
+		"desc": {
+			"en": "Control Müller Licht tint Zigbee smart lights via deCONZ/ConBee including full Tint remote support with color wheel",
+			"de": "Steuerung von Müller Licht tint Zigbee-Leuchten über deCONZ/ConBee inkl. vollständiger Tint-Fernbedienungsunterstützung mit Farbrad",
+			"ru": "Управление умными светильниками Müller Licht tint Zigbee через deCONZ/ConBee, включая полную поддержку пульта Tint с цветовым колесом",
+			"pt": "Controle luzes inteligentes Müller Licht tint Zigbee via deCONZ/ConBee incluindo suporte completo ao controlo remoto Tint com roda de cores",
+			"nl": "Bedien Müller Licht tint Zigbee slimme lampen via deCONZ/ConBee inclusief volledige Tint-afstandsbediening met kleurenwiel",
+			"fr": "Contrôlez les éclairages intelligents Müller Licht tint Zigbee via deCONZ/ConBee avec support complet de la télécommande Tint et roue chromatique",
+			"it": "Controlla le luci intelligenti Müller Licht tint Zigbee tramite deCONZ/ConBee con pieno supporto del telecomando Tint con ruota dei colori",
+			"es": "Controle las luces inteligentes Müller Licht tint Zigbee a través de deCONZ/ConBee con soporte completo del mando Tint con rueda de colores",
+			"pl": "Steruj inteligentnymi lampami Müller Licht tint Zigbee przez deCONZ/ConBee z pełną obsługą pilota Tint z kołem kolorów",
+			"uk": "Керуйте розумними лампами Müller Licht tint Zigbee через deCONZ/ConBee з повною підтримкою пульта Tint із колесом кольорів",
+			"zh-cn": "通过deCONZ/ConBee控制Müller Licht tint Zigbee智能灯，包括完整的Tint遥控器色轮支持"
+		},
+		"authors": [
+			"ssbingo <s.sternitzke@online.de>"
+		],
+		"keywords": [
+			"MüllerLicht",
+			"Tint",
+			"Zigbee",
+			"deCONZ",
+			"ConBee",
+			"RGBW"
+		],
+		"licenseInformation": {
+			"type": "free",
+			"license": "MIT"
+		},
+		"platform": "Javascript/Node.js",
+		"icon": "tint.png",
+		"enabled": true,
+		"extIcon": "https://raw.githubusercontent.com/ssbingo/ioBroker.tint/main/admin/tint.png",
+		"readme": "https://github.com/ssbingo/ioBroker.tint/blob/main/README.md",
+		"loglevel": "info",
+		"tier": 3,
+		"mode": "daemon",
+		"type": "hardware",
+		"compact": true,
+		"messagebox": true,
+		"connectionType": "local",
+		"dataSource": "push",
+		"adminUI": {
+			"config": "json"
+		},
+		"dependencies": [
+			{
+				"js-controller": ">=6.0.11"
+			}
+		],
+		"globalDependencies": [
+			{
+				"admin": ">=7.0.23"
+			}
+		]
+	},
+	"native": {
+		"ip": "192.168.1.100",
+		"port": 80,
+		"wsPort": 443,
+		"apiKey": "",
+		"pollingInterval": 60,
+		"autoApplyColorWheel": true,
+		"transitionTime": 4,
+		"watchdogMinutes": 120
+	},
+	"encryptedNative": [
+		"apiKey"
+	],
+	"protectedNative": [
+		"apiKey"
+	],
+	"objects": [],
+	"instanceObjects": [
+		{
+			"_id": "info.connection",
+			"type": "state",
+			"common": {
+				"name": {
+					"en": "Connection to deCONZ",
+					"de": "Verbindung zu deCONZ"
+				},
+				"type": "boolean",
+				"role": "indicator.connected",
+				"read": true,
+				"write": false,
+				"def": false
+			},
+			"native": {}
+		}
+	]
+}

package/lib/adapter-config.d.ts

@@ -0,0 +1,20 @@
+// This file extends the AdapterConfig type from "@types/iobroker"
+
+// Inhere the actual properties of your adapter config
+declare global {
+	namespace ioBroker {
+		interface AdapterConfig {
+			ip: string;
+			port: number;
+			wsPort: number;
+			apiKey: string;
+			pollingInterval: number;
+			autoApplyColorWheel: boolean;
+			transitionTime: number;
+			watchdogMinutes: number;
+		}
+	}
+}
+
+// this is required so the above global namespace changes take effect
+export {};

package/lib/admin-projections.js

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * Trims raw deCONZ light/group objects down to only the fields the admin
+ * UI tabs actually read (admin/src/components/LightsTab.jsx, PlugsTab.jsx,
+ * CoversTab.jsx, GroupsTab.jsx, GroupDialog.jsx, ScenesTab.jsx,
+ * deviceCategory.js).
+ *
+ * Why this exists: deCONZ's raw /lights payload includes large, unused
+ * fields per light — most notably "capabilities" (color gamut points,
+ * effect/alert enum lists, etc.), plus etag/lastannounced/swversion/
+ * uniqueid/hascolor that no admin tab displays. For an installation with
+ * ~30 lights this raw payload is tens of KB; sending it verbatim over the
+ * same socket.io connection admin uses to track host-alive heartbeats can
+ * make the browser's main thread busy parsing/rendering it long enough to
+ * delay heartbeat processing, which iobroker.admin's HostSelectors
+ * component (adminWww bootstrap bundle) interprets as the host going
+ * briefly "not alive" — surfacing as a red, "switch host" warning despite
+ * nothing actually being wrong. Trimming the response to only what's
+ * displayed removes the root cause instead of just the symptom.
+ */
+
+/**
+ * @param {object} light - Raw deCONZ light object
+ * @returns {object} Minimal projection used by the admin Lights/Plugs/Covers tabs
+ */
+function trimLightForAdmin(light) {
+	const s = light?.state || {};
+	return {
+		name: light?.name,
+		modelid: light?.modelid,
+		manufacturername: light?.manufacturername,
+		type: light?.type,
+		state: {
+			on: s.on,
+			bri: s.bri,
+			reachable: s.reachable,
+			lift: s.lift,
+			open: s.open,
+		},
+	};
+}
+
+/**
+ * @param {object} group - Raw deCONZ group object
+ * @returns {object} Minimal projection used by the admin Groups/Scenes tabs
+ */
+function trimGroupForAdmin(group) {
+	const st = group?.state || {};
+	return {
+		name: group?.name,
+		lights: group?.lights,
+		scenes: group?.scenes,
+		state: {
+			all_on: st.all_on,
+			any_on: st.any_on,
+		},
+	};
+}
+
+module.exports = { trimLightForAdmin, trimGroupForAdmin };

package/lib/color-utils.js

@@ -0,0 +1,230 @@
+'use strict';
+
+/**
+ * Color utility functions for Müller Licht tint adapter
+ * - CIE xy ↔ sRGB Hex conversion
+ * - Tint Remote color wheel position map (36 positions × 10°)
+ * - Brightness % ↔ deCONZ bri (0–254)
+ * - Color temperature Kelvin ↔ Mired
+ */
+
+// ─── Brightness ───────────────────────────────────────────────────────────────
+
+/**
+ * deCONZ bri (0–254) → percentage (0–100)
+ *
+ * @param {number} bri - deCONZ brightness value (0–254)
+ * @returns {number} Brightness percentage (0–100)
+ */
+function briToPercent(bri) {
+	return Math.round((Math.max(0, Math.min(254, bri)) / 254) * 100);
+}
+
+/**
+ * Percentage (0–100) → deCONZ bri (0–254)
+ *
+ * @param {number} pct - Brightness percentage (0–100)
+ * @returns {number} deCONZ brightness value (0–254)
+ */
+function percentToBri(pct) {
+	return Math.round((Math.max(0, Math.min(100, pct)) / 100) * 254);
+}
+
+// ─── Color Temperature ────────────────────────────────────────────────────────
+
+/**
+ * Mired → Kelvin
+ *
+ * deCONZ reports ct=0 for lights/groups that don't support color temperature
+ * (e.g. plugs, or a group with no CT-capable members) — clamp to the
+ * colorTemp state's declared range (2000–6500 K) instead of letting that
+ * sentinel produce a huge out-of-range value.
+ *
+ * @param {number} mired - Color temperature in Mired
+ * @returns {number} Color temperature in Kelvin
+ */
+function miredToKelvin(mired) {
+	return Math.max(2000, Math.min(6500, Math.round(1000000 / Math.max(1, mired))));
+}
+
+/**
+ * Kelvin → Mired
+ *
+ * @param {number} kelvin - Color temperature in Kelvin
+ * @returns {number} Color temperature in Mired
+ */
+function kelvinToMired(kelvin) {
+	return Math.round(1000000 / Math.max(1, kelvin));
+}
+
+// ─── CIE xy → sRGB Hex ───────────────────────────────────────────────────────
+
+/**
+ * Convert CIE 1931 xy chromaticity + brightness to sRGB Hex string.
+ * Uses Wide Gamut D65 matrix (matches Philips Hue / Müller Licht tint)
+ *
+ * @param {number} x - CIE x chromaticity (0.0–1.0)
+ * @param {number} y - CIE y chromaticity (0.0–1.0)
+ *  @param {number} [bri] - deCONZ brightness (0–254, default 254) (0–254)
+ * @returns {string} sRGB hex color string e.g. "#FF4400"
+ */
+function xyToHex(x, y, bri = 254) {
+	if (y === 0) {
+		return '#000000';
+	}
+
+	const Y = bri / 254;
+	const X = (Y / y) * x;
+	const Z = (Y / y) * (1.0 - x - y);
+
+	// Wide Gamut D65 matrix (sRGB)
+	let r = X * 1.656492 - Y * 0.354851 - Z * 0.255038;
+	let g = -X * 0.707196 + Y * 1.655397 + Z * 0.036152;
+	let b = X * 0.051713 - Y * 0.121364 + Z * 1.01153;
+
+	// Clamp negatives
+	r = Math.max(0, r);
+	g = Math.max(0, g);
+	b = Math.max(0, b);
+
+	// Normalise so largest channel = 1.0
+	const max = Math.max(r, g, b, 1);
+	r /= max;
+	g /= max;
+	b /= max;
+
+	// Gamma correction (sRGB)
+	const gamma = v => (v <= 0.0031308 ? 12.92 * v : (1.0 + 0.055) * Math.pow(v, 1.0 / 2.4) - 0.055);
+
+	const R = Math.round(gamma(r) * 255);
+	const G = Math.round(gamma(g) * 255);
+	const B = Math.round(gamma(b) * 255);
+
+	return `#${[R, G, B]
+		.map(v => v.toString(16).padStart(2, '0'))
+		.join('')
+		.toUpperCase()}`;
+}
+
+/**
+ * sRGB Hex → CIE xy array [x, y].
+ * Useful for writing a hex color to a light.
+ *
+ * @param {string} hex - sRGB hex color e.g. "#FF4400" or "FF4400"
+ * @returns {[number, number]} CIE xy chromaticity pair
+ */
+function hexToXy(hex) {
+	const clean = hex.replace('#', '');
+	const R = parseInt(clean.slice(0, 2), 16) / 255;
+	const G = parseInt(clean.slice(2, 4), 16) / 255;
+	const B = parseInt(clean.slice(4, 6), 16) / 255;
+
+	// Reverse gamma
+	const linear = v => (v > 0.04045 ? Math.pow((v + 0.055) / 1.055, 2.4) : v / 12.92);
+
+	const r = linear(R);
+	const g = linear(G);
+	const b = linear(B);
+
+	// Wide Gamut D65 (inverse of the matrix above, approximate)
+	const X = r * 0.664511 + g * 0.154324 + b * 0.162028;
+	const Y = r * 0.283881 + g * 0.668433 + b * 0.047685;
+	const Z = r * 0.000088 + g * 0.07231 + b * 0.986039;
+
+	const sum = X + Y + Z;
+	if (sum === 0) {
+		return [0, 0];
+	}
+
+	return [Math.round((X / sum) * 10000) / 10000, Math.round((Y / sum) * 10000) / 10000];
+}
+
+// ─── Tint Remote color wheel (36 positions, 10° steps) ───────────────────────
+//
+// Source: empirical measurements from the community
+// (github.com/dresden-elektronik/deconz-rest-plugin, xaviml/controllerx)
+// angle → CIE xy sent by the remote on buttonevent 6002
+
+/**
+ * Tint Remote color wheel map: angle (0–350°, 10° steps) → CIE xy
+ *
+ *  {Record<number, {x: number, y: number}>}
+ */
+const COLOR_WHEEL_MAP = {
+	0: { x: 0.7, y: 0.299 }, // Red
+	10: { x: 0.68, y: 0.305 },
+	20: { x: 0.65, y: 0.32 },
+	30: { x: 0.61, y: 0.36 }, // Red-Orange
+	40: { x: 0.57, y: 0.39 },
+	50: { x: 0.53, y: 0.43 }, // Orange
+	60: { x: 0.49, y: 0.45 },
+	70: { x: 0.45, y: 0.47 }, // Yellow-Orange
+	80: { x: 0.42, y: 0.5 },
+	90: { x: 0.38, y: 0.52 }, // Yellow
+	100: { x: 0.34, y: 0.54 },
+	110: { x: 0.3, y: 0.54 },
+	120: { x: 0.25, y: 0.53 }, // Yellow-Green
+	130: { x: 0.21, y: 0.51 },
+	140: { x: 0.18, y: 0.48 }, // Green
+	150: { x: 0.16, y: 0.44 },
+	160: { x: 0.15, y: 0.39 },
+	170: { x: 0.155, y: 0.34 }, // Cyan-Green
+	180: { x: 0.165, y: 0.29 }, // Cyan
+	190: { x: 0.175, y: 0.25 },
+	200: { x: 0.19, y: 0.21 },
+	210: { x: 0.21, y: 0.175 }, // Cyan-Blue
+	220: { x: 0.23, y: 0.15 },
+	230: { x: 0.25, y: 0.13 }, // Blue
+	240: { x: 0.2, y: 0.1 },
+	250: { x: 0.16, y: 0.08 },
+	260: { x: 0.14, y: 0.065 }, // Dark Blue
+	270: { x: 0.16, y: 0.065 }, // Violet-Blue
+	280: { x: 0.195, y: 0.075 },
+	290: { x: 0.24, y: 0.085 }, // Violet
+	300: { x: 0.28, y: 0.1 },
+	310: { x: 0.33, y: 0.11 }, // Magenta
+	320: { x: 0.39, y: 0.13 },
+	330: { x: 0.46, y: 0.16 }, // Pink-Red
+	340: { x: 0.54, y: 0.2 },
+	350: { x: 0.62, y: 0.25 }, // Red-Pink
+};
+
+/**
+ * Tint Remote zone group IDs → zone number (1–3)
+ *
+ *  {Record<number, number>}
+ */
+const ZONE_GROUP_MAP = {
+	16388: 1,
+	16389: 2,
+	16390: 3,
+};
+
+/**
+ * Decode the active zone from the sensor config.group string.
+ * Returns 0 when "all" or undetermined.
+ *
+ * @param {string} groupString - Comma-separated group ids e.g. "16388" or "16388,16389,16390"
+ * @returns {number} Zone number 0=all, 1=zone1, 2=zone2, 3=zone3
+ */
+function decodeRemoteZone(groupString) {
+	if (!groupString) {
+		return 0;
+	}
+	const parts = groupString.split(',').map(Number);
+	if (parts.length === 1) {
+		return ZONE_GROUP_MAP[parts[0]] || 0;
+	}
+	return 0; // multiple groups = "all"
+}
+
+module.exports = {
+	briToPercent,
+	percentToBri,
+	miredToKelvin,
+	kelvinToMired,
+	xyToHex,
+	hexToXy,
+	COLOR_WHEEL_MAP,
+	decodeRemoteZone,
+};