feat: auto-detect cover entities from lighting group labels

Groups on the Lighting application (56) whose label contains a cover
keyword (blind/shutter/shade/awning/curtain/roller/garage door) are now
discovered as Home Assistant cover entities instead of light. This fixes
the common case where shutter relays share the lighting application with
real lights and previously all appeared as lights.

Classification is label-only and conservative: a manual type_overrides
entry and application-id mappings always take precedence; auto-detection
only ever upgrades the default light. Gated by ha_discovery_auto_type
(default on), with ha_discovery_auto_type_name_heuristics and a tunable
ha_discovery_auto_type_cover_keywords list.

Author: dougrathbone

README.md

@@ -164,10 +164,18 @@ The crucial step is setting the correct `ha_discovery_*_app_id` values to match
 **Important Notes:**
 
 *   Discovery for Covers, Switches, Relays, PIRs, and HVAC is **disabled by default** (`null`). Only the Lighting application (56) is discovered automatically, and **every** Lighting group is published as a `light`. You *must* set the corresponding `ha_discovery_*_app_id` in `settings.js` to the correct C-Bus Application ID to enable the other types.
-*   **Devices that live on the Lighting application (56) but are not lights** — e.g. shutter-relay units (blinds use lighting group addresses) or a thermostat exposed on app 56 — will appear as `light` entities because classification is purely by Application ID. To reclassify an individual group, add a per-group `type_overrides` entry in your labels file (`"<net>/<app>/<group>": "cover" | "switch" | "relay" | "pir" | "hvac"`) or via the web UI; this is the only way to change the type of a group that shares the Lighting application with real lights.
+*   **Devices that live on the Lighting application (56) but are not lights** — e.g. shutter-relay units (blinds use lighting group addresses) or a thermostat exposed on app 56 — are classified by Application ID and so default to `light`. Motorised covers whose label contains a cover keyword are now auto-detected (see *Automatic cover detection* below). For anything auto-detection can't infer, add a per-group `type_overrides` entry in your labels file (`"<net>/<app>/<group>": "cover" | "switch" | "relay" | "pir" | "hvac"`) or via the web UI; an override always wins.
 *   If multiple discovery types (e.g., Cover and Switch) are configured with the *same* Application ID, `cgateweb` prioritizes discovery in this order: Cover > Switch > Relay > PIR. Only the first matching type will be discovered for a given C-Bus group using that Application ID.
 *   For more technical details, see `docs/project-homeassistant-discovery.md`.
 
+#### Automatic cover detection
+
+Groups on the Lighting application (56) whose label contains a cover keyword (`blind`, `shutter`, `shade`, `awning`, `curtain`, `roller`, `garage door`) are published as Home Assistant `cover` entities instead of `light`. This is on by default (`ha_discovery_auto_type: true`).
+
+Precedence: a manual `type_overrides` entry always wins, then application-id mappings, then this automatic detection, then the default `light`. To disable auto-detection set `ha_discovery_auto_type: false`; to keep it on but turn off keyword matching set `ha_discovery_auto_type_name_heuristics: false`. Customise the keyword list with `ha_discovery_auto_type_cover_keywords` (matching is case-insensitive and catches plurals).
+
+Note: a shutter relay with a non-descriptive name still appears as a light — add a `type_overrides` entry (e.g. `"254/56/15": "cover"`) for those.
+
 ### Testing
 
 This project uses Jest for unit testing.

homeassistant-addon/DOCS.md

@@ -174,6 +174,9 @@ Disable auto-discovery (`auto_discover_networks: false`) if:
 | `ha_discovery_switch_app_id` | integer | (null) | C-Bus app ID for switches (optional). Leave empty to disable switch discovery. |
 | `ha_discovery_trigger_app_id` | integer | (null) | C-Bus app ID for trigger groups (keypads, scene buttons). Typically `202`. Each group is exposed as an HA `event` entity, a companion `button` entity, and (when `ha_discovery_scene_enabled` is `true`) a `scene` entity. Leave empty to disable. |
 | `ha_discovery_scene_enabled` | boolean | `true` | Publish an HA `scene` entity for each C-Bus trigger group in addition to the `event` and `button` entities. Set to `false` to suppress scene entities. |
+| `ha_discovery_auto_type` | boolean | `true` | Auto-detect device types for Lighting-application (56) groups. Currently detects motorised covers (blinds/shutters) from the group label. A manual `type_overrides` entry and application-id mappings always take precedence; auto-detection only upgrades the default `light`. |
+| `ha_discovery_auto_type_name_heuristics` | boolean | `true` | When `ha_discovery_auto_type` is on, classify covers by matching the group label against the cover keyword list. Set to `false` to turn keyword matching off. |
+| `ha_discovery_auto_type_cover_keywords` | list | `[blind, shutter, shade, awning, curtain, roller, garage door]` | Keywords that mark a Lighting group as a cover. Matching is case-insensitive and catches plurals. |
 | `ha_discovery_hvac_app_id` | integer | (null) | C-Bus app ID for HVAC/climate zones. The standard C-Bus HVAC application is `201`. Each group is exposed as an HA `climate` entity. Leave empty to disable. |
 | `ha_hvac_temperature_unit` | list | `C` | Temperature unit for HVAC climate entities: `C` for Celsius, `F` for Fahrenheit. |
 | `ha_bridge_diagnostics_enabled` | boolean | `true` | Publish bridge health/diagnostic entities to Home Assistant via MQTT Discovery |

src/defaultSettings.js

@@ -51,6 +51,15 @@ const defaultSettings = {
     ha_discovery_pir_app_id: null,
     ha_discovery_trigger_app_id: null,
     ha_discovery_scene_enabled: true,
+    // Automatic device-type detection for groups on the Lighting application
+    // (56). Phase 1: detect motorised covers (blinds/shutters) from the group
+    // label. Only ever upgrades the lighting fallback — manual type_overrides
+    // and application-id mappings always take precedence.
+    ha_discovery_auto_type: true,
+    ha_discovery_auto_type_name_heuristics: true,
+    ha_discovery_auto_type_cover_keywords: [
+        'blind', 'shutter', 'shade', 'awning', 'curtain', 'roller', 'garage door'
+    ],
     ha_discovery_hvac_app_id: null,
     ha_hvac_temperature_unit: 'C',
     ha_bridge_diagnostics_enabled: true,

src/deviceTypeClassifier.js

@@ -0,0 +1,41 @@
+// Conservative keyword list for detecting motorised cover devices (blinds,
+// shutters, curtains, etc.) that are wired onto the C-Bus Lighting application
+// (56). The C-Gate tree cannot tell a shutter relay from a lighting relay, so
+// the group's name is the only automatic signal. Leading word-boundary match
+// (no trailing boundary) so plurals like "blinds"/"shutters" are caught.
+const DEFAULT_COVER_KEYWORDS = [
+    'blind', 'shutter', 'shade', 'awning', 'curtain', 'roller', 'garage door'
+];
+
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Decide an effective HA discovery type for a Lighting-application group from
+ * its resolved label. Returns 'cover' on a keyword match, otherwise null
+ * (meaning "leave as the default light").
+ *
+ * @param {string} label - The resolved group label (custom label or TREEXML label).
+ * @param {object} settings - Bridge settings.
+ * @returns {'cover'|null}
+ */
+function classifyLightingGroup(label, settings = {}) {
+    if (settings.ha_discovery_auto_type === false) return null;
+    if (settings.ha_discovery_auto_type_name_heuristics === false) return null;
+    if (typeof label !== 'string' || !label.trim()) return null;
+
+    const keywords = (Array.isArray(settings.ha_discovery_auto_type_cover_keywords)
+        && settings.ha_discovery_auto_type_cover_keywords.length)
+        ? settings.ha_discovery_auto_type_cover_keywords
+        : DEFAULT_COVER_KEYWORDS;
+
+    for (const kw of keywords) {
+        if (typeof kw !== 'string' || !kw.trim()) continue;
+        const re = new RegExp(`\\b${escapeRegExp(kw.trim())}`, 'i');
+        if (re.test(label)) return 'cover';
+    }
+    return null;
+}
+
+module.exports = { classifyLightingGroup, DEFAULT_COVER_KEYWORDS };

src/haDiscovery.js

@@ -1,6 +1,7 @@
 const parseString = require('xml2js').parseString;
 const { createLogger } = require('./logger');
 const { getDiscoveryTypeForApp, getDiscoveryConfig } = require('./haDiscoveryConfigs');
+const { classifyLightingGroup } = require('./deviceTypeClassifier');
 const { findNetworkData, collectUnitGroups } = require('./haDiscoveryTree');
 const { backoffDelay } = require('./backoff');
 const {
@@ -670,11 +671,20 @@ class HaDiscovery {
                 return;
             }
 
-            const typeOverride = typeOverrides.get(labelKey);
-            if (typeOverride && typeOverride !== 'light') {
-                const config = getDiscoveryConfig(typeOverride);
+            // Resolve an effective type. Manual type_overrides have absolute
+            // priority; auto-detection only fills in when there is no override
+            // and only ever upgrades the lighting fallback (it never returns
+            // 'light'). Application-id mappings are handled in
+            // _processEnableControlGroups and never reach this lighting path.
+            const labelForClassification = labelMap.get(labelKey) || group.Label || '';
+            let resolvedType = typeOverrides.get(labelKey);
+            if (!resolvedType) {
+                resolvedType = classifyLightingGroup(labelForClassification, this.settings);
+            }
+            if (resolvedType && resolvedType !== 'light') {
+                const config = getDiscoveryConfig(resolvedType);
                 if (config) {
-                    this.logger.debug(`Type override: ${labelKey} -> ${typeOverride}`);
+                    this.logger.debug(`Resolved type: ${labelKey} -> ${resolvedType}`);
                     if (config.isHvac) {
                         // HVAC needs the dedicated climate payload (temperature/mode
                         // topics); the generic builder would publish a broken
@@ -685,15 +695,15 @@ class HaDiscovery {
                     }
                     // Remove any stale retained light config for this group.
                     // This covers the case where the type changes within the same session
-                    // (e.g. first run saw it as a light; this run sees the type override).
+                    // (e.g. first run saw it as a light; this run resolves a non-light type).
                     const uniqueId = `cgateweb_${networkId}_${appId}_${groupId}`;
                     const staleTopic = `${this.settings.ha_discovery_prefix}/${HA_COMPONENT_LIGHT}/${uniqueId}/${HA_DISCOVERY_SUFFIX}`;
                     this._publish(staleTopic, '', MQTT_RETAINED_STATE_OPTIONS);
                     // Ensure the stale light topic is not retained in _publishedTopics
                     this._publishedTopics.delete(staleTopic);
                     return;
                 }
-                this.logger.warn(`Unknown type override "${typeOverride}" for ${labelKey}, falling back to light`);
+                this.logger.warn(`Unknown resolved type "${resolvedType}" for ${labelKey}, falling back to light`);
             }
 
             const customLabel = labelMap.get(labelKey);

tests/defaultSettings.test.js

@@ -0,0 +1,13 @@
+const { defaultSettings } = require('../src/defaultSettings');
+
+describe('defaultSettings — auto device-type detection', () => {
+    it('enables auto type detection and name heuristics by default', () => {
+        expect(defaultSettings.ha_discovery_auto_type).toBe(true);
+        expect(defaultSettings.ha_discovery_auto_type_name_heuristics).toBe(true);
+    });
+
+    it('ships a non-empty default cover keyword list', () => {
+        expect(Array.isArray(defaultSettings.ha_discovery_auto_type_cover_keywords)).toBe(true);
+        expect(defaultSettings.ha_discovery_auto_type_cover_keywords).toContain('blind');
+    });
+});

tests/deviceTypeClassifier.test.js

@@ -0,0 +1,58 @@
+const {
+    classifyLightingGroup,
+    DEFAULT_COVER_KEYWORDS
+} = require('../src/deviceTypeClassifier');
+
+describe('classifyLightingGroup', () => {
+    const on = { ha_discovery_auto_type: true };
+
+    it('returns "cover" for blind/shutter labels (incl. plurals)', () => {
+        expect(classifyLightingGroup('Master Bedroom Blind', on)).toBe('cover');
+        expect(classifyLightingGroup('Living Blinds', on)).toBe('cover');
+        expect(classifyLightingGroup('Patio Shutter', on)).toBe('cover');
+        expect(classifyLightingGroup('Kitchen Curtains', on)).toBe('cover');
+        expect(classifyLightingGroup('Front Awning', on)).toBe('cover');
+        expect(classifyLightingGroup('Roller Door', on)).toBe('cover');
+        expect(classifyLightingGroup('Garage Door', on)).toBe('cover');
+    });
+
+    it('returns null for ordinary light labels', () => {
+        expect(classifyLightingGroup('Kitchen Downlights', on)).toBeNull();
+        expect(classifyLightingGroup('Hallway', on)).toBeNull();
+        expect(classifyLightingGroup('Bedroom Lamp', on)).toBeNull();
+    });
+
+    it('returns null for empty/invalid labels', () => {
+        expect(classifyLightingGroup('', on)).toBeNull();
+        expect(classifyLightingGroup('   ', on)).toBeNull();
+        expect(classifyLightingGroup(undefined, on)).toBeNull();
+        expect(classifyLightingGroup(null, on)).toBeNull();
+    });
+
+    it('is disabled when auto_type is false', () => {
+        expect(classifyLightingGroup('Master Blind', { ha_discovery_auto_type: false })).toBeNull();
+    });
+
+    it('is disabled when name heuristics are turned off', () => {
+        expect(classifyLightingGroup('Master Blind', {
+            ha_discovery_auto_type: true,
+            ha_discovery_auto_type_name_heuristics: false
+        })).toBeNull();
+    });
+
+    it('defaults to enabled when auto_type key is absent', () => {
+        expect(classifyLightingGroup('Master Blind', {})).toBe('cover');
+    });
+
+    it('honours a custom keyword list', () => {
+        const s = { ha_discovery_auto_type: true, ha_discovery_auto_type_cover_keywords: ['persiana'] };
+        expect(classifyLightingGroup('Persiana Salon', s)).toBe('cover');
+        expect(classifyLightingGroup('Bedroom Blind', s)).toBeNull();
+    });
+
+    it('exports the default keyword list', () => {
+        expect(DEFAULT_COVER_KEYWORDS).toEqual(
+            expect.arrayContaining(['blind', 'shutter', 'curtain', 'awning', 'roller', 'garage door', 'shade'])
+        );
+    });
+});

tests/haDiscovery.test.js

@@ -1187,6 +1187,95 @@ describe('HaDiscovery', () => {
             expect(payload.modes).toEqual(expect.arrayContaining(['off', 'auto', 'cool', 'heat', 'fan_only']));
         });
 
+        describe('Auto device-type detection (cover name-heuristic)', () => {
+            function makeHa(settings, labelData) {
+                return new HaDiscovery(settings, mockPublishFn, mockSendCommandFn, labelData);
+            }
+
+            it('publishes a cover (not light) when a lighting group label looks like a blind', () => {
+                const settings = { ...mockSettings, ha_discovery_auto_type: true, ha_discovery_cover_app_id: null };
+                const labelData = {
+                    labels: new Map([['254/56/10', 'Master Bedroom Blinds']]),
+                    typeOverrides: new Map(),
+                    entityIds: new Map(),
+                    exclude: new Set()
+                };
+                const ha = makeHa(settings, labelData);
+                ha._publishDiscoveryFromTree('254', MOCK_TREEXML_RESULT_NET254);
+
+                const coverCall = mockPublishFn.mock.calls.find(
+                    c => c[0] === 'testhomeassistant/cover/cgateweb_254_56_10/config'
+                );
+                expect(coverCall).toBeDefined();
+                const payload = JSON.parse(coverCall[1]);
+                expect(payload.device.name).toBe('Master Bedroom Blinds');
+
+                // The stale light config must be cleared with an empty retained payload.
+                const lightCall = mockPublishFn.mock.calls.find(
+                    c => c[0] === 'testhomeassistant/light/cgateweb_254_56_10/config'
+                );
+                expect(lightCall).toBeDefined();
+                expect(lightCall[1]).toBe('');
+            });
+
+            it('leaves ordinary lighting labels as lights', () => {
+                const settings = { ...mockSettings, ha_discovery_auto_type: true };
+                const labelData = {
+                    labels: new Map([['254/56/10', 'Kitchen Downlights']]),
+                    typeOverrides: new Map(), entityIds: new Map(), exclude: new Set()
+                };
+                const ha = makeHa(settings, labelData);
+                ha._publishDiscoveryFromTree('254', MOCK_TREEXML_RESULT_NET254);
+
+                const lightCall = mockPublishFn.mock.calls.find(
+                    c => c[0] === 'testhomeassistant/light/cgateweb_254_56_10/config'
+                );
+                expect(lightCall).toBeDefined();
+                expect(lightCall[1]).not.toBe('');
+                const coverCall = mockPublishFn.mock.calls.find(
+                    c => c[0] === 'testhomeassistant/cover/cgateweb_254_56_10/config'
+                );
+                expect(coverCall).toBeUndefined();
+            });
+
+            it('does nothing when auto_type is disabled (no behaviour change)', () => {
+                const settings = { ...mockSettings, ha_discovery_auto_type: false };
+                const labelData = {
+                    labels: new Map([['254/56/10', 'Master Bedroom Blinds']]),
+                    typeOverrides: new Map(), entityIds: new Map(), exclude: new Set()
+                };
+                const ha = makeHa(settings, labelData);
+                ha._publishDiscoveryFromTree('254', MOCK_TREEXML_RESULT_NET254);
+
+                const lightCall = mockPublishFn.mock.calls.find(
+                    c => c[0] === 'testhomeassistant/light/cgateweb_254_56_10/config'
+                );
+                expect(lightCall).toBeDefined();
+                expect(lightCall[1]).not.toBe('');
+            });
+
+            it('manual type_overrides win over auto-detection', () => {
+                // Label looks like a blind, but the user explicitly forces 'switch'.
+                const settings = { ...mockSettings, ha_discovery_auto_type: true };
+                const labelData = {
+                    labels: new Map([['254/56/10', 'Master Bedroom Blinds']]),
+                    typeOverrides: new Map([['254/56/10', 'switch']]),
+                    entityIds: new Map(), exclude: new Set()
+                };
+                const ha = makeHa(settings, labelData);
+                ha._publishDiscoveryFromTree('254', MOCK_TREEXML_RESULT_NET254);
+
+                const switchCall = mockPublishFn.mock.calls.find(
+                    c => c[0] === 'testhomeassistant/switch/cgateweb_254_56_10/config'
+                );
+                expect(switchCall).toBeDefined();
+                const coverCall = mockPublishFn.mock.calls.find(
+                    c => c[0] === 'testhomeassistant/cover/cgateweb_254_56_10/config'
+                );
+                expect(coverCall).toBeUndefined();
+            });
+        });
+
         it('should inject default_entity_id with domain prefix when entity_ids has an entry', () => {
             const labelData = {
                 labels: new Map([['254/56/10', 'Kitchen']]),