@mp-consulting/homebridge-unifi-access 1.0.0

package/homebridge-ui/server.js

@@ -0,0 +1,374 @@
+/* server.js: @mp-consulting/homebridge-unifi-access webUI server API. */
+"use strict";
+
+import { featureOptionCategories, featureOptions } from "../dist/access-options.js";
+import { AccessApi } from "unifi-access";
+import { HomebridgePluginUiServer } from "@homebridge/plugin-ui-utils";
+import dgram from "node:dgram";
+import https from "node:https";
+import os from "node:os";
+import util from "node:util";
+
+// Validate a controller address, rejecting loopback, link-local, and unspecified addresses.
+function isValidAddress(address) {
+
+  if(!address || (typeof address !== "string")) {
+
+    return false;
+  }
+
+  const trimmed = address.trim().toLowerCase();
+
+  if(!trimmed || (trimmed === "localhost") || trimmed.startsWith("127.") || trimmed.startsWith("169.254.") || (trimmed === "0.0.0.0") ||
+    trimmed.startsWith("[") || trimmed.includes("::")) {
+
+    return false;
+  }
+
+  return true;
+}
+
+// Number of adjacent /24 subnets to scan in each direction from each local interface.
+// A value of 5 means scanning ±5 subnets (up to 2,540 unicast probes per local subnet).
+// Only used for discovering UniFi devices on routed subnets where broadcasts don't reach.
+const ADJACENT_SUBNET_RANGE = 5;
+const DISCOVERY_TIMEOUT = 5000;
+const UBNT_DISCOVERY_PORT = 10001;
+
+// Ubiquiti L2 Discovery Protocol: send a 4-byte packet, devices respond with TLV data.
+const UBNT_DISCOVERY_PACKET = globalThis.Buffer.from([ 0x01, 0x00, 0x00, 0x00 ]);
+
+// TLV field types in the Ubiquiti discovery response.
+const UBNT_TLV = {
+
+  FIRMWARE: 0x03,     // Firmware version string
+  HOSTNAME: 0x0B,     // Device hostname
+  MAC_IP: 0x02,       // 6-byte MAC + 4-byte IP
+  MODEL_LONG: 0x14,   // Full model name
+  MODEL_SHORT: 0x0C   // Short model name (e.g. "UNVR")
+};
+
+class PluginUiServer extends HomebridgePluginUiServer {
+
+  errorInfo;
+
+  constructor() {
+
+    super();
+
+    this.errorInfo = "";
+
+    // Register getErrorMessage() with the Homebridge server API.
+    this.#registerGetErrorMessage();
+
+    // Register getDevices() with the Homebridge server API.
+    this.#registerGetDevices();
+
+    // Register getOptions() with the Homebridge server API.
+    this.#registerGetOptions();
+
+    // Register discover() with the Homebridge server API.
+    this.#registerDiscover();
+
+    // Register checkStatus() with the Homebridge server API.
+    this.#registerCheckStatus();
+
+    this.ready();
+  }
+
+  // Register the getErrorMessage() webUI server API endpoint.
+  #registerGetErrorMessage() {
+
+    // Return the most recent error message generated by the Access API.
+    this.onRequest("/getErrorMessage", () => this.errorInfo);
+  }
+
+  // Register the getDevices() webUI server API endpoint.
+  #registerGetDevices() {
+
+    // Return the list of Access devices.
+    this.onRequest("/getDevices", async (controller) => {
+
+      // Validate the controller address before attempting a connection.
+      if(!isValidAddress(controller.address)) {
+
+        return [];
+      }
+
+      try {
+
+        const log = {
+
+          debug: () => {},
+          error: (message, parameters = []) => {
+
+            // Save the error to inform the user in the webUI.
+            this.errorInfo = util.format(message, ...(Array.isArray(parameters) ? parameters : [parameters]));
+
+            // eslint-disable-next-line no-console
+            console.error(this.errorInfo);
+          },
+          info: () => {},
+          warn: () => {}
+        };
+
+        // Connect to the Access controller.
+        const udaApi = new AccessApi(log);
+
+        if(!(await udaApi.login(controller.address, controller.username, controller.password))) {
+
+          return [];
+        }
+
+        // Bootstrap the controller. It will emit a message once it's received the bootstrap JSON, or you can alternatively wait for the Promise to resolve.
+        if(!(await udaApi.getBootstrap())) {
+
+          return [];
+        }
+
+        const devices = udaApi.devices.filter(x => x.is_managed);
+
+        devices.sort((a, b) => {
+
+          const nonEmpty = (...args) => args.find(v => (v !== undefined) && (v !== null) && (v !== ""));
+
+          const aCase = nonEmpty(a.alias, a.name, a.model).toLowerCase();
+          const bCase = nonEmpty(b.alias, b.name, b.model).toLowerCase();
+
+          return aCase > bCase ? 1 : (bCase > aCase ? -1 : 0);
+        });
+
+        const result = [ udaApi.controller, ...devices ];
+
+        // Clean up the API session.
+        udaApi.logout();
+
+        return result;
+      } catch(err) {
+
+        // eslint-disable-next-line no-console
+        console.log(err);
+
+        // Return nothing if we error out for some reason.
+        return [];
+      }
+    });
+  }
+
+  // Register the getOptions() webUI server API endpoint.
+  #registerGetOptions() {
+
+    // Return the list of options configured for a given Access device.
+    this.onRequest("/getOptions", () => ({ categories: featureOptionCategories, options: featureOptions }));
+  }
+
+  // Register the discover() webUI server API endpoint using the Ubiquiti L2 Discovery Protocol.
+  #registerDiscover() {
+
+    this.onRequest("/discover", () => {
+
+      return new Promise((resolve) => {
+
+        const devices = [];
+        const seen = new Set();
+
+        const socket = dgram.createSocket({ reuseAddr: true, type: "udp4" });
+
+        socket.on("message", (msg) => {
+
+          // Parse the Ubiquiti discovery response (TLV format after 4-byte header).
+          if(msg.length < 4) { return; }
+
+          const device = {};
+          let offset = 4;
+
+          while(offset + 3 <= msg.length) {
+
+            const type = msg[offset];
+            const length = msg.readUInt16BE(offset + 1);
+
+            offset += 3;
+
+            if(offset + length > msg.length) { break; }
+
+            const value = msg.subarray(offset, offset + length);
+
+            switch(type) {
+
+              case UBNT_TLV.MAC_IP:
+
+                if(length >= 10) {
+
+                  device.mac = [...value.subarray(0, 6)].map(b => b.toString(16).padStart(2, "0")).join(":");
+                  device.ip = value[6] + "." + value[7] + "." + value[8] + "." + value[9];
+                }
+
+                break;
+
+              case UBNT_TLV.HOSTNAME:
+
+                device.hostname = value.toString("utf8");
+
+                break;
+
+              case UBNT_TLV.MODEL_SHORT:
+
+                device.model = value.toString("utf8");
+
+                break;
+
+              case UBNT_TLV.MODEL_LONG:
+
+                device.modelLong = value.toString("utf8");
+
+                break;
+
+              case UBNT_TLV.FIRMWARE:
+
+                device.firmware = value.toString("utf8");
+
+                break;
+
+              default:
+
+                break;
+            }
+
+            offset += length;
+          }
+
+          if(device.ip && !seen.has(device.ip)) {
+
+            seen.add(device.ip);
+
+            devices.push({
+
+              firmware: device.firmware || "",
+              ip: device.ip,
+              mac: device.mac || "",
+              model: device.model || "",
+              modelLong: device.modelLong || "",
+              name: device.hostname || device.model || device.ip
+            });
+          }
+        });
+
+        socket.on("error", () => {
+
+          try { socket.close(); } catch{ /* ignore */ }
+          resolve([]);
+        });
+
+        socket.bind(() => {
+
+          socket.setBroadcast(true);
+
+          // Broadcast to all local subnet broadcast addresses to reach devices on directly-connected subnets.
+          const broadcastAddresses = new Set(["255.255.255.255"]);
+          const localSubnets = [];
+
+          for(const iface of Object.values(os.networkInterfaces())) {
+
+            for(const info of (iface || [])) {
+
+              if((info.family === "IPv4") && !info.internal) {
+
+                const ipParts = info.address.split(".").map(Number);
+                const maskParts = info.netmask.split(".").map(Number);
+                const broadcast = ipParts.map((ip, i) => (ip | (~maskParts[i] & 0xFF))).join(".");
+
+                broadcastAddresses.add(broadcast);
+
+                // Track /24+ subnets for adjacent unicast scanning.
+                if(maskParts[2] === 255) {
+
+                  localSubnets.push([ ipParts[0], ipParts[1], ipParts[2] ]);
+                }
+              }
+            }
+          }
+
+          for(const addr of broadcastAddresses) {
+
+            socket.send(UBNT_DISCOVERY_PACKET, 0, UBNT_DISCOVERY_PACKET.length, UBNT_DISCOVERY_PORT, addr);
+          }
+
+          // Unicast scan adjacent /24 subnets to find devices across routed subnets (broadcasts don't cross routers).
+          const scannedSubnets = new Set(localSubnets.map(s => s.join(".")));
+
+          for(const [ a, b, c ] of localSubnets) {
+
+            for(let offset = -ADJACENT_SUBNET_RANGE; offset <= ADJACENT_SUBNET_RANGE; offset++) {
+
+              const adjacentC = c + offset;
+
+              if((adjacentC < 0) || (adjacentC > 255)) {
+
+                continue;
+              }
+
+              const subnetKey = a + "." + b + "." + adjacentC;
+
+              if(scannedSubnets.has(subnetKey)) {
+
+                continue;
+              }
+
+              scannedSubnets.add(subnetKey);
+
+              for(let host = 1; host <= 254; host++) {
+
+                socket.send(UBNT_DISCOVERY_PACKET, 0, UBNT_DISCOVERY_PACKET.length, UBNT_DISCOVERY_PORT, a + "." + b + "." + adjacentC + "." + host);
+              }
+            }
+          }
+        });
+
+        // Stop after timeout and return results.
+        globalThis.setTimeout(() => {
+
+          try { socket.close(); } catch{ /* ignore */ }
+          resolve(devices);
+        }, DISCOVERY_TIMEOUT);
+      });
+    });
+  }
+
+  // Register the checkStatus() webUI server API endpoint.
+  #registerCheckStatus() {
+
+    this.onRequest("/checkStatus", (payload) => {
+
+      return new Promise((resolve) => {
+
+        if(!isValidAddress(payload?.address)) {
+
+          resolve({ online: false });
+
+          return;
+        }
+
+        const req = https.request({
+
+          hostname: payload.address,
+          method: "HEAD",
+          path: "/",
+          port: 443,
+          rejectUnauthorized: false,
+          timeout: 5000
+        }, () => resolve({ online: true }));
+
+        req.on("error", () => resolve({ online: false }));
+        req.on("timeout", () => {
+
+          req.destroy();
+          resolve({ online: false });
+        });
+
+        req.end();
+      });
+    });
+  }
+}
+
+(() => new PluginUiServer())();

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@mp-consulting/homebridge-unifi-access",
+  "version": "1.0.0",
+  "displayName": "UniFi Access",
+  "description": "Complete HomeKit support for UniFi Access devices — locks, doorbells, sensors, and readers — with automatic device discovery and realtime events.",
+  "author": "Mickael Palma",
+  "homepage": "https://github.com/mp-consulting/homebridge-unifi-access#readme",
+  "license": "MIT",
+  "funding": {
+    "type": "paypal",
+    "url": "https://paypal.me/mickaelpalma"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/mp-consulting/homebridge-unifi-access.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mp-consulting/homebridge-unifi-access/issues"
+  },
+  "type": "module",
+  "engines": {
+    "homebridge": ">=1.8.0 || >=2.0.0",
+    "node": ">=18"
+  },
+  "keywords": [
+    "homebridge",
+    "homebridge-plugin",
+    "homebridge-unifi-access",
+    "homekit",
+    "camera",
+    "doorbell",
+    "ubiquiti",
+    "unifi",
+    "unifi access",
+    "unifi protect",
+    "motion",
+    "motion sensor",
+    "security",
+    "udm",
+    "udm pro",
+    "udm-pro",
+    "unifi camera",
+    "unifi cloud key",
+    "unifi dream machine pro",
+    "unifios"
+  ],
+  "scripts": {
+    "prebuild": "npm run clean",
+    "build": "tsc",
+    "clean": "shx rm -rf dist",
+    "lint": "eslint . --max-warnings=0",
+    "postpublish": "npm run clean",
+    "prepublishOnly": "npm test && npm run lint && npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "watch": "npm run build && npm link && nodemon",
+    "start": "npm run build && homebridge -U ./test/hbConfig -D -I -P .",
+    "monitor:events": "npx tsx scripts/event-schema-monitor.ts"
+  },
+  "main": "dist/index.js",
+  "dependencies": {
+    "@homebridge/plugin-ui-utils": "2.1.2",
+    "homebridge-plugin-utils": "1.30.0",
+    "unifi-access": "1.5.3"
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "5.7.1",
+    "@types/node": "25.0.10",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "9.39.2",
+    "homebridge": "1.11.1",
+    "homebridge-config-ui-x": "^4.80.0",
+    "nodemon": "^3.1.11",
+    "shx": "0.4.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.53.1",
+    "vitest": "^4.0.18"
+  },
+  "overrides": {
+    "@types/readable-stream": "4.0.23"
+  }
+}