@mp-consulting/homebridge-daikin-cloud 1.6.2 → 1.7.0

package/README.md

@@ -29,6 +29,7 @@ A [Homebridge](https://homebridge.io) plugin that integrates Daikin air conditio
   - Fan only mode (`showFanOnlyMode`)
   - Holiday (away) mode (`showHolidayMode`)
 - **Separate Fan Tile** (`showSeparateFanControl`): Expose fan speed and oscillation as a standalone Fan tile, so both stay visible even when the accessory is grouped into a single tile in the Home app
+- **Assistant (optional)**: Explains connection, login and offline-unit problems in the settings UI and suggests config changes, using the AI provider you set up in Homebridge AI Kit
 - **Firmware Updates** (`showFirmwareUpdateSwitch`): Manage gateway firmware updates from HomeKit instead of the Onecta app. The plugin logs when Daikin stages an update for your unit and exposes a "Firmware Update" switch — turn it on to install; it stays on while the update runs and the plugin logs the outcome. Not part of `showExtraFeatures`: it must be enabled explicitly, so an "all switches on" scene can never trigger an install. The unit is unavailable (and rejects commands) while it updates. The current firmware version is also shown in each accessory's HomeKit details.
 
 > **Note**: HomeKit doesn't natively support all Daikin operation modes. Extra features appear as switches in the Home app. Enable them individually in the plugin settings UI.
@@ -233,6 +234,33 @@ These errors indicate temporary issues with the Daikin Cloud servers:
 - If errors persist, the Daikin API may be experiencing extended downtime
 - Check [Daikin's status page](https://www.daikin.eu/) or try again later
 
+## Assistant
+
+The settings UI can explain problems and suggest configuration changes with the
+**Assistant**. It is off until you set up an AI provider once for all MP Consulting
+plugins in [Homebridge AI Kit](https://github.com/mp-consulting/homebridge-ai-kit)
+(or the Homebridge Glass UI): the plugin reads the shared `HomebridgeAiKit` platform
+block from `config.json` and has no AI settings of its own. When it is not set up,
+the UI looks exactly as before, with a small tip in the Settings tab.
+
+When it is enabled:
+
+- **Explain** buttons appear next to a failed connection test, a failed Mobile App
+  login, a Developer Portal login that cannot start or complete, a failed device list,
+  and every unit the Onecta cloud reports as offline. The answer streams into an
+  Assistant panel below.
+- **Describe Your Setup** (Settings tab) turns a request such as *"show the Powerful and
+  Econo switches and poll every 10 minutes"* into a configuration change, shown as a diff
+  to apply or reject. Like every other change in the Settings tab, an applied change is
+  saved straight away; restart Homebridge to use it.
+
+What is sent to the provider: the error message, the authentication method, the update
+interval, the WebSocket and HTTP transport settings, and for a unit its name, Daikin
+device ID, model, type, online flag and enabled feature switches. Your Daikin email and
+password, Client ID and Client Secret, tokens, and the callback and bind addresses are
+never sent (e-mail and IP addresses are also masked in error messages), and the
+provider's API key stays on the Homebridge server.
+
 ## Supported Devices
 
 Any device compatible with the [Daikin Onecta app](https://www.daikin.eu/en_us/product-group/control-systems/onecta/connectable-units.html), including:
@@ -266,6 +294,12 @@ npm run test:coverage
 npm run schema:check
 ```
 
+The build copies `@mp-consulting/homebridge-ui-kit` and Bootstrap Icons into
+`homebridge-ui/public/lib/` with `mp-ui-kit-copy --vendor`.
+The Assistant routes come from `@mp-consulting/homebridge-ai-core`, the slim core of
+Homebridge AI Kit (its only runtime dependency is `ajv`), so the plugin does not pull in
+the MCP SDK or socket.io.
+
 ### Code Quality
 
 This plugin uses:

package/homebridge-ui/assistant.js

@@ -0,0 +1,62 @@
+/**
+ * Assistant routes for the custom settings UI (/ai/status, /ai/explain, /ai/ask,
+ * /ai/config), from @mp-consulting/homebridge-ai-core/plugin. The provider is set up
+ * once in the shared `HomebridgeAiKit` block of config.json; its key never reaches
+ * the browser.
+ *
+ * ai-core is ESM-only and this UI server is CommonJS, so it is loaded lazily with
+ * import(). When it cannot be loaded the routes are simply missing: the UI calls
+ * /ai/status, gets an error and hides everything Assistant-related.
+ */
+
+const ASSISTANT_PLUGIN_NAME = '@mp-consulting/homebridge-daikin-cloud';
+
+/**
+ * Daikin background the Assistant gets with every request from this plugin's
+ * settings UI. Keep it short: it is sent with each prompt.
+ */
+const DAIKIN_AI_CONTEXT = [
+  'The plugin bridges Daikin air conditioners and Altherma heat pumps (climateControl and domesticHotWaterTank',
+  'management points) from the Daikin Onecta cloud to HomeKit; it never talks to the units on the LAN.',
+  'Authentication methods ("authMode"): "developer_portal" uses OAuth 2.0 with a Client ID and Client Secret from',
+  'the Daikin Developer Portal and allows 200 API calls per day; "mobile_app" logs in with the Onecta app email and',
+  'password (Gigya login at id.daikin.eu), allows 3000 calls per day and adds real-time WebSocket updates',
+  '("enableWebSocket"). Developer Portal login needs a temporary HTTPS callback server with a self-signed certificate',
+  '(the browser warns about it): the redirect URI registered in the portal must be exactly',
+  'https://<callbackServerExternalAddress>:<callbackServerPort> (default port 8582), the port must be reachable from',
+  'the browser, the bind address ("oidcCallbackServerBindAddr", default 0.0.0.0) may only be loopback when the browser',
+  'runs on the Homebridge host, and the callback server stops after 10 minutes. Tokens are stored in',
+  '.daikin-controller-cloud-tokenset (Developer Portal) or .daikin-mobile-tokenset (Mobile App) in the Homebridge',
+  'storage path. Common errors: "Unauthorized (401): Token refresh failed. Please re-authenticate." or "invalid_grant"',
+  'means the refresh token expired or was revoked, so authenticate again; "Rate limited. Retry after N seconds." (HTTP',
+  '429) means the daily or per-minute quota is used up, so raise "updateIntervalInMinutes" (15+ for Developer Portal)',
+  'or switch to Mobile App; "Bad Gateway (502)", "Service Unavailable (503)" or "Gateway Timeout (504)" with "The',
+  'Daikin API is temporarily unavailable" is a Daikin-side outage (polls back off on their own); "Device <id> is',
+  'offline (cloud connection down)" or a device shown Offline means its Wi-Fi adapter lost the Onecta cloud',
+  'connection (check power, Wi-Fi and the Onecta app); "Request to <host> failed after N attempts" (ETIMEDOUT,',
+  'ECONNRESET, ECONNREFUSED) points at the Homebridge host network: DNS, firewall, broken IPv6 or a low MTU; "returned',
+  'a non-JSON response" usually means a proxy or WAF answered instead of Daikin, and some WAFs drop Node\'s TLS',
+  'fingerprint, which "httpTransport": "curl" works around. Mobile App login errors carry the Gigya error code in',
+  'parentheses. Hidden devices are listed in "excludedDevicesByDeviceId". Never ask the user for their password,',
+  'Client Secret, tokens or API keys.',
+].join(' ');
+
+/**
+ * Adds the Assistant routes to the plugin UI server. Resolves once they are
+ * registered (or immediately when ai-core cannot be loaded).
+ *
+ * `options` is passed through to `registerAiRoutes` (tests inject a provider).
+ */
+function registerAssistant(server, options = {}) {
+  return import('@mp-consulting/homebridge-ai-core/plugin')
+    .then(({ registerAiRoutes }) => registerAiRoutes(server, {
+      pluginName: ASSISTANT_PLUGIN_NAME,
+      systemContext: DAIKIN_AI_CONTEXT,
+      ...options,
+    }))
+    .catch((error) => {
+      console.warn('[DaikinCloud] Assistant unavailable:', error.message);
+    });
+}
+
+module.exports = { ASSISTANT_PLUGIN_NAME, DAIKIN_AI_CONTEXT, registerAssistant };

package/homebridge-ui/public/index.html

@@ -82,6 +82,8 @@
                     <p class="text-muted small">Make sure you're authenticated and your Daikin devices are set up in the Onecta app.</p>
                 </div>
                 <div id="devices-error" class="alert alert-danger d-none"></div>
+                <!-- Assistant: explain the device list error (filled by script.js) -->
+                <div id="devices-problem" class="mb-3 d-none"></div>
             </div>
 
             <!-- Settings Tab -->
@@ -297,6 +299,27 @@
                         </div>
                     </div>
                 </div>
+
+                <!-- Assistant: describe your setup (shown only when the Assistant is enabled) -->
+                <div class="card mt-3 d-none" id="assistant-config-card">
+                    <div class="card-header d-flex align-items-center gap-2">
+                        <span>Describe Your Setup</span>
+                        <span id="assistant-config-badge"></span>
+                    </div>
+                    <div class="card-body">
+                        <label class="form-label" for="assistant-config-request">What should change?</label>
+                        <textarea class="form-control mb-2" id="assistant-config-request" rows="2"
+                                  placeholder="e.g. Show Powerful and Econo mode switches and poll every 10 minutes"></textarea>
+                        <div class="form-text mb-3">The Assistant suggests a configuration change for you to review. Your Daikin credentials and network addresses are never sent.</div>
+                        <div id="assistant-config-action"></div>
+                        <div id="assistant-config-result" class="mt-3"></div>
+                    </div>
+                </div>
+
+                <p id="assistant-hint" class="small text-muted mt-3 mb-0 d-none">
+                    <i class="bi bi-info-circle me-1"></i>Tip: install and enable <strong>Homebridge AI Kit</strong> to get the Assistant,
+                    which explains connection and device errors here.
+                </p>
             </div>
 
             <!-- Authentication Tab -->
@@ -347,6 +370,8 @@
                             </button>
                         </div>
                         <div id="test-result" class="alert mt-3 mb-0 d-none"></div>
+                        <!-- Assistant: explain a failed connection test (filled by script.js) -->
+                        <div id="test-problem" class="mt-2 d-none"></div>
                     </div>
                 </div>
 
@@ -371,6 +396,8 @@
                         </div>
 
                         <div id="mobile-auth-errors" class="alert alert-danger d-none"></div>
+                        <!-- Assistant: explain a failed Mobile App login (filled by script.js) -->
+                        <div id="mobile-auth-problem" class="mb-3 d-none"></div>
                         <div id="mobile-auth-success" class="alert alert-success d-none"></div>
 
                         <div class="d-flex gap-2 justify-content-end">
@@ -433,6 +460,8 @@
                             </div>
 
                             <div id="validation-errors" class="alert alert-danger d-none"></div>
+                            <!-- Assistant: explain why the login cannot start (filled by script.js) -->
+                            <div id="wizard-start-problem" class="mb-3 d-none"></div>
 
                             <div class="d-flex gap-2 justify-content-end">
                                 <button class="btn btn-outline-secondary" onclick="hideWizard()">Cancel</button>
@@ -459,6 +488,9 @@
                                 </button>
                             </div>
 
+                            <!-- Assistant: failed authorization + explanation (filled by script.js) -->
+                            <div id="wizard-auth-problem" class="mb-3 d-none"></div>
+
                             <!-- Automatic callback status -->
                             <div id="callback-server-status" class="d-none">
                                 <div class="alert alert-success">