homebridge-unifi-access 0.0.1 → 1.1.0

package/homebridge-ui/public/index.html

@@ -0,0 +1,151 @@
+<p class="text-center">
+  <img src="https://raw.githubusercontent.com/hjdhjd/homebridge-unifi-access/main/images/homebridge-unifi-access.svg" alt="homebridge-unifi-access logo" class="w-50" />
+</p>
+<div id="pageFirstRun" style="display: none;">
+  <div class="text-center">
+    <p>Please enter the address of your UniFi Access controller (e.g. unvr.local or 10.0.0.1) and the login credentials for a <strong>local user</strong> to get started with <strong>homebridge-unifi-access</strong>.</p>
+    <table class="table table-sm table-borderless">
+      <tr>
+        <td>
+          <input type="test" placeholder="Access controller hostname or IP address" size="40" id="address"></input>
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <input type="username" placeholder="Access controller username" size="40" id="username"></input>
+        </td>
+      </tr>
+      <tr>
+        <td>
+          <input type="password" placeholder="Access controller password" size="40" id="password"></input>
+        </td>
+      </tr>
+      <tr>
+        <td class="m-0 p-2 text-center font-weight-bold text-danger" id="loginError">
+          &nbsp;
+        </td>
+      </tr>
+    </table>
+    <br>
+      <button type="button" class="btn btn-primary" id="firstRun">Login to UniFi Access &rarr;</button>
+    <br>
+      To optimize performance and responsiveness, please make this plugin a <a target="_blank" href="https://github.com/homebridge/homebridge/wiki/Child-Bridges">child bridge</a> once you've completed configuration.
+  </div>
+</div>
+<div id="menuWrapper" class="btn-group w-100 mb-0" role="group" aria-label="UI Menu" style="display: none;">
+  <button type="button" class="btn btn-primary" id="menuSettings">Settings</button>
+  <button type="button" class="btn btn-primary" id="menuFeatureOptions">Feature Options</button>
+  <button type="button" class="btn btn-primary mr-0" id="menuHome">Support</button>
+</div>
+<div id="pageFeatureOptions" class="mt-2" style="display: none;">
+  <div id="deviceInfo">
+    <table class="table table-sm table-borderless">
+      <tr class="align-center">
+        <td id="headerInfo" colspan="2" class="m-0 p-2 text-center font-weight-bold"></td>
+      </tr>
+      <tr class="align-top">
+        <td rowspan="3" class="w-25">
+          <table id="sidebar" class="table table-sm table-bordered m-0 p-0">
+            <tr>
+              <td>
+                <table class="table table-sm table-borderless m-0 p-0" id="controllersTable"></table>
+              </td>
+            </tr>
+            <tr>
+              <td>
+                <table class="table table-sm table-borderless m-0 p-0" id="devicesTable"></table>
+              </td>
+            </tr>
+          </table>
+        </td>
+        <td id="deviceStatsTable">
+          <table class="table table-sm table-borderless border-bottom m-0 p-0">
+            <tr id="deviceStatsHeader">
+              <th class="m-0 p-0" style="width: 30%;"><B>Model<B></th>
+              <th class="m-0 p-0 w-25"><B>IP Address</B></th>
+              <th class="m-0 p-0" style="width: 25%;"><B>MAC Address</B></th>
+              <th class="m-0 p-0 w-25"><B>Status</B></th>
+            </tr>
+            <tr>
+              <td id="device_model" class="m-0 p-0"></td>
+              <td id="device_address" class="m-0 p-0"></td>
+              <td id="device_mac" class="m-0 p-0"></td>
+              <td id="device_online" class="m-0 p-0"></td>
+            </tr>
+          </table>
+        </td>
+      </tr>
+      <tr>
+        <td id="configTable" class="w-100"></td>
+      </tr>
+    </table>
+  </div>
+</div>
+<div id="pageSupport" class="mt-4" style="display: none;">
+  <h5>Introduction</h5>
+    <p class="px-4">I hope you enjoy <a target="_blank" href="https://github.com/hjdhjd/homebridge-unifi-access">homebridge-unifi-access</a> as much as I enjoy developing it. All my projects are labors of love. If you'd like to show your appreciation - <a target="_blank" href="https://github.com/hjdhjd/homebridge-unifi-access">star this project on Github</A> and do some good in your community, either financially or with your time: a food bank, an animal shelter (two of my passions), or whatever resonates with you that can give something back to the world around you.</p>
+
+    <div class="px-4">
+      Other plugins by <a target="_blank" href="https://github.com/hjdhjd">HJD</a>:
+
+      <ul dir="auto">
+      <ul dir="auto">
+        <li><a target="_blank" href="https://github.com/hjdhjd/homebridge-myq">homebridge-myQ: Liftmaster and Chamberlain garage door and gate opener support for HomeKit</a></li>
+        <li><a target="_blank" href="https://github.com/hjdhjd/homebridge-ratgdo">homebridge-ratgdo: Ratgdo (non-myQ Liftmaster and Chamberlain) garage door and gate opener support for HomeKit</a></li>      </ul>
+        <li><a target="_blank" href="https://github.com/hjdhjd/homebridge-unifi-protect">homebridge-unifi-protect: Complete HomeKit integration for the entire UniFi Protect ecosystem</a></li>
+      </ul>
+    </div>
+
+  <h5>Getting Started</h5>
+    <ul dir="auto">
+      <li>
+          <a target="_blank" href="#installation">Installation</a>
+          : installing this plugin, including system requirements.
+      </li>
+      <li>
+          <a target="_blank" href="#plugin-configuration">Plugin Configuration</a>
+          : how to quickly get up and running.
+      </li>
+    </ul>
+
+  <h5>Advanced Topics</h5>
+    <ul dir="auto">
+      <li>
+        <a target="_blank" href="https://github.com/hjdhjd/homebridge-unifi-access/blob/main/docs/FeatureOptions.md">Feature Options</a>: granular options to allow you to set the camera quality individually, show or hide specific cameras, controllers, and more.
+      </li>
+      <li>
+        <a target="_blank" href="https://github.com/hjdhjd/homebridge-unifi-access/blob/main/docs/MQTT.md">MQTT</a>: how to configure MQTT support.
+      </li>
+      <li>
+        <a target="_blank" href="https://github.com/hjdhjd/unifi-access">UniFi Access native API Documentation</a>: documentation of how the undocumented native Ubiquiti UniFi Access API.
+      </li>
+      <li>
+        <a target="_blank" href="https://github.com/hjdhjd/homebridge-unifi-access/blob/main/docs/Changelog.md">Changelog</a>: changes and release history of this plugin.
+      </li>
+    </ul>
+
+  <h5>Support</h5>
+  <ul>
+    <li>
+      <a target="_blank" href="https://discord.gg/QXqfHEW">Discord Support Channel</a>
+    </li>
+    <li>
+      <a target="_blank" href="https://github.com/hjdhjd/homebridge-unifi-access/issues/new/choose">Create a Developer Support Request</a>
+    </li>
+    <li>
+      <a target="_blank" href="https://github.com/hjdhjd/homebridge-unifi-access/blob/main/docs/Changelog.md">View the Changelog and Release Notes</a>
+    </li>
+  </ul>
+</div>
+<noscript>
+  <h2>A JavaScript-enabled web browser is required to use this webUI.</h2>
+</noscript>
+<script>
+  <!--
+  (async () => {
+
+    // We use dynamic imports because web browsers often attempt to cache modules and we always want to pull a fresh copy, in case they've been updated.
+    await import("./ui.mjs");
+  })();
+  // -->
+</script>

package/homebridge-ui/public/lib/featureoptions.mjs

@@ -0,0 +1,201 @@
+/* Copyright(C) 2017-2024, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * featureoptions.mjs: Feature option webUI base class.
+ */
+"use strict";
+
+export class FeatureOptions {
+
+  controller;
+
+  featureOptionGroups;
+  featureOptionList;
+  optionsList;
+
+  constructor() {
+
+    this.featureOptionGroups = {};
+    this.featureOptionList = {};
+    this.controller = null;
+    this.optionsList = [];
+  }
+
+  // Abstract method to be implemented by subclasses to render the feature option webUI.
+  async showUI() {
+  }
+
+  // Is this feature option set explicitly?
+  isOptionSet(featureOption, deviceMac) {
+
+    const optionRegex = new RegExp("^(?:Enable|Disable)\\." + featureOption + (!deviceMac ? "" : "\\." + deviceMac) + "$", "gi");
+    return this.optionsList.filter(x => optionRegex.test(x)).length ? true : false;
+  }
+
+  // Is a feature option globally enabled?
+  isGlobalOptionEnabled(featureOption, defaultState) {
+
+    featureOption = featureOption.toUpperCase();
+
+    // Test device-specific options.
+    return this.optionsList.some(x => x === ("ENABLE." + featureOption)) ? true :
+      (this.optionsList.some(x => x === ("DISABLE." + featureOption)) ? false : defaultState
+      );
+  }
+
+  // Is a feature option enabled at the device or global level. This function does not traverse the scoping hierarchy.
+  isDeviceOptionEnabled(featureOption, mac, defaultState) {
+
+    if(!mac) {
+
+      return this.isGlobalOptionEnabled(featureOption, defaultState);
+    }
+
+    featureOption = featureOption.toUpperCase();
+    mac = mac.toUpperCase();
+
+    // Test device-specific options.
+    return this.optionsList.some(x => x === ("ENABLE." + featureOption + "." + mac)) ? true :
+      (this.optionsList.some(x => x === ("DISABLE." + featureOption + "." + mac)) ? false : defaultState
+      );
+  }
+
+  // Is a value-centric feature option enabled at the device or global level. This function does not traverse the scoping hierarchy.
+  isOptionValueSet(featureOption, deviceMac) {
+
+    const optionRegex = new RegExp("^Enable\\." + featureOption + (!deviceMac ? "" : "\\." + deviceMac) + "\\.([^\\.]+)$", "gi");
+
+
+    return this.optionsList.some(x => optionRegex.test(x));
+  }
+
+  // Get the value of a value-centric feature option.
+  getOptionValue(featureOption, deviceMac) {
+
+    const optionRegex = new RegExp("^Enable\\." + featureOption + (!deviceMac ? "" : "\\." + deviceMac) + "\\.([^\\.]+)$", "gi");
+
+    // Get the option value, if we have one.
+    for(const option of this.optionsList) {
+
+      const regexMatch = optionRegex.exec(option);
+
+      if(regexMatch) {
+
+        return regexMatch[1];
+      }
+    }
+
+    return undefined;
+  }
+
+  // Is a feature option enabled at the device or global level. It does traverse the scoping hierarchy.
+  isOptionEnabled(featureOption, deviceMac) {
+
+    const defaultState = this.featureOptionList[featureOption]?.default ?? true;
+
+    if(deviceMac) {
+
+      // Device level check.
+      if(this.isDeviceOptionEnabled(featureOption, deviceMac, defaultState) !== defaultState) {
+
+        return !defaultState;
+      }
+
+      // Controller level check.
+      if(this.isDeviceOptionEnabled(featureOption, this.controller, defaultState) !== defaultState) {
+
+        return !defaultState;
+      }
+    }
+
+    // Global check.
+    if(this.isGlobalOptionEnabled(featureOption, defaultState) !== defaultState) {
+
+      return !defaultState;
+    }
+
+    // Return the default.
+    return defaultState;
+  };
+
+  // Return the scope level of a feature option.
+  optionScope(featureOption, deviceMac, defaultState, isOptionValue = false) {
+
+    // Scope priority is always: device, controller, global.
+
+    // If we have a value-centric feature option, our lookups are a bit different.
+    if(isOptionValue) {
+
+      if(deviceMac) {
+
+        if(this.isOptionValueSet(featureOption, deviceMac)) {
+
+          return "device";
+        }
+
+        if(this.isOptionValueSet(featureOption, this.controller)) {
+
+          return "controller";
+        }
+      }
+
+      if(this.isOptionValueSet(featureOption)) {
+
+        return "global";
+      }
+
+      return "none";
+    }
+
+    if(deviceMac) {
+
+      // Let's see if we've set it at the device-level.
+      if((this.isDeviceOptionEnabled(featureOption, deviceMac, defaultState) !== defaultState) || this.isOptionSet(featureOption, deviceMac)) {
+
+        return "device";
+      }
+
+      // Now let's test the controller level.
+      if((this.isDeviceOptionEnabled(featureOption, this.controller, defaultState) !== defaultState) || this.isOptionSet(featureOption, this.controller)) {
+
+        return "controller";
+      }
+    }
+
+    // Finally, let's test the global level.
+    if((this.isGlobalOptionEnabled(featureOption, defaultState) !== defaultState) || this.isOptionSet(featureOption)) {
+
+      return "global";
+    }
+
+    // Option isn't set to a non-default value.
+    return "none";
+  };
+
+  // Return the color hinting for a given option's scope.
+  optionScopeColor(featureOption, deviceMac, defaultState, isOptionValue) {
+
+    switch(this.optionScope(featureOption, deviceMac, defaultState, isOptionValue)) {
+
+      case "device":
+
+        return "text-info";
+        break;
+
+      case "controller":
+
+        return "text-success";
+        break;
+
+      case "global":
+
+        return deviceMac ? "text-warning" : "text-info";
+        break;
+
+      default:
+
+        break;
+    }
+
+    return null;
+  };
+}

package/homebridge-ui/public/ui.mjs

@@ -0,0 +1,182 @@
+/* Copyright(C) 2017-2024, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * ui.mjs: HBUA webUI.
+ */
+"use strict";
+
+// Keep a list of all the feature options and option groups. We dynamically import our modules to avoid browser caches.
+const featureOptions = new (await import("./access-featureoptions.mjs")).AccessFeatureOptions();
+
+// Show the first run user experience if we don't have valid login credentials.
+function showFirstRun () {
+
+  const buttonFirstRun = document.getElementById("firstRun");
+  const inputAddress = document.getElementById("address");
+  const inputUsername = document.getElementById("username");
+  const inputPassword = document.getElementById("password");
+  const tdLoginError = document.getElementById("loginError");
+
+  // If we don't have any controllers configured, initialize the list.
+  if(!featureOptions.currentConfig[0].controllers) {
+
+    featureOptions.currentConfig[0].controllers = [ {} ];
+  }
+
+  // Pre-populate with anything we might already have in our configuration.
+  inputAddress.value = featureOptions.currentConfig[0].controllers[0].address ?? "";
+  inputUsername.value = featureOptions.currentConfig[0].controllers[0].username ?? "";
+  inputPassword.value = featureOptions.currentConfig[0].controllers[0].password ?? "";
+
+  // Clear login error messages when the login credentials change.
+  inputAddress.addEventListener("input", () => {
+
+    tdLoginError.innerHTML = " ";
+  });
+
+  inputUsername.addEventListener("input", () => {
+
+    tdLoginError.innerHTML = " ";
+  });
+
+  inputPassword.addEventListener("input", () => {
+
+    tdLoginError.innerHTML = " ";
+  });
+
+  // First run user experience.
+  buttonFirstRun.addEventListener("click", async () => {
+
+    // Show the beachball while we setup.
+    homebridge.showSpinner();
+
+    const address = inputAddress.value;
+    const username = inputUsername.value;
+    const password = inputPassword.value;
+
+    tdLoginError.innerHTML = " ";
+
+    if(!address?.length || !username?.length || !password?.length) {
+
+      tdLoginError.appendChild(document.createTextNode("Please enter a valid UniFi Access controller address, username and password."));
+      homebridge.hideSpinner();
+      return;
+    }
+
+    const udaDevices = await homebridge.request("/getDevices", { address: address, username: username, password: password });
+
+    // Couldn't connect to the Access controller for some reason.
+    if(!udaDevices?.length) {
+
+      tdLoginError.innerHTML = "Unable to login to the UniFi Access controller.<br>Please check your controller address, username, and password.<br><code class=\"text-danger\">" + (await homebridge.request("/getErrorMessage")) + "</code>";
+      homebridge.hideSpinner();
+      return;
+    }
+
+    // Save the login credentials to our configuration.
+    featureOptions.currentConfig[0].controllers[0].address = address;
+    featureOptions.currentConfig[0].controllers[0].username = username;
+    featureOptions.currentConfig[0].controllers[0].password = password;
+
+    await homebridge.updatePluginConfig(featureOptions.currentConfig);
+
+    // Create our UI.
+    document.getElementById("pageFirstRun").style.display = "none";
+    document.getElementById("menuWrapper").style.display = "inline-flex";
+    featureOptions.showUI();
+  });
+
+  document.getElementById("pageFirstRun").style.display = "block";
+}
+
+// Show the main plugin configuration tab.
+function showSettings () {
+
+  // Show the beachball while we setup.
+  homebridge.showSpinner();
+
+  // Create our UI.
+  document.getElementById("menuHome").classList.remove("btn-elegant");
+  document.getElementById("menuHome").classList.add("btn-primary");
+  document.getElementById("menuFeatureOptions").classList.remove("btn-elegant");
+  document.getElementById("menuFeatureOptions").classList.add("btn-primary");
+  document.getElementById("menuSettings").classList.add("btn-elegant");
+  document.getElementById("menuSettings").classList.remove("btn-primary");
+
+  document.getElementById("pageSupport").style.display = "none";
+  document.getElementById("pageFeatureOptions").style.display = "none";
+
+  homebridge.showSchemaForm();
+
+  // All done. Let the user interact with us.
+  homebridge.hideSpinner();
+}
+
+// Show the support tab.
+function showSupport() {
+
+  // Show the beachball while we setup.
+  homebridge.showSpinner();
+  homebridge.hideSchemaForm();
+
+  // Create our UI.
+  document.getElementById("menuHome").classList.add("btn-elegant");
+  document.getElementById("menuHome").classList.remove("btn-primary");
+  document.getElementById("menuFeatureOptions").classList.remove("btn-elegant");
+  document.getElementById("menuFeatureOptions").classList.add("btn-primary");
+  document.getElementById("menuSettings").classList.remove("btn-elegant");
+  document.getElementById("menuSettings").classList.add("btn-primary");
+
+  document.getElementById("pageSupport").style.display = "block";
+  document.getElementById("pageFeatureOptions").style.display = "none";
+
+  // All done. Let the user interact with us.
+  homebridge.hideSpinner();
+}
+
+// Launch our webUI.
+async function launchWebUI() {
+
+  // Retrieve the current plugin configuration.
+  featureOptions.currentConfig = await homebridge.getPluginConfig();
+
+  // Add our event listeners to animate the UI.
+  menuHome.addEventListener("click", () => showSupport());
+  menuFeatureOptions.addEventListener("click", () => featureOptions.showUI());
+  menuSettings.addEventListener("click", () => showSettings());
+
+  // If we've got a valid Access controller, username, and password configured, we launch our feature option UI. Otherwise, we launch our first run UI.
+  if(featureOptions.currentConfig.length && featureOptions.currentConfig[0].controllers?.length && featureOptions.currentConfig[0].controllers[0]?.address?.length && featureOptions.currentConfig[0].controllers[0]?.username?.length && featureOptions.currentConfig[0].controllers[0]?.password?.length) {
+
+    document.getElementById("menuWrapper").style.display = "inline-flex";
+    featureOptions.showUI();
+    return;
+  }
+
+  // If we have no configuration, let's create one.
+  if(!featureOptions.currentConfig.length) {
+
+    featureOptions.currentConfig.push({ controllers: [ {} ], name: "UniFi Access" });
+  } else if(!("name" in featureOptions.currentConfig[0])) {
+
+    // If we haven't set the name, let's do so now.
+    featureOptions.currentConfig[0].name = "UniFi Access";
+  }
+
+  // Update the plugin configuration and launch the first run UI.
+  await homebridge.updatePluginConfig(featureOptions.currentConfig);
+  showFirstRun();
+}
+
+// Fire off our UI, catching errors along the way.
+try {
+
+  launchWebUI();
+} catch(err) {
+
+  // If we had an error instantiating or updating the UI, notify the user.
+  homebridge.toast.error(err.message, "Error");
+} finally {
+
+  // Always leave the UI in a usable place for the end user.
+  homebridge.hideSpinner();
+}

package/homebridge-ui/server.js

@@ -0,0 +1,153 @@
+/* Copyright(C) 2017-2024, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * server.js: homebridge-unifi-access webUI server API.
+ *
+ * This module is heavily inspired by the homebridge-config-ui-x source code and borrows from both.
+ * Thank you oznu for your contributions to the HomeKit world.
+ */
+"use strict";
+
+import { featureOptionCategories, featureOptions, isOptionEnabled } from "../dist/access-options.js";
+import { AccessApi } from "unifi-access";
+import { HomebridgePluginUiServer } from "@homebridge/plugin-ui-utils";
+import util from "node:util";
+
+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();
+
+    this.ready();
+  }
+
+  // Register the getErrorMessage() webUI server API endpoint.
+  #registerGetErrorMessage() {
+
+    // Return the most recent error message generated by the Access API.
+    this.onRequest("/getErrorMessage", async () => {
+
+      try {
+
+        return this.errorInfo;
+      } catch(err) {
+
+        console.log(err);
+
+        // Return nothing if we error out for some reason.
+        return "";
+      }
+    });
+  }
+
+  // Register the getDevices() webUI server API endpoint.
+  #registerGetDevices() {
+
+    // Return the list of Access devices.
+    this.onRequest("/getDevices", async (controller) => {
+
+      try {
+
+        const log = {
+
+          debug: (message, parameters) => {},
+          error: (message, parameters = []) => {
+
+            // Save the error to inform the user in the webUI.
+            if(!!parameters?.[Symbol.iterator]) {
+
+              this.errorInfo = util.format(message, ...parameters);
+            } else {
+
+              this.errorInfo = util.format(message, parameters);
+            }
+
+            console.error(this.errorInfo);
+          },
+          info: (message, parameters) => {},
+          warn: (message, parameters = []) => {}
+        };
+
+        // 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_adopted && x.is_managed);
+
+        devices.sort((a, b) => {
+
+          const aCase = (a.name ?? a.model).toLowerCase();
+          const bCase = (b.name ?? b.model).toLowerCase();
+
+          return aCase > bCase ? 1 : (bCase > aCase ? -1 : 0);
+        });
+
+        return [ udaApi.controller, ...devices ];
+      } catch(err) {
+
+        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", async(request) => {
+
+      try {
+
+        const optionSet = {};
+
+        // Loop through all the feature option categories.
+        for(const category of featureOptionCategories) {
+
+          optionSet[category.name] = [];
+
+          for(const options of featureOptions[category.name]) {
+
+            options.value = isOptionEnabled(request.configOptions, request.controllerUda, request.deviceUda, category.name + "." + options.name, options.default);
+            optionSet[category.name].push(options);
+          }
+        }
+
+        return { categories: featureOptionCategories, options: optionSet };
+
+      } catch(err) {
+
+        console.log(err);
+
+        // Return nothing if we error out for some reason.
+        return {};
+      }
+    });
+  }
+}
+
+(() => new PluginUiServer())();