From dd47c4a1a9fc104397f123bf677056d57d40dbab Mon Sep 17 00:00:00 2001
From: Claude Fable 5 <noreply@anthropic.com>
Date: Tue, 28 Jul 2026 16:20:39 +0200
Subject: [PATCH] feat(web): install devices by mDNS name, warn to reserve raw
 IPs

The setup wizard showed a discovered device's mDNS hostname in the scan
table but always bound the raw IP into the driver config. Prefer the
self-broadcast .local name when the device advertises one, so the
connection survives DHCP lease changes; other reverse-DNS names stay
display-only since resolving them depends on the router.

When the configured host is an IP literal, a live hint under the host
field now tells the operator to reserve that IP for the device in the
router's DHCP settings. The Settings device help texts carry the same
advice.

Co-authored-by: HuggeK <48095810+HuggeK@users.noreply.github.com>
---
 .changeset/mdns-first-device-install.md |  9 +++
 web/settings/tabs/devices.js            |  4 +-
 web/setup.html                          | 23 ++++++-
 web/setup.js                            | 82 ++++++++++++++++++++-----
 web/setup.test.mjs                      | 23 +++++++
 5 files changed, 122 insertions(+), 19 deletions(-)
 create mode 100644 .changeset/mdns-first-device-install.md

diff --git a/.changeset/mdns-first-device-install.md b/.changeset/mdns-first-device-install.md
new file mode 100644
index 00000000..0cfb9253
--- /dev/null
+++ b/.changeset/mdns-first-device-install.md
@@ -0,0 +1,9 @@
+---
+"ftw": patch
+---
+
+The setup wizard now installs a discovered device by its self-broadcast mDNS
+(.local) name instead of its raw IP when the device advertises one, so the
+connection survives DHCP lease changes. When only an IP address is used, the
+wizard and device settings now tell the operator to reserve that IP for the
+device in the router's DHCP settings.
diff --git a/web/settings/tabs/devices.js b/web/settings/tabs/devices.js
index 07218ec1..9fef2bdb 100644
--- a/web/settings/tabs/devices.js
+++ b/web/settings/tabs/devices.js
@@ -80,7 +80,7 @@
         if (modbus) {
           html += '<fieldset><legend>Modbus TCP</legend>' +
             '<div class="field-row"><div>' +
-            '<label>Host ' + help('IP of the Modbus-TCP device (e.g. Sungrow inverter LAN port).') + '</label>' +
+            '<label>Host ' + help('IP or hostname of the Modbus-TCP device (e.g. Sungrow inverter LAN port). If you use a raw IP, reserve it for the device in your router\'s DHCP settings so it can\'t change.') + '</label>' +
             '<input type="text" data-path="drivers.' + idx + '.capabilities.modbus.host" value="' + escHtml(modbus.host) + '">' +
             '</div><div>' +
             '<label>Port</label><input type="number" data-path="drivers.' + idx + '.capabilities.modbus.port" value="' + (modbus.port || 502) + '">' +
@@ -145,7 +145,7 @@
           // post-render DOM edit mirrors the site-meter pattern above
           // and avoids a re-render race with the async catalog fetch.
           html += '<fieldset><legend>HTTP</legend>' +
-            '<label>Host / IP ' + help('Hostname (e.g. zap.local) or IP address of the device. mDNS names work when your OS resolver supports them; otherwise use the LAN IP.') + '</label>' +
+            '<label>Host / IP ' + help('Hostname (e.g. zap.local) or IP address of the device. Prefer the device\'s mDNS (.local) name when it broadcasts one — it survives DHCP lease changes. If you use a raw IP, reserve it for the device in your router\'s DHCP settings so it can\'t change.') + '</label>' +
             '<input type="text" data-path="drivers.' + idx + '.config.host" value="' + escHtml(lcfg.host || '') + '" placeholder="zap.local">' +
             '<div class="drv-local-creds" data-drv-lua="' + escHtml(d.lua || '') + '"' + (localCreds ? '' : ' hidden') + '>' +
               '<label style="margin-top:8px">Username ' + help('Username for the device\'s local API (HTTP Basic auth). For NIBE this is the local-API account you set up in the myUplink app.') + '</label>' +
diff --git a/web/setup.html b/web/setup.html
index c99ab597..5c4c92f7 100644
--- a/web/setup.html
+++ b/web/setup.html
@@ -353,6 +353,21 @@
       margin: 1rem 0;
     }
 
+    /* ---- Host addressing hint (mDNS name vs fixed IP) ---- */
+    .host-hint {
+      margin: 0 0 1rem;
+      padding: 10px 12px;
+      background: var(--ink-raised);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      font-size: 0.78rem;
+      color: var(--fg-dim);
+      line-height: 1.5;
+    }
+
+    .host-hint.mdns { border-color: color-mix(in srgb, var(--green-e) 45%, var(--line)); }
+    .host-hint.dhcp { border-color: color-mix(in srgb, var(--yellow) 55%, var(--line)); }
+
     /* ---- Driver picker ---- */
     .driver-desc {
       margin-top: 0.5rem;
@@ -595,8 +610,8 @@ <h2>Find devices</h2>
     <div id="manual-ip-form" style="display:none">
       <div class="form-row">
         <div class="form-group">
-          <label for="manual-ip">IP address</label>
-          <input type="text" id="manual-ip" placeholder="192.168.1.10">
+          <label for="manual-ip">IP address or hostname</label>
+          <input type="text" id="manual-ip" placeholder="192.168.1.10 or inverter.local">
         </div>
         <div class="form-group">
           <label for="manual-port">Port</label>
@@ -644,7 +659,7 @@ <h2>Configure driver</h2>
 
     <div class="form-row">
       <div class="form-group">
-        <label for="drv-ip">IP address</label>
+        <label for="drv-ip">IP address or hostname</label>
         <input type="text" id="drv-ip" placeholder="192.168.1.10">
       </div>
       <div class="form-group">
@@ -653,6 +668,8 @@ <h2>Configure driver</h2>
       </div>
     </div>
 
+    <p class="host-hint" id="drv-host-hint" style="display:none"></p>
+
     <div class="form-group" id="drv-unitid-group">
       <label for="drv-unitid">Unit ID (Modbus)</label>
       <input type="number" id="drv-unitid" value="1" min="0" max="255">
diff --git a/web/setup.js b/web/setup.js
index c1fc6fbf..dbf2e33c 100644
--- a/web/setup.js
+++ b/web/setup.js
@@ -9,7 +9,7 @@
 
   // Collected state
   var configuredDrivers = [];    // array of driver objects ready for config.drivers
-  var selectedDevice = null;     // { ip, port, protocol } from scan or manual entry
+  var selectedDevice = null;     // { ip, port, protocol, hostname } from scan or manual entry
   var selectedCatalog = null;    // CatalogEntry from /api/drivers/catalog
   var driverCatalog = [];        // full catalog cache
 
@@ -95,7 +95,7 @@
             '<td>' + identity + '</td>' +
             '<td><button class="btn-use">Use this device</button></td>';
           tr.querySelector('.btn-use').addEventListener('click', function () {
-            useScanDevice(d.ip, d.port, proto, match && match.driver);
+            useScanDevice(d, proto, match && match.driver);
           });
           tbody.appendChild(tr);
         });
@@ -112,16 +112,22 @@
     document.getElementById('manual-ip-toggle').style.display = 'none';
   };
 
-  function useScanDevice(ip, port, protocol, matchedFilename) {
-    selectedDevice = { ip: ip, port: port, protocol: protocol, matchedFilename: matchedFilename || '' };
+  function useScanDevice(dev, protocol, matchedFilename) {
+    selectedDevice = {
+      ip: dev.ip,
+      port: dev.port,
+      protocol: protocol,
+      hostname: dev.hostname || '',
+      matchedFilename: matchedFilename || ''
+    };
     goStep(4);
   }
 
   window.useManualDevice = function () {
-    var ip = document.getElementById('manual-ip').value.trim();
+    var host = document.getElementById('manual-ip').value.trim();
     var port = parseInt(document.getElementById('manual-port').value, 10) || 502;
-    if (!ip) return;
-    selectedDevice = { ip: ip, port: port, protocol: guessProtocol(port) };
+    if (!host) return;
+    selectedDevice = { ip: host, port: port, protocol: guessProtocol(port), hostname: '' };
     goStep(4);
   };
 
@@ -241,9 +247,15 @@
     document.getElementById('drv-name').value = name;
 
     if (selectedDevice) {
-      document.getElementById('drv-ip').value = selectedDevice.ip;
+      // Prefer the device's self-broadcast mDNS (.local) name over the raw
+      // IP: the name follows the device across DHCP lease changes, the IP
+      // doesn't. Other reverse-DNS names stay display-only — resolving them
+      // at runtime depends on the router, so the IP is the safer default.
+      var host = isMDNSName(selectedDevice.hostname) ? selectedDevice.hostname : selectedDevice.ip;
+      document.getElementById('drv-ip').value = host;
       document.getElementById('drv-port').value = selectedDevice.port;
     }
+    updateHostHint();
 
     // Show/hide unit ID for modbus
     var isModbus = !selectedCatalog.protocols || selectedCatalog.protocols.length === 0 ||
@@ -290,11 +302,51 @@
     });
   }
 
+  // A self-broadcast mDNS name (RFC 6762 .local). Only these are safe to
+  // prefer over the IP — any other hostname needs the router's DNS to
+  // resolve, which FTW can't verify from here.
+  function isMDNSName(host) {
+    return /\.local\.?$/i.test(host || '');
+  }
+
+  function isIPv4Literal(host) {
+    return /^\d{1,3}(\.\d{1,3}){3}$/.test(host || '');
+  }
+
+  // Addressing hint under the host field: a .local name survives DHCP
+  // lease changes; a raw IP only stays valid if the operator reserves it
+  // for the device in the router's DHCP pool. Tracks user edits live.
+  function updateHostHint() {
+    var el = document.getElementById('drv-host-hint');
+    var input = document.getElementById('drv-ip');
+    if (!el || !input) return;
+    var host = input.value.trim();
+    el.style.display = 'none';
+    el.className = 'host-hint';
+    if (isMDNSName(host)) {
+      var discovered = '';
+      if (selectedDevice && selectedDevice.ip &&
+          host.toLowerCase() === (selectedDevice.hostname || '').toLowerCase()) {
+        discovered = ' (discovered at ' + selectedDevice.ip + ')';
+      }
+      el.textContent = 'Connecting by the device’s mDNS name' + discovered +
+        ' — it keeps working even if your router assigns the device a new IP address.';
+      el.className = 'host-hint mdns';
+      el.style.display = 'block';
+    } else if (isIPv4Literal(host)) {
+      el.textContent = 'No mDNS (.local) name in use — FTW will connect to this fixed IP address. ' +
+        'Reserve it for the device in your router’s DHCP settings so a new ' +
+        'DHCP lease can’t move the device and break the connection.';
+      el.className = 'host-hint dhcp';
+      el.style.display = 'block';
+    }
+  }
+
   window.saveDriver = function () {
     var name = document.getElementById('drv-name').value.trim();
     if (!name) { alert('Driver name is required.'); return; }
 
-    var ip = document.getElementById('drv-ip').value.trim();
+    var host = document.getElementById('drv-ip').value.trim();
     var port = parseInt(document.getElementById('drv-port').value, 10);
     var unitId = parseInt(document.getElementById('drv-unitid').value, 10) || 1;
     var isSiteMeter = document.getElementById('drv-site-meter').checked;
@@ -310,7 +362,7 @@
       ? (parseFloat(document.getElementById('drv-battery-kwh').value) || 0)
       : 0;
 
-    if (!ip) { alert('IP address is required.'); return; }
+    if (!host) { alert('IP address or hostname is required.'); return; }
 
     // Determine protocol from catalog entry
     var protocol = 'modbus';
@@ -336,11 +388,11 @@
     }
 
     if (protocol === 'modbus') {
-      driver.capabilities.modbus = { host: ip, port: port, unit_id: unitId };
+      driver.capabilities.modbus = { host: host, port: port, unit_id: unitId };
     } else if (protocol === 'mqtt') {
-      driver.capabilities.mqtt = { host: ip, port: port };
+      driver.capabilities.mqtt = { host: host, port: port };
     } else if (protocol === 'http') {
-      driver.capabilities.http = { allowed_hosts: [ip] };
+      driver.capabilities.http = { allowed_hosts: [host] };
       // connection_defaults.host is declared only by drivers that take a
       // user-configurable local endpoint — seed config.host from the IP the
       // user just entered. Cloud drivers (Easee etc.) declare http_hosts
@@ -353,7 +405,7 @@
       // Cloud drivers don't declare it and key off email/password.
       if (Object.prototype.hasOwnProperty.call(connDefaults, 'host')) {
         driver.config = driver.config || {};
-        driver.config.host = ip;
+        driver.config.host = host;
       }
     }
 
@@ -784,6 +836,8 @@
     return n;
   }
 
+  document.getElementById('drv-ip').addEventListener('input', updateHostHint);
+
   renderDots();
   goStep(initialStep());
 })();
diff --git a/web/setup.test.mjs b/web/setup.test.mjs
index 606b48bc..9249f166 100644
--- a/web/setup.test.mjs
+++ b/web/setup.test.mjs
@@ -137,3 +137,26 @@ describe("price provider defaults", () => {
     assert.match(PRICE_JS, /\["sourceful", "elprisetjustnu", "entsoe", "none"\], "sourceful"/);
   });
 });
+
+describe("setup wizard — mDNS-first device addressing", () => {
+  it("carries the discovered hostname into the selected device", () => {
+    assert.match(JS, /hostname:\s*dev\.hostname/,
+      "useScanDevice must not drop the scan's mDNS/DNS hostname");
+  });
+
+  it("prefers a self-broadcast .local name over the raw IP when prefilling", () => {
+    assert.match(JS, /isMDNSName\(selectedDevice\.hostname\)\s*\?\s*selectedDevice\.hostname\s*:\s*selectedDevice\.ip/,
+      "the host field must prefill the mDNS name when the device broadcasts one");
+    assert.match(JS, /\\\.local\\\.\?\$/,
+      "only RFC 6762 .local names qualify — other DNS names depend on the router");
+  });
+
+  it("tells the operator to reserve a raw IP in the router's DHCP pool", () => {
+    assert.match(HTML, /id=["']drv-host-hint["']/,
+      "the addressing hint element must exist under the host field");
+    assert.match(JS, /Reserve it for the device in your router/,
+      "an IP-literal host must surface the DHCP-reservation warning");
+    assert.match(JS, /addEventListener\(['"]input['"],\s*updateHostHint\)/,
+      "the hint must track manual edits of the host field");
+  });
+});