@benjaminmichoux/homebridge-leviton 2.2.0

package/README.md

@@ -0,0 +1,56 @@
+# homebridge-leviton
+
+[![verified-by-homebridge](https://badgen.net/badge/homebridge/verified/purple)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
+Homebridge plugin for Leviton Decora Smart devices
+
+## Supports
+
+These models are tested, though any other WiFi model should work.
+
+- DW6HD 600W Dimmer
+- D26HD 600W Dimmer (2nd Gen)
+- DW1KD 1000W Dimmer
+- DW3HL Wi-Fi Plugin Dimmer
+- D23LP Wi-Fi Plugin Dimmer (2nd Gen)
+- DW15P Wi-Fi Plugin Outlet
+- DW4SF Fan Speed Controller
+
+## Requirements
+
+- Node.js 18, 20, or 22
+- Homebridge 1.8+ or 2.x
+
+## Setup
+
+_You must use the main "My Leviton" login credentials._
+
+- add `homebridge-leviton` in your Homebridge Config UI X web interface
+- Add to your config.json:
+
+```json
+"platforms": [
+  {
+    "platform": "LevitonDecoraSmart",
+    "email": "your@email.com",
+    "password": "supersecretpassword",
+    "loglevel": "info",
+    "excludedModels": ["DWP15"],
+    "excludedSerials": ["1000_0023_CCE2"]
+  }
+]
+```
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `email` | yes | — | My Leviton account email |
+| `password` | yes | — | My Leviton account password |
+| `loglevel` | no | `info` | `debug`, `info`, `warn`, or `error` |
+| `excludedModels` | no | `[]` | Skip entire model families (e.g. fully HomeKit-native devices) |
+| `excludedSerials` | no | `[]` | Skip individual devices by serial number |
+
+## Features
+
+- Automatically discovers devices on your My Leviton account
+- On/Off, Brightness (with min/max limits), Fan speed
+- Real-time state updates via WebSocket (auto-reconnects on connection drop)
+- Shows serial/model/firmware in HomeKit accessory info

package/api.js

@@ -0,0 +1,118 @@
+const SockJS = require('sockjs-client')
+
+const baseURL = 'https://my.leviton.com/api'
+const toQueryString = (params) =>
+  Object.keys(params)
+    .map((key) => `${key}=${params[key]}`)
+    .join('&')
+
+function getResidenceIotSwitches({ residenceID, token }) {
+  return fetch(`${baseURL}/Residences/${residenceID}/iotSwitches`, {
+    method: 'GET',
+    headers: { 'Content-Type': 'application/json; charset=utf-8', Authorization: token },
+  }).then((res) => res.json())
+}
+
+function getIotSwitch({ switchID, token }) {
+  return fetch(`${baseURL}/IotSwitches/${switchID}`, {
+    method: 'GET',
+    headers: { 'Content-Type': 'application/json; charset=utf-8', Authorization: token },
+  }).then((res) => res.json())
+}
+
+function putIotSwitch({ switchID, power, brightness, token }) {
+  const body = {}
+  if (brightness) body.brightness = brightness
+  if (power) body.power = power
+  return fetch(`${baseURL}/IotSwitches/${switchID}`, {
+    method: 'PUT',
+    body: JSON.stringify(body),
+    headers: { 'Content-Type': 'application/json; charset=utf-8', Authorization: token },
+  }).then((res) => res.json())
+}
+
+function getPersonResidentialPermissions({ personID, token }) {
+  return fetch(`${baseURL}/Person/${personID}/residentialPermissions`, {
+    method: 'GET',
+    headers: { 'Content-Type': 'application/json; charset=utf-8', Authorization: token },
+  }).then((res) => res.json())
+}
+
+function getResidentialAccounts({ accountID, token }) {
+  return fetch(`${baseURL}/ResidentialAccounts/${accountID}`, {
+    method: 'GET',
+    headers: { 'Content-Type': 'application/json; charset=utf-8', Authorization: token },
+  }).then((res) => res.json())
+}
+
+function getResidentialAccountsV2({ residenceObjectID, token }) {
+  return fetch(`${baseURL}/ResidentialAccounts/${residenceObjectID}/residences`, {
+    method: 'GET',
+    headers: { 'Content-Type': 'application/json; charset=utf-8', Authorization: token },
+  }).then((res) => res.json())
+}
+
+function postPersonLogin({ email, password }) {
+  const query = toQueryString({ include: 'user' })
+  return fetch(`${baseURL}/Person/login?${query}`, {
+    method: 'POST',
+    body: JSON.stringify({ email, password }),
+    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+  }).then((res) => res.json())
+}
+
+function subscribe(login, devices, callback, scope, retryDelay = 5000) {
+  const ws = new SockJS('https://my.leviton.com/socket')
+
+  ws.onclose = function (ev) {
+    scope.log.error(`Socket connection closed: ${JSON.stringify(ev)}`)
+    const nextDelay = Math.min(retryDelay * 2, 60000)
+    scope.log.info(`Reconnecting in ${retryDelay / 1000}s...`)
+    setTimeout(() => subscribe(login, devices, callback, scope, nextDelay), retryDelay)
+  }
+
+  ws.onerror = function (ev) {
+    scope.log.error(`Socket error: ${JSON.stringify(ev)}`)
+  }
+
+  ws.onopen = function (ev) {
+    scope.log.debug(`Socket connection opened: ${JSON.stringify(ev)}`)
+  }
+
+  ws.onmessage = function (message) {
+    let data
+    try {
+      data = JSON.parse(message.data)
+    } catch (err) {
+      scope.log.error(`Received bad json: ${String(message.data)}`)
+      return
+    }
+    if (data.type === 'challenge') {
+      ws.send([JSON.stringify({ token: login })])
+    }
+    if (data.type === 'status' && data.status === 'ready') {
+      devices.forEach((element) => {
+        ws.send([JSON.stringify({ type: 'subscribe', subscription: { modelName: 'IotSwitch', modelId: element.id } })])
+      })
+    }
+    if (data.type === 'notification' && data.notification?.data?.power) {
+      const payload = {
+        id: data.notification.modelId,
+        power: data.notification.data.power,
+      }
+      if (data.notification.data.brightness) payload.brightness = data.notification.data.brightness
+      callback(payload)
+    }
+  }
+}
+
+module.exports = {
+  getIotSwitch,
+  getPersonResidentialPermissions,
+  getResidenceIotSwitches,
+  getResidentialAccounts,
+  getResidentialAccountsV2,
+  postPersonLogin,
+  putIotSwitch,
+  subscribe,
+}

package/config.schema.json

@@ -0,0 +1,47 @@
+{
+  "pluginAlias": "LevitonDecoraSmart",
+  "pluginType": "platform",
+  "singular": false,
+  "schema": {
+    "type": "object",
+    "properties": {
+      "email": {
+        "title": "email",
+        "type": "string",
+        "required": true,
+        "x-schema-form": {
+          "type": "username"
+        }
+      },
+      "password": {
+        "title": "password",
+        "type": "string",
+        "required": true,
+        "x-schema-form": {
+          "type": "password"
+        }
+      },
+      "loglevel": {
+        "title": "Log Level",
+        "type": "string",
+        "default": "info",
+        "enum": ["debug", "info", "warn", "error"],
+        "description": "Verbosity of plugin logging. Default is info."
+      },
+      "excludedModels": {
+        "type": "array",
+        "description": "List of device models to exclude (e.g. fully HomeKit-native devices)",
+        "items": {
+          "type": "string"
+        }
+      },
+      "excludedSerials": {
+        "type": "array",
+        "description": "List of device serial numbers to exclude",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/index.js

@@ -0,0 +1,350 @@
+let Service, Characteristic, Accessory, UUID
+const Leviton = require('./api.js')
+const PLUGIN_NAME = '@benjaminmichoux/homebridge-leviton'
+const PLATFORM_NAME = 'LevitonDecoraSmart'
+const levels = ['debug', 'info', 'warn', 'error']
+
+class LevitonDecoraSmartPlatform {
+  constructor(log, config, api) {
+    this.config = config
+    this.api = api
+    this.accessories = []
+
+    const noop = function () {}
+    const logger = (level) => (msg) =>
+      levels.indexOf((config && levels.includes(config.loglevel) && config.loglevel) || 'info') <= levels.indexOf(level)
+        ? log(msg)
+        : noop()
+
+    this.log = levels.reduce((a, l) => {
+      a[l] = logger(l)
+      return a
+    }, {})
+
+    if (!config) {
+      this.log.error(`No config for ${PLUGIN_NAME} defined.`)
+      return
+    }
+
+    if (!config.email || !config.password) {
+      this.log.error(`email and password for ${PLUGIN_NAME} are required in config.json`)
+      return
+    }
+
+    api.on('didFinishLaunching', async () => {
+      this.log.debug('didFinishLaunching')
+      const { devices, token } = await this.initialize(config)
+      const excludedModels = (config.excludedModels || []).map((name) => name.toUpperCase())
+      const excludedSerials = (config.excludedSerials || []).map((name) => name.toUpperCase())
+      if (Array.isArray(devices) && devices.length > 0) {
+        devices.forEach((device) => {
+          if (!this.accessories.find((acc) => acc.context.device.serial === device.serial)) {
+            if (!excludedModels.includes(device.model) && !excludedSerials.includes(device.serial)) {
+              this.addAccessory(device, token)
+            }
+          }
+        })
+      } else {
+        this.log.error('Unable to initialize: no devices found')
+      }
+    })
+  }
+
+  subscriptionCallback(payload) {
+    const accessory = this.accessories.find((acc) => acc.context.device.id === payload.id)
+
+    if (!accessory) return
+
+    const { id, power, brightness } = payload
+    this.log.debug(`Socket: ${accessory.displayName} (${id}): ${power} ${brightness ? `${brightness}%` : ''}`)
+
+    const service =
+      accessory.getService(Service.Fan) ||
+      accessory.getService(Service.Switch) ||
+      accessory.getService(Service.Outlet) ||
+      accessory.getService(Service.Lightbulb)
+    const isFan = !!accessory.getService(Service.Fan)
+
+    if (brightness)
+      service
+        .getCharacteristic(isFan ? Characteristic.RotationSpeed : Characteristic.Brightness)
+        .updateValue(brightness)
+    service.getCharacteristic(Characteristic.On).updateValue(power === 'ON')
+  }
+
+  async initialize() {
+    this.log.debug('initialize')
+
+    try {
+      var login = await Leviton.postPersonLogin({
+        email: this.config['email'],
+        password: this.config['password'],
+      })
+      var { id: token, userId: personID } = login
+      this.log.debug(`personID: ${personID}, hasToken: ${!!token}`)
+    } catch (err) {
+      this.log.error(`Failed to login to leviton: ${err.message}`)
+    }
+    try {
+      const permissions = await Leviton.getPersonResidentialPermissions({
+        personID,
+        token,
+      })
+      var accountID = permissions[0].residentialAccountId
+      this.log.debug(`accountID: ${accountID}`)
+    } catch (err) {
+      this.log.error(`Failed to get leviton accountID: ${err.message}`)
+    }
+    try {
+      var { primaryResidenceId: residenceID, id: residenceObjectID } = await Leviton.getResidentialAccounts({
+        accountID,
+        token,
+      })
+      this.log.debug(`residenceID: ${residenceID}`)
+    } catch (err) {
+      this.log.error(`Failed to get leviton residenceID: ${err.message}`)
+    }
+    try {
+      var devices = await Leviton.getResidenceIotSwitches({
+        residenceID,
+        token,
+      })
+      this.log.debug(`devices: ${JSON.stringify(devices)}`)
+    } catch (err) {
+      this.log.error(`Failed to get leviton devices: ${err.message}`)
+    }
+
+    try {
+      if (!Array.isArray(devices) || devices.length < 1) {
+        this.log.info('No devices found for primary residence id. Trying residence v2')
+
+        const accountsV2Response = await Leviton.getResidentialAccountsV2({
+          residenceObjectID,
+          token,
+        })
+
+        if (accountsV2Response[0]) {
+          residenceID = accountsV2Response[0].id
+          devices = await Leviton.getResidenceIotSwitches({
+            residenceID,
+            token,
+          })
+        } else {
+          throw new Error('No residenceIDs found')
+        }
+
+        if (!Array.isArray(devices) || devices.length < 1) {
+          throw new Error(
+            `No devices found for residenceID: ${residenceID} or residenceIDV2 method: ${residenceObjectID}`
+          )
+        } else {
+          Leviton.subscribe(login, devices, this.subscriptionCallback.bind(this), this)
+        }
+      } else {
+        Leviton.subscribe(login, devices, this.subscriptionCallback.bind(this), this)
+      }
+    } catch (err) {
+      this.log.error(`Error subscribing devices to websocket updates: ${err.message}`)
+    }
+
+    return { devices, token }
+  }
+
+  async addAccessory(device, token) {
+    this.log.info(`addAccessory ${device.name}`)
+
+    const uuid = UUID.generate(device.serial)
+    const accessory = new this.api.platformAccessory(device.name, uuid)
+
+    accessory.context.device = device
+    accessory.context.token = token
+
+    accessory
+      .getService(Service.AccessoryInformation)
+      .setCharacteristic(Characteristic.Name, device.name)
+      .setCharacteristic(Characteristic.SerialNumber, device.serial)
+      .setCharacteristic(Characteristic.Manufacturer, device.manufacturer)
+      .setCharacteristic(Characteristic.Model, device.model)
+      .setCharacteristic(Characteristic.FirmwareRevision, device.version)
+
+    await this.setupService(accessory)
+    this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory])
+
+    this.accessories.push(accessory)
+    this.log.debug(`Finished adding accessory ${device.name}`)
+  }
+
+  async configureAccessory(accessory) {
+    this.log.debug(`configureAccessory: ${accessory.displayName}`)
+    await this.setupService(accessory)
+    this.accessories.push(accessory)
+  }
+
+  async getStatus(device, token) {
+    this.log.debug(`getStatus: ${device.name}`)
+    return Leviton.getIotSwitch({ switchID: device.id, token })
+  }
+
+  async setupService(accessory) {
+    this.log.debug(`setupService: ${accessory.displayName}`)
+
+    const device = accessory.context.device
+    this.log.debug(`Device Model: ${device.model}`)
+
+    switch (device.model) {
+      case 'DW4SF':
+        await this.setupFanService(accessory)
+        break
+      case 'DWVAA':
+      case 'DW1KD':
+      case 'DW6HD':
+      case 'D26HD':
+      case 'D23LP':
+      case 'DW3HL':
+        await this.setupLightbulbService(accessory)
+        break
+      case 'DW15R':
+      case 'DW15A':
+      case 'DW15P':
+        await this.setupOutletService(accessory)
+        break
+      default:
+        await this.setupSwitchService(accessory)
+        break
+    }
+  }
+
+  async setupSwitchService(accessory) {
+    this.log.debug(`Setting up device as Switch: ${accessory.displayName}`)
+
+    const device = accessory.context.device
+    const token = accessory.context.token
+    const status = await this.getStatus(device, token)
+
+    const service = accessory.getService(Service.Switch) || accessory.addService(Service.Switch, device.name)
+
+    service
+      .getCharacteristic(Characteristic.On)
+      .onGet(async () => {
+        const res = await Leviton.getIotSwitch({ switchID: device.id, token })
+        this.log.debug(`onGetPower: ${device.name} ${res.power}`)
+        return res.power === 'ON'
+      })
+      .onSet(async (value) => {
+        const res = await Leviton.putIotSwitch({ switchID: device.id, power: value ? 'ON' : 'OFF', token })
+        this.log.info(`onSetPower: ${device.name} ${res.power}`)
+      })
+      .updateValue(status.power === 'ON')
+  }
+
+  async setupOutletService(accessory) {
+    this.log.debug(`Setting up device as Outlet: ${accessory.displayName}`)
+
+    const device = accessory.context.device
+    const token = accessory.context.token
+    const status = await this.getStatus(device, token)
+
+    const service = accessory.getService(Service.Outlet) || accessory.addService(Service.Outlet, device.name)
+
+    service
+      .getCharacteristic(Characteristic.On)
+      .onGet(async () => {
+        const res = await Leviton.getIotSwitch({ switchID: device.id, token })
+        this.log.debug(`onGetPower: ${device.name} ${res.power}`)
+        return res.power === 'ON'
+      })
+      .onSet(async (value) => {
+        const res = await Leviton.putIotSwitch({ switchID: device.id, power: value ? 'ON' : 'OFF', token })
+        this.log.info(`onSetPower: ${device.name} ${res.power}`)
+      })
+      .updateValue(status.power === 'ON')
+  }
+
+  async setupLightbulbService(accessory) {
+    this.log.debug(`Setting up device as Lightbulb: ${accessory.displayName}`)
+
+    const device = accessory.context.device
+    const token = accessory.context.token
+    const status = await this.getStatus(device, token)
+
+    const service = accessory.getService(Service.Lightbulb) || accessory.addService(Service.Lightbulb, device.name)
+
+    service
+      .getCharacteristic(Characteristic.On)
+      .onGet(async () => {
+        const res = await Leviton.getIotSwitch({ switchID: device.id, token })
+        this.log.debug(`onGetPower: ${device.name} ${res.power}`)
+        return res.power === 'ON'
+      })
+      .onSet(async (value) => {
+        const res = await Leviton.putIotSwitch({ switchID: device.id, power: value ? 'ON' : 'OFF', token })
+        this.log.info(`onSetPower: ${device.name} ${res.power}`)
+      })
+      .updateValue(status.power === 'ON')
+
+    service
+      .getCharacteristic(Characteristic.Brightness)
+      .onGet(async () => {
+        const res = await Leviton.getIotSwitch({ switchID: device.id, token })
+        this.log.debug(`onGetBrightness: ${device.name} @ ${res.brightness}%`)
+        return res.brightness
+      })
+      .onSet(async (brightness) => {
+        const res = await Leviton.putIotSwitch({ switchID: device.id, brightness, token })
+        this.log.info(`onSetBrightness: ${device.name} @ ${res.brightness}%`)
+      })
+      .setProps({ minValue: status.minLevel, maxValue: status.maxLevel, minStep: 1 })
+      .updateValue(status.brightness)
+  }
+
+  async setupFanService(accessory) {
+    this.log.debug(`Setting up device as Fan: ${accessory.displayName}`)
+
+    const device = accessory.context.device
+    const token = accessory.context.token
+    const status = await this.getStatus(device, token)
+
+    const service = accessory.getService(Service.Fan) || accessory.addService(Service.Fan, device.name)
+
+    service
+      .getCharacteristic(Characteristic.On)
+      .onGet(async () => {
+        const res = await Leviton.getIotSwitch({ switchID: device.id, token })
+        this.log.debug(`onGetPower: ${device.name} ${res.power}`)
+        return res.power === 'ON'
+      })
+      .onSet(async (value) => {
+        const res = await Leviton.putIotSwitch({ switchID: device.id, power: value ? 'ON' : 'OFF', token })
+        this.log.info(`onSetPower: ${device.name} ${res.power}`)
+      })
+      .updateValue(status.power === 'ON')
+
+    service
+      .getCharacteristic(Characteristic.RotationSpeed)
+      .onGet(async () => {
+        const res = await Leviton.getIotSwitch({ switchID: device.id, token })
+        this.log.debug(`onGetRotationSpeed: ${device.name} @ ${res.brightness}%`)
+        return res.brightness
+      })
+      .onSet(async (brightness) => {
+        const res = await Leviton.putIotSwitch({ switchID: device.id, brightness, token })
+        this.log.info(`onSetRotationSpeed: ${device.name} @ ${res.brightness}%`)
+      })
+      .setProps({ minValue: 0, maxValue: status.maxLevel, minStep: status.minLevel })
+      .updateValue(status.brightness)
+  }
+
+  removeAccessories() {
+    this.log.info('Removing all accessories')
+    this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, this.accessories)
+    this.accessories.splice(0, this.accessories.length)
+  }
+}
+
+module.exports = function (homebridge) {
+  Service = homebridge.hap.Service
+  Characteristic = homebridge.hap.Characteristic
+  Accessory = homebridge.hap.Accessory
+  UUID = homebridge.hap.uuid
+  homebridge.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, LevitonDecoraSmartPlatform, true)
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@benjaminmichoux/homebridge-leviton",
+  "version": "2.2.0",
+  "description": "A homebridge plugin for Leviton Decora Smart devices",
+  "main": "index.js",
+  "keywords": [
+    "homebridge-plugin"
+  ],
+  "author": "tabrindle@gmail.com",
+  "contributors": [
+    "Benjamin Michoux (https://github.com/benjaminmichoux)"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/benjaminmichoux/homebridge-leviton.git"
+  },
+  "homepage": "https://github.com/benjaminmichoux/homebridge-leviton#readme",
+  "bugs": {
+    "url": "https://github.com/benjaminmichoux/homebridge-leviton/issues"
+  },
+  "dependencies": {
+    "sockjs-client": "^1.6.0"
+  },
+  "engines": {
+    "node": "^18.20.4 || ^20.14.0 || ^22 || ^24",
+    "homebridge": "^1.8.0 || ^2.0.0"
+  }
+}