Use Shelly RPC for dynamic cover and presence features

Author: MaxRink

src/devices/shelly.ts

@@ -12,12 +12,30 @@ const ea = exposes.access;
 
 const SHELLY_ENDPOINT_ID = 239;
 const SHELLY_OPTIONS = {profileId: ZSpec.CUSTOM_SHELLY_PROFILE_ID};
+const SHELLY_PRESENCE_MAX_ZONES = 10;
 
 const NS = "zhc:shelly";
 
 const HA_ELECTRICAL_MEASUREMENT_CLUSTER_ID = 0x0b04;
 const HA_ELECTRICAL_MEASUREMENT_POWER_FACTOR_ATTR_ID = 0x0510;
 
+const checkOption = (device: Zh.Device | DummyDevice, options: KeyValue, key: string, defaultValue = false): boolean => {
+    if (options?.[key] === "true") return true;
+    if (options?.[key] === "false") return false;
+    if (!utils.isDummyDevice(device) && device.meta[key] !== undefined) return !!device.meta[key];
+
+    return defaultValue;
+};
+
+const shellyPresenceEndpointNames = (device: Zh.Device | DummyDevice): string[] => {
+    const count =
+        !utils.isDummyDevice(device) && typeof device.meta.presence_zone_count === "number"
+            ? Math.min(Math.max(Math.trunc(device.meta.presence_zone_count), 1), SHELLY_PRESENCE_MAX_ZONES)
+            : SHELLY_PRESENCE_MAX_ZONES;
+
+    return Array.from({length: count}, (_, index) => String(index + 1));
+};
+
 interface ShellyRPC {
     attributes: {
         data: string;
@@ -371,6 +389,56 @@ const shellyModernExtend = {
             }),
         ];
     },
+    shellyWindowCovering(): ModernExtend {
+        const result = m.windowCovering({controls: ["lift", "tilt"]});
+        const tiltOption = e
+            .enum("cover_tilt_enabled", ea.SET, ["auto", "true", "false"])
+            .withDescription("Expose tilt/slat controls for covers with Shelly slat control enabled");
+        const exposesFn: DefinitionExposesFunction = (device, options) => {
+            const cover = e.cover().withPosition();
+            if (checkOption(device, options, "cover_tilt_enabled")) {
+                cover.withTilt();
+            }
+
+            return [cover];
+        };
+
+        result.exposes = [exposesFn];
+        result.options = [...(result.options ?? []), tiltOption];
+
+        return result;
+    },
+    shellyPresenceOccupancy(): ModernExtend {
+        const exposesFn: DefinitionExposesFunction = (device) => {
+            return shellyPresenceEndpointNames(device).map((endpointName) => e.occupancy().withAccess(ea.STATE_GET).withEndpoint(endpointName));
+        };
+
+        const fromZigbee: Fz.Converter<"msOccupancySensing">[] = [
+            {
+                cluster: "msOccupancySensing",
+                type: ["attributeReport", "readResponse"],
+                convert: (model, msg, publish, options, meta) => {
+                    if (!("occupancy" in msg.data)) return;
+
+                    const endpointName = utils.getEndpointName(msg, model, meta).toString();
+                    if (!shellyPresenceEndpointNames(meta.device).includes(endpointName)) return;
+
+                    return {[utils.postfixWithEndpointName("occupancy", msg, model, meta)]: (msg.data.occupancy & 1) > 0};
+                },
+            },
+        ];
+
+        const toZigbee: Tz.Converter[] = [
+            {
+                key: ["occupancy"],
+                convertGet: async (entity, key, meta) => {
+                    await determineEndpoint(entity, meta, "msOccupancySensing").read("msOccupancySensing", ["occupancy"]);
+                },
+            },
+        ];
+
+        return {exposes: [exposesFn], fromZigbee, toZigbee, isModernExtend: true};
+    },
     shellyRPCSetup(features: string[] = []): ModernExtend {
         // Set helper variables
         const shellyRPCBugFixed = false; // For firmware 20250819-150402/ga0def2d
@@ -380,6 +448,8 @@ const shellyModernExtend = {
         const featurePowerstripPowerOnBehavior = features.includes("PowerstripPowerOnBehavior");
         const featureTwoPMInputMode = features.includes("2PMInputMode");
         const featureOnePMInputMode = features.includes("1PMInputMode");
+        const featureCoverTiltAuto = features.includes("CoverTiltAuto");
+        const featurePresenceZonesAuto = features.includes("PresenceZonesAuto");
 
         // Generic helper functions
         const validateTime = (value: string) => {
@@ -423,13 +493,33 @@ const shellyModernExtend = {
 
         const rpcSend = async (endpoint: Zh.Endpoint | Zh.Group, method: string, params: object = undefined) => {
             const command = {
-                id: 1, // We can't read replies anyway so don't care for now
+                id: 1,
                 method: method,
                 params: params,
             };
             return await rpcSendRaw(endpoint, JSON.stringify(command));
         };
 
+        const rpcRequest = async (endpoint: Zh.Endpoint | Zh.Group, method: string, params: object = undefined): Promise<KeyValue | undefined> => {
+            await rpcSend(endpoint, method, params);
+            const rxCtlResult = await endpoint.read<"shellyRPCCluster", ShellyRPC>("shellyRPCCluster", ["rxCtl"], SHELLY_OPTIONS);
+            const expectedLen = rxCtlResult.rxCtl;
+            if (!expectedLen) return undefined;
+
+            let accumulated = "";
+            while (accumulated.length < expectedLen) {
+                const dataResult = await endpoint.read<"shellyRPCCluster", ShellyRPC>("shellyRPCCluster", ["data"], {
+                    ...SHELLY_OPTIONS,
+                    timeout: 1000,
+                });
+                if (!dataResult.data) break;
+                accumulated += dataResult.data;
+            }
+
+            if (accumulated.length < expectedLen) return undefined;
+            return JSON.parse(accumulated.substring(0, expectedLen));
+        };
+
         const rpcReceive = async (endpoint: Zh.Endpoint | Zh.Group, key: string) => {
             logger.debug(`||| shellyRPC rpcReceive(${key})`, NS);
             if (key === "rpc_rxctl") {
@@ -763,6 +853,55 @@ const shellyModernExtend = {
                 }
             });
         }
+        if (featureCoverTiltAuto) {
+            configure.push(async (device) => {
+                const ep = device.getEndpoint(SHELLY_ENDPOINT_ID);
+                if (!ep) return;
+                try {
+                    const response = await rpcRequest(ep, "Cover.GetConfig", {id: 0});
+                    if (!response?.result) return;
+                    assertObject<KeyValue>(response.result);
+                    if (!response.result.slat) return;
+                    assertObject<KeyValue>(response.result.slat);
+                    const enabled = response.result.slat.enable;
+                    if (typeof enabled === "boolean" && device.meta.cover_tilt_enabled !== enabled) {
+                        device.meta.cover_tilt_enabled = enabled;
+                        device.save();
+                    }
+                } catch (e) {
+                    logger.warning(`Failed to read cover_tilt_enabled during configure, use manual option to override: ${e}`, NS);
+                }
+            });
+        }
+        if (featurePresenceZonesAuto) {
+            configure.push(async (device) => {
+                const ep = device.getEndpoint(SHELLY_ENDPOINT_ID);
+                if (!ep) return;
+                try {
+                    const response = await rpcRequest(ep, "Shelly.GetConfig");
+                    const result = response?.result ?? response?.params ?? response;
+                    if (!result) return;
+                    assertObject<KeyValue>(result);
+
+                    let zoneCount = Object.keys(result).filter((key) => /^presencezone:\d+$/.test(key)).length;
+                    if (zoneCount === 0) {
+                        const presenceConfig = result.presence;
+                        if (presenceConfig) {
+                            assertObject<KeyValue>(presenceConfig);
+                            zoneCount = typeof presenceConfig.main_zone === "string" ? 1 : 0;
+                        }
+                    }
+                    if (zoneCount < 1 || zoneCount > SHELLY_PRESENCE_MAX_ZONES) return;
+
+                    if (device.meta.presence_zone_count !== zoneCount) {
+                        device.meta.presence_zone_count = zoneCount;
+                        device.save();
+                    }
+                } catch (e) {
+                    logger.warning(`Failed to read presence zones during configure, using last known or default exposed zones: ${e}`, NS);
+                }
+            });
+        }
         return {exposes, fromZigbee, toZigbee, configure, isModernExtend: true};
     },
     shellyWiFiSetup(): ModernExtend {
@@ -1501,9 +1640,9 @@ export const definitions: DefinitionWithExtend[] = [
         ],
         extend: [
             m.deviceEndpoints({endpoints: {sw1: 2, sw2: 3}}),
-            m.windowCovering({controls: ["lift", "tilt"]}),
+            shellyModernExtend.shellyWindowCovering(),
             ...shellyModernExtend.shellyCustomClusters(),
-            shellyModernExtend.shellyRPCSetup(["2PMInputMode"]),
+            shellyModernExtend.shellyRPCSetup(["2PMInputMode", "CoverTiltAuto"]),
             shellyModernExtend.shellyWiFiSetup(),
         ],
         configure: async (device, coordinatorEndpoint) => {
@@ -1987,19 +2126,11 @@ export const definitions: DefinitionWithExtend[] = [
         description: "Presence Gen4 Zigbee",
         extend: [
             m.deviceEndpoints({endpoints: {"1": 1, "2": 2, "3": 3, "4": 4, "5": 5, "6": 6, "7": 7, "8": 8, "9": 9, "10": 10}}),
-            m.occupancy({reporting: false, endpointNames: ["1"]}),
-            m.occupancy({reporting: false, endpointNames: ["2"]}),
-            m.occupancy({reporting: false, endpointNames: ["3"]}),
-            m.occupancy({reporting: false, endpointNames: ["4"]}),
-            m.occupancy({reporting: false, endpointNames: ["5"]}),
-            m.occupancy({reporting: false, endpointNames: ["6"]}),
-            m.occupancy({reporting: false, endpointNames: ["7"]}),
-            m.occupancy({reporting: false, endpointNames: ["8"]}),
-            m.occupancy({reporting: false, endpointNames: ["9"]}),
-            m.occupancy({reporting: false, endpointNames: ["10"]}),
+            shellyModernExtend.shellyPresenceOccupancy(),
             ...shellyModernExtend.shellyLightLevel(),
             m.identify(),
             ...shellyModernExtend.shellyCustomClusters(),
+            shellyModernExtend.shellyRPCSetup(["PresenceZonesAuto"]),
             shellyModernExtend.shellyWiFiSetup(),
         ],
     },

test/shelly.test.ts

@@ -0,0 +1,161 @@
+import assert from "node:assert";
+import {describe, expect, it, vi} from "vitest";
+import {findByDevice} from "../src/index";
+import type {DefinitionExposesFunction, Expose} from "../src/lib/types";
+import {mockDevice} from "./utils";
+
+const getFeatureNames = (expose: Expose): string[] => {
+    return "features" in expose ? expose.features.map((feature) => feature.name) : [];
+};
+
+describe("Shelly 2PM Gen4 cover mode", () => {
+    const mockShelly2PMCover = (read?: ReturnType<typeof vi.fn>) =>
+        mockDevice({
+            modelID: "2PM",
+            manufacturerName: "Shelly",
+            endpoints: [
+                {ID: 1, profileID: 260, deviceID: 514, inputClusterIDs: [0, 3, 4, 5, 258], outputClusterIDs: []},
+                {ID: 239, profileID: 49153, deviceID: 8193, inputClusterIDs: [64513, 64514], outputClusterIDs: [], read},
+                {ID: 242, profileID: 41440, deviceID: 97, inputClusterIDs: [], outputClusterIDs: [33]},
+            ],
+        });
+
+    it("exposes lift-only covers by default and opt-in tilt controls", async () => {
+        const device = mockShelly2PMCover();
+        const definition = await findByDevice(device);
+        expect(definition.model).toBe("S4SW-002P16EU-COVER");
+        expect(typeof definition.exposes).toBe("function");
+        const exposes = definition.exposes as DefinitionExposesFunction;
+
+        const defaultCover = exposes(device, {}).find((expose) => expose.type === "cover");
+        const tiltCover = exposes(device, {cover_tilt_enabled: "true"}).find((expose) => expose.type === "cover");
+        device.meta.cover_tilt_enabled = true;
+        const autoDetectedTiltCover = exposes(device, {cover_tilt_enabled: "auto"}).find((expose) => expose.type === "cover");
+        assert(defaultCover);
+        assert(tiltCover);
+        assert(autoDetectedTiltCover);
+
+        expect(getFeatureNames(defaultCover)).toContain("position");
+        expect(getFeatureNames(defaultCover)).not.toContain("tilt");
+        expect(getFeatureNames(tiltCover)).toContain("position");
+        expect(getFeatureNames(tiltCover)).toContain("tilt");
+        expect(getFeatureNames(autoDetectedTiltCover)).toContain("tilt");
+        expect(definition.options?.some((option) => option.name === "cover_tilt_enabled")).toBe(true);
+    });
+
+    it("persists Shelly slat control from Cover.GetConfig during configure", async () => {
+        const response = JSON.stringify({id: 1, result: {id: 0, slat: {enable: true}}});
+        const read = vi
+            .fn()
+            .mockResolvedValueOnce({rxCtl: 0})
+            .mockResolvedValueOnce({rxCtl: 0})
+            .mockResolvedValueOnce({rxCtl: response.length})
+            .mockResolvedValueOnce({data: response});
+        const device = mockShelly2PMCover(read);
+        const save = vi.spyOn(device, "save").mockImplementation(() => {});
+        const definition = await findByDevice(device);
+
+        await definition.configure?.(device, mockShelly2PMCover().getEndpoint(1), definition);
+
+        expect(device.meta.cover_tilt_enabled).toBe(true);
+        expect(save).toHaveBeenCalledTimes(1);
+        expect(read).toHaveBeenCalledWith("shellyRPCCluster", ["rxCtl"], expect.any(Object));
+        expect(read).toHaveBeenCalledWith("shellyRPCCluster", ["data"], expect.any(Object));
+        expect(device.getEndpoint(239).write).toHaveBeenCalledWith(
+            "shellyRPCCluster",
+            {data: expect.stringContaining("Cover.GetConfig")},
+            expect.any(Object),
+        );
+    });
+
+    it("leaves persisted slat control unchanged when Cover.GetConfig has no boolean slat flag", async () => {
+        const response = JSON.stringify({id: 1, result: {id: 0}});
+        const read = vi
+            .fn()
+            .mockResolvedValueOnce({rxCtl: 0})
+            .mockResolvedValueOnce({rxCtl: 0})
+            .mockResolvedValueOnce({rxCtl: response.length})
+            .mockResolvedValueOnce({data: response});
+        const device = mockShelly2PMCover(read);
+        device.meta.cover_tilt_enabled = true;
+        const save = vi.spyOn(device, "save").mockImplementation(() => {});
+        const definition = await findByDevice(device);
+
+        await definition.configure?.(device, mockShelly2PMCover().getEndpoint(1), definition);
+
+        expect(device.meta.cover_tilt_enabled).toBe(true);
+        expect(save).not.toHaveBeenCalled();
+    });
+});
+
+describe("Shelly Presence Gen4", () => {
+    const mockShellyPresence = (read?: ReturnType<typeof vi.fn>) =>
+        mockDevice({
+            modelID: "Presence",
+            manufacturerName: "Shelly",
+            endpoints: [
+                ...Array.from({length: 10}, (_, index) => ({
+                    ID: index + 1,
+                    inputClusterIDs: [0, 3, 1030, 0xfc21],
+                    outputClusterIDs: [],
+                })),
+                {ID: 239, profileID: 49153, deviceID: 8193, inputClusterIDs: [64513, 64514], outputClusterIDs: [], read},
+                {ID: 242, profileID: 41440, deviceID: 97, inputClusterIDs: [], outputClusterIDs: [33]},
+            ],
+        });
+
+    const occupancyEndpoints = (definition: Awaited<ReturnType<typeof findByDevice>>, device: ReturnType<typeof mockShellyPresence>) => {
+        expect(typeof definition.exposes).toBe("function");
+        const exposes = definition.exposes as DefinitionExposesFunction;
+        return exposes(device, {})
+            .filter((expose) => expose.name === "occupancy")
+            .map((expose) => expose.endpoint);
+    };
+
+    it("falls back to all possible zone endpoints until the device config is read", async () => {
+        const device = mockShellyPresence();
+        const definition = await findByDevice(device);
+
+        expect(definition.model).toBe("S4SN-0U61X");
+        expect(occupancyEndpoints(definition, device)).toStrictEqual(["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"]);
+    });
+
+    it("uses the persisted PresenceZone count for occupancy exposes", async () => {
+        const device = mockShellyPresence();
+        device.meta.presence_zone_count = 2;
+        const definition = await findByDevice(device);
+
+        expect(occupancyEndpoints(definition, device)).toStrictEqual(["1", "2"]);
+    });
+
+    it("persists the PresenceZone count from Shelly.GetConfig during configure", async () => {
+        const response = JSON.stringify({
+            id: 1,
+            result: {
+                presence: {main_zone: "presencezone:200"},
+                "presencezone:200": {id: 200, name: "Room"},
+                "presencezone:201": {id: 201, name: "Desk"},
+                "presencezone:202": {id: 202, name: "Door"},
+            },
+        });
+        const read = vi.fn((cluster: string, attributes: string[]) => {
+            if (cluster === "shellyRPCCluster" && attributes.includes("rxCtl")) return Promise.resolve({rxCtl: response.length});
+            if (cluster === "shellyRPCCluster" && attributes.includes("data")) return Promise.resolve({data: response});
+            return Promise.resolve({});
+        });
+        const device = mockShellyPresence(read);
+        const save = vi.spyOn(device, "save").mockImplementation(() => {});
+        const definition = await findByDevice(device);
+
+        await definition.configure?.(device, mockShellyPresence().getEndpoint(1), definition);
+
+        expect(device.meta.presence_zone_count).toBe(3);
+        expect(save).toHaveBeenCalledTimes(1);
+        expect(device.getEndpoint(239).write).toHaveBeenCalledWith(
+            "shellyRPCCluster",
+            {data: expect.stringContaining("Shelly.GetConfig")},
+            expect.any(Object),
+        );
+        expect(occupancyEndpoints(definition, device)).toStrictEqual(["1", "2", "3"]);
+    });
+});