homebridge-inco-cron 0.6.0

package/README.md

@@ -0,0 +1,115 @@
+# homebridge-inco-cron
+
+Expose controller scheduling gates as Apple Home on/off switches.
+
+## Requirements and installation
+
+Requires Node.js 18 or newer, Homebridge 1.6 or newer, and `npm-inco-pkg ^1.3.0`.
+The Homebridge host must be able to reach the controller over IPv4 UDP port 1964.
+
+Install the published package through Homebridge Plugins, or run
+`npm install homebridge-inco-cron` in the Homebridge installation directory.
+
+For local development builds, run `npm pack` in this plugin's source directory and in
+`npm-inco-pkg`. Copy the resulting archives to the Homebridge host, then install
+both from the Homebridge installation directory using its Node/npm environment:
+
+```sh
+npm install /path/to/npm-inco-pkg-1.3.0.tgz /path/to/homebridge-inco-cron-VERSION.tgz
+```
+
+Replace the archive paths and `VERSION` with the files you built. If the required
+library is already installed, only the plugin archive is needed. Local versions
+need not be published to the npm registry. Save configuration before restarting
+Homebridge.
+
+## Configuration
+
+Merge this example into the existing Homebridge configuration; it is a fragment,
+not a replacement for the whole file. Preserve the bridge, other accessories and
+other platforms. Add entries to existing arrays rather than creating duplicate
+JSON keys.
+
+```json
+{
+  "inco": {
+    "controller": "10.0.0.3"
+  },
+  "platforms": [
+    {
+      "platform": "IncoCron",
+      "name": "INCO Cron",
+      "accessories": [
+        {
+          "name": "Parents automatic",
+          "path": "Home.Upper.Parents.Cron"
+        },
+        {
+          "name": "Joel automatic",
+          "path": "Home.Upper.Joel.Cron"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Set **`inco.controller` once at the root of `config.json`**, shared by the light,
+window-cover, temperature and cron plugins. In the Homebridge web interface,
+edit this through the main **Config** JSON editor. It is not an individual plugin
+setting. A valid IPv4 address is required; missing or invalid configuration fails
+explicitly. Remove old `controller` and `host` fields from INCO accessories and
+platforms. Save and restart Homebridge after configuration changes.
+
+## Controller behavior
+
+The configured accessory path is used exactly as supplied:
+
+| Operation | Controller call |
+|---|---|
+| Read enabled state | `GetVariable(path)`: 1 means enabled, 0 means disabled |
+| Enable | `PutVariable(path, 1)` |
+| Disable | `PutVariable(path, 0)` |
+
+No suffix is appended and no procedure is called. Every write is followed by a
+read of the same path to verify the requested state. Invalid values, read/write
+errors and verification failures are reported to HomeKit. Startup does not write.
+The controller should make writes immediately readable and persist them as needed.
+
+The controller owns schedules and executes their commands. A switch can control
+a home, floor or room gate, rather than one scheduled action. For example,
+`Home.Upper.Parents.Cron` reflects the Parents gate only: if `Home.Cron` or another
+ancestor gate is zero, scheduling can remain suppressed while Parents is on.
+
+Entries are configured manually. There is no schedule discovery or background
+polling; external changes appear when HomeKit next requests the state. Requests
+for each switch are serialized, with a five-second deadline per transport call.
+
+## Migration and identity
+
+Cron entries belong under the `IncoCron` platform, not the root `accessories`
+array. Remove old standalone IncoCron entries when migrating, retaining unrelated
+accessories. The old `.Enabled`/`.Enable()`/`.Disable()` interface is unsupported.
+Use the actual readable/writable gate path.
+
+Each switch uses its path as its internal identity unless `uuid_base` is supplied.
+Keep paths or explicit IDs stable to preserve pairing identity. Duplicate paths
+within the platform are rejected. Duplicate display names can use different paths.
+
+## Frame limits and troubleshooting
+
+`npm-inco-pkg` enforces a **494-byte complete encoded INCO message** limit,
+including headers, checksums, escape bytes and terminators. IP/UDP headers are
+outside this count. There is no arbitrary 36-character path cap. Operation
+suffixes and numeric write data also consume frame space.
+
+Oversized requests fail before transmission with `INCO_FRAME_TOO_LARGE`.
+If a device is unavailable, check the root controller address, the actual INCO
+variable or procedure path, controller connectivity, and the Homebridge log.
+All INCO plugins must use the shared controller setting.
+
+## Development checks
+
+Run `npm test` from this plugin's source directory. This runs the plugin's mocked behavior tests.
+Tests do not exercise a real controller. Repository-level INCO transport and
+error-propagation tests provide additional coverage.

package/config.schema.json

@@ -0,0 +1,36 @@
+{
+  "pluginAlias": "IncoCron",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Controller address is shared by all INCO plugins. Set inco.controller once in the main Homebridge config.json.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "type": "string",
+        "default": "INCO Cron"
+      },
+      "accessories": {
+        "title": "Cron accessories",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "title": "Name",
+              "type": "string",
+              "required": true
+            },
+            "path": {
+              "title": "Cron INCO Path",
+              "type": "string",
+              "required": true,
+              "pattern": "^[A-Za-z0-9_.]+$",
+              "description": "INCO path. Complete encoded requests, including any operation suffixes, must fit the 494-byte controller frame limit; checked by npm-inco-pkg."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/controller-config.js

@@ -0,0 +1,16 @@
+"use strict";
+
+// Read the same root setting in every INCO plugin, including child bridges.
+module.exports = function configureController(homebridge, inco) {
+  const fs = require('fs');
+  const net = require('net');
+  const config = JSON.parse(fs.readFileSync(homebridge.user.configPath(), 'utf8'));
+  const controller = config.inco && config.inco.controller;
+  if (typeof controller !== 'string' || net.isIP(controller) !== 4) {
+    throw new Error('Set inco.controller to the controller IPv4 address in Homebridge config.json');
+  }
+  // Each plugin initializes its transport from exactly the same source.
+  // No accessory constructor may override this address.
+  inco.init(controller);
+  return controller;
+};

package/index.js

@@ -0,0 +1,83 @@
+'use strict';
+
+module.exports = function register(homebridge) {
+  const inco = require('npm-inco-pkg');
+  require('./controller-config')(homebridge, inco);
+  const { Service, Characteristic } = homebridge.hap;
+
+  class IncoCron {
+    constructor(log, config) {
+      this.log = log;
+      this.name = config.name;
+      this.path = config.path;
+      if (!this.name || !/^[A-Za-z0-9_.]+$/.test(this.path || '')) {
+        throw new Error('Cron name and a valid INCO path are required');
+      }
+      this.uuid_base = config.uuid_base || config.path;
+      this.pending = Promise.resolve();
+      this.service = new Service.Switch(this.name);
+      this.service.getCharacteristic(Characteristic.On)
+        .onGet(() => this.enqueue(() => this.readEnabled()))
+        .onSet(value => this.enqueue(async () => {
+          await this.request('putVariable', this.path, value ? 1 : 0);
+          const enabled = await this.readEnabled();
+          if (enabled !== Boolean(value)) throw new Error('Controller did not apply cron enabled state');
+        }));
+    }
+
+    enqueue(operation) {
+      const result = this.pending.then(operation);
+      this.pending = result.catch(() => {});
+      return result;
+    }
+
+    request(method, path, ...args) {
+      return new Promise((resolve, reject) => {
+        // Deadline also covers time spent queued behind other accessories.
+        const timer = setTimeout(() => reject(new Error('INCO request timed out: ' + path)), 5000);
+        try {
+          inco[method](path, ...args, (err, value) => {
+            clearTimeout(timer);
+            if (err) reject(err);
+            else resolve(value);
+          });
+        } catch (err) {
+          clearTimeout(timer);
+          reject(err);
+        }
+      });
+    }
+
+    async readEnabled() {
+      const value = await this.request('getVariable', this.path);
+      if (value !== 0 && value !== 1) throw new Error('Cron value must be numeric 0 or 1');
+      return value === 1;
+    }
+
+    getServices() { return [this.service]; }
+  }
+
+  class IncoCronPlatform {
+    constructor(log, config) {
+      this.log = log;
+      this.config = config;
+      if ('controller' in config || 'host' in config) {
+        throw new Error('Set controller only in the root inco.controller setting');
+      }
+      const entries = config.accessories || [];
+      if (new Set(entries.map(entry => entry.path)).size !== entries.length) {
+        throw new Error('Duplicate cron accessory paths');
+      }
+      if (entries.some(entry => 'controller' in entry || 'host' in entry)) {
+        throw new Error('Set controller only in the root inco.controller setting');
+      }
+    }
+
+    accessories(callback) {
+      callback((this.config.accessories || []).map(entry =>
+        new IncoCron(this.log, entry)));
+    }
+  }
+
+  homebridge.registerPlatform('homebridge-inco-cron', 'IncoCron', IncoCronPlatform);
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "homebridge-inco-cron",
+  "version": "0.6.0",
+  "description": "Enable and disable controller-owned INCO cron entries in Apple Home",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "config.schema.json",
+    "README.md",
+    "controller-config.js"
+  ],
+  "scripts": {
+    "test": "node --test test.js"
+  },
+  "engines": {
+    "node": ">=18",
+    "homebridge": ">=1.6.0"
+  },
+  "keywords": [
+    "homebridge-plugin",
+    "INCO",
+    "cron"
+  ],
+  "author": "Christoph Hirzel",
+  "license": "ISC",
+  "dependencies": {
+    "npm-inco-pkg": "^1.3.0"
+  }
+}