homebridge-envoy-solar-sensor 0.1.1

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/README.md

@@ -0,0 +1,104 @@
+Homebridge Envoy Solar Sensor
+
+Homebridge Envoy Solar Sensor is a Homebridge platform plugin that reads real time solar production data from an Enphase Envoy and exposes it to Apple HomeKit as a sensor.
+
+By converting photovoltaic production into a simple active or inactive state, HomeKit automations can react to actual daylight conditions instead of fixed schedules or unreliable ambient light sensors. This makes it ideal for switching outdoor lighting, garden lights or other devices based on real solar output.
+
+How it works
+
+The plugin periodically polls the local Enphase Envoy for current solar production measured in watts.
+
+When production rises above a configurable on threshold, the HomeKit sensor becomes active.
+When production falls below a configurable off threshold, the sensor becomes inactive again.
+
+Using two separate thresholds creates hysteresis, preventing rapid switching during clouds, shade or twilight conditions.
+
+In HomeKit the sensor is exposed as a Contact Sensor.
+Active solar production is represented as an open contact.
+Low or no production is represented as a closed contact.
+
+Supported Envoy endpoints
+
+The plugin supports the most commonly available local Envoy endpoints.
+
+Older Envoy firmware using the production.json endpoint.
+Newer Envoy firmware using the api v1 production endpoint.
+
+The correct endpoint can be selected directly in the Homebridge UI.
+
+Installation
+
+Install Homebridge if it is not already installed on your system.
+
+Install the plugin using npm.
+
+npm install homebridge-envoy-solar-sensor
+
+
+Restart Homebridge after installation to load the plugin.
+
+Configuration using Homebridge UI
+
+This plugin is fully configurable using the Homebridge web interface.
+
+Open the Homebridge UI and navigate to the plugin settings for Homebridge Envoy Solar Sensor.
+All configuration options are presented as form fields and no manual editing of config.json is required.
+
+The Envoy IP Address field should contain the local IP address or hostname of your Enphase Envoy.
+
+The Protocol option allows selecting HTTP or HTTPS depending on your Envoy configuration.
+
+The Envoy API Mode setting determines which endpoint is used to read production data.
+
+The Poll Interval defines how often the Envoy is queried for new production values.
+
+The On Threshold specifies the production level in watts above which the sensor becomes active.
+
+The Off Threshold specifies the production level in watts below which the sensor becomes inactive again.
+
+An optional authentication token can be provided for secured Envoy installations.
+
+Example Homebridge configuration
+
+When configured through the UI, Homebridge generates the following configuration internally.
+
+{
+  "platform": "EnvoySolarSensor",
+  "name": "Solar Production",
+  "host": "192.168.1.50",
+  "protocol": "http",
+  "mode": "productionJson",
+  "pollIntervalSeconds": 10,
+  "onThresholdW": 80,
+  "offThresholdW": 30
+}
+
+HomeKit automations
+
+Once the plugin is running, a Contact Sensor named Solar Production appears in the Home app.
+
+Typical automations include turning outdoor lights off when solar production becomes active and turning outdoor lights on when solar production becomes inactive.
+
+Because the automation is based on real solar output, lighting behavior naturally adapts to seasons, weather and cloud cover.
+
+Error handling and reliability
+
+If the Envoy cannot be reached or returns invalid data, the sensor reports a fault state in HomeKit.
+Once communication is restored, the fault state is cleared automatically.
+
+Polling is fully local and does not rely on cloud services.
+
+Requirements
+
+Node.js version 18 or higher is required.
+Homebridge version 1.6 or higher is required.
+An Enphase Envoy accessible on the local network is required.
+
+License
+
+This project is licensed under the MIT License.
+
+Contributing
+
+Contributions, improvements and feature requests are welcome.
+Please open an issue or pull request on GitHub.

package/config.schema.json

@@ -0,0 +1,74 @@
+{
+    "pluginAlias": "EnvoySolarSensor",
+    "pluginType": "platform",
+    "singular": true,
+    "schema": {
+      "type": "object",
+      "required": ["host"],
+      "properties": {
+        "name": {
+          "title": "Accessory Name",
+          "type": "string",
+          "default": "Solar Production",
+          "description": "Name shown in HomeKit"
+        },
+        "host": {
+          "title": "Envoy IP Address",
+          "type": "string",
+          "description": "IP address or hostname of the Enphase Envoy on your local network"
+        },
+        "protocol": {
+          "title": "Protocol",
+          "type": "string",
+          "default": "http",
+          "oneOf": [
+            { "title": "HTTP", "enum": ["http"] },
+            { "title": "HTTPS", "enum": ["https"] }
+          ],
+          "description": "Protocol used to connect to the Envoy"
+        },
+        "mode": {
+          "title": "Envoy API Mode",
+          "type": "string",
+          "default": "productionJson",
+          "oneOf": [
+            {
+              "title": "production.json (older Envoy)",
+              "enum": ["productionJson"]
+            },
+            {
+              "title": "api/v1/production (newer Envoy)",
+              "enum": ["v1Production"]
+            }
+          ],
+          "description": "Select which Envoy API endpoint is available on your device"
+        },
+        "pollIntervalSeconds": {
+          "title": "Poll Interval",
+          "type": "integer",
+          "default": 10,
+          "minimum": 5,
+          "description": "How often the Envoy is polled for production data in seconds"
+        },
+        "onThresholdW": {
+          "title": "On Threshold (Watts)",
+          "type": "integer",
+          "default": 80,
+          "description": "Production level above which the sensor becomes active"
+        },
+        "offThresholdW": {
+          "title": "Off Threshold (Watts)",
+          "type": "integer",
+          "default": 30,
+          "description": "Production level below which the sensor becomes inactive"
+        },
+        "token": {
+          "title": "Authentication Token",
+          "type": "string",
+          "default": "",
+          "description": "Optional bearer token for secured Envoy endpoints"
+        }
+      }
+    }
+  }
+  

package/index.js

@@ -0,0 +1,213 @@
+'use strict';
+
+const PLUGIN_NAME = 'homebridge-envoy-solar-sensor';
+const PLATFORM_NAME = 'EnvoySolarSensor';
+
+module.exports = (api) => {
+  api.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, EnvoySolarPlatform);
+};
+
+class EnvoySolarPlatform {
+  constructor(log, config, api) {
+    this.log = log;
+    this.config = config || {};
+    this.api = api;
+
+    this.Service = this.api.hap.Service;
+    this.Characteristic = this.api.hap.Characteristic;
+
+    this.accessory = null;
+    this.pollTimer = null;
+
+    this.api.on('didFinishLaunching', () => {
+      this.log.info('Platform gestart');
+      this.setupAccessory();
+      this.startPolling();
+    });
+  }
+
+  configureAccessory(accessory) {
+    this.accessory = accessory;
+  }
+
+  setupAccessory() {
+    const name = this.config.name || 'Zon Opwekking';
+    const host = this.config.host;
+    if (!host) {
+      this.log.error('Config mist host. Voorbeeld: "host": "192.168.1.50"');
+      return;
+    }
+
+    const uuid = this.api.hap.uuid.generate(`envoy-solar-sensor:${host}`);
+
+    if (!this.accessory) {
+      this.accessory = new this.api.platformAccessory(name, uuid);
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [this.accessory]);
+    } else {
+      this.accessory.displayName = name;
+    }
+
+    const info = this.accessory.getService(this.Service.AccessoryInformation)
+      || this.accessory.addService(this.Service.AccessoryInformation);
+
+    info
+      .setCharacteristic(this.Characteristic.Manufacturer, 'Enphase')
+      .setCharacteristic(this.Characteristic.Model, 'Envoy')
+      .setCharacteristic(this.Characteristic.SerialNumber, String(host));
+
+    const service = this.accessory.getService(this.Service.ContactSensor)
+      || this.accessory.addService(this.Service.ContactSensor, 'Opwekking Actief', 'production-active');
+
+    service.setCharacteristic(this.Characteristic.Name, 'Opwekking Actief');
+
+    if (service.testCharacteristic(this.Characteristic.StatusActive)) {
+      service.updateCharacteristic(this.Characteristic.StatusActive, true);
+    }
+
+    this.log.info(`Accessoire klaar: ${name} op host ${host}`);
+  }
+
+  startPolling() {
+    if (!this.accessory) return;
+
+    const interval = Math.max(5, Number(this.config.pollIntervalSeconds ?? 10));
+    this.log.info(`Poll interval: ${interval} seconden`);
+
+    const tick = async () => {
+      try {
+        const watts = await this.readProductionWatts();
+        this.updateState(watts);
+      } catch (err) {
+        this.log.warn(`Uitlezen mislukt: ${err && err.message ? err.message : String(err)}`);
+        this.markFault();
+      }
+    };
+
+    tick();
+    this.pollTimer = setInterval(tick, interval * 1000);
+  }
+
+  getThresholds() {
+    const onT = Number(this.config.onThresholdW ?? 80);
+    const offT = Number(this.config.offThresholdW ?? 30);
+    return { onT, offT };
+  }
+
+  getMode() {
+    return this.config.mode || 'productionJson';
+  }
+
+  getHost() {
+    return this.config.host;
+  }
+
+  getToken() {
+    return this.config.token;
+  }
+
+  getBaseUrl() {
+    const proto = this.config.protocol || 'http';
+    return `${proto}://${this.getHost()}`;
+  }
+
+  markFault() {
+    if (!this.accessory) return;
+    const service = this.accessory.getService(this.Service.ContactSensor);
+    if (!service) return;
+
+    if (service.testCharacteristic(this.Characteristic.StatusFault)) {
+      service.updateCharacteristic(this.Characteristic.StatusFault, this.Characteristic.StatusFault.GENERAL_FAULT);
+    }
+  }
+
+  clearFault() {
+    if (!this.accessory) return;
+    const service = this.accessory.getService(this.Service.ContactSensor);
+    if (!service) return;
+
+    if (service.testCharacteristic(this.Characteristic.StatusFault)) {
+      service.updateCharacteristic(this.Characteristic.StatusFault, this.Characteristic.StatusFault.NO_FAULT);
+    }
+  }
+
+  updateState(productionWatts) {
+    if (!this.accessory) return;
+
+    const service = this.accessory.getService(this.Service.ContactSensor);
+    if (!service) return;
+
+    const { onT, offT } = this.getThresholds();
+
+    const current = service.getCharacteristic(this.Characteristic.ContactSensorState).value;
+    const isOpenNow = current === this.Characteristic.ContactSensorState.CONTACT_NOT_DETECTED;
+
+    let shouldBeOpen = isOpenNow;
+
+    if (!isOpenNow && productionWatts >= onT) {
+      shouldBeOpen = true;
+    }
+
+    if (isOpenNow && productionWatts <= offT) {
+      shouldBeOpen = false;
+    }
+
+    const nextValue = shouldBeOpen
+      ? this.Characteristic.ContactSensorState.CONTACT_NOT_DETECTED
+      : this.Characteristic.ContactSensorState.CONTACT_DETECTED;
+
+    service.updateCharacteristic(this.Characteristic.ContactSensorState, nextValue);
+    this.clearFault();
+
+    this.log.debug(`Productie ${productionWatts} W, aan ${onT} W, uit ${offT} W, actief ${shouldBeOpen}`);
+  }
+
+  async readProductionWatts() {
+    const mode = this.getMode();
+    const base = this.getBaseUrl();
+
+    let url = '';
+    if (mode === 'productionJson') url = `${base}/production.json`;
+    else if (mode === 'v1Production') url = `${base}/api/v1/production`;
+    else throw new Error(`Onbekende mode: ${mode}`);
+
+    const data = await this.fetchJson(url);
+
+    if (mode === 'productionJson') return this.extractWattsFromProductionJson(data);
+    return this.extractWattsFromV1Production(data);
+  }
+
+  extractWattsFromProductionJson(data) {
+    const productionArray = data && data.production;
+    if (!Array.isArray(productionArray)) throw new Error('production.json mist production array');
+
+    const eim = productionArray.find((x) => x && x.type === 'eim');
+    const wNow = eim && eim.wNow;
+
+    if (typeof wNow !== 'number') throw new Error('production.json mist wNow (type eim)');
+    return Math.max(0, wNow);
+  }
+
+  extractWattsFromV1Production(data) {
+    const wattsNow = data && (data.wattsNow ?? data.watts_now);
+    if (typeof wattsNow === 'number') return Math.max(0, wattsNow);
+
+    const wNow = data && data.production && Array.isArray(data.production) ? data.production?.[0]?.wNow : undefined;
+    if (typeof wNow !== 'number') throw new Error('api/v1/production mist wattsNow of production[0].wNow');
+
+    return Math.max(0, wNow);
+  }
+
+  async fetchJson(url) {
+    const headers = { Accept: 'application/json' };
+    const token = this.getToken();
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const res = await fetch(url, { headers });
+
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status} op ${url}`);
+    }
+
+    return await res.json();
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "homebridge-envoy-solar-sensor",
+  "version": "0.1.1",
+  "description": "Expose Enphase Envoy PV production as a HomeKit sensor for automations",
+  "main": "index.js",
+  "keywords": [
+    "homebridge-plugin",
+    "homekit",
+    "enphase",
+    "envoy",
+    "solar"
+  ],
+  "engines": {
+    "node": ">=18.0.0",
+    "homebridge": ">=1.6.0"
+  },
+  "license": "MIT",
+  "dependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourname/homebridge-envoy-solar-sensor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourname/homebridge-envoy-solar-sensor/issues"
+  },
+  "homepage": "https://github.com/yourname/homebridge-envoy-solar-sensor#readme"
+}