homebridge-legrand-radiant 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# Homebridge Legrand Radiant
+
+[![npm](https://img.shields.io/npm/v/homebridge-legrand-radiant.svg)](https://www.npmjs.com/package/homebridge-legrand-radiant)
+[![License](https://img.shields.io/npm/l/homebridge-legrand-radiant.svg)](https://github.com/yourusername/homebridge-legrand-radiant/blob/main/LICENSE)
+
+Homebridge plugin to control **Legrand Radiant WiFi smart switches and dimmers** via the Legrand cloud API.
+
+## Features
+
+- 🔌 Control Legrand Radiant WiFi switches and dimmers via HomeKit
+- 🔄 Automatic device discovery - no manual configuration needed
+- 🔐 Secure OAuth2 authentication with automatic token refresh
+- 📡 Real-time status updates
+- 💡 Support for both switches and dimmers
+
+## Supported Devices
+
+This plugin works with Legrand Radiant WiFi smart devices that use the **Legrand Smart Lights** app, including:
+
+- Radiant Smart WiFi Switch
+- Radiant Smart WiFi Dimmer
+- Other WiFi-enabled devices using the Legrand Smart Lights app
+
+> **Note:** This plugin is for WiFi-based switches that use the cloud API. It does **not** support RF-based switches that require the LC7001 hub.
+
+## Requirements
+
+- [Homebridge](https://homebridge.io/) v1.6.0 or later
+- Node.js v18 or later
+- A Legrand Smart Lights account with configured devices
+
+## Installation
+
+### Via Homebridge UI (Recommended)
+
+1. Open the Homebridge UI
+2. Go to **Plugins**
+3. Search for `homebridge-legrand-radiant`
+4. Click **Install**
+
+### Via npm
+
+```bash
+npm install -g homebridge-legrand-radiant
+```
+
+## Configuration
+
+Add the platform to your Homebridge `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "LegrandRadiant",
+      "name": "Legrand",
+      "email": "your-email@example.com",
+      "password": "your-password"
+    }
+  ]
+}
+```
+
+### Configuration Options
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `platform` | Yes | - | Must be `LegrandRadiant` |
+| `name` | Yes | - | Display name in Homebridge logs |
+| `email` | Yes | - | Your Legrand Smart Lights account email |
+| `password` | Yes | - | Your Legrand Smart Lights account password |
+| `debug` | No | `false` | Enable verbose debug logging |
+
+### Advanced Configuration
+
+If you need to manually specify devices (instead of auto-discovery):
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "LegrandRadiant",
+      "name": "Legrand",
+      "email": "your-email@example.com",
+      "password": "your-password",
+      "devices": [
+        {
+          "id": "e182f1e0-ae64-41e6-a892-43fd7c5b2bad",
+          "name": "Kitchen Light",
+          "type": "dimmer"
+        }
+      ],
+      "debug": true
+    }
+  ]
+}
+```
+
+| Device Option | Required | Description |
+|---------------|----------|-------------|
+| `id` | Yes | Device UUID from the Legrand API |
+| `name` | Yes | Display name in HomeKit |
+| `type` | No | `switch` or `dimmer` (auto-detected if not specified) |
+
+## How It Works
+
+This plugin connects to Legrand's cloud API to control your WiFi smart switches:
+
+1. **Authentication** - Securely logs in using OAuth2 with your Legrand account
+2. **Discovery** - Automatically finds all your configured devices
+3. **Control** - Sends commands through the cloud API
+4. **Status** - Retrieves current device state
+
+```
+HomeKit → Homebridge → Legrand Cloud API → Your WiFi Switch
+```
+
+## Development
+
+### Building
+
+```bash
+npm install
+npm run build
+```
+
+### Testing
+
+```bash
+# Test the API directly
+npx ts-node tools/testCloudApi.ts <deviceId> interactive <token>
+```
+
+### Development Mode
+
+```bash
+npm run watch
+```
+
+## Troubleshooting
+
+### Devices not appearing
+
+1. Make sure your devices are set up in the Legrand Smart Lights app
+2. Verify your email and password are correct
+3. Enable `debug: true` in the config and check Homebridge logs
+
+### Authentication errors
+
+1. Verify your credentials are correct
+2. Try logging out and back in to the Legrand Smart Lights app
+3. Check if your account has 2FA enabled (not currently supported)
+
+### Commands not working
+
+1. Check that the device is online in the Legrand app
+2. Verify your internet connection
+3. Enable debug mode to see API responses
+
+## API Documentation
+
+This plugin uses the Legrand Developer API:
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /servicecatalog/api/v3.0/plants` | List homes |
+| `GET /servicecatalog/api/v3.0/plants/{id}/modules` | List devices |
+| `POST /devicemanagement/api/v2.0/modules/{id}/commands/setState` | Control device |
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues and pull requests.
+
+## Credits
+
+- Inspired by [homebridge-lc7001](https://github.com/sbozarth/homebridge-lc7001)
+- Uses the Legrand cloud API (reverse engineered)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Disclaimer
+
+This plugin is not affiliated with or endorsed by Legrand. Use at your own risk.

package/config.schema.json

@@ -0,0 +1,127 @@
+{
+  "pluginAlias": "LegrandRadiant",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Control your Legrand Radiant WiFi smart switches and dimmers through HomeKit. Enter your Legrand Smart Lights app credentials below.",
+  "footerDisplay": "Devices are automatically discovered from your Legrand account. For issues, check the [GitHub repository](https://github.com/yourusername/homebridge-legrand-radiant).",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Platform Name",
+        "type": "string",
+        "default": "Legrand",
+        "required": true,
+        "description": "Name shown in Homebridge logs"
+      },
+      "email": {
+        "title": "Email",
+        "type": "string",
+        "format": "email",
+        "required": true,
+        "description": "Your Legrand Smart Lights account email"
+      },
+      "password": {
+        "title": "Password",
+        "type": "string",
+        "required": true,
+        "description": "Your Legrand Smart Lights account password"
+      },
+      "pollingInterval": {
+        "title": "Polling Interval (seconds)",
+        "type": "integer",
+        "default": 30,
+        "minimum": 10,
+        "maximum": 300,
+        "description": "How often to check for state changes (10-300 seconds)"
+      },
+      "debug": {
+        "title": "Debug Mode",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable verbose logging for troubleshooting"
+      },
+      "accessToken": {
+        "title": "Manual Access Token",
+        "type": "string",
+        "description": "Optional: Only use if automatic login fails"
+      },
+      "devices": {
+        "title": "Manual Device List",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "title": "Device ID",
+              "type": "string",
+              "required": true
+            },
+            "name": {
+              "title": "Device Name",
+              "type": "string",
+              "required": true
+            },
+            "type": {
+              "title": "Device Type",
+              "type": "string",
+              "oneOf": [
+                { "title": "Switch", "enum": ["switch"] },
+                { "title": "Dimmer", "enum": ["dimmer"] }
+              ],
+              "default": "switch"
+            }
+          }
+        },
+        "description": "Optional: Only needed if auto-discovery doesn't work"
+      }
+    },
+    "required": ["name", "email", "password"]
+  },
+  "layout": [
+    {
+      "type": "fieldset",
+      "title": "Legrand Account",
+      "expandable": false,
+      "items": [
+        "email",
+        {
+          "key": "password",
+          "type": "password"
+        }
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Settings",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "name",
+        "pollingInterval",
+        "debug"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Advanced",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "accessToken",
+        {
+          "key": "devices",
+          "type": "array",
+          "title": "Manual Devices",
+          "expandable": true,
+          "expanded": false,
+          "items": [
+            "devices[].id",
+            "devices[].name",
+            "devices[].type"
+          ]
+        }
+      ]
+    }
+  ]
+}

package/dist/cloudAccessory.d.ts

@@ -0,0 +1,35 @@
+import { PlatformAccessory } from 'homebridge';
+import { LegrandCloudPlatform } from './cloudPlatform';
+/**
+ * Accessory handler for a Legrand Cloud-controlled switch
+ */
+export declare class LegrandCloudAccessory {
+    private readonly platform;
+    private readonly accessory;
+    private readonly deviceId;
+    private readonly deviceName;
+    private service;
+    private state;
+    private readonly isDimmer;
+    constructor(platform: LegrandCloudPlatform, accessory: PlatformAccessory, deviceId: string, deviceName: string, deviceType: string);
+    /**
+     * Handle SET On
+     */
+    private setOn;
+    /**
+     * Handle GET On
+     */
+    private getOn;
+    /**
+     * Handle SET Brightness (for dimmers)
+     */
+    private setBrightness;
+    /**
+     * Handle GET Brightness (for dimmers)
+     */
+    private getBrightness;
+    /**
+     * Update state from external source (polling)
+     */
+    updateState(isOn: boolean, brightness?: number): void;
+}

package/dist/cloudAccessory.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LegrandCloudAccessory = void 0;
+/**
+ * Accessory handler for a Legrand Cloud-controlled switch
+ */
+class LegrandCloudAccessory {
+    platform;
+    accessory;
+    deviceId;
+    deviceName;
+    service;
+    state = {
+        on: false,
+        brightness: 100,
+    };
+    isDimmer;
+    constructor(platform, accessory, deviceId, deviceName, deviceType) {
+        this.platform = platform;
+        this.accessory = accessory;
+        this.deviceId = deviceId;
+        this.deviceName = deviceName;
+        this.isDimmer = deviceType === 'dimmer';
+        // Set accessory information
+        this.accessory.getService(this.platform.Service.AccessoryInformation)
+            .setCharacteristic(this.platform.Characteristic.Manufacturer, 'Legrand')
+            .setCharacteristic(this.platform.Characteristic.Model, `Radiant WiFi ${this.isDimmer ? 'Dimmer' : 'Switch'}`)
+            .setCharacteristic(this.platform.Characteristic.SerialNumber, deviceId.substring(0, 8))
+            .setCharacteristic(this.platform.Characteristic.FirmwareRevision, '1.0.0');
+        // Remove any conflicting services
+        const existingLightbulb = this.accessory.getService(this.platform.Service.Lightbulb);
+        const existingSwitch = this.accessory.getService(this.platform.Service.Switch);
+        if (this.isDimmer) {
+            // Remove switch service if exists (in case device type changed)
+            if (existingSwitch) {
+                this.accessory.removeService(existingSwitch);
+            }
+            // Get or create lightbulb service
+            this.service = existingLightbulb || this.accessory.addService(this.platform.Service.Lightbulb, deviceName);
+            // Set up brightness characteristic
+            this.service.getCharacteristic(this.platform.Characteristic.Brightness)
+                .onSet(this.setBrightness.bind(this))
+                .onGet(this.getBrightness.bind(this));
+        }
+        else {
+            // Remove lightbulb service if exists
+            if (existingLightbulb) {
+                this.accessory.removeService(existingLightbulb);
+            }
+            // Get or create switch service
+            this.service = existingSwitch || this.accessory.addService(this.platform.Service.Switch, deviceName);
+        }
+        // Set the display name
+        this.service.setCharacteristic(this.platform.Characteristic.Name, deviceName);
+        // Register handlers for on/off
+        this.service.getCharacteristic(this.platform.Characteristic.On)
+            .onSet(this.setOn.bind(this))
+            .onGet(this.getOn.bind(this));
+    }
+    /**
+     * Handle SET On
+     */
+    async setOn(value) {
+        const isOn = value;
+        this.platform.log.debug(`Setting ${this.deviceName} to ${isOn ? 'ON' : 'OFF'}`);
+        try {
+            const success = isOn
+                ? await this.platform.cloudApi.turnOn(this.deviceId)
+                : await this.platform.cloudApi.turnOff(this.deviceId);
+            if (success) {
+                this.state.on = isOn;
+                this.platform.log.info(`${this.deviceName} is now ${isOn ? 'ON' : 'OFF'}`);
+            }
+            else {
+                throw new Error('Failed to set power state');
+            }
+        }
+        catch (error) {
+            this.platform.log.error(`Error setting power: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * Handle GET On
+     */
+    async getOn() {
+        return this.state.on;
+    }
+    /**
+     * Handle SET Brightness (for dimmers)
+     */
+    async setBrightness(value) {
+        const brightness = value;
+        this.platform.log.debug(`Setting ${this.deviceName} brightness to ${brightness}%`);
+        try {
+            const success = await this.platform.cloudApi.setBrightness(this.deviceId, brightness);
+            if (success) {
+                this.state.brightness = brightness;
+                this.state.on = brightness > 0;
+            }
+            else {
+                throw new Error('Failed to set brightness');
+            }
+        }
+        catch (error) {
+            this.platform.log.error(`Error setting brightness: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * Handle GET Brightness (for dimmers)
+     */
+    async getBrightness() {
+        return this.state.brightness;
+    }
+    /**
+     * Update state from external source (polling)
+     */
+    updateState(isOn, brightness) {
+        // Only update if state has changed
+        if (this.state.on !== isOn) {
+            this.state.on = isOn;
+            this.service.updateCharacteristic(this.platform.Characteristic.On, isOn);
+            this.platform.log.debug(`${this.deviceName} state updated: ${isOn ? 'ON' : 'OFF'}`);
+        }
+        if (this.isDimmer && brightness !== undefined && this.state.brightness !== brightness) {
+            this.state.brightness = brightness;
+            this.service.updateCharacteristic(this.platform.Characteristic.Brightness, brightness);
+            this.platform.log.debug(`${this.deviceName} brightness updated: ${brightness}%`);
+        }
+    }
+}
+exports.LegrandCloudAccessory = LegrandCloudAccessory;

package/dist/cloudPlatform.d.ts

@@ -0,0 +1,50 @@
+import { API, DynamicPlatformPlugin, Logger, PlatformAccessory, PlatformConfig, Service, Characteristic } from 'homebridge';
+import { LegrandCloudApi } from './legrandCloudApi';
+/**
+ * Legrand Radiant Cloud Platform Plugin
+ * Controls Legrand Radiant WiFi smart switches via the cloud API
+ */
+export declare class LegrandCloudPlatform implements DynamicPlatformPlugin {
+    readonly log: Logger;
+    readonly config: PlatformConfig;
+    readonly api: API;
+    readonly Service: typeof Service;
+    readonly Characteristic: typeof Characteristic;
+    readonly accessories: PlatformAccessory[];
+    private readonly accessoryHandlers;
+    cloudApi: LegrandCloudApi;
+    private pollingInterval;
+    constructor(log: Logger, config: PlatformConfig, api: API);
+    /**
+     * Start polling for device status updates
+     */
+    private startPolling;
+    /**
+     * Stop polling
+     */
+    private stopPolling;
+    /**
+     * Poll all devices for their current status using real-time getState command
+     */
+    private pollDeviceStatus;
+    /**
+     * Called when homebridge restores cached accessories from disk
+     */
+    configureAccessory(accessory: PlatformAccessory): void;
+    /**
+     * Discover and register devices
+     */
+    private discoverDevices;
+    /**
+     * Remove cached accessories that are no longer present
+     */
+    private cleanupOldAccessories;
+    /**
+     * Add a device from an API module
+     */
+    private addDeviceFromModule;
+    /**
+     * Add a device as a HomeKit accessory
+     */
+    private addDevice;
+}