@mp-consulting/homebridge-unifi-access 1.0.0

package/eslint.config.mjs

@@ -0,0 +1,99 @@
+/* Copyright(C) 2026, Mickael Palma. All rights reserved.
+ *
+ * eslint.config.mjs: Linting defaults for Homebridge plugins.
+ */
+import eslintJs from "@eslint/js";
+import hbPluginUtils from "homebridge-plugin-utils/build/eslint-rules.mjs";
+import ts from "typescript-eslint";
+import tsParser from "@typescript-eslint/parser";
+
+export default ts.config(
+
+  { ignores: ["dist"] },
+
+  eslintJs.configs.recommended,
+
+  {
+
+    files: ["src/**.ts"],
+    rules: {
+
+      ...hbPluginUtils.rules.ts
+    }
+  },
+
+  {
+
+    files: [ "homebridge-ui/public/**/*.js", "homebridge-ui/server.js", "eslint.config.mjs" ],
+    rules: {
+
+      ...hbPluginUtils.rules.js
+    }
+  },
+
+  {
+
+    files: [ "src/**.ts", "homebridge-ui/*.js", "homebridge-ui/public/**/*.js", "eslint.config.mjs" ],
+
+    languageOptions: {
+
+      ecmaVersion: "latest",
+      parser: tsParser,
+      parserOptions: {
+
+        ecmaVersion: "latest",
+
+        projectService: {
+
+          allowDefaultProject: [ "eslint.config.mjs", "homebridge-ui/*.js", "homebridge-ui/public/*.js", "homebridge-ui/public/modules/*.js" ],
+          defaultProject: "./tsconfig.json",
+          maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 20 // eslint-disable-line camelcase
+        }
+      },
+
+      sourceType: "module"
+    },
+
+    linterOptions: {
+
+      reportUnusedDisableDirectives: "error"
+    },
+
+    plugins: {
+
+      ...hbPluginUtils.plugins
+    },
+
+    rules: {
+
+      ...hbPluginUtils.rules.common
+    }
+  },
+
+  {
+
+    files: [ "homebridge-ui/public/*.js", "homebridge-ui/public/modules/*.js" ],
+
+    languageOptions: {
+
+      globals: {
+
+        ...hbPluginUtils.globals.ui
+      }
+    }
+  },
+
+  {
+
+    files: ["homebridge-ui/server.js"],
+
+    languageOptions: {
+
+      globals: {
+
+        console: "readonly",
+        fetch: "readonly"
+      }
+    }
+  }
+);

package/homebridge-ui/public/app.js

@@ -0,0 +1,104 @@
+/* @mp-consulting/homebridge-unifi-access Custom UI. */
+import { $, showScreen } from "./modules/dom-helpers.js";
+import { getControllers, state } from "./modules/state.js";
+import { handleSetupSubmit, openAddController, renderControllers } from "./modules/controllers.js";
+import { PLUGIN_NAME } from "./modules/constants.js";
+import { handleDiscover } from "./modules/discovery.js";
+import { renderOptions } from "./modules/feature-options.js";
+
+// Search & toolbar.
+let searchTimeout = null;
+
+$("optionsSearch").addEventListener("input", () => {
+
+
+  clearTimeout(searchTimeout);
+  searchTimeout = setTimeout(() => renderOptions(), 300);
+});
+
+$("clearSearchBtn").addEventListener("click", () => {
+
+
+  $("optionsSearch").value = "";
+  renderOptions();
+});
+
+$("scopeSelect").addEventListener("change", () => renderOptions());
+$("modifiedOnlyToggle").addEventListener("change", () => renderOptions());
+
+// Event listeners.
+$("discoverBtn").addEventListener("click", handleDiscover);
+$("manualEntryBtn").addEventListener("click", () => openAddController());
+$("cancelDiscoveryBtn").addEventListener("click", () => {
+
+
+  showScreen("controllersScreen");
+  renderControllers();
+});
+$("addControllerBtn").addEventListener("click", () => {
+
+
+  if(getControllers().length) {
+
+
+    showScreen("discoveryScreen");
+    $("cancelDiscoveryBtn").style.display = "inline-block";
+  } else {
+
+
+    showScreen("discoveryScreen");
+  }
+});
+$("setupForm").addEventListener("submit", handleSetupSubmit);
+$("cancelSetupBtn").addEventListener("click", () => {
+
+
+  if(getControllers().length) {
+
+
+    showScreen("controllersScreen");
+    renderControllers();
+  } else {
+
+
+    showScreen("discoveryScreen");
+  }
+});
+$("backFromOptionsBtn").addEventListener("click", () => {
+
+
+  showScreen("controllersScreen");
+  renderControllers();
+});
+$("backFromSupportBtn").addEventListener("click", () => {
+
+
+  showScreen("controllersScreen");
+  renderControllers();
+});
+$("supportBtn").addEventListener("click", () => showScreen("supportScreen"));
+
+// Initialization.
+state.pluginConfig = await homebridge.getPluginConfig();
+
+if(!state.pluginConfig.length) {
+
+
+  state.pluginConfig = [{ name: PLUGIN_NAME }];
+  await homebridge.updatePluginConfig(state.pluginConfig);
+}
+
+state.pluginConfig[0].name ||= PLUGIN_NAME;
+
+// Show the right screen.
+if(getControllers().length) {
+
+
+  showScreen("controllersScreen");
+  renderControllers();
+} else {
+
+
+  showScreen("discoveryScreen");
+  $("cancelDiscoveryBtn").style.display = "none";
+}

package/homebridge-ui/public/index.html

@@ -0,0 +1,267 @@
+<link rel="stylesheet" href="styles.css">
+
+<div id="app" class="container">
+  <div class="text-center mb-3">
+    <img src="https://raw.githubusercontent.com/mp-consulting/homebridge-unifi-access/main/docs/media/homebridge-unifi-access.svg" alt="homebridge-unifi-access logo" style="max-width: 200px;" />
+    <hr>
+  </div>
+
+  <!-- Screen: Discovery -->
+  <div id="discoveryScreen">
+    <h5><i class="fas fa-search"></i> Discover Your Controller</h5>
+    <p class="text-muted">Scan your network for UniFi Access controllers, or enter the address manually.</p>
+
+    <div class="alert alert-info mb-3">
+      <i class="fas fa-info-circle"></i> Ensure your UniFi console is powered on and connected to the same network.
+    </div>
+
+    <div class="row g-2 mb-3">
+      <div class="col-12">
+        <button id="discoverBtn" class="btn btn-secondary">
+          <span id="discoverSpinner" class="spinner-border spinner-border-sm" style="display: none;"></span>
+          <span id="discoverBtnText"><i class="fas fa-search"></i> Discover Controllers</span>
+        </button>
+        <button id="manualEntryBtn" class="btn btn-outline-primary">
+          <i class="fas fa-keyboard"></i> Manual Entry
+        </button>
+        <button id="cancelDiscoveryBtn" class="btn btn-primary" style="display: none;">Cancel</button>
+      </div>
+    </div>
+
+    <div id="deviceList" style="display: none;">
+      <div id="deviceListContainer"></div>
+    </div>
+  </div>
+
+  <!-- Screen: Setup Controller (Add/Edit) -->
+  <div id="setupScreen">
+    <h5><i class="fas fa-shield-alt"></i> <span id="setupTitle">Add UniFi Access Controller</span></h5>
+    <p class="text-muted" id="setupSubtitle">Enter your UniFi Access controller details and login credentials.</p>
+
+    <form id="setupForm" novalidate>
+      <div class="mb-3 row">
+        <label for="inputAddress" class="col-sm-3 col-form-label"><i class="fas fa-server"></i> Controller</label>
+        <div class="col-sm-9">
+          <input type="text" class="form-control" id="inputAddress" placeholder="Hostname or IP (e.g. unvr.local)" required>
+          <small class="form-text text-muted">The address of your UniFi Access controller.</small>
+        </div>
+      </div>
+      <div class="mb-3 row">
+        <label for="inputUsername" class="col-sm-3 col-form-label"><i class="fas fa-user"></i> Username</label>
+        <div class="col-sm-9">
+          <input type="text" class="form-control" id="inputUsername" autocomplete="username" placeholder="Local user account username" required>
+        </div>
+      </div>
+      <div class="mb-3 row">
+        <label for="inputPassword" class="col-sm-3 col-form-label"><i class="fas fa-lock"></i> Password</label>
+        <div class="col-sm-9">
+          <input type="password" class="form-control" id="inputPassword" autocomplete="current-password" placeholder="Local user account password" required>
+        </div>
+      </div>
+
+      <div id="setupError" class="alert alert-danger" style="display: none;">
+        <i class="fas fa-exclamation-circle"></i> <span id="setupErrorText"></span>
+      </div>
+
+      <div class="alert alert-info">
+        <i class="fas fa-info-circle"></i>
+        <strong>Local account required.</strong> Ubiquiti.com/UI.com accounts are not supported. Create one via the <em>Admins & Users</em> tab in your UniFi console.
+      </div>
+
+      <hr>
+      <div class="col-12">
+        <button id="saveControllerBtn" class="btn btn-success" type="submit">
+          <i class="fas fa-save"></i> Save Controller
+        </button>
+        <button id="cancelSetupBtn" class="btn btn-secondary" type="button">Cancel</button>
+      </div>
+    </form>
+  </div>
+
+  <!-- Screen: Controllers List (Main) -->
+  <div id="controllersScreen">
+    <h5><i class="fas fa-network-wired"></i> Configured Controllers</h5>
+    <div id="noControllersMessage" class="alert alert-info mb-3">
+      <i class="fas fa-info-circle"></i> No controllers configured yet. Add one to get started.
+    </div>
+    <ul id="controllersList" class="list-group mb-3"></ul>
+    <div class="d-flex gap-2">
+      <button id="addControllerBtn" class="btn btn-primary">
+        <i class="fas fa-plus"></i> Add Controller
+      </button>
+      <button id="supportBtn" class="btn btn-outline-secondary">
+        <i class="fas fa-life-ring"></i> Support
+      </button>
+    </div>
+  </div>
+
+  <!-- Screen: Feature Options (split layout) -->
+  <div id="featureOptionsScreen">
+    <div class="d-flex justify-content-between align-items-center mb-3">
+      <h5 class="mb-0"><i class="fas fa-sliders-h"></i> Feature Options</h5>
+      <button id="backFromOptionsBtn" class="btn btn-secondary btn-sm">
+        <i class="fas fa-arrow-left"></i> Back
+      </button>
+    </div>
+
+    <div class="row">
+      <!-- Left sidebar: scope -->
+      <div class="col-sm-4">
+        <div class="scope-sidebar">
+          <!-- Scope selector -->
+          <div class="card mb-3">
+            <div class="card-body py-2">
+              <label class="form-label mb-1 text-muted"><small><i class="fas fa-layer-group"></i> Scope</small></label>
+              <select class="form-select form-select-sm" id="scopeSelect"></select>
+            </div>
+          </div>
+
+          <!-- Visual cascade -->
+          <div class="card mb-3">
+            <div class="card-body py-3" id="scopeCascade">
+              <div class="scope-cascade">
+                <div class="scope-level" data-scope="global">
+                  <div class="scope-dot"><i class="fas fa-globe-americas"></i></div>
+                  <div class="scope-text">
+                    <div class="scope-label">Global</div>
+                    <div class="scope-hint">All devices</div>
+                  </div>
+                </div>
+                <div class="scope-connector"><div class="scope-connector-line"></div></div>
+                <div class="scope-level" data-scope="controller">
+                  <div class="scope-dot"><i class="fas fa-server"></i></div>
+                  <div class="scope-text">
+                    <div class="scope-label">Controller</div>
+                    <div class="scope-hint">Overrides global</div>
+                  </div>
+                </div>
+                <div class="scope-connector"><div class="scope-connector-line"></div></div>
+                <div class="scope-level" data-scope="device">
+                  <div class="scope-dot"><i class="fas fa-microchip"></i></div>
+                  <div class="scope-text">
+                    <div class="scope-label">Device</div>
+                    <div class="scope-hint">Final value</div>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <!-- Device info panel -->
+          <div id="deviceInfoPanel" class="card mb-3" style="display: none;">
+            <div class="card-body py-2">
+              <div class="mb-2"><small class="text-muted d-block">Model</small><strong id="infoModel"></strong></div>
+              <div class="mb-2"><small class="text-muted d-block">MAC</small><code id="infoMac" style="font-size:0.75rem"></code></div>
+              <div class="mb-2"><small class="text-muted d-block">IP</small><code id="infoIp"></code></div>
+              <div><small class="text-muted d-block">Status</small><span id="infoStatus"></span></div>
+            </div>
+          </div>
+
+          <!-- Legend -->
+          <div class="card mb-3">
+            <div class="card-body py-2">
+              <small class="text-muted d-block mb-2"><i class="fas fa-palette"></i> Legend</small>
+              <div class="d-flex flex-column gap-1" style="font-size: 0.75rem;">
+                <div class="d-flex align-items-center gap-2">
+                  <span class="scope-legend-bar" style="background: #ffc107;"></span> Set at global
+                </div>
+                <div class="d-flex align-items-center gap-2">
+                  <span class="scope-legend-bar" style="background: #198754;"></span> Set at controller
+                </div>
+                <div class="d-flex align-items-center gap-2">
+                  <span class="scope-legend-bar" style="background: #0dcaf0;"></span> Set at device
+                </div>
+              </div>
+            </div>
+          </div>
+
+        </div>
+      </div>
+
+      <!-- Right main: options -->
+      <div class="col-sm-8">
+        <!-- Search & filter -->
+        <div class="d-flex align-items-center gap-2 mb-3">
+          <div class="input-group flex-grow-1">
+            <span class="input-group-text"><i class="fas fa-search"></i></span>
+            <input type="text" class="form-control" placeholder="Search options..." id="optionsSearch">
+            <button class="btn btn-outline-secondary" type="button" id="clearSearchBtn"><i class="fas fa-times"></i></button>
+          </div>
+          <div class="form-check form-switch mb-0 flex-shrink-0" style="min-width: 110px;">
+            <input class="form-check-input" type="checkbox" id="modifiedOnlyToggle">
+            <label class="form-check-label text-muted text-nowrap" for="modifiedOnlyToggle"><small>Modified <span id="modifiedSummary"></span></small></label>
+          </div>
+        </div>
+
+        <!-- Loading -->
+        <div id="optionsLoading" class="text-center my-4">
+          <div class="spinner-border text-primary" role="status">
+            <span class="visually-hidden">Loading...</span>
+          </div>
+          <p class="mt-2 text-muted">Loading options...</p>
+        </div>
+
+        <!-- Options container -->
+        <div id="optionsContainer" class="mb-3"></div>
+
+        <!-- Unsaved changes notice -->
+        <div class="alert alert-warning mb-3" id="unsavedChanges" style="display: none;">
+          <i class="fas fa-exclamation-triangle"></i> You have unsaved changes. Click <strong>Save</strong> in Homebridge to apply.
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Screen: Support -->
+  <div id="supportScreen">
+    <div class="d-flex justify-content-between align-items-center mb-3">
+      <h5 class="mb-0"><i class="fas fa-life-ring"></i> Support</h5>
+      <button id="backFromSupportBtn" class="btn btn-secondary btn-sm">
+        <i class="fas fa-arrow-left"></i> Back
+      </button>
+    </div>
+
+    <div class="card mb-3">
+      <div class="card-header bg-transparent"><i class="fas fa-heart"></i> About This Plugin</div>
+      <div class="card-body">
+        <p class="card-text mb-0">If you find this plugin useful, please consider <a target="_blank" href="https://github.com/mp-consulting/homebridge-unifi-access">starring the project on GitHub</a>.</p>
+      </div>
+    </div>
+
+    <div class="card mb-3">
+      <div class="card-header bg-transparent"><i class="fas fa-book"></i> Getting Started</div>
+      <div class="list-group list-group-flush">
+        <a href="https://github.com/mp-consulting/homebridge-unifi-access/blob/main/README.md#installation" target="_blank" class="list-group-item list-group-item-action">
+          <i class="fas fa-download text-primary"></i> <strong>Installation</strong>
+          <small class="text-muted d-block">Installing this plugin, including system requirements.</small>
+        </a>
+        <a href="https://github.com/mp-consulting/homebridge-unifi-access/blob/main/docs/FeatureOptions.md" target="_blank" class="list-group-item list-group-item-action">
+          <i class="fas fa-sliders-h text-primary"></i> <strong>Feature Options</strong>
+          <small class="text-muted d-block">Granular options to configure at a controller or device level.</small>
+        </a>
+        <a href="https://github.com/mp-consulting/homebridge-unifi-access/blob/main/docs/MQTT.md" target="_blank" class="list-group-item list-group-item-action">
+          <i class="fas fa-broadcast-tower text-primary"></i> <strong>MQTT</strong>
+          <small class="text-muted d-block">How to configure MQTT support.</small>
+        </a>
+        <a href="https://github.com/mp-consulting/homebridge-unifi-access/blob/main/CHANGELOG.md" target="_blank" class="list-group-item list-group-item-action">
+          <i class="fas fa-history text-primary"></i> <strong>Changelog</strong>
+          <small class="text-muted d-block">Changes and release history.</small>
+        </a>
+      </div>
+    </div>
+
+    <div class="card mb-3">
+      <div class="card-header bg-transparent"><i class="fas fa-life-ring"></i> Get Help</div>
+      <div class="list-group list-group-flush">
+        <a href="https://discord.gg/QXqfHEW" target="_blank" class="list-group-item list-group-item-action">
+          <i class="fab fa-discord text-primary"></i> <strong>Discord Support Channel</strong>
+        </a>
+        <a href="https://github.com/mp-consulting/homebridge-unifi-access/issues/new/choose" target="_blank" class="list-group-item list-group-item-action">
+          <i class="fab fa-github text-primary"></i> <strong>Create a Developer Support Request</strong>
+        </a>
+      </div>
+    </div>
+  </div>
+</div>
+
+<script type="module" src="app.js"></script>

package/homebridge-ui/public/modules/constants.js

@@ -0,0 +1,22 @@
+export const SCREENS = [ "discoveryScreen", "setupScreen", "controllersScreen", "featureOptionsScreen", "supportScreen" ];
+export const PLUGIN_NAME = "UniFi Access";
+
+export const CATEGORY_ICONS = {
+
+
+  AccessMethod: "fa-fingerprint",
+  Controller: "fa-server",
+  Device: "fa-microchip",
+  Hub: "fa-door-open",
+  Log: "fa-file-alt"
+};
+
+export const CATEGORY_COLORS = {
+
+
+  AccessMethod: "#fd7e14",
+  Controller: "#6f42c1",
+  Device: "#0d6efd",
+  Hub: "#20c997",
+  Log: "#6c757d"
+};