From 2944d3d160c81b2f96d10e2fbfaaf0162d5a5f44 Mon Sep 17 00:00:00 2001
From: Matthias Jobst <matthias.jobst@gmx.net>
Date: Thu, 25 Jun 2026 21:16:53 +0200
Subject: [PATCH 1/8] Add Somfy Links tab for shade-to-shade and remote linking

Introduce a dedicated "Links" subtab under Somfy that consolidates all
linking actions: pick a source shade, view its linked shades/remotes
(app shades shown by name), add a link to another app shade via a
dropdown, link a physical remote via the press-a-remote flow, and unlink
any entry. The Shades editor keeps its linked-remotes list display but no
longer hosts the Link Remote button.

WebShades: honor SomfyShade::linkRemote's return value so a full
linked-remote table reports an error instead of silently no-opping, and
stop double-sending the response on the error branches.

Web assets: shared .info-text size class; cache-bust bumped to v0.7.1h.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 data/index.html        |  43 ++++++++---
 data/somfy.js          | 158 +++++++++++++++++++++++++++++++++++++----
 data/widgets.css       |  19 +++++
 main/web/WebShades.cpp |  21 +++---
 4 files changed, 208 insertions(+), 33 deletions(-)

diff --git a/data/index.html b/data/index.html
index b39c8838..4c585521 100644
--- a/data/index.html
+++ b/data/index.html
@@ -8,9 +8,9 @@
     <meta name="apple-mobile-web-app-title" content="ESPSomfy RTS App">
     <meta name="apple-mobile-web-app-status-bar-style" content="black">
 
-    <link rel="stylesheet" href="main.css?v=v0.7.1a" type="text/css" />
-    <link rel="stylesheet" href="widgets.css?v=v0.7.1a" type="text/css" />
-    <link rel="stylesheet" href="icons.css?v=v0.7.1a" type="text/css" />
+    <link rel="stylesheet" href="main.css?v=v0.7.1h" type="text/css" />
+    <link rel="stylesheet" href="widgets.css?v=v0.7.1h" type="text/css" />
+    <link rel="stylesheet" href="icons.css?v=v0.7.1h" type="text/css" />
     <link rel="icon" type="image/png" href="favicon.png" />
 
     <!-- iPad retina icon -->
@@ -115,14 +115,14 @@
 
 
     <script type="text/javascript" src="qrcode.min.js"></script>
-    <script type="text/javascript" src="index.js?v=v0.7.1a"></script>
+    <script type="text/javascript" src="index.js?v=v0.7.1h"></script>
     <script type="text/javascript">
     // Cache-bust query appended to every versioned asset (CSS + scripts). It is the
     // app version plus a trailing asset-revision letter (e.g. v0.6.1a) so it stays
     // distinct from the firmware/application version. bump_version.sh resets every
     // version query token in this file to "<tag>a" on release; between releases bump
     // the letter by hand (a→b→c) when iterating on assets, then reflash the data partition.
-    window.assetVer = '?v=v0.7.1a';
+    window.assetVer = '?v=v0.7.1h';
     // Load remaining scripts one at a time so the ESP32 never receives
     // more than one file request simultaneously. The browser's preload
     // scanner would otherwise fetch all <script src> tags in parallel,
@@ -498,7 +498,7 @@ <h1 style="text-align: center;">
                     </div>
                 </div>
                 <div id="divSomfySettings" style="display:none;">
-                    <div class="subtab-container"><span class="selected" data-grpid="divSomfyRooms">Rooms</span><span class="" data-grpid="divSomfyMotors">Shades</span><span data-grpid="divSomfyGroups">Groups</span><span data-grpid="divRepeater">Repeater</span><span class="tabname-virtual-remote" data-grpid="divVirtualRemote"></span></div>
+                    <div class="subtab-container"><span class="selected" data-grpid="divSomfyRooms">Rooms</span><span class="" data-grpid="divSomfyMotors">Shades</span><span data-grpid="divSomfyGroups">Groups</span><span data-grpid="divSomfyLinks">Links</span><span data-grpid="divRepeater">Repeater</span><span class="tabname-virtual-remote" data-grpid="divVirtualRemote"></span></div>
                     <div id="divSomfyRooms" class="subtab-content" style="padding-top:10px;">
                         <div id="divRoomListContainer">
                             <div style="font-size:.8em;">Drag each item to set the order in which they appear in the list.</div>
@@ -747,9 +747,6 @@ <h1 style="text-align: center;">
                             <hr />
                             <div id="divLinkedRemoteList"></div>
                             <div class="button-container">
-                                <button id="btnLinkRemote" type="button" onclick="somfy.linkRemote(parseInt(document.getElementById('spanShadeId').innerText, 10));">
-                                    Link Remote
-                                </button>
                                 <button id="btnBtnShadeGoBack" type="button" onclick="somfy.showEditShade(false);">
                                     Done
                                 </button>
@@ -845,6 +842,34 @@ <h1 style="text-align: center;">
                         </div>
 
                     </div>
+                    <div id="divSomfyLinks" class="subtab-content" style="display:none;padding-top:10px;position:relative;">
+                        <div class="info-text">Link a shade to other shades or a physical remote so it follows the same commands. Each linked shade tracks its own position independently.</div>
+                        <hr />
+                        <div class="link-tab-label">Shade</div>
+                        <div class="button-container">
+                            <select id="selLinkTabShade" class="link-appshade-select" onchange="somfy.loadShadeLinks();"></select>
+                        </div>
+                        <div id="divLinkTabList"></div>
+                        <hr />
+                        <div id="divLinkAppShade" style="display:none;">
+                            <div class="link-tab-label">Add a linked shade</div>
+                            <div class="button-container">
+                                <select id="selLinkAppShade" class="link-appshade-select"></select>
+                            </div>
+                            <div class="button-container">
+                                <button id="btnLinkAppShade" type="button" onclick="somfy.addShadeLink();">
+                                    Link Shade
+                                </button>
+                            </div>
+                            <div class="linkappshade-hint">A linked shade follows the same commands; its position is tracked independently.</div>
+                        </div>
+                        <div class="link-tab-label">Link a physical remote</div>
+                        <div class="button-container">
+                            <button id="btnLinkTabRemote" type="button" onclick="somfy.linkRemoteFromTab();">
+                                Link Remote
+                            </button>
+                        </div>
+                    </div>
                     <div id="divRepeater" style="display:none;padding-top:10px;" class="subtab-content">
                         <div id="divRepeaterListContainer">
                             <div style="font-size:.8em;">All repeated remote addresses are listed below.</div>
diff --git a/data/somfy.js b/data/somfy.js
index 11372f10..9f0e9f7a 100644
--- a/data/somfy.js
+++ b/data/somfy.js
@@ -403,6 +403,8 @@ class Somfy {
         document.getElementById('divShadeList').innerHTML = divCfg;
         let shadeControls = document.getElementById('divShadeControls');
         shadeControls.innerHTML = divCtl;
+        // Keep the Links tab's source-shade picker in sync with the shade list.
+        this.populateLinkTabShades(shades);
         // Attach the timer for setting the My Position for the shade.
         let btns = shadeControls.querySelectorAll('div.cmd-button');
         for (let i = 0; i < btns.length; i++) {
@@ -851,20 +853,138 @@ class Somfy {
         });
     }
     setLinkedRemotesList(shade) {
+        // Fetch the full shade list so linked rows can show the owning shade's
+        // name when a linked remote is actually another app shade.
+        getJSON('/shades', (err, shades) => {
+            let allShades = (!err && Array.isArray(shades)) ? shades : [];
+            this.renderLinkedRemotesList(shade, allShades);
+        });
+    }
+    renderLinkedRemotesList(shade, allShades, opts) {
+        opts = opts || {};
+        let targetId = opts.targetId || 'divLinkedRemoteList';
+        let unlinkFn = opts.unlinkFn || 'unlinkRemote';
+        let header = opts.header || 'Linked Remotes';
+        let emptyText = opts.empty || 'No linked remotes';
+        let target = document.getElementById(targetId);
+        if (!target) return;
         let linkedRemotes = (shade && shade.linkedRemotes) ? shade.linkedRemotes : [];
-        let divCfg = '<div class="linkedremote-header">Linked Remotes</div>';
+        let divCfg = `<div class="linkedremote-header">${header}</div>`;
         if (linkedRemotes.length === 0) {
-            divCfg += '<div class="linkedremote-none">No linked remotes</div>';
+            divCfg += `<div class="linkedremote-none">${emptyText}</div>`;
         }
         for (let i = 0; i < linkedRemotes.length; i++) {
             let remote = linkedRemotes[i];
+            // When the linked address belongs to another app shade, label it
+            // with that shade's name; otherwise show the bare address.
+            let match = allShades.find(s => s.remoteAddress === remote.remoteAddress && s.shadeId !== shade.shadeId);
+            let label = match ? `${match.name} — ${remote.remoteAddress}` : `${remote.remoteAddress}`;
             divCfg += `<div class="somfyLinkedRemote" data-shadeid="${shade.shadeId}" data-remoteaddress="${remote.remoteAddress}">`;
-            divCfg += `<span class="linkedremote-address">${remote.remoteAddress}</span>`;
+            divCfg += `<span class="linkedremote-address">${label}</span>`;
             divCfg += `<span class="linkedremote-code">${remote.lastRollingCode}</span>`;
-            divCfg += `<div class="button-outline" onclick="somfy.unlinkRemote(${shade.shadeId}, ${remote.remoteAddress});"><i class="icss-trash"></i></div>`;
+            divCfg += `<div class="button-outline" onclick="somfy.${unlinkFn}(${shade.shadeId}, ${remote.remoteAddress});"><i class="icss-trash"></i></div>`;
             divCfg += '</div>';
         }
-        document.getElementById('divLinkedRemoteList').innerHTML = divCfg;
+        target.innerHTML = divCfg;
+    }
+    populateLinkAppShadeList(shade, allShades) {
+        let sel = document.getElementById('selLinkAppShade');
+        let container = document.getElementById('divLinkAppShade');
+        let btn = document.getElementById('btnLinkAppShade');
+        if (!sel || !container) return;
+        let linkedRemotes = (shade && shade.linkedRemotes) ? shade.linkedRemotes : [];
+        let linkedAddrs = linkedRemotes.map(r => r.remoteAddress);
+        // Candidates: every other saved shade with a real address that is not
+        // already linked to this shade.
+        let candidates = allShades.filter(s =>
+            s.shadeId !== shade.shadeId &&
+            s.remoteAddress &&
+            linkedAddrs.indexOf(s.remoteAddress) === -1);
+        // Always reveal the block; show an explicit empty state (rather than
+        // vanishing) when there is nothing to link, so the option is discoverable.
+        container.style.display = '';
+        if (candidates.length === 0) {
+            sel.innerHTML = '<option value="" disabled selected>No other shades available to link</option>';
+            if (btn) btn.classList.add('disabled');
+            if (btn) btn.disabled = true;
+            return;
+        }
+        let opts = '';
+        for (let i = 0; i < candidates.length; i++) {
+            let s = candidates[i];
+            let room = _rooms.find(x => x.roomId === s.roomId);
+            let prefix = (room && room.name && room.roomId !== 0) ? `${room.name}: ` : '';
+            opts += `<option value="${s.remoteAddress}">${prefix}${s.name} (${s.remoteAddress})</option>`;
+        }
+        sel.innerHTML = opts;
+        if (btn) btn.classList.remove('disabled');
+        if (btn) btn.disabled = false;
+    }
+    // ── Links tab: manage shade-to-shade links in one place ───────────────────
+    // Fill the "source shade" picker (which shade to add links to). Kept in sync
+    // from setShadesList(). Preserves the current selection across refreshes.
+    populateLinkTabShades(shades) {
+        let sel = document.getElementById('selLinkTabShade');
+        if (!sel) return;
+        let prev = sel.value;
+        let list = (shades || []).filter(s => s.remoteAddress);
+        let opts = '';
+        for (let i = 0; i < list.length; i++) {
+            let s = list[i];
+            let room = _rooms.find(x => x.roomId === s.roomId);
+            let prefix = (room && room.name && room.roomId !== 0) ? `${room.name}: ` : '';
+            opts += `<option value="${s.shadeId}">${prefix}${s.name} (${s.remoteAddress})</option>`;
+        }
+        sel.innerHTML = opts || '<option value="" disabled selected>No shades configured</option>';
+        if (prev && sel.querySelector(`option[value="${prev}"]`)) sel.value = prev;
+        this.loadShadeLinks();
+    }
+    // Render the selected source shade's links and the "add link" candidates.
+    loadShadeLinks() {
+        let srcSel = document.getElementById('selLinkTabShade');
+        let listEl = document.getElementById('divLinkTabList');
+        if (!srcSel || !srcSel.value) {
+            if (listEl) listEl.innerHTML = '';
+            this.populateLinkAppShadeList({ shadeId: -1, linkedRemotes: [] }, []);
+            return;
+        }
+        let shadeId = parseInt(srcSel.value, 10);
+        getJSON('/shades', (err, shades) => {
+            let allShades = (!err && Array.isArray(shades)) ? shades : [];
+            getJSON(`/shade?shadeId=${shadeId}`, (errShade, shade) => {
+                let current = (!errShade && shade) ? shade : { shadeId: shadeId, linkedRemotes: [] };
+                this.renderLinkedRemotesList(current, allShades, {
+                    targetId: 'divLinkTabList',
+                    unlinkFn: 'unlinkShadeLink',
+                    header: 'Linked shades & remotes',
+                    empty: 'No links yet'
+                });
+                this.populateLinkAppShadeList(current, allShades);
+            });
+        });
+    }
+    // Link the chosen candidate shade's remote to the selected source shade.
+    addShadeLink() {
+        let src = document.getElementById('selLinkTabShade');
+        let cand = document.getElementById('selLinkAppShade');
+        if (!src || !src.value || !cand || !cand.value) return;
+        let obj = { shadeId: parseInt(src.value, 10), remoteAddress: parseInt(cand.value, 10) };
+        putJSON('/linkRemote', obj, (err) => {
+            if (err) {
+                ui.serviceError(err);
+                return;
+            }
+            this.loadShadeLinks();
+        });
+    }
+    unlinkShadeLink(shadeId, remoteAddress) {
+        putJSON('/unlinkRemote', { shadeId: shadeId, remoteAddress: remoteAddress }, (err) => {
+            if (err) {
+                ui.serviceError(err);
+                return;
+            }
+            this.loadShadeLinks();
+        });
     }
     setLinkedShadesList(group) {
         let divCfg = '';
@@ -960,8 +1080,15 @@ class Somfy {
             putJSON('/linkRemote', obj, (err, shade) => {
                 console.log(shade);
                 overlay.remove();
+                // Keep the linking dialog open on error so the user sees the
+                // failure (e.g. no free linked-remote slots) and can retry/cancel.
+                if (err) {
+                    ui.serviceError(err);
+                    return;
+                }
                 lnk.remove();
-                this.setLinkedRemotesList(shade);
+                // RF linking is initiated from the Links tab; refresh it.
+                this.loadShadeLinks();
             });
         }
         else {
@@ -1118,7 +1245,6 @@ class Somfy {
             getJSONSync('/getNextShade', (err, shade) => {
                 document.getElementById('btnPairShade').style.display = 'none';
                 document.getElementById('btnUnpairShade').style.display = 'none';
-                document.getElementById('btnLinkRemote').style.display = 'none';
                 document.getElementById('btnSaveShade').innerText = 'Add Shade';
                 document.getElementById('spanShadeId').innerText = '*';
                 document.getElementById('divLinkedRemoteList').innerHTML = '';
@@ -1148,7 +1274,6 @@ class Somfy {
             document.getElementById('btnSaveShade').style.display = 'none';
             document.getElementById('btnPairShade').style.display = 'none';
             document.getElementById('btnUnpairShade').style.display = 'none';
-            document.getElementById('btnLinkRemote').style.display = 'none';
 
             document.getElementById('btnSaveShade').innerText = 'Save Shade';
             document.getElementById('spanShadeId').innerText = shadeId;
@@ -1161,7 +1286,6 @@ class Somfy {
                     ui.toElement(document.getElementById('somfyShade'), shade);
                     this.showEditShade(true);
                     document.getElementById('btnSaveShade').style.display = 'inline-block';
-                    document.getElementById('btnLinkRemote').style.display = '';
                     this.onShadeTypeChanged(document.getElementById('selShadeType'));
                     let ico = document.getElementById('icoShade');
                     let tilt = ico.parentElement.querySelector('i.icss-window-tilt');
@@ -1380,7 +1504,6 @@ class Somfy {
                         document.getElementById('spanShadeId').innerText = shade.shadeId;
                         document.getElementById('btnSaveShade').innerText = 'Save Shade';
                         document.getElementById('btnSaveShade').style.display = 'inline-block';
-                        document.getElementById('btnLinkRemote').style.display = '';
                         document.getElementById(shade.paired ? 'btnUnpairShade' : 'btnPairShade').style.display = 'inline-block';
                         document.getElementById('btnSetRollingCode').style.display = 'inline-block';
                         this.updateShadeList();
@@ -1578,7 +1701,6 @@ class Somfy {
                 document.getElementById('somfyMain').style.display = 'none';
                 document.getElementById('somfyShade').style.display = '';
                 document.getElementById('btnSaveShade').style.display = 'inline-block';
-                document.getElementById('btnLinkRemote').style.display = '';
                 document.getElementsByName('shadeAddress')[0].value = shade.remoteAddress;
                 document.getElementsByName('shadeName')[0].value = shade.name;
                 document.getElementsByName('shadeUpTime')[0].value = shade.upTime;
@@ -1612,7 +1734,6 @@ class Somfy {
                 document.getElementById('somfyMain').style.display = 'none';
                 document.getElementById('somfyShade').style.display = '';
                 document.getElementById('btnSaveShade').style.display = 'inline-block';
-                document.getElementById('btnLinkRemote').style.display = '';
                 document.getElementsByName('shadeAddress')[0].value = shade.remoteAddress;
                 document.getElementsByName('shadeName')[0].value = shade.name;
                 document.getElementsByName('shadeUpTime')[0].value = shade.upTime;
@@ -1687,7 +1808,6 @@ class Somfy {
                 console.log(shade);
                 this.showEditShade(true);
                 document.getElementById('btnSaveShade').style.display = 'inline-block';
-                document.getElementById('btnLinkRemote').style.display = '';
                 if (shade.paired) {
                     document.getElementById('btnUnpairShade').style.display = 'inline-block';
                     document.getElementById('btnPairShade').style.display = 'none';
@@ -1948,15 +2068,23 @@ class Somfy {
                 if (typeof cb === 'function') cb(err, shade);
             });
     }
+    // Open the press-a-remote popup for the shade currently selected in the
+    // Links tab's source picker.
+    linkRemoteFromTab() {
+        let src = document.getElementById('selLinkTabShade');
+        if (!src || !src.value) return;
+        this.linkRemote(parseInt(src.value, 10));
+    }
     linkRemote(shadeId) {
         let div = document.createElement('div');
         let html = `<div id="divLinking" class="instructions" data-type="link-remote" data-shadeid="${shadeId}">`;
-        html += '<div>Press any button on the remote to link it to this shade.  This will not change the pairing for the remote and this screen will close when the remote is detected.</div>';
+        html += '<div>Press any button on the remote to link it to the selected shade.  This will not change the pairing for the remote and this screen will close when the remote is detected.</div>';
         html += '<hr></hr>';
         html += `<div><div class="button-container"><button id="btnStopLinking" type="button" style="padding-left:20px;padding-right:20px;" onclick="document.getElementById('divLinking').remove();">Cancel</button></div>`;
         html += '</div>';
         div.innerHTML = html;
-        document.getElementById('somfyShade').appendChild(div);
+        // Anchor the overlay over the Links tab (its positioning context).
+        document.getElementById('divSomfyLinks').appendChild(div);
         return div;
     }
     linkRepeatRemote() {
diff --git a/data/widgets.css b/data/widgets.css
index 8730ff4c..e2e00a85 100644
--- a/data/widgets.css
+++ b/data/widgets.css
@@ -155,6 +155,25 @@
         text-align: left;
         white-space: nowrap;
     }
+.link-appshade-select {
+    width: 100%;
+    box-sizing: border-box;
+}
+.linkappshade-hint {
+    font-size: .75em;
+    font-style: italic;
+    text-align: center;
+    padding: 0 0 4px;
+    opacity: .8;
+}
+.link-tab-label {
+    font-size: .8em;
+    color: #00bcd4;
+    padding: 4px 0 2px;
+}
+.info-text {
+    font-size: 20px;
+}
 .pin-digit {
     margin: 0 0.3rem;
     padding: 0.5rem;
diff --git a/main/web/WebShades.cpp b/main/web/WebShades.cpp
index e2a22c02..759c0910 100644
--- a/main/web/WebShades.cpp
+++ b/main/web/WebShades.cpp
@@ -510,17 +510,20 @@ void WebShades::remoteLinkOp(WebServer &server, bool link)
             if (obj.containsKey("shadeId")) {
                 SomfyShade *shade = requireShade(json, obj["shadeId"].as<uint8_t>());
                 if (shade) {
-                    if (obj.containsKey("remoteAddress")) {
-                        if (link) {
-                            if (obj.containsKey("rollingCode"))
-                                shade->linkRemote(obj["remoteAddress"], obj["rollingCode"]);
-                            else
-                                shade->linkRemote(obj["remoteAddress"]);
-                        } else {
-                            shade->unlinkRemote(obj["remoteAddress"]);
+                    if (!obj.containsKey("remoteAddress")) {
+                        json.respondJson().error("Remote address not provided.");
+                        return;
+                    }
+                    if (link) {
+                        bool linked = obj.containsKey("rollingCode")
+                                          ? shade->linkRemote(obj["remoteAddress"], obj["rollingCode"])
+                                          : shade->linkRemote(obj["remoteAddress"]);
+                        if (!linked) {
+                            json.respondJson().error("No free linked-remote slots available.");
+                            return;
                         }
                     } else {
-                        json.respondJson().error("Remote address not provided.");
+                        shade->unlinkRemote(obj["remoteAddress"]);
                     }
                     sendShadeJSON(json, shade);
                 }

From 93ed3b07a1781705dade8c253a70dc21715e2a0b Mon Sep 17 00:00:00 2001
From: Matthias Jobst <matthias.jobst@gmx.net>
Date: Fri, 26 Jun 2026 16:51:55 +0200
Subject: [PATCH 2/8] UI cleanup, header icon swap, and third-party license
 notices

- main.css: remove dead rules and merge duplicate blocks (field-group /
  button-container, input/select); drop the .field-group1 variant in
  favour of .field-group + .field-sep / .radioPins.
- Reorder the top tabs to Somfy, HomeKit, Radio, Network, System
  (System stays the initial landing tab).
- Links tab: source-shade picker now uses the same field-group look as
  the Virtual Remote selector.
- Replace the CSS-drawn config gear/home with Bootstrap Icons
  house-gear-fill / house-fill, served from LittleFS and registered in
  WebFiles.cpp; recoloured via CSS mask so they stay white on the button.
  Toggle now flips a `show-home` class instead of swapping icss classes.
- Delete the now-unused icss-gear/icss-gears/icss-home definitions.
- Add THIRD-PARTY-NOTICES.md and a README License section clarifying that
  the Unlicense covers only this project's own code; bundled components
  (Bootstrap Icons, ArduinoJson, etc.) keep their own licenses.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md                |  9 ++++
 THIRD-PARTY-NOTICES.md   | 58 +++++++++++++++++++++++++
 data/house-fill.svg      |  9 ++++
 data/house-gear-fill.svg | 10 +++++
 data/icons.css           | 91 ----------------------------------------
 data/index.html          | 39 +++++++++--------
 data/main.css            | 73 +++++++++++++++-----------------
 data/ui.js               |  4 +-
 main/web/WebFiles.cpp    |  2 +
 9 files changed, 145 insertions(+), 150 deletions(-)
 create mode 100644 THIRD-PARTY-NOTICES.md
 create mode 100644 data/house-fill.svg
 create mode 100644 data/house-gear-fill.svg

diff --git a/README.md b/README.md
index 2fea574a..7aa6e1c3 100644
--- a/README.md
+++ b/README.md
@@ -138,3 +138,12 @@ MQTT was tempting to remove as well since I don't use it, but it is genuinely us
 
 ### Improving the transmission
 
+## License
+
+This project's own source is released into the public domain under [The Unlicense](LICENSE).
+
+The Unlicense covers **only the original code in this repository**. The firmware and
+web bundle also include third-party components (e.g. Bootstrap Icons, ArduinoJson,
+arduino-esp32) that remain under their own licenses and are **not** public domain.
+Those components and their notices are listed in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
+
diff --git a/THIRD-PARTY-NOTICES.md b/THIRD-PARTY-NOTICES.md
new file mode 100644
index 00000000..7bcd21c2
--- /dev/null
+++ b/THIRD-PARTY-NOTICES.md
@@ -0,0 +1,58 @@
+# Third-Party Notices
+
+This project's own source is released into the public domain under [The Unlicense](LICENSE).
+
+That dedication applies **only to the original code in this repository**. The project
+also bundles and distributes third-party components that remain under their own
+licenses — these are **not** public domain. Their copyright and permission notices are
+retained below, and the full license texts ship alongside each component
+(`components/<name>/LICENSE*`, `managed_components/<name>/`).
+
+## Web assets (`data/`)
+
+| Component | License | Copyright | Source |
+|---|---|---|---|
+| Bootstrap Icons (`house-fill.svg`, `house-gear-fill.svg`) | MIT | Copyright (c) 2019-2024 The Bootstrap Authors | https://github.com/twbs/icons |
+| QR Code Generator for JavaScript (`qrcode.min.js`) | MIT | Copyright (c) 2009 Kazuhiko Arase | http://www.d-project.com/ |
+
+## Firmware libraries (`components/`)
+
+| Component | License | Copyright | Source |
+|---|---|---|---|
+| ArduinoJson | MIT | Copyright © 2014-2025 Benoit Blanchon | https://arduinojson.org |
+| PubSubClient | MIT | Copyright (c) 2008-2020 Nicholas O'Leary | https://github.com/knolleary/pubsubclient |
+| arduinoWebSockets | LGPL-2.1 | Copyright (c) Markus Sattler | https://github.com/Links2004/arduinoWebSockets |
+| ELECHOUSE CC1101 driver | see component source headers | Copyright (c) 2010 Michael (ELECHOUSE) | https://github.com/LSatan/SmartRC-CC1101-Driver-Lib |
+| esp-homekit-sdk | Apache-2.0 | Copyright (c) Espressif Systems | https://github.com/espressif/esp-homekit-sdk |
+
+## Managed components (`managed_components/`, via the ESP-IDF Component Manager)
+
+| Component | License | Copyright |
+|---|---|---|
+| arduino-esp32 | LGPL-2.1 | Espressif Systems |
+| joltwallet/esp_littlefs (bundles `littlefs`) | MIT (esp_littlefs) / BSD-3-Clause (littlefs core) | Brian Pugh / Christopher Haster |
+| Espressif ESP-IDF components (mdns, json_parser, libsodium, etc.) | Apache-2.0 unless otherwise noted in the component | Espressif Systems |
+
+The MIT License (used by several components above) reads:
+
+```
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
+Refer to each component's bundled `LICENSE` file for the authoritative, full text of
+its license (including the LGPL-2.1, Apache-2.0, and BSD-3-Clause terms).
diff --git a/data/house-fill.svg b/data/house-fill.svg
new file mode 100644
index 00000000..b24b3d05
--- /dev/null
+++ b/data/house-fill.svg
@@ -0,0 +1,9 @@
+<!--
+  Bootstrap Icons (house-fill) — https://github.com/twbs/icons
+  Copyright (c) 2019-2024 The Bootstrap Authors
+  Licensed under the MIT License.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-house-fill" viewBox="0 0 16 16">
+  <path d="M8.707 1.5a1 1 0 0 0-1.414 0L.646 8.146a.5.5 0 0 0 .708.708L8 2.207l6.646 6.647a.5.5 0 0 0 .708-.708L13 5.793V2.5a.5.5 0 0 0-.5-.5h-1a.5.5 0 0 0-.5.5v1.293z"/>
+  <path d="m8 3.293 6 6V13.5a1.5 1.5 0 0 1-1.5 1.5h-9A1.5 1.5 0 0 1 2 13.5V9.293z"/>
+</svg>
diff --git a/data/house-gear-fill.svg b/data/house-gear-fill.svg
new file mode 100644
index 00000000..ec268ad2
--- /dev/null
+++ b/data/house-gear-fill.svg
@@ -0,0 +1,10 @@
+<!--
+  Bootstrap Icons (house-gear-fill) — https://github.com/twbs/icons
+  Copyright (c) 2019-2024 The Bootstrap Authors
+  Licensed under the MIT License.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-house-gear-fill" viewBox="0 0 16 16">
+  <path d="M7.293 1.5a1 1 0 0 1 1.414 0L11 3.793V2.5a.5.5 0 0 1 .5-.5h1a.5.5 0 0 1 .5.5v3.293l2.354 2.353a.5.5 0 0 1-.708.708L8 2.207 1.354 8.854a.5.5 0 1 1-.708-.708z"/>
+  <path d="M11.07 9.047a1.5 1.5 0 0 0-1.742.26l-.02.021a1.5 1.5 0 0 0-.261 1.742 1.5 1.5 0 0 0 0 2.86 1.5 1.5 0 0 0-.12 1.07H3.5A1.5 1.5 0 0 1 2 13.5V9.293l6-6 4.724 4.724a1.5 1.5 0 0 0-1.654 1.03"/>
+  <path d="m13.158 9.608-.043-.148c-.181-.613-1.049-.613-1.23 0l-.043.148a.64.64 0 0 1-.921.382l-.136-.074c-.561-.306-1.175.308-.87.869l.075.136a.64.64 0 0 1-.382.92l-.148.045c-.613.18-.613 1.048 0 1.229l.148.043a.64.64 0 0 1 .382.921l-.074.136c-.306.561.308 1.175.869.87l.136-.075a.64.64 0 0 1 .92.382l.045.149c.18.612 1.048.612 1.229 0l.043-.15a.64.64 0 0 1 .921-.38l.136.074c.561.305 1.175-.309.87-.87l-.075-.136a.64.64 0 0 1 .382-.92l.149-.044c.612-.181.612-1.049 0-1.23l-.15-.043a.64.64 0 0 1-.38-.921l.074-.136c.305-.561-.309-1.175-.87-.87l-.136.075a.64.64 0 0 1-.92-.382ZM12.5 14a1.5 1.5 0 1 1 0-3 1.5 1.5 0 0 1 0 3"/>
+</svg>
diff --git a/data/icons.css b/data/icons.css
index bf793e7b..7b3a7d4b 100644
--- a/data/icons.css
+++ b/data/icons.css
@@ -401,67 +401,6 @@ i.icss-trash {
         border-radius: .07em;
         transform: translateX(-50%);
     }
-i.icss-gear {
-    width: .5em;
-    height: .5em;
-    position: relative;
-    border-radius: 100%;
-    background-color: transparent;
-    border-width: .07em;
-    border-style: solid;
-    border-color: transparent;
-    margin: .25em;
-    box-shadow: 0 0 0 .1em, inset 0 0 0 .3em;
-}
-
-    i.icss-gear:before {
-        width: .18em;
-        height: .18em;
-        top: 50%;
-        left: 50%;
-        transform: translate(-50%, -50%);
-        box-shadow: .41em 0, -.41em 0, 0 .41em, 0 -.41em;
-    }
-
-    i.icss-gear:after {
-        width: .18em;
-        height: .18em;
-        top: 50%;
-        left: 50%;
-        transform: translate(-50%, -50%) rotate(45deg);
-        box-shadow: .42em 0, -.42em 0, 0 .42em, 0 -.42em;
-    }
-i.icss-gears {
-    width: .5em;
-    height: .5em;
-    position: relative;
-    border-radius: 100%;
-    border-width: .063em;
-    border-style: solid;
-    border-color: transparent;
-    margin: .36em .532em .08em .1em;
-    box-shadow: .51em -.32em 0 -.06em;
-}
-
-    i.icss-gears:before {
-        width: .7em;
-        height: .7em;
-        border-radius: 100%;
-        background: linear-gradient(0deg,transparent 39%,currentcolor 39%,currentcolor 61%, transparent 61%), linear-gradient(60deg,transparent 42%, currentcolor 42%,currentcolor 58%, transparent 58%), linear-gradient(120deg,transparent 42%, currentcolor 42%,currentcolor 58%, transparent 58%);
-        top: 50%;
-        left: 50%;
-        transform: translate(-50%, -50%);
-    }
-
-    i.icss-gears:after {
-        width: .55em;
-        height: .55em;
-        border-radius: 100%;
-        background: linear-gradient(0deg,transparent 37%,currentcolor 37%,currentcolor 63%, transparent 63%), linear-gradient(60deg,transparent 40%, currentcolor 40%,currentcolor 60%, transparent 60%), linear-gradient(120deg,transparent 40%, currentcolor 40%,currentcolor 60%, transparent 60%);
-        top: -.135em;
-        left: .695em;
-        transform: translate(-50%, -50%) rotate(25deg);
-    }
 i.icss-somfy-down {
     width: 1em;
     height: 1em;
@@ -529,36 +468,6 @@ i.icss-somfy-toggle {
 
 
 
-i.icss-home {
-    width: .8em;
-    height: .45em;
-    background-color: transparent;
-    border-width: 0;
-    border-style: solid;
-    border-radius: 0 0 .02em .02em;
-    box-shadow: inset .285em .1em, inset -.285em .1em;
-    margin: .55em .1em 0;
-}
-
-    i.icss-home:before {
-        border-width: 0 .4em .4em;
-        border-style: solid;
-        border-color: currentColor transparent;
-        transform: translateX(-50%);
-        box-shadow: 0 .1em;
-        top: -.4em;
-        left: 50%;
-    }
-
-    i.icss-home:after {
-        width: .76em;
-        height: .76em;
-        border-width: 0.065em 0 0 0.065em;
-        border-style: solid;
-        transform: translateX(-50%) rotate(45deg);
-        top: -0.4em;
-        left: 50%;
-    }
 i.icss-window {
     width: 1.1em;
     height: .75em;
diff --git a/data/index.html b/data/index.html
index 4c585521..b0cc18fb 100644
--- a/data/index.html
+++ b/data/index.html
@@ -8,9 +8,9 @@
     <meta name="apple-mobile-web-app-title" content="ESPSomfy RTS App">
     <meta name="apple-mobile-web-app-status-bar-style" content="black">
 
-    <link rel="stylesheet" href="main.css?v=v0.7.1h" type="text/css" />
-    <link rel="stylesheet" href="widgets.css?v=v0.7.1h" type="text/css" />
-    <link rel="stylesheet" href="icons.css?v=v0.7.1h" type="text/css" />
+    <link rel="stylesheet" href="main.css?v=v0.7.1q" type="text/css" />
+    <link rel="stylesheet" href="widgets.css?v=v0.7.1q" type="text/css" />
+    <link rel="stylesheet" href="icons.css?v=v0.7.1q" type="text/css" />
     <link rel="icon" type="image/png" href="favicon.png" />
 
     <!-- iPad retina icon -->
@@ -115,14 +115,14 @@
 
 
     <script type="text/javascript" src="qrcode.min.js"></script>
-    <script type="text/javascript" src="index.js?v=v0.7.1h"></script>
+    <script type="text/javascript" src="index.js?v=v0.7.1q"></script>
     <script type="text/javascript">
     // Cache-bust query appended to every versioned asset (CSS + scripts). It is the
     // app version plus a trailing asset-revision letter (e.g. v0.6.1a) so it stays
     // distinct from the firmware/application version. bump_version.sh resets every
     // version query token in this file to "<tag>a" on release; between releases bump
     // the letter by hand (a→b→c) when iterating on assets, then reflash the data partition.
-    window.assetVer = '?v=v0.7.1h';
+    window.assetVer = '?v=v0.7.1q';
     // Load remaining scripts one at a time so the ESP32 never receives
     // more than one file request simultaneously. The browser's preload
     // scanner would otherwise fetch all <script src> tags in parallel,
@@ -157,7 +157,10 @@ <h1 style="text-align: center;">
                 <span>ESPSomfy RTS</span>
                 <span class="button-outline" onclick="ui.toggleConfig();" style="float:right;font-size:1.25rem;vertical-align:middle;width:38px;height:38px;position:relative;padding-top:4px;">
                     <span style="vertical-align:middle;clear:both;text-align:center;display:inline-block;">
-                        <i id="icoConfig" class="icss-gear"></i>
+                        <span id="icoConfig">
+                            <span class="ct-icon ct-gear" aria-hidden="true"></span>
+                            <span class="ct-icon ct-home" aria-hidden="true"></span>
+                        </span>
                     </span>
                 </span>
                 <img src="HomeKit.svg" id="icoHomeKit" style="width:38px;float:right;margin-right:4px;vertical-align:middle;" />
@@ -180,7 +183,7 @@ <h1 style="text-align: center;">
                         <div><span style="text-align:right;display:inline-block;width:57px;color:#00bcd4">Speed:</span><span id="spanEthernetSpeed" style="padding-left:4px;display:inline-block;text-align:left;width:120px;">--</span></div>
                     </div>
                 </div>
-                <div class="tab-container"><span class="selected" data-grpid="divSystemSettings">System</span><span data-grpid="divNetworkSettings">Network</span><span data-grpid="divHomeKitSettings">HomeKit</span><span data-grpid="divSomfySettings">Somfy</span><span data-grpid="divRadioSettings">Radio</span></div>
+                <div class="tab-container"><span data-grpid="divSomfySettings">Somfy</span><span data-grpid="divHomeKitSettings">HomeKit</span><span data-grpid="divRadioSettings">Radio</span><span data-grpid="divNetworkSettings">Network</span><span class="selected" data-grpid="divSystemSettings">System</span></div>
                 <div id="divSystemSettings" class="tab-content">
                     <div class="subtab-container"><span class="selected" data-grpid="divSystemOptions">Options</span><span data-grpid="divSecurityOptions">Security</span><span data-grpid="divFirmware">Firmware</span></div>
                     <div id="divSystemOptions" class="subtab-content">
@@ -431,15 +434,15 @@ <h1 style="text-align: center;">
                                 <label for="cbPubDisco" style="display:inline-block;cursor:pointer;">Publish Discovery</label>
                             </div>
                         </div>
-                        <div class="field-group1" style="white-space:nowrap;">
+                        <div class="field-group" style="white-space:nowrap;">
                             <select name="mqtt-protocol" data-bind="mqtt.protocol" style="width:54px;">
                                 <option>MQTT</option>
                                 <option>MQTTS</option>
                             </select>
-                            <span>://</span>
-                            <input name="mqtt-host" type="text" length=64 placeholder="Host" data-bind="mqtt.hostname" style="width:calc(100% - 137px);">
-                            <span>:</span>
-                            <input name="mqtt-port" type="text" length=5 placeholder="Port" data-bind="mqtt.port" data-datatype="int" style="width:50px;">
+                            <span class="field-sep">://</span>
+                            <input name="mqtt-host" type="text" length=64 placeholder="Host" data-bind="mqtt.hostname" style="display:inline-block;width:calc(100% - 137px);">
+                            <span class="field-sep">:</span>
+                            <input name="mqtt-port" type="text" length=5 placeholder="Port" data-bind="mqtt.port" data-datatype="int" style="display:inline-block;width:50px;">
                         </div>
                         <div class="field-group">
                             <input id="fldMqttUsername" name="mqtt-username" type="text" data-bind="mqtt.username" length=32 placeholder="Username" autocomplete="username">
@@ -843,11 +846,11 @@ <h1 style="text-align: center;">
 
                     </div>
                     <div id="divSomfyLinks" class="subtab-content" style="display:none;padding-top:10px;position:relative;">
-                        <div class="info-text">Link a shade to other shades or a physical remote so it follows the same commands. Each linked shade tracks its own position independently.</div>
+                        <div class="info-text">Link a shade to other shades or a physical remote so it follows the same commands.<br />Each linked shade tracks its own position independently.</div>
                         <hr />
-                        <div class="link-tab-label">Shade</div>
-                        <div class="button-container">
-                            <select id="selLinkTabShade" class="link-appshade-select" onchange="somfy.loadShadeLinks();"></select>
+                        <div class="field-group">
+                            <select id="selLinkTabShade" style="width:100%;" onchange="somfy.loadShadeLinks();"></select>
+                            <label for="selLinkTabShade">Select a Shade</label>
                         </div>
                         <div id="divLinkTabList"></div>
                         <hr />
@@ -1007,7 +1010,7 @@ <h1 style="text-align: center;">
                             <label for="cbEnableRadio" style="display:inline-block;cursor:pointer;">Enable Radio</label>
                         </div>
                         <div class="field-group" style="margin-top:-18px;"><label style="font-size:12px;">(default when adding new motors)</label></div>
-                        <div class="field-group1" style="white-space:nowrap">
+                        <div class="field-group" style="white-space:nowrap">
                             <div class="field-group radioPins">
                                 <select id="selTransSCKPin" name="transSCK" data-bind="transceiver.config.SCKPin" data-datatype="int"></select>
                                 <label for="selTransSCKPin">SCLK</label>
@@ -1025,7 +1028,7 @@ <h1 style="text-align: center;">
                                 <label for="selTransMISOPin">MISO</label>
                             </div>
                         </div>
-                        <div class="field-group1" style="margin-top:-20px;">
+                        <div class="field-group" style="margin-top:-20px;">
                             <div class="field-group radioPins">
                                 <select id="selTransTXPin" name="transTX" data-bind="transceiver.config.TXPin" data-datatype="int"></select>
                                 <label for="selTransTXPin">TX</label>
diff --git a/data/main.css b/data/main.css
index d8e03de9..65551816 100644
--- a/data/main.css
+++ b/data/main.css
@@ -79,16 +79,8 @@ form {
     margin-top:-18px;
 }
 
-.field-group {
-    box-sizing: border-box;
-    clear: both;
-    padding: 4px 0;
-    position: relative;
-    margin: 1px 0;
-    width: 100%;
-}
-
-.field-group1 {
+.field-group,
+.button-container {
     box-sizing: border-box;
     clear: both;
     padding: 4px 0;
@@ -97,7 +89,7 @@ form {
     width: 100%;
 }
 
-    .field-group1 > span {
+    .field-sep {
         color: #757575;
         display: inline-block;
         margin: 0 0 5px 0;
@@ -120,7 +112,7 @@ form {
     margin-top:-10px;
     color:#00bcd4;
 }
-.field-group1 > div.field-group {
+.radioPins {
     display:inline-block;
     width:auto;
 }
@@ -130,24 +122,10 @@ form {
 
 input[type=password],
 input[type=number],
-input[type=text] {
-    font-size: 15px;
-    margin-bottom: 14px;
-    -webkit-appearance: none;
-    appearance: none;
-    background: #fafafa;
-    color: #636363;
-    border: none;
-    border-radius: 0;
-    border-top: none;
-    border-left: none;
-    border-right: none;
-    border-bottom: 1px solid #00bcd4;
-    background-color: transparent;
-}
-
+input[type=text],
 select {
     font-size: 15px;
+    margin-bottom: 14px;
     -webkit-appearance: none;
     appearance: none;
     background: #fafafa;
@@ -159,7 +137,6 @@ select {
     border-right: none;
     border-bottom: 1px solid #00bcd4;
     background-color: transparent;
-    margin-bottom:14px;
 }
 
 .field-group input[type=password],
@@ -178,12 +155,8 @@ input[type=text]:focus {
 }
 
 .button-container {
-    box-sizing: border-box;
-    clear: both;
-    margin: 1px 0 0;
-    padding: 4px 0;
-    position: relative;
-    width: 100%;
+    /* shares the .field-group base above; only the bottom margin differs */
+    margin-bottom: 0;
 }
 
 button[type=button],
@@ -353,9 +326,6 @@ input[type=checkbox] {
     height:20px;
     vertical-align:middle;
 }
-div.field-group1.inputPin {
-    margin-top:-10px;
-}
 legend {
     border: 1px solid #ccc;
     border-bottom: 0;
@@ -680,7 +650,6 @@ div.wait-overlay > .lds-roller {
     .somfyShadeCtl[data-roomid="0"] .shadectl-room {
         display:none;
     }
-    .somfyGroupCtl .groupctl-mypos,
     .somfyShadeCtl .shadectl-mypos {
         white-space: nowrap;
         font-size: 12px;
@@ -854,6 +823,32 @@ div.frame-pulses {
     text-overflow:ellipsis;
     display:none;
 }
+#icoConfig .ct-icon {
+    /* Bootstrap Icons SVGs served from LittleFS, recolored to the button's
+       currentColor via CSS mask so they stay white on the blue button. */
+    width: 22px;
+    height: 22px;
+    display: inline-block;
+    vertical-align: middle;
+    background-color: currentColor;
+    -webkit-mask-repeat: no-repeat;
+            mask-repeat: no-repeat;
+    -webkit-mask-position: center;
+            mask-position: center;
+    -webkit-mask-size: contain;
+            mask-size: contain;
+}
+    #icoConfig .ct-gear {
+        -webkit-mask-image: url('/house-gear-fill.svg');
+                mask-image: url('/house-gear-fill.svg');
+    }
+    #icoConfig .ct-home {
+        -webkit-mask-image: url('/house-fill.svg');
+                mask-image: url('/house-fill.svg');
+        display: none;
+    }
+    #icoConfig.show-home .ct-gear { display: none; }
+    #icoConfig.show-home .ct-home { display: inline-block; }
 #icoHomeKit {
     opacity: 0.25;
     transition: filter 0.3s, opacity 0.3s;
diff --git a/data/ui.js b/data/ui.js
index 7954a545..53e72c39 100644
--- a/data/ui.js
+++ b/data/ui.js
@@ -481,7 +481,7 @@ class UIBinder {
         let divHome = document.getElementById('divHomePnl');
         divHome.style.display = 'none';
         divCfg.style.display = '';
-        document.getElementById('icoConfig').className = 'icss-home';
+        document.getElementById('icoConfig').classList.add('show-home');
         if (sockIsOpen) socket.send('join:0');
         let overlay = ui.waitMessage(document.getElementById('divSecurityOptions'));
         overlay.style.borderRadius = '5px';
@@ -500,7 +500,7 @@ class UIBinder {
         let divHome = document.getElementById('divHomePnl');
         divHome.style.display = '';
         divCfg.style.display = 'none';
-        document.getElementById('icoConfig').className = 'icss-gear';
+        document.getElementById('icoConfig').classList.remove('show-home');
         if (sockIsOpen) socket.send('leave:0');
         general.setSecurityConfig({ type: 0, username: '', password: '', pin: '', permissions: 0 });
     }
diff --git a/main/web/WebFiles.cpp b/main/web/WebFiles.cpp
index f3dd5acb..f337954c 100644
--- a/main/web/WebFiles.cpp
+++ b/main/web/WebFiles.cpp
@@ -34,6 +34,8 @@ const WebFiles::StaticFile WebFiles::s_files[] = {
     {"/icon.svg", "/icon.svg", "image/svg+xml", true},
     {"/apple-icon.png", "/apple-icon.png", "image/png", true},
     {"/HomeKit.svg", "/HomeKit.svg", "image/svg+xml", true},
+    {"/house-fill.svg", "/house-fill.svg", "image/svg+xml", true},
+    {"/house-gear-fill.svg", "/house-gear-fill.svg", "image/svg+xml", true},
 };
 const size_t WebFiles::s_fileCount = sizeof(s_files) / sizeof(s_files[0]);
 

From a42d5904b355965585f335a425e17036a3e81ad0 Mon Sep 17 00:00:00 2001
From: Matthias Jobst <matthias.jobst@gmx.net>
Date: Sat, 27 Jun 2026 20:51:12 +0200
Subject: [PATCH 3/8] Add link-shade GUI assets and icons

New SVG icons, web UI for shade linking, and matching third-party notices.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 THIRD-PARTY-NOTICES.md         |   2 +-
 data/file-earmark-arrow-up.svg |   9 ++
 data/icons.css                 | 229 +++++----------------------------
 data/index.html                |  40 +++---
 data/pencil-fill.svg           |   8 ++
 data/somfy.js                  |  94 +++++++++-----
 data/sun-fill.svg              |   8 ++
 data/sun.svg                   |   8 ++
 data/trash-fill.svg            |   8 ++
 data/widgets.css               |  12 --
 main/web/WebFiles.cpp          |   5 +
 11 files changed, 157 insertions(+), 266 deletions(-)
 create mode 100644 data/file-earmark-arrow-up.svg
 create mode 100644 data/pencil-fill.svg
 create mode 100644 data/sun-fill.svg
 create mode 100644 data/sun.svg
 create mode 100644 data/trash-fill.svg

diff --git a/THIRD-PARTY-NOTICES.md b/THIRD-PARTY-NOTICES.md
index 7bcd21c2..b4e15264 100644
--- a/THIRD-PARTY-NOTICES.md
+++ b/THIRD-PARTY-NOTICES.md
@@ -12,7 +12,7 @@ retained below, and the full license texts ship alongside each component
 
 | Component | License | Copyright | Source |
 |---|---|---|---|
-| Bootstrap Icons (`house-fill.svg`, `house-gear-fill.svg`) | MIT | Copyright (c) 2019-2024 The Bootstrap Authors | https://github.com/twbs/icons |
+| Bootstrap Icons (SVG files in `data/`: house-fill, house-gear-fill, pencil-fill, trash-fill, sun, sun-fill, file-earmark-arrow-up) | MIT | Copyright (c) 2019-2024 The Bootstrap Authors | https://github.com/twbs/icons |
 | QR Code Generator for JavaScript (`qrcode.min.js`) | MIT | Copyright (c) 2009 Kazuhiko Arase | http://www.d-project.com/ |
 
 ## Firmware libraries (`components/`)
diff --git a/data/file-earmark-arrow-up.svg b/data/file-earmark-arrow-up.svg
new file mode 100644
index 00000000..2f9de52b
--- /dev/null
+++ b/data/file-earmark-arrow-up.svg
@@ -0,0 +1,9 @@
+<!--
+  Bootstrap Icons (file-earmark-arrow-up) — https://github.com/twbs/icons
+  Copyright (c) 2019-2024 The Bootstrap Authors
+  Licensed under the MIT License.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-file-earmark-arrow-up" viewBox="0 0 16 16">
+  <path d="M8.5 11.5a.5.5 0 0 1-1 0V7.707L6.354 8.854a.5.5 0 1 1-.708-.708l2-2a.5.5 0 0 1 .708 0l2 2a.5.5 0 0 1-.708.708L8.5 7.707z"/>
+  <path d="M14 14V4.5L9.5 0H4a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h8a2 2 0 0 0 2-2M9.5 3A1.5 1.5 0 0 0 11 4.5h2V14a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V2a1 1 0 0 1 1-1h5.5z"/>
+</svg>
diff --git a/data/icons.css b/data/icons.css
index 7b3a7d4b..0281131a 100644
--- a/data/icons.css
+++ b/data/icons.css
@@ -341,66 +341,22 @@ i.icss-anim:after {
             top: 54%;
             left: 54%;
         }
+/* Bootstrap Icons served from LittleFS, painted via CSS mask so they inherit
+   the element's currentColor (the base i[class*="icss-"] rule sets
+   background-color: currentColor). */
 i.icss-edit {
     width: 1em;
     height: 1em;
-    background-color: transparent;
-    border-radius: 50% 45% 50% 35%;
-    overflow: hidden;
-    margin: 0;
+    -webkit-mask: url('/pencil-fill.svg') center / contain no-repeat;
+            mask: url('/pencil-fill.svg') center / contain no-repeat;
 }
 
-    i.icss-edit:before {
-        width: .3em;
-        height: .8em;
-        border: .15em solid transparent;
-        border-top: .24em solid currentColor;
-        transform: rotate(45deg) translate(-50%);
-        transform-origin: 0 0;
-        box-shadow: 0 -.05em, .24em -.8em, -.24em -.8em, 0 -1.5em;
-        clip: rect(-.9em .3em 1em 0);
-        left: .25em;
-        top: .75em;
-    }
-
-    i.icss-edit:after {
-        width: .1em;
-        height: 0;
-        background-color: transparent;
-        transform: translate(-50%, -50%);
-        top: 50%;
-        left: 50%;
-    }
-
 i.icss-trash {
-    width: .68em;
-    height: .9em;
-    background-color: transparent;
-    border-width: .1em .1em;
-    border-style: solid;
-    border-radius: .05em;
-    margin: .1em .15em 0;
+    width: 1em;
+    height: 1em;
+    -webkit-mask: url('/trash-fill.svg') center / contain no-repeat;
+            mask: url('/trash-fill.svg') center / contain no-repeat;
 }
-
-    i.icss-trash:before {
-        border-style: solid;
-        border-width: .1em;
-        top: -.23em;
-        left: 50%;
-        border-radius: .1em;
-        width: .275em;
-        height: 1.03em;
-        transform: translateX(-50%);
-    }
-
-    i.icss-trash:after {
-        border-width: .1em .43em;
-        border-style: solid;
-        left: 50%;
-        top: -.05em;
-        border-radius: .07em;
-        transform: translateX(-50%);
-    }
 i.icss-somfy-down {
     width: 1em;
     height: 1em;
@@ -814,27 +770,10 @@ i.icss-lightbulb {
 
 i.icss-upload {
     width: 1em;
-    height: .6em;
-    background-color: transparent;
-    border-width: 0 .2em .3em;
-    border-style: solid;
-    border-radius: .03em;
-    margin: .4em 0 0;
+    height: 1em;
+    -webkit-mask: url('/file-earmark-arrow-up.svg') center / contain no-repeat;
+            mask: url('/file-earmark-arrow-up.svg') center / contain no-repeat;
 }
-    i.icss-upload:before {
-        height: .5em;
-        border-style: solid;
-        border-width: 0 .25em .25em;
-        border-color: transparent;
-        border-bottom-color: currentColor;
-        background-color: transparent;
-        box-shadow: 0em .35em 0 -.13em;
-        top: -.6em;
-        left: 50%;
-        transform: translateX(-50%);
-    }
-    i.icss-upload:after {
-    }
 i.icss-file {
     width: .8em;
     height: 1em;
@@ -907,129 +846,29 @@ i.icss-awning {
         background-image: repeating-linear-gradient(90deg, var(--shade-color, currentColor), var(--shade-color, currentColor) calc(25% - 4px), black calc(25% - 2px), var(--shade-color, currentColor) calc(25% - 2px)); 
         background-color: rgba(71, 212, 255, 0);
     }
+/* Sun icons: sun-fill (lit / "on") and sun (outline / "off"), masked from the
+   served Bootstrap SVGs. icss-sun-c is the filled state, icss-sun-o the outline,
+   icss-sun the standalone indicator. */
 i.icss-sun-c {
     width: 1em;
     height: 1em;
-    border-radius: 50%;
-    background-color: transparent;
-    background-image: radial-gradient(ellipse at center, #fd0 1%, #fb0 39%, #fb0 39%, #d61 100%);
-    box-shadow: 0 0 .06em .03em rgba(255, 107, 0, 0.4), 0 0 22px 11px rgba(255, 203, 0, 0.13);
-    background-position: -.7em -.6em;
-    background-size: 165%;
-    margin: 0;
+    -webkit-mask: url('/sun-fill.svg') center / contain no-repeat;
+            mask: url('/sun-fill.svg') center / contain no-repeat;
 }
 
-    i.icss-sun-c:before {
-    }
-
-    i.icss-sun-c:after {
-    }
-
 i.icss-sun {
-    width: .6em;
-    height: .6em;
-    border-radius: 50%;
-    background-color: transparent;
-    border: 0.03em solid transparent;
-    box-shadow: inset 0 0 0 .5em;
-    margin: .2em;
-}
-
-    i.icss-sun:before {
-        width: .1em;
-        height: .1em;
-        background-color: transparent;
-        top: 50%;
-        left: 50%;
-        transform: translate(-50%, -50%);
-        box-shadow: .45em 0, .38em 0, -.45em 0, -.38em 0, 0 .45em, 0 .38em, 0 -.45em, 0 -.38em;
-    }
-
-    i.icss-sun:after {
-        width: .1em;
-        height: .1em;
-        background-color: transparent;
-        top: 50%;
-        left: 50%;
-        transform: translate(-50%, -50%) rotate(45deg);
-        box-shadow: .45em 0, .38em 0, -.45em 0, -.38em 0, 0 .45em, 0 .38em, 0 -.45em, 0 -.38em;
-    }
-i.icss-sun-o {
-    width: .6em;
-    height: .6em;
-    border-radius: 50%;
-    background-color: transparent;
-    border: 0.03em solid transparent;
-    box-shadow: inset 0 0 0 .065em;
-    margin: .2em;
-}
-
-    i.icss-sun-o:before {
-        width: .1em;
-        height: .1em;
-        background-color: transparent;
-        top: 50%;
-        left: 50%;
-        transform: translate(-50%, -50%);
-        box-shadow: .45em 0, .38em 0, -.45em 0, -.38em 0, 0 .45em, 0 .38em, 0 -.45em, 0 -.38em;
-    }
-
-    i.icss-sun-o:after {
-        width: .1em;
-        height: .1em;
-        background-color: transparent;
-        top: 50%;
-        left: 50%;
-        transform: translate(-50%, -50%) rotate(45deg);
-        box-shadow: .45em 0, .38em 0, -.45em 0, -.38em 0, 0 .45em, 0 .38em, 0 -.45em, 0 -.38em;
-    }
-i.icss-sun-c {
     width: 1em;
     height: 1em;
-    border-radius: 50%;
-    background-color: transparent;
-    background-image: radial-gradient(ellipse at center, #fd0 1%, #fb0 39%, #fb0 39%, #d61 100%);
-    box-shadow: 0 0 .06em .03em rgba(255, 107, 0, 0.4), 0 0 22px 11px rgba(255, 203, 0, 0.13);
-    background-position: -.7em -.6em;
-    background-size: 165%;
-    margin: 0;
+    -webkit-mask: url('/sun-fill.svg') center / contain no-repeat;
+            mask: url('/sun-fill.svg') center / contain no-repeat;
 }
 
-    i.icss-sun-c:before {
-    }
-
-    i.icss-sun-c:after {
-    }
-
 i.icss-sun-o {
-    width: .6em;
-    height: .6em;
-    border-radius: 50%;
-    background-color: transparent;
-    border: 0.03em solid transparent;
-    box-shadow: inset 0 0 0 .065em;
-    margin: .2em;
+    width: 1em;
+    height: 1em;
+    -webkit-mask: url('/sun.svg') center / contain no-repeat;
+            mask: url('/sun.svg') center / contain no-repeat;
 }
-
-    i.icss-sun-o:before {
-        width: .1em;
-        height: .1em;
-        background-color: transparent;
-        top: 50%;
-        left: 50%;
-        transform: translate(-50%, -50%);
-        box-shadow: .45em 0, .38em 0, -.45em 0, -.38em 0, 0 .45em, 0 .38em, 0 -.45em, 0 -.38em;
-    }
-
-    i.icss-sun-o:after {
-        width: .1em;
-        height: .1em;
-        background-color: transparent;
-        top: 50%;
-        left: 50%;
-        transform: translate(-50%, -50%) rotate(45deg);
-        box-shadow: .45em 0, .38em 0, -.45em 0, -.38em 0, 0 .45em, 0 .38em, 0 -.45em, 0 -.38em;
-    }
 div.button-light {
     position:absolute;
     margin-left:-30px;
@@ -1062,23 +901,19 @@ div.button-sunflag {
     margin-left:-30px;
     cursor:pointer;
 }
-    div.button-sunflag[data-on=false] i.icss-sun-c {
-        background-image: radial-gradient(ellipse at center, gainsboro 1%, #ccc 39%, silver 39%, gray 100%);
-    }
-
-    div.button-sunflag > i.icss-sun-c {
-        position: absolute;
-        font-size: 18px;
-        color: orange;
-        left: 6px;
-        top: 7px;
-    }
-
+    /* The fill (sun-c) and outline (sun-o) overlay in the same spot; data-on
+       picks which one shows. background-color paints the mask (orange here;
+       overridden to white inline in the Virtual Remote). */
+    div.button-sunflag > i.icss-sun-c,
     div.button-sunflag > i.icss-sun-o {
         position: absolute;
         font-size: 32px;
-        color: orange;
+        background-color: orange;
+        left: 0;
+        top: 0;
     }
+    div.button-sunflag[data-on=false] > i.icss-sun-c { display: none; }
+    div.button-sunflag[data-on=true]  > i.icss-sun-o { display: none; }
 i.icss-warning {
     width: 1em;
     height: .1em;
diff --git a/data/index.html b/data/index.html
index b0cc18fb..2d3e2857 100644
--- a/data/index.html
+++ b/data/index.html
@@ -8,9 +8,9 @@
     <meta name="apple-mobile-web-app-title" content="ESPSomfy RTS App">
     <meta name="apple-mobile-web-app-status-bar-style" content="black">
 
-    <link rel="stylesheet" href="main.css?v=v0.7.1q" type="text/css" />
-    <link rel="stylesheet" href="widgets.css?v=v0.7.1q" type="text/css" />
-    <link rel="stylesheet" href="icons.css?v=v0.7.1q" type="text/css" />
+    <link rel="stylesheet" href="main.css?v=v0.7.1v" type="text/css" />
+    <link rel="stylesheet" href="widgets.css?v=v0.7.1v" type="text/css" />
+    <link rel="stylesheet" href="icons.css?v=v0.7.1v" type="text/css" />
     <link rel="icon" type="image/png" href="favicon.png" />
 
     <!-- iPad retina icon -->
@@ -115,14 +115,14 @@
 
 
     <script type="text/javascript" src="qrcode.min.js"></script>
-    <script type="text/javascript" src="index.js?v=v0.7.1q"></script>
+    <script type="text/javascript" src="index.js?v=v0.7.1v"></script>
     <script type="text/javascript">
     // Cache-bust query appended to every versioned asset (CSS + scripts). It is the
     // app version plus a trailing asset-revision letter (e.g. v0.6.1a) so it stays
     // distinct from the firmware/application version. bump_version.sh resets every
     // version query token in this file to "<tag>a" on release; between releases bump
     // the letter by hand (a→b→c) when iterating on assets, then reflash the data partition.
-    window.assetVer = '?v=v0.7.1q';
+    window.assetVer = '?v=v0.7.1v';
     // Load remaining scripts one at a time so the ESP32 never receives
     // more than one file request simultaneously. The browser's preload
     // scanner would otherwise fetch all <script src> tags in parallel,
@@ -155,15 +155,15 @@
             <h1 style="text-align: center;">
                 <img src="icon.png" style="width:50px;float:left;margin-left:1px;margin-top:-10px;" />
                 <span>ESPSomfy RTS</span>
-                <span class="button-outline" onclick="ui.toggleConfig();" style="float:right;font-size:1.25rem;vertical-align:middle;width:38px;height:38px;position:relative;padding-top:4px;">
-                    <span style="vertical-align:middle;clear:both;text-align:center;display:inline-block;">
+                <span style="float:right;display:flex;align-items:center;">
+                    <img src="HomeKit.svg" id="icoHomeKit" style="width:38px;margin-right:4px;" />
+                    <span class="button-outline" onclick="ui.toggleConfig();" style="font-size:1.25rem;width:38px;height:38px;position:relative;padding:0;display:flex;align-items:center;justify-content:center;">
                         <span id="icoConfig">
                             <span class="ct-icon ct-gear" aria-hidden="true"></span>
                             <span class="ct-icon ct-home" aria-hidden="true"></span>
                         </span>
                     </span>
                 </span>
-                <img src="HomeKit.svg" id="icoHomeKit" style="width:38px;float:right;margin-right:4px;vertical-align:middle;" />
             </h1>
             <div id="divConfigPnl" style="display:none;">
                 <div id="divWiFiStrength" style="margin-top:-10px;text-align:center;font-size:12px;">
@@ -854,21 +854,11 @@ <h1 style="text-align: center;">
                         </div>
                         <div id="divLinkTabList"></div>
                         <hr />
-                        <div id="divLinkAppShade" style="display:none;">
-                            <div class="link-tab-label">Add a linked shade</div>
-                            <div class="button-container">
-                                <select id="selLinkAppShade" class="link-appshade-select"></select>
-                            </div>
-                            <div class="button-container">
-                                <button id="btnLinkAppShade" type="button" onclick="somfy.addShadeLink();">
-                                    Link Shade
-                                </button>
-                            </div>
-                            <div class="linkappshade-hint">A linked shade follows the same commands; its position is tracked independently.</div>
-                        </div>
-                        <div class="link-tab-label">Link a physical remote</div>
-                        <div class="button-container">
-                            <button id="btnLinkTabRemote" type="button" onclick="somfy.linkRemoteFromTab();">
+                        <div class="button-container" style="text-align:center;">
+                            <button id="btnLinkAppShade" type="button" onclick="somfy.openLinkShade();" style="display:inline-block;width:47%;">
+                                Link Shade
+                            </button>
+                            <button id="btnLinkTabRemote" type="button" onclick="somfy.linkRemoteFromTab();" style="display:inline-block;width:47%;">
                                 Link Remote
                             </button>
                         </div>
@@ -963,8 +953,8 @@ <h1 style="text-align: center;">
                         <div class="vr-button vr-updown">
                             <span>Sun Flag</span>
                             <div>
-                                <div class="button-outline" style="width: 59px; text-align: center; border-radius: 33%; font-size: 2em; padding: 10px; height: 52px;" data-cmd="SunFlag" onmousedown="somfy.sendVRCommand(this);" ontouchstart="somfy.sendVRCommand(this);" onmouseup="somfy.endVRCommand();" onmouseleave="somfy.endVRCommand();" ontouchend="somfy.endVRCommand();" ontouchcancel="somfy.endVRCommand();"><div class="button-sunflag" data-on="true" style="margin:0px;margin-left:4px;"><i class="icss-sun-c" style="background:white;"></i><i class="icss-sun-o" style="left:0px;color:white;"></i></div></div>
-                                <div class="button-outline" style="width: 59px; text-align: center; border-radius: 33%; font-size: 2em; padding: 10px; height: 52px;" data-cmd="Flag" onmousedown="somfy.sendVRCommand(this);" ontouchstart="somfy.sendVRCommand(this);" onmouseup="somfy.endVRCommand();" onmouseleave="somfy.endVRCommand();" ontouchend="somfy.endVRCommand();" ontouchcancel="somfy.endVRCommand();"><div class="button-sunflag" data-on="false" style="margin:0px;margin-left:4px;"><i class="icss-sun-c" style="background:transparent;"></i><i class="icss-sun-o" style="left:0px;color:white;"></i></div></div>
+                                <div class="button-outline" style="width: 59px; text-align: center; border-radius: 33%; font-size: 2em; padding: 10px; height: 52px;" data-cmd="SunFlag" onmousedown="somfy.sendVRCommand(this);" ontouchstart="somfy.sendVRCommand(this);" onmouseup="somfy.endVRCommand();" onmouseleave="somfy.endVRCommand();" ontouchend="somfy.endVRCommand();" ontouchcancel="somfy.endVRCommand();"><div class="button-sunflag" data-on="true" style="margin:0px;margin-left:4px;"><i class="icss-sun-c" style="background:white;"></i><i class="icss-sun-o" style="left:0px;background:white;"></i></div></div>
+                                <div class="button-outline" style="width: 59px; text-align: center; border-radius: 33%; font-size: 2em; padding: 10px; height: 52px;" data-cmd="Flag" onmousedown="somfy.sendVRCommand(this);" ontouchstart="somfy.sendVRCommand(this);" onmouseup="somfy.endVRCommand();" onmouseleave="somfy.endVRCommand();" ontouchend="somfy.endVRCommand();" ontouchcancel="somfy.endVRCommand();"><div class="button-sunflag" data-on="false" style="margin:0px;margin-left:4px;"><i class="icss-sun-c" style="background:transparent;"></i><i class="icss-sun-o" style="left:0px;background:white;"></i></div></div>
                             </div>
                         </div>
                         <div class="vr-button">
diff --git a/data/pencil-fill.svg b/data/pencil-fill.svg
new file mode 100644
index 00000000..d6e06261
--- /dev/null
+++ b/data/pencil-fill.svg
@@ -0,0 +1,8 @@
+<!--
+  Bootstrap Icons (pencil-fill) — https://github.com/twbs/icons
+  Copyright (c) 2019-2024 The Bootstrap Authors
+  Licensed under the MIT License.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-pencil-fill" viewBox="0 0 16 16">
+  <path d="M12.854.146a.5.5 0 0 0-.707 0L10.5 1.793 14.207 5.5l1.647-1.646a.5.5 0 0 0 0-.708zm.646 6.061L9.793 2.5 3.293 9H3.5a.5.5 0 0 1 .5.5v.5h.5a.5.5 0 0 1 .5.5v.5h.5a.5.5 0 0 1 .5.5v.5h.5a.5.5 0 0 1 .5.5v.207zm-7.468 7.468A.5.5 0 0 1 6 13.5V13h-.5a.5.5 0 0 1-.5-.5V12h-.5a.5.5 0 0 1-.5-.5V11h-.5a.5.5 0 0 1-.5-.5V10h-.5a.5.5 0 0 1-.175-.032l-.179.178a.5.5 0 0 0-.11.168l-2 5a.5.5 0 0 0 .65.65l5-2a.5.5 0 0 0 .168-.11z"/>
+</svg>
diff --git a/data/somfy.js b/data/somfy.js
index 9f0e9f7a..6d1d86fc 100644
--- a/data/somfy.js
+++ b/data/somfy.js
@@ -887,38 +887,22 @@ class Somfy {
         }
         target.innerHTML = divCfg;
     }
-    populateLinkAppShadeList(shade, allShades) {
-        let sel = document.getElementById('selLinkAppShade');
-        let container = document.getElementById('divLinkAppShade');
-        let btn = document.getElementById('btnLinkAppShade');
-        if (!sel || !container) return;
-        let linkedRemotes = (shade && shade.linkedRemotes) ? shade.linkedRemotes : [];
-        let linkedAddrs = linkedRemotes.map(r => r.remoteAddress);
-        // Candidates: every other saved shade with a real address that is not
-        // already linked to this shade.
-        let candidates = allShades.filter(s =>
+    // Candidate shades for linking: every other saved shade with a real address
+    // that is not already linked to this shade.
+    linkCandidates(shade, allShades) {
+        let linkedAddrs = ((shade && shade.linkedRemotes) || []).map(r => r.remoteAddress);
+        return (allShades || []).filter(s =>
             s.shadeId !== shade.shadeId &&
             s.remoteAddress &&
             linkedAddrs.indexOf(s.remoteAddress) === -1);
-        // Always reveal the block; show an explicit empty state (rather than
-        // vanishing) when there is nothing to link, so the option is discoverable.
-        container.style.display = '';
-        if (candidates.length === 0) {
-            sel.innerHTML = '<option value="" disabled selected>No other shades available to link</option>';
-            if (btn) btn.classList.add('disabled');
-            if (btn) btn.disabled = true;
-            return;
-        }
-        let opts = '';
-        for (let i = 0; i < candidates.length; i++) {
-            let s = candidates[i];
-            let room = _rooms.find(x => x.roomId === s.roomId);
-            let prefix = (room && room.name && room.roomId !== 0) ? `${room.name}: ` : '';
-            opts += `<option value="${s.remoteAddress}">${prefix}${s.name} (${s.remoteAddress})</option>`;
-        }
-        sel.innerHTML = opts;
-        if (btn) btn.classList.remove('disabled');
-        if (btn) btn.disabled = false;
+    }
+    // Enable the tab's "Link Shade" button only when there is something to link.
+    updateLinkShadeButton(shade, allShades) {
+        let btn = document.getElementById('btnLinkAppShade');
+        if (!btn) return;
+        let none = this.linkCandidates(shade, allShades).length === 0;
+        btn.classList.toggle('disabled', none);
+        btn.disabled = none;
     }
     // ── Links tab: manage shade-to-shade links in one place ───────────────────
     // Fill the "source shade" picker (which shade to add links to). Kept in sync
@@ -945,7 +929,7 @@ class Somfy {
         let listEl = document.getElementById('divLinkTabList');
         if (!srcSel || !srcSel.value) {
             if (listEl) listEl.innerHTML = '';
-            this.populateLinkAppShadeList({ shadeId: -1, linkedRemotes: [] }, []);
+            this.updateLinkShadeButton({ shadeId: -1, linkedRemotes: [] }, []);
             return;
         }
         let shadeId = parseInt(srcSel.value, 10);
@@ -959,10 +943,56 @@ class Somfy {
                     header: 'Linked shades & remotes',
                     empty: 'No links yet'
                 });
-                this.populateLinkAppShadeList(current, allShades);
+                this.updateLinkShadeButton(current, allShades);
             });
         });
     }
+    // Open a popup to pick and link another shade to the selected source shade
+    // (mirrors linkRemote's press-a-remote popup).
+    openLinkShade() {
+        let src = document.getElementById('selLinkTabShade');
+        if (!src || !src.value) return;
+        let shadeId = parseInt(src.value, 10);
+        let div = document.createElement('div');
+        let html = `<div id="divLinkShade" class="instructions" data-shadeid="${shadeId}">`;
+        html += '<div>Link the following shade</div>';
+        html += `<div class="field-group" style="text-align:center;background-color:white;border-radius:5px;">`;
+        html += '<select id="selLinkAppShade" class="link-appshade-select"></select>';
+        html += '<label for="selLinkAppShade">Select a shade</label>';
+        html += '</div>';
+        html += '<div class="button-container" style="text-align:center;margin-top:10px;">';
+        html += `<button type="button" style="display:inline-block;width:45%;margin:0 2%;" onclick="somfy.addShadeLink();">Link</button>`;
+        html += `<button type="button" style="display:inline-block;width:45%;margin:0 2%;" onclick="document.getElementById('divLinkShade').remove();">Cancel</button>`;
+        html += '</div></div>';
+        div.innerHTML = html;
+        document.getElementById('divSomfyLinks').appendChild(div);
+        // Fetch candidates (full list minus self and already-linked) and fill the select.
+        getJSON('/shades', (err, shades) => {
+            let allShades = (!err && Array.isArray(shades)) ? shades : [];
+            getJSON(`/shade?shadeId=${shadeId}`, (errShade, shade) => {
+                let current = (!errShade && shade) ? shade : { shadeId: shadeId, linkedRemotes: [] };
+                this.fillLinkCandidateSelect(current, allShades);
+            });
+        });
+        return div;
+    }
+    fillLinkCandidateSelect(shade, allShades) {
+        let sel = document.getElementById('selLinkAppShade');
+        if (!sel) return;
+        let candidates = this.linkCandidates(shade, allShades);
+        if (candidates.length === 0) {
+            sel.innerHTML = '<option value="" disabled selected>No other shades available to link</option>';
+            return;
+        }
+        let opts = '';
+        for (let i = 0; i < candidates.length; i++) {
+            let s = candidates[i];
+            let room = _rooms.find(x => x.roomId === s.roomId);
+            let prefix = (room && room.name && room.roomId !== 0) ? `${room.name}: ` : '';
+            opts += `<option value="${s.remoteAddress}">${prefix}${s.name} (${s.remoteAddress})</option>`;
+        }
+        sel.innerHTML = opts;
+    }
     // Link the chosen candidate shade's remote to the selected source shade.
     addShadeLink() {
         let src = document.getElementById('selLinkTabShade');
@@ -974,6 +1004,8 @@ class Somfy {
                 ui.serviceError(err);
                 return;
             }
+            let pop = document.getElementById('divLinkShade');
+            if (pop) pop.remove();
             this.loadShadeLinks();
         });
     }
diff --git a/data/sun-fill.svg b/data/sun-fill.svg
new file mode 100644
index 00000000..50b5b633
--- /dev/null
+++ b/data/sun-fill.svg
@@ -0,0 +1,8 @@
+<!--
+  Bootstrap Icons (sun-fill) — https://github.com/twbs/icons
+  Copyright (c) 2019-2024 The Bootstrap Authors
+  Licensed under the MIT License.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-sun-fill" viewBox="0 0 16 16">
+  <path d="M8 12a4 4 0 1 0 0-8 4 4 0 0 0 0 8M8 0a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 0m0 13a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 13m8-5a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2a.5.5 0 0 1 .5.5M3 8a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2A.5.5 0 0 1 3 8m10.657-5.657a.5.5 0 0 1 0 .707l-1.414 1.415a.5.5 0 1 1-.707-.708l1.414-1.414a.5.5 0 0 1 .707 0m-9.193 9.193a.5.5 0 0 1 0 .707L3.05 13.657a.5.5 0 0 1-.707-.707l1.414-1.414a.5.5 0 0 1 .707 0m9.193 2.121a.5.5 0 0 1-.707 0l-1.414-1.414a.5.5 0 0 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707M4.464 4.465a.5.5 0 0 1-.707 0L2.343 3.05a.5.5 0 1 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .708"/>
+</svg>
diff --git a/data/sun.svg b/data/sun.svg
new file mode 100644
index 00000000..3c025d04
--- /dev/null
+++ b/data/sun.svg
@@ -0,0 +1,8 @@
+<!--
+  Bootstrap Icons (sun) — https://github.com/twbs/icons
+  Copyright (c) 2019-2024 The Bootstrap Authors
+  Licensed under the MIT License.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-sun" viewBox="0 0 16 16">
+  <path d="M8 11a3 3 0 1 1 0-6 3 3 0 0 1 0 6m0 1a4 4 0 1 0 0-8 4 4 0 0 0 0 8M8 0a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 0m0 13a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 13m8-5a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2a.5.5 0 0 1 .5.5M3 8a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2A.5.5 0 0 1 3 8m10.657-5.657a.5.5 0 0 1 0 .707l-1.414 1.415a.5.5 0 1 1-.707-.708l1.414-1.414a.5.5 0 0 1 .707 0m-9.193 9.193a.5.5 0 0 1 0 .707L3.05 13.657a.5.5 0 0 1-.707-.707l1.414-1.414a.5.5 0 0 1 .707 0m9.193 2.121a.5.5 0 0 1-.707 0l-1.414-1.414a.5.5 0 0 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707M4.464 4.465a.5.5 0 0 1-.707 0L2.343 3.05a.5.5 0 1 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .708"/>
+</svg>
diff --git a/data/trash-fill.svg b/data/trash-fill.svg
new file mode 100644
index 00000000..fb6a3d1e
--- /dev/null
+++ b/data/trash-fill.svg
@@ -0,0 +1,8 @@
+<!--
+  Bootstrap Icons (trash-fill) — https://github.com/twbs/icons
+  Copyright (c) 2019-2024 The Bootstrap Authors
+  Licensed under the MIT License.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-trash-fill" viewBox="0 0 16 16">
+  <path d="M2.5 1a1 1 0 0 0-1 1v1a1 1 0 0 0 1 1H3v9a2 2 0 0 0 2 2h6a2 2 0 0 0 2-2V4h.5a1 1 0 0 0 1-1V2a1 1 0 0 0-1-1H10a1 1 0 0 0-1-1H7a1 1 0 0 0-1 1zm3 4a.5.5 0 0 1 .5.5v7a.5.5 0 0 1-1 0v-7a.5.5 0 0 1 .5-.5M8 5a.5.5 0 0 1 .5.5v7a.5.5 0 0 1-1 0v-7A.5.5 0 0 1 8 5m3 .5v7a.5.5 0 0 1-1 0v-7a.5.5 0 0 1 1 0"/>
+</svg>
diff --git a/data/widgets.css b/data/widgets.css
index e2e00a85..cba0e445 100644
--- a/data/widgets.css
+++ b/data/widgets.css
@@ -159,18 +159,6 @@
     width: 100%;
     box-sizing: border-box;
 }
-.linkappshade-hint {
-    font-size: .75em;
-    font-style: italic;
-    text-align: center;
-    padding: 0 0 4px;
-    opacity: .8;
-}
-.link-tab-label {
-    font-size: .8em;
-    color: #00bcd4;
-    padding: 4px 0 2px;
-}
 .info-text {
     font-size: 20px;
 }
diff --git a/main/web/WebFiles.cpp b/main/web/WebFiles.cpp
index f337954c..c1b1686f 100644
--- a/main/web/WebFiles.cpp
+++ b/main/web/WebFiles.cpp
@@ -36,6 +36,11 @@ const WebFiles::StaticFile WebFiles::s_files[] = {
     {"/HomeKit.svg", "/HomeKit.svg", "image/svg+xml", true},
     {"/house-fill.svg", "/house-fill.svg", "image/svg+xml", true},
     {"/house-gear-fill.svg", "/house-gear-fill.svg", "image/svg+xml", true},
+    {"/pencil-fill.svg", "/pencil-fill.svg", "image/svg+xml", true},
+    {"/trash-fill.svg", "/trash-fill.svg", "image/svg+xml", true},
+    {"/sun-fill.svg", "/sun-fill.svg", "image/svg+xml", true},
+    {"/sun.svg", "/sun.svg", "image/svg+xml", true},
+    {"/file-earmark-arrow-up.svg", "/file-earmark-arrow-up.svg", "image/svg+xml", true},
 };
 const size_t WebFiles::s_fileCount = sizeof(s_files) / sizeof(s_files[0]);
 

From fa21b5f4f14d79351f6df79236c8ccf831974db9 Mon Sep 17 00:00:00 2001
From: Matthias Jobst <matthias.jobst@gmx.net>
Date: Sat, 27 Jun 2026 20:51:24 +0200
Subject: [PATCH 4/8] Fix HomeKit accessory-AID NVS bloat

Key shade AIDs by stable id instead of name (with one-time migration of
existing name-keyed entries), and prune orphaned AID entries on boot and
shade delete. Stops hap_main filling the nvs partition, which broke PHY
calibration writes (0x1105). Adds an NVS-usage diagnostic at boot.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 main/HomeKit.cpp                    | 176 +++++++++++++++++++++++++++-
 main/HomeKit.h                      |  15 +++
 main/app_main.cpp                   |  59 ++++++++++
 main/somfy/SomfyShadeController.cpp |   1 +
 test/unit/stubs/HomeKit.h           |   1 +
 5 files changed, 249 insertions(+), 3 deletions(-)

diff --git a/main/HomeKit.cpp b/main/HomeKit.cpp
index 964395b2..5cd7ec95 100644
--- a/main/HomeKit.cpp
+++ b/main/HomeKit.cpp
@@ -2,8 +2,11 @@
 
 #include <cstdio>
 #include <cstring>
+#include <string>
+#include <vector>
 #include <esp_log.h>
 #include <esp_mac.h>
+#include <nvs.h>
 #include <hap.h>
 #include <hap_apple_chars.h>
 #include <hap_apple_servs.h>
@@ -15,6 +18,9 @@ static const char *s_TAG = "HomeKit";
 
 #define HAP_SETUP_ID "SMFY"
 
+// Namespace holding HAP's runtime keystore (see hap_platform_keystore).
+#define HAP_RUNTIME_NAMESPACE "hap_main"
+
 extern ConfigSettings settings;
 extern SomfyShadeController somfy;
 
@@ -36,6 +42,85 @@ static uint8_t directionToPositionState(int8_t direction)
     return HAP_POS_STATE_STOPPED;
 }
 
+/**
+ * @brief Build the stable HomeKit identity string for a shade.
+ *
+ * Derived from the immutable shade id (not the user-editable name), so it never
+ * changes across renames. Used both as the accessory serial number and as the
+ * key for HAP's persistent accessory-AID mapping. Keying the AID by this id keeps
+ * a shade's HomeKit AID — and therefore its room, scene and automation
+ * assignments — stable when it is renamed, and stays within the NVS key length
+ * limit that long shade names would otherwise exceed.
+ *
+ * @param shade Shade to identify. Must not be NULL.
+ * @param buf   Output buffer.
+ * @param len   Size of @p buf.
+ */
+static void shadeStableId(SomfyShade *shade, char *buf, size_t len)
+{
+    snprintf(buf, len, "SMF-%03d", shade->getShadeId());
+}
+
+/**
+ * @brief One-time migration of a shade's accessory AID from name-keyed to id-keyed.
+ *
+ * Firmware before the id-keying change stored the persistent HomeKit AID under the
+ * (mutable) shade name. To preserve a shade's AID — and therefore its HomeKit
+ * room, scene and automation assignments — across an OTA update, copy any legacy
+ * name-keyed entry to the stable id key and delete the old one. No-op once
+ * migrated, or for shades that never had a legacy entry. Runs in place on the
+ * existing `nvs` partition, so no data is lost on update.
+ *
+ * @note MIGRATION SHIM — introduced after v0.7.1. Pure backward-compatibility:
+ *       it does nothing on devices already on id-keyed AIDs. Remove this function
+ *       and its call in uniqueAidForShade() once the installed base has updated
+ *       past the introducing release (no device still holds name-keyed AIDs);
+ *       pruneOrphanAccessoryAids() then cleans up any stragglers anyway.
+ *
+ * @param shade Shade being registered. Must not be NULL.
+ * @param id    Stable id key for the shade (from shadeStableId()).
+ */
+static void migrateLegacyNamedAid(SomfyShade *shade, const char *id)
+{
+    if (shade->name[0] == '\0') return;
+
+    nvs_handle_t handle;
+    if (nvs_open_from_partition(CONFIG_HAP_PLATFORM_DEF_NVS_RUNTIME_PARTITION, HAP_RUNTIME_NAMESPACE,
+                                NVS_READWRITE, &handle) != ESP_OK)
+        return;
+
+    size_t sz = 0;
+    bool haveStable = (nvs_get_blob(handle, id, nullptr, &sz) == ESP_OK);
+
+    int aid = 0;
+    sz = sizeof(aid);
+    bool haveLegacy = (nvs_get_blob(handle, shade->name, &aid, &sz) == ESP_OK && sz == sizeof(aid));
+
+    if (!haveStable && haveLegacy && nvs_set_blob(handle, id, &aid, sizeof(aid)) == ESP_OK) {
+        nvs_erase_key(handle, shade->name);
+        nvs_commit(handle);
+        ESP_LOGI(s_TAG, "Migrated HomeKit AID %d: '%s' -> %s", aid, shade->name, id);
+    }
+    nvs_close(handle);
+}
+
+/**
+ * @brief Resolve (and persist on first use) the stable HomeKit AID for a shade.
+ *
+ * Migrates any pre-existing name-keyed AID first, so a shade keeps its AID across
+ * the upgrade to id-based keys.
+ *
+ * @param shade Shade to look up. Must not be NULL.
+ * @return Accessory instance id, stable across reboots and renames.
+ */
+static int uniqueAidForShade(SomfyShade *shade)
+{
+    char id[16];
+    shadeStableId(shade, id, sizeof(id));
+    migrateLegacyNamedAid(shade, id); // MIGRATION SHIM (post-v0.7.1) — removable, see function doc
+    return hap_get_unique_aid(id);
+}
+
 /**
  * @brief Retrieve the Window Covering service from a bridged accessory.
  *
@@ -151,7 +236,7 @@ static hap_acc_t *createShadeAccessory(SomfyShade *shade)
     uint8_t posState = directionToPositionState(shade->direction);
 
     char serial[24];
-    snprintf(serial, sizeof(serial), "SMF-%03d", shade->getShadeId());
+    shadeStableId(shade, serial, sizeof(serial));
 
     hap_acc_cfg_t cfg = {
         .name = shade->name,
@@ -225,7 +310,7 @@ void HomeKitClass::begin()
         if (shade->getShadeId() == 255 || shade->name[0] == '\0') continue;
         hap_acc_t *acc = createShadeAccessory(shade);
         if (acc) {
-            hap_add_bridged_accessory(acc, hap_get_unique_aid(shade->name));
+            hap_add_bridged_accessory(acc, uniqueAidForShade(shade));
             ESP_LOGI(s_TAG, "Added shade '%s' (id=%d)", shade->name, shade->getShadeId());
         }
     }
@@ -253,6 +338,8 @@ void HomeKitClass::begin()
 
     hap_start();
     _started = true;
+    // Reclaim AID entries left behind by shades renamed/deleted in a previous session.
+    pruneOrphanAccessoryAids();
     ESP_LOGI(s_TAG, "HomeKit bridge started");
 }
 
@@ -305,7 +392,7 @@ void HomeKitClass::addShade(SomfyShade *shade)
     if (!_started || !shade || shade->getShadeId() == 255 || shade->name[0] == '\0') return;
     hap_acc_t *acc = createShadeAccessory(shade);
     if (acc) {
-        hap_add_bridged_accessory(acc, hap_get_unique_aid(shade->name));
+        hap_add_bridged_accessory(acc, uniqueAidForShade(shade));
         hap_update_config_number();
         ESP_LOGI(s_TAG, "Dynamically added shade '%s'", shade->name);
     }
@@ -328,3 +415,86 @@ void HomeKitClass::removeShade(SomfyShade *shade)
         acc = hap_acc_get_next(acc);
     }
 }
+
+/**
+ * @brief Test whether a `hap_main` key is HAP identity/counter data that must be kept.
+ *
+ * HAP stores its accessory identity and config counters under fixed, well-known
+ * keys. Everything else in the namespace is a per-accessory `name -> AID` blob.
+ *
+ * @param key NVS key name.
+ * @return true if the key is a fixed HAP key and must never be pruned.
+ */
+static bool isFixedHapKey(const char *key)
+{
+    static const char *const kKeptKeys[] = {"acc_id",     "ltska",     "ltpka", "fw_rev",
+                                            "config_num", "state_num", "cur_aid"};
+    for (const char *kept : kKeptKeys) {
+        if (strcmp(key, kept) == 0) return true;
+    }
+    return false;
+}
+
+/**
+ * @brief Decide whether a `hap_main` blob is an orphaned accessory-AID entry.
+ *
+ * An entry is an orphan when it is a 4-byte (sizeof(int)) AID blob whose key is
+ * neither a fixed HAP key nor the stable id of a currently-registered shade. The
+ * size check is a safeguard: identity blobs (keys, ids, fw revision) are larger
+ * and counters are 2 bytes, so an unrecognised future key is only ever removed
+ * if it has the exact shape of an AID entry.
+ *
+ * @param handle Open handle on the HAP runtime keystore namespace.
+ * @param key    NVS key to evaluate.
+ * @return true if the entry should be deleted.
+ */
+static bool isOrphanAidEntry(nvs_handle_t handle, const char *key)
+{
+    if (isFixedHapKey(key)) return false;
+
+    size_t len = 0;
+    if (nvs_get_blob(handle, key, nullptr, &len) != ESP_OK) return false;
+    if (len != sizeof(int)) return false;
+
+    // Keep entries that match a shade HomeKit currently registers (same filter as begin()).
+    for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
+        SomfyShade *shade = &somfy.shades[i];
+        if (shade->getShadeId() == 255 || shade->name[0] == '\0') continue;
+        char id[16];
+        shadeStableId(shade, id, sizeof(id));
+        if (strcmp(key, id) == 0) return false;
+    }
+    return true;
+}
+
+void HomeKitClass::pruneOrphanAccessoryAids()
+{
+    if (!_started) return;
+
+    const char *partition = CONFIG_HAP_PLATFORM_DEF_NVS_RUNTIME_PARTITION;
+    nvs_handle_t handle;
+    if (nvs_open_from_partition(partition, HAP_RUNTIME_NAMESPACE, NVS_READWRITE, &handle) != ESP_OK) {
+        ESP_LOGW(s_TAG, "AID prune: cannot open NVS %s/%s", partition, HAP_RUNTIME_NAMESPACE);
+        return;
+    }
+
+    // Collect first, erase after — erasing during iteration invalidates the iterator.
+    std::vector<std::string> orphans;
+    nvs_iterator_t it = nullptr;
+    esp_err_t res = nvs_entry_find(partition, HAP_RUNTIME_NAMESPACE, NVS_TYPE_BLOB, &it);
+    while (res == ESP_OK) {
+        nvs_entry_info_t info;
+        nvs_entry_info(it, &info);
+        if (isOrphanAidEntry(handle, info.key)) orphans.emplace_back(info.key);
+        res = nvs_entry_next(&it);
+    }
+    nvs_release_iterator(it);
+
+    for (const std::string &key : orphans) nvs_erase_key(handle, key.c_str());
+    if (!orphans.empty()) nvs_commit(handle);
+    nvs_close(handle);
+
+    if (!orphans.empty())
+        ESP_LOGI(s_TAG, "AID prune: removed %u orphaned accessory entr%s", (unsigned)orphans.size(),
+                 orphans.size() == 1 ? "y" : "ies");
+}
diff --git a/main/HomeKit.h b/main/HomeKit.h
index 52a741e9..7d65c2d0 100644
--- a/main/HomeKit.h
+++ b/main/HomeKit.h
@@ -46,6 +46,21 @@ class HomeKitClass {
      */
     void resetPairings();
 
+    /**
+     * @brief Delete orphaned accessory-AID entries from the HomeKit runtime keystore.
+     *
+     * HAP persists one AID blob per bridged accessory (keyed by the shade's stable
+     * id) so AIDs stay constant across reboots; these are never pruned by the SDK,
+     * so deleted shades — and entries left over from older firmware that keyed by
+     * name — accumulate and fill the NVS partition. This removes every `hap_main`
+     * AID blob that no longer matches a live shade, while preserving the HAP
+     * identity/counter keys. Safe to call repeatedly; only runs once the HAP stack
+     * has started.
+     *
+     * Invoked on boot after the bridge is built, and whenever a shade is deleted.
+     */
+    void pruneOrphanAccessoryAids();
+
     /**
      * @brief Serialize HomeKit status to JSON for the /homekit API endpoint.
      *
diff --git a/main/app_main.cpp b/main/app_main.cpp
index 26498421..a1838f01 100644
--- a/main/app_main.cpp
+++ b/main/app_main.cpp
@@ -5,6 +5,7 @@
 // all initialisation and the poll loop run inside mainLoop which has a full
 // 8192-byte stack.
 
+#include <cstring>
 #include <esp_log.h>
 #include <esp_system.h>
 #include <esp_task_wdt.h>
@@ -28,6 +29,7 @@
 #include "Web.h"
 
 static void setCodeForHomeKit();
+static void logNvsUsage();
 
 ConfigSettings settings;
 Web webServer;
@@ -65,6 +67,7 @@ static void mainLoop(void *)
         ESP_LOGE(s_TAG, "Error mounting file system");
     settings.begin();
     setCodeForHomeKit();
+    logNvsUsage();
     if (WiFi.status() == WL_CONNECTED) WiFi.disconnect(true);
     vTaskDelay(pdMS_TO_TICKS(10));
     ESP_LOGI(s_TAG, "Initializing web server...");
@@ -167,6 +170,62 @@ static void setCodeForHomeKit()
     }
 }
 
+/**
+ * @brief Log NVS partition usage and a per-namespace entry breakdown.
+ *
+ * Diagnostic for the `nvs` partition filling up (seen as PHY calibration
+ * write failures, ESP_ERR_NVS_NOT_ENOUGH_SPACE 0x1105). HomeKit (HAP) stores
+ * its runtime pairing data in this same partition, so it can crowd out the app
+ * config and the PHY cal blob. Prints overall used/free/total entries and the
+ * number of keys per namespace so the dominant consumer can be identified.
+ */
+static void logNvsUsage()
+{
+    nvs_stats_t stats;
+    if (nvs_get_stats(NULL, &stats) == ESP_OK) {
+        ESP_LOGI(s_TAG, "NVS 'nvs' partition: used=%zu free=%zu total=%zu entries (%.0f%% full), namespaces=%zu",
+                 stats.used_entries, stats.free_entries, stats.total_entries,
+                 stats.total_entries ? 100.0f * stats.used_entries / stats.total_entries : 0.0f,
+                 stats.namespace_count);
+    } else {
+        ESP_LOGW(s_TAG, "NVS stats unavailable");
+        return;
+    }
+
+    // Tally keys per namespace. Namespace names are short (<= 15 chars); track a
+    // small fixed set of distinct names and their counts.
+    struct {
+        char name[16];
+        uint32_t count;
+    } seen[24] = {};
+    size_t distinct = 0;
+    uint32_t total = 0;
+
+    nvs_iterator_t it = NULL;
+    esp_err_t res = nvs_entry_find("nvs", NULL, NVS_TYPE_ANY, &it);
+    while (res == ESP_OK) {
+        nvs_entry_info_t info;
+        nvs_entry_info(it, &info);
+        total++;
+        size_t i = 0;
+        for (; i < distinct; i++) {
+            if (strncmp(seen[i].name, info.namespace_name, sizeof(seen[i].name)) == 0) break;
+        }
+        if (i == distinct && distinct < sizeof(seen) / sizeof(seen[0])) {
+            strncpy(seen[distinct].name, info.namespace_name, sizeof(seen[distinct].name) - 1);
+            distinct++;
+        }
+        if (i < sizeof(seen) / sizeof(seen[0])) seen[i].count++;
+        res = nvs_entry_next(&it);
+    }
+    nvs_release_iterator(it);
+
+    for (size_t i = 0; i < distinct; i++) {
+        ESP_LOGI(s_TAG, "  NVS ns [%s]: %lu keys", seen[i].name, seen[i].count);
+    }
+    ESP_LOGI(s_TAG, "NVS total keys enumerated: %lu", total);
+}
+
 /** @brief Linker stub — arduino-esp32 references setup() even when CONFIG_AUTOSTART_ARDUINO=n. */
 void setup() {}
 /** @brief Linker stub — arduino-esp32 references loop() even when CONFIG_AUTOSTART_ARDUINO=n. */
diff --git a/main/somfy/SomfyShadeController.cpp b/main/somfy/SomfyShadeController.cpp
index 6cb7dbaa..96577fda 100644
--- a/main/somfy/SomfyShadeController.cpp
+++ b/main/somfy/SomfyShadeController.cpp
@@ -247,6 +247,7 @@ bool SomfyShadeController::deleteShade(uint8_t shadeId)
             this->commandDispatcher.cmdQueue.reset(); // drop commands bound to the removed shade
         }
     }
+    homekit.pruneOrphanAccessoryAids(); // reclaim the deleted shade's AID entry
     this->store.commit();
     return true;
 }
diff --git a/test/unit/stubs/HomeKit.h b/test/unit/stubs/HomeKit.h
index 48ca7f2f..b760c5fc 100644
--- a/test/unit/stubs/HomeKit.h
+++ b/test/unit/stubs/HomeKit.h
@@ -10,6 +10,7 @@ class HomeKitClass {
     void notifyShadeState(SomfyShade *) {}
     void addShade(SomfyShade *) {}
     void removeShade(SomfyShade *) {}
+    void pruneOrphanAccessoryAids() {}
     void resetPairings() {}
     void toJSON(JsonResponse &) {}
     void end() {}

From cb9c3383388096349f724cd77868464d826023b8 Mon Sep 17 00:00:00 2001
From: Matthias Jobst <matthias.jobst@gmx.net>
Date: Sat, 27 Jun 2026 20:58:16 +0200
Subject: [PATCH 5/8] Remove NVS-usage boot diagnostic

It served its purpose diagnosing the hap_main bloat; drop the per-boot
per-key enumeration and its log noise.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 main/app_main.cpp | 59 -----------------------------------------------
 1 file changed, 59 deletions(-)

diff --git a/main/app_main.cpp b/main/app_main.cpp
index a1838f01..26498421 100644
--- a/main/app_main.cpp
+++ b/main/app_main.cpp
@@ -5,7 +5,6 @@
 // all initialisation and the poll loop run inside mainLoop which has a full
 // 8192-byte stack.
 
-#include <cstring>
 #include <esp_log.h>
 #include <esp_system.h>
 #include <esp_task_wdt.h>
@@ -29,7 +28,6 @@
 #include "Web.h"
 
 static void setCodeForHomeKit();
-static void logNvsUsage();
 
 ConfigSettings settings;
 Web webServer;
@@ -67,7 +65,6 @@ static void mainLoop(void *)
         ESP_LOGE(s_TAG, "Error mounting file system");
     settings.begin();
     setCodeForHomeKit();
-    logNvsUsage();
     if (WiFi.status() == WL_CONNECTED) WiFi.disconnect(true);
     vTaskDelay(pdMS_TO_TICKS(10));
     ESP_LOGI(s_TAG, "Initializing web server...");
@@ -170,62 +167,6 @@ static void setCodeForHomeKit()
     }
 }
 
-/**
- * @brief Log NVS partition usage and a per-namespace entry breakdown.
- *
- * Diagnostic for the `nvs` partition filling up (seen as PHY calibration
- * write failures, ESP_ERR_NVS_NOT_ENOUGH_SPACE 0x1105). HomeKit (HAP) stores
- * its runtime pairing data in this same partition, so it can crowd out the app
- * config and the PHY cal blob. Prints overall used/free/total entries and the
- * number of keys per namespace so the dominant consumer can be identified.
- */
-static void logNvsUsage()
-{
-    nvs_stats_t stats;
-    if (nvs_get_stats(NULL, &stats) == ESP_OK) {
-        ESP_LOGI(s_TAG, "NVS 'nvs' partition: used=%zu free=%zu total=%zu entries (%.0f%% full), namespaces=%zu",
-                 stats.used_entries, stats.free_entries, stats.total_entries,
-                 stats.total_entries ? 100.0f * stats.used_entries / stats.total_entries : 0.0f,
-                 stats.namespace_count);
-    } else {
-        ESP_LOGW(s_TAG, "NVS stats unavailable");
-        return;
-    }
-
-    // Tally keys per namespace. Namespace names are short (<= 15 chars); track a
-    // small fixed set of distinct names and their counts.
-    struct {
-        char name[16];
-        uint32_t count;
-    } seen[24] = {};
-    size_t distinct = 0;
-    uint32_t total = 0;
-
-    nvs_iterator_t it = NULL;
-    esp_err_t res = nvs_entry_find("nvs", NULL, NVS_TYPE_ANY, &it);
-    while (res == ESP_OK) {
-        nvs_entry_info_t info;
-        nvs_entry_info(it, &info);
-        total++;
-        size_t i = 0;
-        for (; i < distinct; i++) {
-            if (strncmp(seen[i].name, info.namespace_name, sizeof(seen[i].name)) == 0) break;
-        }
-        if (i == distinct && distinct < sizeof(seen) / sizeof(seen[0])) {
-            strncpy(seen[distinct].name, info.namespace_name, sizeof(seen[distinct].name) - 1);
-            distinct++;
-        }
-        if (i < sizeof(seen) / sizeof(seen[0])) seen[i].count++;
-        res = nvs_entry_next(&it);
-    }
-    nvs_release_iterator(it);
-
-    for (size_t i = 0; i < distinct; i++) {
-        ESP_LOGI(s_TAG, "  NVS ns [%s]: %lu keys", seen[i].name, seen[i].count);
-    }
-    ESP_LOGI(s_TAG, "NVS total keys enumerated: %lu", total);
-}
-
 /** @brief Linker stub — arduino-esp32 references setup() even when CONFIG_AUTOSTART_ARDUINO=n. */
 void setup() {}
 /** @brief Linker stub — arduino-esp32 references loop() even when CONFIG_AUTOSTART_ARDUINO=n. */

From d865b7d0d4a5fbdeccb880d01c245fb4c85c6033 Mon Sep 17 00:00:00 2001
From: Matthias Jobst <matthias.jobst@gmx.net>
Date: Fri, 3 Jul 2026 23:12:25 +0200
Subject: [PATCH 6/8] Move the virtual remote behind a button that appears when
 accessing SomfyTab in settings. Fixed a bug when adding 30 shades. Needed to
 extend the licenses because the remote is used from google.

---
 THIRD-PARTY-NOTICES.md                  |  1 +
 data/index.html                         | 20 +++++++-----
 data/main.css                           | 41 +++++++++++++++++++++++++
 data/settings_remote.svg                |  5 +++
 data/somfy.js                           |  6 ++++
 main/somfy/SomfyShadeController.cpp     |  3 +-
 main/web/WebFiles.cpp                   |  1 +
 main/web/WebShades.cpp                  |  2 +-
 test/unit/test_somfyShadeController.cpp | 23 ++++++++++++--
 9 files changed, 90 insertions(+), 12 deletions(-)
 create mode 100644 data/settings_remote.svg

diff --git a/THIRD-PARTY-NOTICES.md b/THIRD-PARTY-NOTICES.md
index b4e15264..c49346b6 100644
--- a/THIRD-PARTY-NOTICES.md
+++ b/THIRD-PARTY-NOTICES.md
@@ -14,6 +14,7 @@ retained below, and the full license texts ship alongside each component
 |---|---|---|---|
 | Bootstrap Icons (SVG files in `data/`: house-fill, house-gear-fill, pencil-fill, trash-fill, sun, sun-fill, file-earmark-arrow-up) | MIT | Copyright (c) 2019-2024 The Bootstrap Authors | https://github.com/twbs/icons |
 | QR Code Generator for JavaScript (`qrcode.min.js`) | MIT | Copyright (c) 2009 Kazuhiko Arase | http://www.d-project.com/ |
+| Material Symbols (`settings_remote.svg`) | Apache-2.0 | Copyright Google LLC | https://github.com/google/material-design-icons |
 
 ## Firmware libraries (`components/`)
 
diff --git a/data/index.html b/data/index.html
index 2d3e2857..8a4f37a9 100644
--- a/data/index.html
+++ b/data/index.html
@@ -8,9 +8,9 @@
     <meta name="apple-mobile-web-app-title" content="ESPSomfy RTS App">
     <meta name="apple-mobile-web-app-status-bar-style" content="black">
 
-    <link rel="stylesheet" href="main.css?v=v0.7.1v" type="text/css" />
-    <link rel="stylesheet" href="widgets.css?v=v0.7.1v" type="text/css" />
-    <link rel="stylesheet" href="icons.css?v=v0.7.1v" type="text/css" />
+    <link rel="stylesheet" href="main.css?v=v0.7.1z" type="text/css" />
+    <link rel="stylesheet" href="widgets.css?v=v0.7.1z" type="text/css" />
+    <link rel="stylesheet" href="icons.css?v=v0.7.1z" type="text/css" />
     <link rel="icon" type="image/png" href="favicon.png" />
 
     <!-- iPad retina icon -->
@@ -115,14 +115,14 @@
 
 
     <script type="text/javascript" src="qrcode.min.js"></script>
-    <script type="text/javascript" src="index.js?v=v0.7.1v"></script>
+    <script type="text/javascript" src="index.js?v=v0.7.1z"></script>
     <script type="text/javascript">
     // Cache-bust query appended to every versioned asset (CSS + scripts). It is the
     // app version plus a trailing asset-revision letter (e.g. v0.6.1a) so it stays
     // distinct from the firmware/application version. bump_version.sh resets every
     // version query token in this file to "<tag>a" on release; between releases bump
     // the letter by hand (a→b→c) when iterating on assets, then reflash the data partition.
-    window.assetVer = '?v=v0.7.1v';
+    window.assetVer = '?v=v0.7.1z';
     // Load remaining scripts one at a time so the ESP32 never receives
     // more than one file request simultaneously. The browser's preload
     // scanner would otherwise fetch all <script src> tags in parallel,
@@ -501,7 +501,8 @@ <h1 style="text-align: center;">
                     </div>
                 </div>
                 <div id="divSomfySettings" style="display:none;">
-                    <div class="subtab-container"><span class="selected" data-grpid="divSomfyRooms">Rooms</span><span class="" data-grpid="divSomfyMotors">Shades</span><span data-grpid="divSomfyGroups">Groups</span><span data-grpid="divSomfyLinks">Links</span><span data-grpid="divRepeater">Repeater</span><span class="tabname-virtual-remote" data-grpid="divVirtualRemote"></span></div>
+                    <div class="vr-fab" onclick="somfy.openVirtualRemote();" title="Virtual Remote"><span class="vr-fab-icon" aria-hidden="true"></span></div>
+                    <div class="subtab-container"><span class="" data-grpid="divSomfyMotors">Shades</span><span class="selected" data-grpid="divSomfyRooms">Rooms</span><span data-grpid="divSomfyGroups">Groups</span><span data-grpid="divSomfyLinks">Links</span><span data-grpid="divRepeater">Repeater</span></div>
                     <div id="divSomfyRooms" class="subtab-content" style="padding-top:10px;">
                         <div id="divRoomListContainer">
                             <div style="font-size:.8em;">Drag each item to set the order in which they appear in the list.</div>
@@ -874,8 +875,11 @@ <h1 style="text-align: center;">
                             </div>
                         </div>
                     </div>
-                    <div id="divVirtualRemote" style="display:none;" class="subtab-content" data-bitlength="56">
-                        <div class="field-group" style="margin-top:-18px;display:inline-block;width:100%;">
+                    <div id="divVirtualRemote" data-bitlength="56">
+                        <div class="button-container" style="text-align:right;padding:0;">
+                            <button type="button" onclick="somfy.closeVirtualRemote();" style="display:inline-block;width:auto;padding:6px 18px;margin-top:0;">Done</button>
+                        </div>
+                        <div class="field-group" style="margin-top:0;display:inline-block;width:100%;">
                             <select id="selVRMotor" style="width:100%;" onchange="document.getElementById('divVirtualRemote').setAttribute('data-bitlength', this.options[this.selectedIndex].getAttribute('data-bitlength'));">
                             </select>
                             <label for="selVRMotor">Select a Motor or Group</label>
diff --git a/data/main.css b/data/main.css
index 65551816..864dacee 100644
--- a/data/main.css
+++ b/data/main.css
@@ -677,6 +677,47 @@ div.wait-overlay > .lds-roller {
 #divVirtualRemote[data-bitlength="none"] div.vr-button {
     display:none;
 }
+/* Virtual Remote is launched from the floating button (.vr-fab). When open it
+   takes over the card in normal flow (so the card grows to fit all buttons at
+   full size) and the app chrome is hidden to reclaim vertical space. The toggle
+   class lives on #divContainer because the header/top-tabs are above the Somfy
+   area. */
+#divVirtualRemote {
+    display: none;
+}
+/* Show only the remote: at each level from the card down to the remote, hide
+   every sibling (header, firmware/wifi status, top tabs, subtab bar, FAB, the
+   active subtab). New chrome added later is hidden automatically. */
+#divContainer.vr-open > #divAuthenticated > *:not(#divConfigPnl),
+#divContainer.vr-open #divConfigPnl > *:not(#divSomfySettings),
+#divContainer.vr-open #divSomfySettings > *:not(#divVirtualRemote) {
+    display: none;
+}
+#divContainer.vr-open #divVirtualRemote {
+    display: block;
+}
+.vr-fab {
+    position: absolute;
+    right: 16px;
+    bottom: 16px;
+    width: 52px;
+    height: 52px;
+    border-radius: 50%;
+    background-color: #00bcd4;
+    box-shadow: 0 3px 8px rgba(0, 0, 0, 0.3);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    z-index: 55;
+}
+.vr-fab-icon {
+    width: 28px;
+    height: 28px;
+    background-color: #fff;
+    -webkit-mask: url('/settings_remote.svg') center / contain no-repeat;
+            mask: url('/settings_remote.svg') center / contain no-repeat;
+}
 .shade-positioner {
     position: absolute;
     width: 100%;
diff --git a/data/settings_remote.svg b/data/settings_remote.svg
new file mode 100644
index 00000000..feb37df6
--- /dev/null
+++ b/data/settings_remote.svg
@@ -0,0 +1,5 @@
+<!--
+  Material Symbols (settings_remote) — https://github.com/google/material-design-icons
+  Copyright Google LLC. Licensed under the Apache License, Version 2.0.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="currentColor"><path d="M360-40q-17 0-28.5-11.5T320-80v-480q0-17 11.5-28.5T360-600h240q17 0 28.5 11.5T640-560v480q0 17-11.5 28.5T600-40H360Zm120-350q21 0 35.5-14.5T530-440q0-21-14.5-35.5T480-490q-21 0-35.5 14.5T430-440q0 21 14.5 35.5T480-390ZM338-662l-56-56q40-40 91-61t107-21q56 0 107 21t91 61l-56 56q-29-29-65.5-43.5T480-720q-40 0-76.5 14.5T338-662ZM226-774l-58-58q63-61 143.5-94.5T480-960q88 0 168.5 33.5T790-830l-56 56q-50-52-116-79t-138-27q-72 0-138 27t-116 79Zm174 654h160v-400H400v400Zm0 0h160-160Z"/></svg>
diff --git a/data/somfy.js b/data/somfy.js
index 6d1d86fc..bb3ba2c8 100644
--- a/data/somfy.js
+++ b/data/somfy.js
@@ -2026,6 +2026,12 @@ class Somfy {
             if (typeof cb === 'function') cb(err, group);
         });
     }
+    openVirtualRemote() {
+        document.getElementById('divContainer').classList.add('vr-open');
+    }
+    closeVirtualRemote() {
+        document.getElementById('divContainer').classList.remove('vr-open');
+    }
     sendVRCommand(el) {
         let pnl = document.getElementById('divVirtualRemote');
         let dd = pnl.querySelector('#selVRMotor');
diff --git a/main/somfy/SomfyShadeController.cpp b/main/somfy/SomfyShadeController.cpp
index 96577fda..468a738e 100644
--- a/main/somfy/SomfyShadeController.cpp
+++ b/main/somfy/SomfyShadeController.cpp
@@ -148,7 +148,7 @@ uint8_t SomfyShadeController::getNextShadeId()
 {
     // There is no shortcut for this since the deletion of
     // a shade in the middle makes all of this very difficult.
-    for (uint8_t i = 1; i < SOMFY_MAX_SHADES - 1; i++) {
+    for (uint8_t i = 1; i <= SOMFY_MAX_SHADES; i++) {
         bool id_exists = false;
         for (uint8_t j = 0; j < SOMFY_MAX_SHADES; j++) {
             SomfyShade *shade = &this->shades[j];
@@ -209,6 +209,7 @@ uint32_t SomfyShadeController::getNextRemoteAddress(uint8_t id)
 SomfyShade *SomfyShadeController::addShade(JsonObject &obj)
 {
     SomfyShade *shade = this->addShade();
+    if (!shade) return nullptr; // all shade slots are full
     shade->fromJSON(obj);
     shade->save();
     shade->emitState("shadeAdded");
diff --git a/main/web/WebFiles.cpp b/main/web/WebFiles.cpp
index c1b1686f..ee2ad052 100644
--- a/main/web/WebFiles.cpp
+++ b/main/web/WebFiles.cpp
@@ -41,6 +41,7 @@ const WebFiles::StaticFile WebFiles::s_files[] = {
     {"/sun-fill.svg", "/sun-fill.svg", "image/svg+xml", true},
     {"/sun.svg", "/sun.svg", "image/svg+xml", true},
     {"/file-earmark-arrow-up.svg", "/file-earmark-arrow-up.svg", "image/svg+xml", true},
+    {"/settings_remote.svg", "/settings_remote.svg", "image/svg+xml", true},
 };
 const size_t WebFiles::s_fileCount = sizeof(s_files) / sizeof(s_files[0]);
 
diff --git a/main/web/WebShades.cpp b/main/web/WebShades.cpp
index 759c0910..70dd167c 100644
--- a/main/web/WebShades.cpp
+++ b/main/web/WebShades.cpp
@@ -282,7 +282,7 @@ void WebShades::handleAddShade(WebServer &server)
         JsonObject obj;
         if (!json.parseBody(obj)) return;
         ESP_LOGI(s_TAG, "Counting shades");
-        if (somfy.shadeCount() > SOMFY_MAX_SHADES) {
+        if (somfy.shadeCount() >= SOMFY_MAX_SHADES) {
             json.respondJson().error("Maximum number of shades exceeded.");
             return;
         }
diff --git a/test/unit/test_somfyShadeController.cpp b/test/unit/test_somfyShadeController.cpp
index 73c22281..c47f0963 100644
--- a/test/unit/test_somfyShadeController.cpp
+++ b/test/unit/test_somfyShadeController.cpp
@@ -9,6 +9,7 @@
 #include "ShadeConfigFile.h" // for stub counter externs
 #include "GitOTA.h"
 #include <cstring>
+#include <set>
 #include <gtest/gtest.h>
 
 // ── extern globals defined in globals_stub.cpp ──────────────────────────────
@@ -88,7 +89,7 @@ TEST_F(ControllerTest, GetNextShadeId_GapInMiddle_ReturnsGap)
 
 TEST_F(ControllerTest, GetNextShadeId_AllSlotsUsed_Returns255)
 {
-    for (uint8_t i = 0; i < SOMFY_MAX_SHADES - 2; i++)
+    for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++)
         somfy.shades[i].setShadeId(i + 1);
     EXPECT_EQ(somfy.getNextShadeId(), 255);
 }
@@ -427,11 +428,29 @@ INSTANTIATE_TEST_SUITE_P(SortOrderRange, AddShadeSortOrderTest,
 
 TEST_F(ControllerTest, AddShade_NoIdAvailable_ReturnsNull)
 {
-    for (uint8_t i = 0; i < SOMFY_MAX_SHADES - 2; i++)
+    for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++)
         somfy.shades[i].setShadeId(i + 1);
     EXPECT_EQ(somfy.addShade(), nullptr);
 }
 
+// Guards the full capacity: addShade() must succeed exactly SOMFY_MAX_SHADES
+// times, handing out distinct ids 1..SOMFY_MAX_SHADES, before it runs out of
+// slots. Catches any off-by-one that shrinks usable capacity below the array.
+TEST_F(ControllerTest, AddShade_FillsAllSlots_ThenReturnsNull)
+{
+    std::set<uint8_t> seenIds;
+    for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
+        auto *s = somfy.addShade();
+        ASSERT_NE(s, nullptr) << "addShade() failed at slot " << static_cast<int>(i);
+        const uint8_t id = s->getShadeId();
+        EXPECT_GE(id, 1u);
+        EXPECT_LE(id, SOMFY_MAX_SHADES);
+        EXPECT_TRUE(seenIds.insert(id).second) << "duplicate shade id " << static_cast<int>(id);
+    }
+    EXPECT_EQ(seenIds.size(), static_cast<size_t>(SOMFY_MAX_SHADES));
+    EXPECT_EQ(somfy.addShade(), nullptr);
+}
+
 TEST_F(ControllerTest, AddRoom_Empty_ReturnsRoomWithId1)
 {
     auto *r = somfy.roomController.addRoom();

From cc95061122209a9f0b6b784b6da1facee027cab7 Mon Sep 17 00:00:00 2001
From: Matthias Jobst <matthias.jobst@gmx.net>
Date: Sun, 5 Jul 2026 23:22:00 +0200
Subject: [PATCH 7/8] Fixed bug with max shades, rooms and groups.

---
 main/somfy/SomfyGroupController.cpp     | 23 +++++--
 main/somfy/SomfyRoomController.cpp      | 17 ++++-
 main/somfy/SomfyShadeController.cpp     | 18 +++--
 main/web/WebGroups.cpp                  |  2 +-
 main/web/WebRooms.cpp                   |  2 +-
 test/unit/test_somfyShadeController.cpp | 91 +++++++++++++++++++++++--
 6 files changed, 130 insertions(+), 23 deletions(-)

diff --git a/main/somfy/SomfyGroupController.cpp b/main/somfy/SomfyGroupController.cpp
index 913bce38..38f3bb93 100644
--- a/main/somfy/SomfyGroupController.cpp
+++ b/main/somfy/SomfyGroupController.cpp
@@ -37,7 +37,7 @@ uint8_t SomfyGroupController::getNextGroupId()
 {
     // There is no shortcut for this since the deletion of
     // a group in the middle makes all of this very difficult.
-    for (uint8_t i = 1; i < SOMFY_MAX_GROUPS - 1; i++) {
+    for (uint8_t i = 1; i <= SOMFY_MAX_GROUPS; i++) {
         bool id_exists = false;
         for (uint8_t j = 0; j < SOMFY_MAX_GROUPS; j++) {
             SomfyGroup *group = &this->groups[j];
@@ -78,11 +78,21 @@ uint8_t SomfyGroupController::groupCount()
 SomfyGroup *SomfyGroupController::addGroup()
 {
     uint8_t groupId = this->getNextGroupId();
-    assert((groupId != 0) && (groupId != 255)); // getNextGroupId() returns 255 on failure
-    // The next id is the first slot with an id of 255, so a deleted middle slot
-    // gets reused. See addShade(): compute max before assigning id so the new
-    // (still id=255) slot is skipped by getMaxGroupOrder().
-    SomfyGroup *group = &this->groups[groupId - 1];
+    if (groupId == 0 || groupId == 255) return nullptr;
+    // The slot index is NOT groupId - 1: persistence compacts groups into the
+    // front slots on load, so slot N does not hold groupId N+1 after a reboot.
+    // Place the new group in the first empty slot and look it up by id (see
+    // addShade() for the shade equivalent of this bug).
+    SomfyGroup *group = nullptr;
+    for (uint8_t i = 0; i < SOMFY_MAX_GROUPS; i++) {
+        if (this->groups[i].getGroupId() == 255) {
+            group = &this->groups[i];
+            break;
+        }
+    }
+    if (!group) return nullptr;
+    // Compute max before assigning id so the new (still id=255) slot is skipped
+    // by getMaxGroupOrder().
     group->sortOrder = static_cast<int8_t>(this->getMaxGroupOrder() + 1);
     group->setGroupId(groupId);
     if (this->markDirty) this->markDirty();
@@ -93,6 +103,7 @@ SomfyGroup *SomfyGroupController::addGroup()
 SomfyGroup *SomfyGroupController::addGroup(JsonObject &obj)
 {
     SomfyGroup *group = this->addGroup();
+    if (!group) return nullptr;
     group->fromJSON(obj);
     group->save();
     group->emitState("groupAdded");
diff --git a/main/somfy/SomfyRoomController.cpp b/main/somfy/SomfyRoomController.cpp
index 49854eba..78e1ad33 100644
--- a/main/somfy/SomfyRoomController.cpp
+++ b/main/somfy/SomfyRoomController.cpp
@@ -26,7 +26,7 @@ SomfyRoom *SomfyRoomController::getRoomById(uint8_t roomId)
 
 uint8_t SomfyRoomController::getNextRoomId()
 {
-    for (uint8_t i = 1; i < SOMFY_MAX_ROOMS - 1; i++) {
+    for (uint8_t i = 1; i <= SOMFY_MAX_ROOMS; i++) {
         bool id_exists = false;
         for (uint8_t j = 0; j < SOMFY_MAX_ROOMS; j++) {
             SomfyRoom *room = &this->rooms[j];
@@ -67,8 +67,19 @@ uint8_t SomfyRoomController::roomCount()
 SomfyRoom *SomfyRoomController::addRoom()
 {
     uint8_t roomId = this->getNextRoomId();
-    assert(roomId != 0);
-    SomfyRoom *room = &this->rooms[roomId - 1];
+    if (roomId == 0) return nullptr;
+    // The slot index is NOT roomId - 1: persistence compacts rooms into the front
+    // slots on load, so slot N does not hold roomId N+1 after a reboot. Place the
+    // new room in the first empty slot (roomId == 0) and look it up by id (see
+    // addShade() for the shade equivalent of this bug).
+    SomfyRoom *room = nullptr;
+    for (uint8_t i = 0; i < SOMFY_MAX_ROOMS; i++) {
+        if (this->rooms[i].roomId == 0) {
+            room = &this->rooms[i];
+            break;
+        }
+    }
+    if (!room) return nullptr;
     room->sortOrder = static_cast<int8_t>(this->getMaxRoomOrder() + 1);
     room->roomId = roomId;
     if (this->markDirty) this->markDirty();
diff --git a/main/somfy/SomfyShadeController.cpp b/main/somfy/SomfyShadeController.cpp
index 468a738e..07cc89cb 100644
--- a/main/somfy/SomfyShadeController.cpp
+++ b/main/somfy/SomfyShadeController.cpp
@@ -220,12 +220,20 @@ SomfyShade *SomfyShadeController::addShade(JsonObject &obj)
 SomfyShade *SomfyShadeController::addShade()
 {
     uint8_t shadeId = this->getNextShadeId();
-    // So the next shade id will be the first one we run into with an id of 255 so
-    // if it gets deleted in the middle then it will get the first slot that is empty.
-    // There is no apparent way around this.  In the future we might actually add an indexer
-    // to it for sorting later.  The time has come so the sort order is set below.
     if (shadeId == 255) return nullptr;
-    SomfyShade *shade = &this->shades[shadeId - 1];
+    // The slot index is NOT the shadeId: persistence compacts shades into the
+    // front slots on load (ShadeConfigFile), so slot N does not hold shadeId N+1
+    // after a reboot. Place the new shade in the first empty slot and look it up
+    // by id everywhere else (getShadeById), rather than indexing by shadeId - 1
+    // which would overwrite whichever shade happens to occupy that slot.
+    SomfyShade *shade = nullptr;
+    for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
+        if (this->shades[i].getShadeId() == 255) {
+            shade = &this->shades[i];
+            break;
+        }
+    }
+    if (!shade) return nullptr;
     // Compute the max BEFORE assigning the new id, so the new (still id=255)
     // slot is skipped by getMaxShadeOrder() and doesn't contribute its own
     // freshly-cleared sortOrder=0 to the max.
diff --git a/main/web/WebGroups.cpp b/main/web/WebGroups.cpp
index 6827190f..d086a11a 100644
--- a/main/web/WebGroups.cpp
+++ b/main/web/WebGroups.cpp
@@ -191,7 +191,7 @@ void WebGroups::handleAddGroup(WebServer &server)
         JsonObject obj;
         if (!json.parseBody(obj)) return;
         ESP_LOGI(s_TAG, "Counting shades");
-        if (somfy.groupController.groupCount() > SOMFY_MAX_GROUPS) {
+        if (somfy.groupController.groupCount() >= SOMFY_MAX_GROUPS) {
             json.respondJson().error("Maximum number of groups exceeded.");
             return;
         } else {
diff --git a/main/web/WebRooms.cpp b/main/web/WebRooms.cpp
index ef9c350a..9f2e9615 100644
--- a/main/web/WebRooms.cpp
+++ b/main/web/WebRooms.cpp
@@ -142,7 +142,7 @@ void WebRooms::handleAddRoom(WebServer &server)
         JsonObject obj;
         if (!json.parseBody(obj)) return;
         ESP_LOGI(s_TAG, "Counting rooms");
-        if (somfy.roomController.roomCount() > SOMFY_MAX_ROOMS) {
+        if (somfy.roomController.roomCount() >= SOMFY_MAX_ROOMS) {
             json.respondJson().error("Maximum number of rooms exceeded.");
             return;
         } else {
diff --git a/test/unit/test_somfyShadeController.cpp b/test/unit/test_somfyShadeController.cpp
index c47f0963..f6fbe5b4 100644
--- a/test/unit/test_somfyShadeController.cpp
+++ b/test/unit/test_somfyShadeController.cpp
@@ -103,7 +103,7 @@ TEST_F(ControllerTest, GetNextGroupId_EmptyArray_Returns1)
 
 TEST_F(ControllerTest, GetNextGroupId_AllUsed_Returns255)
 {
-    for (uint8_t i = 0; i < SOMFY_MAX_GROUPS - 2; i++)
+    for (uint8_t i = 0; i < SOMFY_MAX_GROUPS; i++)
         somfy.groupController.groupSlot(i).setGroupId(i + 1);
     EXPECT_EQ(somfy.groupController.getNextGroupId(), 255);
 }
@@ -117,7 +117,7 @@ TEST_F(ControllerTest, GetNextRoomId_EmptyArray_Returns1)
 
 TEST_F(ControllerTest, GetNextRoomId_AllUsed_Returns0)
 {
-    for (uint8_t i = 0; i < SOMFY_MAX_ROOMS - 2; i++)
+    for (uint8_t i = 0; i < SOMFY_MAX_ROOMS; i++)
         somfy.roomController.roomSlot(i).roomId = i + 1;
     EXPECT_EQ(somfy.roomController.getNextRoomId(), 0);
 }
@@ -451,6 +451,29 @@ TEST_F(ControllerTest, AddShade_FillsAllSlots_ThenReturnsNull)
     EXPECT_EQ(somfy.addShade(), nullptr);
 }
 
+// Regression: after a mid-list delete + reload, persistence compacts shades
+// into the front slots, so slot index != shadeId - 1. addShade() must place the
+// new shade in a free slot without clobbering an existing shade that happens to
+// occupy slot (newId - 1). Reproduces the "add succeeds but loses a shade" bug.
+TEST_F(ControllerTest, AddShade_AfterCompaction_DoesNotClobberExistingShade)
+{
+    // Simulate the post-reload state: ids 1 and 3 packed into slots 0 and 1
+    // (as ShadeConfigFile would leave them after shade 2 was deleted).
+    somfy.shades[0].setShadeId(1);
+    somfy.shades[1].setShadeId(3);
+    // getNextShadeId() returns 2 (lowest free id); slot 2-1 == slot 1 holds id 3.
+    auto *s = somfy.addShade();
+    ASSERT_NE(s, nullptr);
+    EXPECT_EQ(s->getShadeId(), 2);
+    // The pre-existing shades must both survive.
+    ASSERT_NE(somfy.getShadeById(1), nullptr);
+    ASSERT_NE(somfy.getShadeById(3), nullptr);
+    ASSERT_NE(somfy.getShadeById(2), nullptr);
+    // The new shade must occupy its own slot, not shade 3's.
+    EXPECT_NE(somfy.getShadeById(2), somfy.getShadeById(3));
+    EXPECT_EQ(somfy.shadeCount(), 3);
+}
+
 TEST_F(ControllerTest, AddRoom_Empty_ReturnsRoomWithId1)
 {
     auto *r = somfy.roomController.addRoom();
@@ -459,14 +482,13 @@ TEST_F(ControllerTest, AddRoom_Empty_ReturnsRoomWithId1)
     EXPECT_TRUE(somfy.store.dirty);
 }
 
-TEST_F(ControllerTest, AddRoom_NoIdAvailable_Asserts)
+TEST_F(ControllerTest, AddRoom_NoIdAvailable_ReturnsNull)
 {
-    // addRoom() treats an exhausted id space as a programming error: getNextRoomId()
-    // returning 0 should be impossible in practice, so it asserts rather than
-    // returning nullptr. Fill every slot so the next id genuinely is 0.
+    // Adding a room when all slots are full is a user-reachable state, not a code
+    // invariant, so addRoom() returns nullptr instead of panicking.
     for (uint8_t i = 0; i < SOMFY_MAX_ROOMS; i++)
         somfy.roomController.roomSlot(i).roomId = i + 1;
-    EXPECT_DEATH(somfy.roomController.addRoom(), "roomId != 0");
+    EXPECT_EQ(somfy.roomController.addRoom(), nullptr);
 }
 
 TEST_F(ControllerTest, AddGroup_Empty_ReturnsGroupWithId1)
@@ -477,6 +499,61 @@ TEST_F(ControllerTest, AddGroup_Empty_ReturnsGroupWithId1)
     EXPECT_TRUE(somfy.store.dirty);
 }
 
+// Regression for the assert-panic crash: adding a group when all slots are full
+// must return nullptr, not abort. Also verifies the full capacity is usable.
+TEST_F(ControllerTest, AddGroup_FillsAllSlots_ThenReturnsNull)
+{
+    std::set<uint8_t> seenIds;
+    for (uint8_t i = 0; i < SOMFY_MAX_GROUPS; i++) {
+        auto *g = somfy.groupController.addGroup();
+        ASSERT_NE(g, nullptr) << "addGroup() failed at slot " << static_cast<int>(i);
+        EXPECT_TRUE(seenIds.insert(g->getGroupId()).second);
+    }
+    EXPECT_EQ(seenIds.size(), static_cast<size_t>(SOMFY_MAX_GROUPS));
+    EXPECT_EQ(somfy.groupController.addGroup(), nullptr);
+}
+
+// Regression: after compaction, slot index != groupId - 1, so addGroup() must
+// not clobber an existing group occupying slot (newId - 1).
+TEST_F(ControllerTest, AddGroup_AfterCompaction_DoesNotClobberExistingGroup)
+{
+    somfy.groupController.groupSlot(0).setGroupId(1);
+    somfy.groupController.groupSlot(1).setGroupId(3);
+    auto *g = somfy.groupController.addGroup();
+    ASSERT_NE(g, nullptr);
+    EXPECT_EQ(g->getGroupId(), 2);
+    ASSERT_NE(somfy.groupController.getGroupById(1), nullptr);
+    ASSERT_NE(somfy.groupController.getGroupById(3), nullptr);
+    EXPECT_NE(somfy.groupController.getGroupById(2), somfy.groupController.getGroupById(3));
+    EXPECT_EQ(somfy.groupController.groupCount(), 3);
+}
+
+// Room equivalents of the two group regressions above.
+TEST_F(ControllerTest, AddRoom_FillsAllSlots_ThenReturnsNull)
+{
+    std::set<uint8_t> seenIds;
+    for (uint8_t i = 0; i < SOMFY_MAX_ROOMS; i++) {
+        auto *r = somfy.roomController.addRoom();
+        ASSERT_NE(r, nullptr) << "addRoom() failed at slot " << static_cast<int>(i);
+        EXPECT_TRUE(seenIds.insert(r->roomId).second);
+    }
+    EXPECT_EQ(seenIds.size(), static_cast<size_t>(SOMFY_MAX_ROOMS));
+    EXPECT_EQ(somfy.roomController.addRoom(), nullptr);
+}
+
+TEST_F(ControllerTest, AddRoom_AfterCompaction_DoesNotClobberExistingRoom)
+{
+    somfy.roomController.roomSlot(0).roomId = 1;
+    somfy.roomController.roomSlot(1).roomId = 3;
+    auto *r = somfy.roomController.addRoom();
+    ASSERT_NE(r, nullptr);
+    EXPECT_EQ(r->roomId, 2);
+    ASSERT_NE(somfy.roomController.getRoomById(1), nullptr);
+    ASSERT_NE(somfy.roomController.getRoomById(3), nullptr);
+    EXPECT_NE(somfy.roomController.getRoomById(2), somfy.roomController.getRoomById(3));
+    EXPECT_EQ(somfy.roomController.roomCount(), 3);
+}
+
 // ══════════════════════════════════════════════════════════════════════════════
 // H  deleteShade / deleteRoom / deleteGroup
 // ══════════════════════════════════════════════════════════════════════════════

From 9f5d235cce3e7d155f9ed53588074562768775f0 Mon Sep 17 00:00:00 2001
From: Matthias Jobst <matthias.jobst@gmx.net>
Date: Wed, 8 Jul 2026 07:51:24 +0200
Subject: [PATCH 8/8] Fix shade/group/room add-at-capacity crashes; unify slot
 allocation

Guard capacity (return nullptr instead of null-deref/assert) and
decouple slot index from id, which persistence compacts on load.
Extract the shared lowest-free-id/first-empty-slot logic into
SlotArray.h with a per-type NO_ID sentinel, plus unit tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 main/somfy/SlotArray.h              |  72 +++++++++++++++
 main/somfy/SomfyGroup.cpp           |   4 +-
 main/somfy/SomfyGroup.h             |   8 +-
 main/somfy/SomfyGroupController.cpp |  40 ++-------
 main/somfy/SomfyRoom.cpp            |   2 +-
 main/somfy/SomfyRoom.h              |   8 +-
 main/somfy/SomfyRoomController.cpp  |  40 ++-------
 main/somfy/SomfyShadeController.cpp |  53 ++++-------
 main/somfy/shade/SomfyShade.cpp     |   4 +-
 main/somfy/shade/SomfyShade.h       |   8 +-
 test/unit/CMakeLists.txt            |   1 +
 test/unit/test_slotArray.cpp        | 133 ++++++++++++++++++++++++++++
 12 files changed, 265 insertions(+), 108 deletions(-)
 create mode 100644 main/somfy/SlotArray.h
 create mode 100644 test/unit/test_slotArray.cpp

diff --git a/main/somfy/SlotArray.h b/main/somfy/SlotArray.h
new file mode 100644
index 00000000..ee412c2a
--- /dev/null
+++ b/main/somfy/SlotArray.h
@@ -0,0 +1,72 @@
+// SlotArray.h — Generic slot-array helpers shared by the shade/group/room
+// controllers. Each controller owns a fixed-size array of records addressed by a
+// logical id (1..N) with a per-type empty-slot sentinel exposed as T::NO_ID
+// (see SomfyShade::NO_ID / SomfyGroup::NO_ID / SomfyRoom::NO_ID). Persistence
+// compacts records into the front slots on load, so the slot index is NOT the
+// id; these helpers keep the "lowest free id" and "first empty slot" logic in one
+// place so an off-by-one or sentinel change cannot diverge between the three.
+//
+// The array length N is deduced from the array reference, the sentinel is read
+// from T::NO_ID, and the id of a record is read via an ADL customization point:
+// each record type provides a free function `uint8_t slotId(T&)` (defined next to
+// the type). Callers therefore pass only the array.
+#pragma once
+#include <bitset>
+#include <concepts>
+#include <cstddef>
+#include <cstdint>
+
+namespace slots {
+
+/**
+ * @brief A record usable with the slot helpers: it exposes an empty-slot
+ *        sentinel `T::NO_ID` and an id readable via an ADL `slotId(T&)`.
+ *
+ * Constraining the helpers on this turns a missing `slotId` overload (or NO_ID)
+ * into a clear "constraint not satisfied" diagnostic at the call site rather than
+ * a deep template error from inside the loop body.
+ */
+template <typename T>
+concept SlotRecord = requires(T &rec) {
+    { slotId(rec) } -> std::convertible_to<uint8_t>;
+    { T::NO_ID } -> std::convertible_to<uint8_t>;
+};
+
+/**
+ * @brief Lowest logical id in [1, N] not currently held by any slot.
+ * @param slotArr Record array; its length N is the highest allocatable id.
+ * @return A free id, or T::NO_ID if the array is full.
+ */
+template <SlotRecord T, size_t N>
+uint8_t lowestFreeId(T (&slotArr)[N])
+{
+    static_assert(N <= 254, "id space (1..N) plus the sentinel must fit in uint8_t");
+    // Single pass: mark every in-use id, reading each slot's id exactly once, then
+    // return the lowest id not marked. The 1..N range check ignores empty slots for
+    // both sentinel conventions (NO_ID == 0 for rooms, 255 for shades/groups).
+    std::bitset<N + 1> inUse; // indexed by id; bit 0 unused
+    for (T &slot : slotArr) {
+        uint8_t id = slotId(slot);
+        if (id >= 1 && id <= N) inUse.set(id);
+    }
+    for (size_t id = 1; id <= N; id++) {
+        if (!inUse[id]) return static_cast<uint8_t>(id);
+    }
+    return T::NO_ID;
+}
+
+/**
+ * @brief First slot whose id equals the empty sentinel T::NO_ID.
+ * @param slotArr Record array.
+ * @return Pointer to the first empty slot, or nullptr if the array is full.
+ */
+template <SlotRecord T, size_t N>
+T *firstEmptySlot(T (&slotArr)[N])
+{
+    for (T &slot : slotArr) {
+        if (slotId(slot) == T::NO_ID) return &slot;
+    }
+    return nullptr;
+}
+
+} // namespace slots
diff --git a/main/somfy/SomfyGroup.cpp b/main/somfy/SomfyGroup.cpp
index 08853376..9f9cb014 100644
--- a/main/somfy/SomfyGroup.cpp
+++ b/main/somfy/SomfyGroup.cpp
@@ -17,10 +17,10 @@ extern MQTTClass mqtt;
 void SomfyGroup::clear()
 {
     ESP_LOGD(s_TAG, "Clearing group.");
-    this->setGroupId(255);
+    this->setGroupId(SomfyGroup::NO_ID);
     this->setRemoteAddress(0);
     this->repeats = 0;
-    this->roomId = 0;
+    this->roomId = SomfyRoom::NO_ID;
     this->sortOrder = 0;
     this->name[0] = 0x00;
     memset(&this->linkedShades, 0x00, sizeof(this->linkedShades));
diff --git a/main/somfy/SomfyGroup.h b/main/somfy/SomfyGroup.h
index 810a7cf3..74b6adfe 100644
--- a/main/somfy/SomfyGroup.h
+++ b/main/somfy/SomfyGroup.h
@@ -5,9 +5,12 @@
 
 class SomfyGroup : public SomfyRemote {
   protected:
-    uint8_t groupId = 255;
+    uint8_t groupId = 255; // = NO_ID; literal kept so the default is visible before NO_ID's declaration.
 
   public:
+    /// Sentinel id marking an empty group slot (0xFF erased-record convention).
+    /// Groups are allocated ids 1..SOMFY_MAX_GROUPS.
+    static constexpr uint8_t NO_ID = 255;
     uint8_t roomId = 0;
     uint8_t sortOrder = 0;
     group_types groupType = group_types::channel;
@@ -44,3 +47,6 @@ class SomfyGroup : public SomfyRemote {
     bool publish(const char *topic, uint16_t val, bool retain = false);
     bool publish(const char *topic, bool val, bool retain = false);
 };
+
+/// ADL id accessor for the SlotArray helpers (slots::lowestFreeId / firstEmptySlot).
+inline uint8_t slotId(SomfyGroup &group) { return group.getGroupId(); }
diff --git a/main/somfy/SomfyGroupController.cpp b/main/somfy/SomfyGroupController.cpp
index 38f3bb93..bc01a1e6 100644
--- a/main/somfy/SomfyGroupController.cpp
+++ b/main/somfy/SomfyGroupController.cpp
@@ -1,11 +1,9 @@
 #include "SomfyGroupController.h"
 #include <cassert>
-#include <esp_log.h>
 #include "SomfyGroup.h"
+#include "SlotArray.h"
 #include "WResp.h" // JsonResponse, used by toJSONGroups()
 
-static const char *s_TAG = "SomfyGroupController";
-
 SomfyGroupController::SomfyGroupController(std::function<void()> markDirty, std::function<void()> resetCommands)
     : markDirty(std::move(markDirty)), resetCommands(std::move(resetCommands))
 {}
@@ -35,23 +33,7 @@ SomfyGroup *SomfyGroupController::findGroupByRemoteAddress(uint32_t address)
 
 uint8_t SomfyGroupController::getNextGroupId()
 {
-    // There is no shortcut for this since the deletion of
-    // a group in the middle makes all of this very difficult.
-    for (uint8_t i = 1; i <= SOMFY_MAX_GROUPS; i++) {
-        bool id_exists = false;
-        for (uint8_t j = 0; j < SOMFY_MAX_GROUPS; j++) {
-            SomfyGroup *group = &this->groups[j];
-            if (group->getGroupId() == i) {
-                id_exists = true;
-                break;
-            }
-        }
-        if (!id_exists) {
-            ESP_LOGI(s_TAG, "Got next Group Id:%d", i);
-            return i;
-        }
-    }
-    return 255;
+    return slots::lowestFreeId(this->groups);
 }
 
 int8_t SomfyGroupController::getMaxGroupOrder()
@@ -59,7 +41,7 @@ int8_t SomfyGroupController::getMaxGroupOrder()
     int16_t order = -1;
     for (uint8_t i = 0; i < SOMFY_MAX_GROUPS; i++) {
         SomfyGroup *group = &this->groups[i];
-        if (group->getGroupId() == 255) continue;
+        if (group->getGroupId() == SomfyGroup::NO_ID) continue;
         if (order < group->sortOrder) order = group->sortOrder;
     }
     assert(order <= 127);
@@ -70,7 +52,7 @@ uint8_t SomfyGroupController::groupCount()
 {
     uint8_t count = 0;
     for (uint8_t i = 0; i < SOMFY_MAX_GROUPS; i++) {
-        if (this->groups[i].getGroupId() != 255) count++;
+        if (this->groups[i].getGroupId() != SomfyGroup::NO_ID) count++;
     }
     return count;
 }
@@ -78,18 +60,12 @@ uint8_t SomfyGroupController::groupCount()
 SomfyGroup *SomfyGroupController::addGroup()
 {
     uint8_t groupId = this->getNextGroupId();
-    if (groupId == 0 || groupId == 255) return nullptr;
+    if (groupId == 0 || groupId == SomfyGroup::NO_ID) return nullptr;
     // The slot index is NOT groupId - 1: persistence compacts groups into the
     // front slots on load, so slot N does not hold groupId N+1 after a reboot.
     // Place the new group in the first empty slot and look it up by id (see
     // addShade() for the shade equivalent of this bug).
-    SomfyGroup *group = nullptr;
-    for (uint8_t i = 0; i < SOMFY_MAX_GROUPS; i++) {
-        if (this->groups[i].getGroupId() == 255) {
-            group = &this->groups[i];
-            break;
-        }
-    }
+    SomfyGroup *group = slots::firstEmptySlot(this->groups);
     if (!group) return nullptr;
     // Compute max before assigning id so the new (still id=255) slot is skipped
     // by getMaxGroupOrder().
@@ -128,7 +104,7 @@ void SomfyGroupController::toJSONGroups(JsonResponse &json)
 {
     for (uint8_t i = 0; i < SOMFY_MAX_GROUPS; i++) {
         SomfyGroup &group = this->groups[i];
-        if (group.getGroupId() != 255) {
+        if (group.getGroupId() != SomfyGroup::NO_ID) {
             json.beginObject();
             group.toJSON(json);
             json.endObject();
@@ -140,7 +116,7 @@ void SomfyGroupController::updateGroupFlags()
 {
     for (uint8_t i = 0; i < SOMFY_MAX_GROUPS; i++) {
         SomfyGroup *group = &this->groups[i];
-        if (group->getGroupId() != 255) {
+        if (group->getGroupId() != SomfyGroup::NO_ID) {
             SomfyFlag oldFlags = group->flags;
             group->updateFlags();
             if (oldFlags != group->flags) group->emitState();
diff --git a/main/somfy/SomfyRoom.cpp b/main/somfy/SomfyRoom.cpp
index 51887fc3..5260fbfc 100644
--- a/main/somfy/SomfyRoom.cpp
+++ b/main/somfy/SomfyRoom.cpp
@@ -14,7 +14,7 @@ extern MQTTClass mqtt;
 
 void SomfyRoom::clear()
 {
-    this->roomId = 0;
+    this->roomId = SomfyRoom::NO_ID;
     this->sortOrder = 0;
     strcpy(this->name, "");
 }
diff --git a/main/somfy/SomfyRoom.h b/main/somfy/SomfyRoom.h
index 941876fa..c78f6443 100644
--- a/main/somfy/SomfyRoom.h
+++ b/main/somfy/SomfyRoom.h
@@ -5,7 +5,10 @@
 
 class SomfyRoom {
   public:
-    uint8_t roomId = 0;
+    /// Sentinel id marking an empty room slot (and the "no room" foreign-key
+    /// value stored on shades/groups). Rooms are allocated ids 1..SOMFY_MAX_ROOMS.
+    static constexpr uint8_t NO_ID = 0;
+    uint8_t roomId = NO_ID;
     char name[21] = "";
     uint8_t sortOrder = 0;
     void clear();
@@ -17,3 +20,6 @@ class SomfyRoom {
     void publish();
     void unpublish();
 };
+
+/// ADL id accessor for the SlotArray helpers (slots::lowestFreeId / firstEmptySlot).
+inline uint8_t slotId(SomfyRoom &room) { return room.roomId; }
diff --git a/main/somfy/SomfyRoomController.cpp b/main/somfy/SomfyRoomController.cpp
index 78e1ad33..9b821a40 100644
--- a/main/somfy/SomfyRoomController.cpp
+++ b/main/somfy/SomfyRoomController.cpp
@@ -1,11 +1,9 @@
 #include "SomfyRoomController.h"
 #include <cassert>
-#include <esp_log.h>
 #include "SomfyRoom.h"
+#include "SlotArray.h"
 #include "WResp.h" // JsonResponse, used by toJSONRooms()
 
-static const char *s_TAG = "SomfyRoomController";
-
 SomfyRoomController::SomfyRoomController(std::function<void()> markDirty, std::function<void(uint8_t)> onRoomRemoved)
     : markDirty(std::move(markDirty)), onRoomRemoved(std::move(onRoomRemoved))
 {}
@@ -26,21 +24,7 @@ SomfyRoom *SomfyRoomController::getRoomById(uint8_t roomId)
 
 uint8_t SomfyRoomController::getNextRoomId()
 {
-    for (uint8_t i = 1; i <= SOMFY_MAX_ROOMS; i++) {
-        bool id_exists = false;
-        for (uint8_t j = 0; j < SOMFY_MAX_ROOMS; j++) {
-            SomfyRoom *room = &this->rooms[j];
-            if (room->roomId == i) {
-                id_exists = true;
-                break;
-            }
-        }
-        if (!id_exists) {
-            ESP_LOGI(s_TAG, "Got next room Id:%d", i);
-            return i;
-        }
-    }
-    return 0;
+    return slots::lowestFreeId(this->rooms);
 }
 
 int8_t SomfyRoomController::getMaxRoomOrder()
@@ -48,7 +32,7 @@ int8_t SomfyRoomController::getMaxRoomOrder()
     int16_t order = -1;
     for (uint8_t i = 0; i < SOMFY_MAX_ROOMS; i++) {
         SomfyRoom *room = &this->rooms[i];
-        if (room->roomId == 0) continue;
+        if (room->roomId == SomfyRoom::NO_ID) continue;
         if (order < room->sortOrder) order = room->sortOrder;
     }
     assert(order <= 127);
@@ -59,7 +43,7 @@ uint8_t SomfyRoomController::roomCount()
 {
     uint8_t count = 0;
     for (uint8_t i = 0; i < SOMFY_MAX_ROOMS; i++) {
-        if (this->rooms[i].roomId != 0) count++;
+        if (this->rooms[i].roomId != SomfyRoom::NO_ID) count++;
     }
     return count;
 }
@@ -67,18 +51,12 @@ uint8_t SomfyRoomController::roomCount()
 SomfyRoom *SomfyRoomController::addRoom()
 {
     uint8_t roomId = this->getNextRoomId();
-    if (roomId == 0) return nullptr;
+    if (roomId == SomfyRoom::NO_ID) return nullptr;
     // The slot index is NOT roomId - 1: persistence compacts rooms into the front
     // slots on load, so slot N does not hold roomId N+1 after a reboot. Place the
-    // new room in the first empty slot (roomId == 0) and look it up by id (see
-    // addShade() for the shade equivalent of this bug).
-    SomfyRoom *room = nullptr;
-    for (uint8_t i = 0; i < SOMFY_MAX_ROOMS; i++) {
-        if (this->rooms[i].roomId == 0) {
-            room = &this->rooms[i];
-            break;
-        }
-    }
+    // new room in the first empty slot and look it up by id (see addShade() for
+    // the shade equivalent of this bug).
+    SomfyRoom *room = slots::firstEmptySlot(this->rooms);
     if (!room) return nullptr;
     room->sortOrder = static_cast<int8_t>(this->getMaxRoomOrder() + 1);
     room->roomId = roomId;
@@ -116,7 +94,7 @@ void SomfyRoomController::toJSONRooms(JsonResponse &json)
 {
     for (uint8_t i = 0; i < SOMFY_MAX_ROOMS; i++) {
         SomfyRoom *room = &this->rooms[i];
-        if (room->roomId != 0) {
+        if (room->roomId != SomfyRoom::NO_ID) {
             json.beginObject();
             room->toJSON(json);
             json.endObject();
diff --git a/main/somfy/SomfyShadeController.cpp b/main/somfy/SomfyShadeController.cpp
index 07cc89cb..00dbb03d 100644
--- a/main/somfy/SomfyShadeController.cpp
+++ b/main/somfy/SomfyShadeController.cpp
@@ -8,6 +8,7 @@
 #include <freertos/task.h>
 #include <WebServer.h>
 #include "SomfyShadeController.h"
+#include "SlotArray.h"
 #include "ConfigSettings.h"
 #include "GitOTA.h"
 #include "HomeKit.h"
@@ -63,7 +64,7 @@ void SomfyShadeController::applyDefaultBitLengths()
     bool saveFlag = false;
     for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
         SomfyShade *shade = &this->shades[i];
-        if (shade->getShadeId() != 255 && shade->bitLength == 0) {
+        if (shade->getShadeId() != SomfyShade::NO_ID && shade->bitLength == 0) {
             ESP_LOGD(s_TAG, "Setting bit length to %d", this->transceiver.config.type);
             shade->bitLength = this->transceiver.config.type;
             saveFlag = true;
@@ -85,21 +86,21 @@ char mqttTopicBuffer[55];
 void SomfyShadeController::processFrame(somfy_frame_t &frame, bool internal)
 {
     for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
-        if (this->shades[i].getShadeId() != 255) this->shades[i].processFrame(frame, internal);
+        if (this->shades[i].getShadeId() != SomfyShade::NO_ID) this->shades[i].processFrame(frame, internal);
     }
 }
 
 void SomfyShadeController::processWaitingFrame()
 {
     for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++)
-        if (this->shades[i].getShadeId() != 255) this->shades[i].processWaitingFrame();
+        if (this->shades[i].getShadeId() != SomfyShade::NO_ID) this->shades[i].processWaitingFrame();
 }
 
 void SomfyShadeController::emitState(uint8_t num)
 {
     for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
         SomfyShade *shade = &this->shades[i];
-        if (shade->getShadeId() == 255) continue;
+        if (shade->getShadeId() == SomfyShade::NO_ID) continue;
         shade->emitState(num);
     }
 }
@@ -110,7 +111,7 @@ void SomfyShadeController::publish()
     char arrIds[128] = "[";
     for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
         SomfyShade *shade = &this->shades[i];
-        if (shade->getShadeId() == 255) continue;
+        if (shade->getShadeId() == SomfyShade::NO_ID) continue;
         if (strlen(arrIds) > 1) strlcat(arrIds, ",", sizeof(arrIds));
         itoa(shade->getShadeId(), &arrIds[strlen(arrIds)], 10);
         shade->publish();
@@ -128,7 +129,7 @@ void SomfyShadeController::publish()
     strcpy(arrIds, "[");
     for (uint8_t i = 0; i < SOMFY_MAX_GROUPS; i++) {
         SomfyGroup *group = &this->groupController.groupSlot(i);
-        if (group->getGroupId() == 255) continue;
+        if (group->getGroupId() == SomfyGroup::NO_ID) continue;
         if (strlen(arrIds) > 1) strlcat(arrIds, ",", sizeof(arrIds));
         itoa(group->getGroupId(), &arrIds[strlen(arrIds)], 10);
         group->publish();
@@ -146,23 +147,7 @@ void SomfyShadeController::publish()
 
 uint8_t SomfyShadeController::getNextShadeId()
 {
-    // There is no shortcut for this since the deletion of
-    // a shade in the middle makes all of this very difficult.
-    for (uint8_t i = 1; i <= SOMFY_MAX_SHADES; i++) {
-        bool id_exists = false;
-        for (uint8_t j = 0; j < SOMFY_MAX_SHADES; j++) {
-            SomfyShade *shade = &this->shades[j];
-            if (shade->getShadeId() == i) {
-                id_exists = true;
-                break;
-            }
-        }
-        if (!id_exists) {
-            ESP_LOGI(s_TAG, "Got next Shade Id:%d", i);
-            return i;
-        }
-    }
-    return 255;
+    return slots::lowestFreeId(this->shades);
 }
 
 int8_t SomfyShadeController::getMaxShadeOrder()
@@ -170,7 +155,7 @@ int8_t SomfyShadeController::getMaxShadeOrder()
     int16_t order = -1;
     for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
         SomfyShade *shade = &this->shades[i];
-        if (shade->getShadeId() == 255) continue;
+        if (shade->getShadeId() == SomfyShade::NO_ID) continue;
         if (order < shade->sortOrder) order = shade->sortOrder;
     }
     assert(order <= 127);
@@ -181,7 +166,7 @@ uint8_t SomfyShadeController::shadeCount()
 {
     uint8_t count = 0;
     for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
-        if (this->shades[i].getShadeId() != 255) count++;
+        if (this->shades[i].getShadeId() != SomfyShade::NO_ID) count++;
     }
     return count;
 }
@@ -193,9 +178,9 @@ uint32_t SomfyShadeController::getNextRemoteAddress(uint8_t id)
     // The assumption here is that the max number of groups will
     // always be less than or equal to the max number of shades.
     while (i < SOMFY_MAX_SHADES) {
-        if ((i < SOMFY_MAX_SHADES && this->shades[i].getShadeId() != 255 &&
+        if ((i < SOMFY_MAX_SHADES && this->shades[i].getShadeId() != SomfyShade::NO_ID &&
              this->shades[i].getRemoteAddress() == address) ||
-            (i < SOMFY_MAX_GROUPS && this->groupController.groupSlot(i).getGroupId() != 255 &&
+            (i < SOMFY_MAX_GROUPS && this->groupController.groupSlot(i).getGroupId() != SomfyGroup::NO_ID &&
              this->groupController.groupSlot(i).getRemoteAddress() == address)) {
             address++;
             i = 0; // Start over we cannot share addresses.
@@ -220,19 +205,13 @@ SomfyShade *SomfyShadeController::addShade(JsonObject &obj)
 SomfyShade *SomfyShadeController::addShade()
 {
     uint8_t shadeId = this->getNextShadeId();
-    if (shadeId == 255) return nullptr;
+    if (shadeId == SomfyShade::NO_ID) return nullptr;
     // The slot index is NOT the shadeId: persistence compacts shades into the
     // front slots on load (ShadeConfigFile), so slot N does not hold shadeId N+1
     // after a reboot. Place the new shade in the first empty slot and look it up
     // by id everywhere else (getShadeById), rather than indexing by shadeId - 1
     // which would overwrite whichever shade happens to occupy that slot.
-    SomfyShade *shade = nullptr;
-    for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
-        if (this->shades[i].getShadeId() == 255) {
-            shade = &this->shades[i];
-            break;
-        }
-    }
+    SomfyShade *shade = slots::firstEmptySlot(this->shades);
     if (!shade) return nullptr;
     // Compute the max BEFORE assigning the new id, so the new (still id=255)
     // slot is skipped by getMaxShadeOrder() and doesn't contribute its own
@@ -281,7 +260,7 @@ void SomfyShadeController::toJSONShades(JsonResponse &json)
 {
     for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
         SomfyShade &shade = this->shades[i];
-        if (shade.getShadeId() != 255) {
+        if (shade.getShadeId() != SomfyShade::NO_ID) {
             json.beginObject();
             shade.toJSON(json);
             json.endObject();
@@ -292,7 +271,7 @@ void SomfyShadeController::toJSONShades(JsonResponse &json)
 void SomfyShadeController::tickShades()
 {
     for (uint8_t i = 0; i < SOMFY_MAX_SHADES; i++) {
-        if (this->shades[i].getShadeId() != 255) {
+        if (this->shades[i].getShadeId() != SomfyShade::NO_ID) {
             this->shades[i].checkMovement();
             this->shades[i].setGPIOs();
         }
diff --git a/main/somfy/shade/SomfyShade.cpp b/main/somfy/shade/SomfyShade.cpp
index 50f26e73..3ff84aad 100644
--- a/main/somfy/shade/SomfyShade.cpp
+++ b/main/somfy/shade/SomfyShade.cpp
@@ -18,10 +18,10 @@ extern GitUpdater git;
 
 void SomfyShade::clear()
 {
-    this->setShadeId(255);
+    this->setShadeId(SomfyShade::NO_ID);
     this->setRemoteAddress(0);
     this->sortOrder = 0;
-    this->roomId = 0;
+    this->roomId = SomfyRoom::NO_ID;
     movementTracker.reset();
     this->flagManager = SomfyFlagManager{};
     mqttPublisher.flipPosition = false;
diff --git a/main/somfy/shade/SomfyShade.h b/main/somfy/shade/SomfyShade.h
index 24b8ebc2..6021c928 100644
--- a/main/somfy/shade/SomfyShade.h
+++ b/main/somfy/shade/SomfyShade.h
@@ -16,6 +16,9 @@
 
 class SomfyShade : public SomfyRemote {
   public:
+    /// Sentinel id marking an empty shade slot (0xFF erased-record convention).
+    /// Shades are allocated ids 1..SOMFY_MAX_SHADES.
+    static constexpr uint8_t NO_ID = 255;
     SomfyShade()
     {
         mqttPublisher.shade = this;
@@ -156,10 +159,13 @@ class SomfyShade : public SomfyRemote {
     SomfyMovementTracker movementTracker;
 
   private:
-    uint8_t shadeId = 255;
+    uint8_t shadeId = NO_ID;
     void markShadeDataDirty();
 
     friend class SomfyCommandProcessor;
     friend class SomfyMovementTracker;
     friend class SomfyJSONSerializer;
 };
+
+/// ADL id accessor for the SlotArray helpers (slots::lowestFreeId / firstEmptySlot).
+inline uint8_t slotId(SomfyShade &shade) { return shade.getShadeId(); }
diff --git a/test/unit/CMakeLists.txt b/test/unit/CMakeLists.txt
index 33e7515f..651ddfed 100644
--- a/test/unit/CMakeLists.txt
+++ b/test/unit/CMakeLists.txt
@@ -65,6 +65,7 @@ add_executable(shade_tests
     test_somfyShadeController.cpp
     test_somfyGroup.cpp
     test_somfyRoom.cpp
+    test_slotArray.cpp
     test_authService.cpp
     ../../main/services/AuthService.cpp
     stubs/globals_stub.cpp
diff --git a/test/unit/test_slotArray.cpp b/test/unit/test_slotArray.cpp
new file mode 100644
index 00000000..a39a7f9f
--- /dev/null
+++ b/test/unit/test_slotArray.cpp
@@ -0,0 +1,133 @@
+// test_slotArray.cpp — Direct unit tests for the generic slot-array helpers.
+// Tested in isolation (no controller) with tiny record types so the "lowest free
+// id" and "first empty slot" logic is verified once, not only via the three
+// controllers that delegate to it. The array length is deduced, the sentinel is
+// read from T::NO_ID, and the id via an ADL slotId(T&), so the helpers take only
+// the array.
+#include <gtest/gtest.h>
+#include <set>
+#include <vector>
+#include "SlotArray.h"
+
+namespace {
+
+// Shade/group-style record: sentinel 255 (0xFF erased-record convention).
+struct Rec {
+    static constexpr uint8_t NO_ID = 255;
+    uint8_t id = NO_ID;
+};
+
+// Room-style record: sentinel 0, which doubles as the "full" return value.
+struct RecZero {
+    static constexpr uint8_t NO_ID = 0;
+    uint8_t id = NO_ID;
+};
+
+// ADL id accessors, mirroring the slotId(Somfy*&) overloads on the real records.
+uint8_t slotId(Rec &r) { return r.id; }
+uint8_t slotId(RecZero &r) { return r.id; }
+
+constexpr uint8_t CAP = 4;
+
+template <typename R, size_t N>
+void fill(R (&arr)[N], std::initializer_list<uint8_t> ids)
+{
+    size_t i = 0;
+    for (uint8_t id : ids) arr[i++].id = id;
+    for (; i < N; i++) arr[i].id = R::NO_ID;
+}
+
+// ── lowestFreeId (parameterized over occupancy scenarios) ─────────────────────
+// Each scenario runs against BOTH sentinel conventions (Rec=255, RecZero=0) so the
+// range guard that ignores empty slots is pinned for both NO_ID values. Occupied
+// ids are placed in the front slots (slot != id-1) to mimic post-compaction state.
+struct FreeIdCase {
+    const char *name;
+    std::vector<uint8_t> occupied;
+    int expectedFree; // >= 1: expected free id; -1: array full -> expect T::NO_ID
+};
+
+class LowestFreeIdTest : public ::testing::TestWithParam<FreeIdCase> {
+  protected:
+    static constexpr size_t kSize = 6;
+
+    template <typename R>
+    uint8_t run(const std::vector<uint8_t> &occupied)
+    {
+        R arr[kSize];
+        for (auto &slot : arr) slot.id = R::NO_ID;
+        size_t i = 0;
+        for (uint8_t id : occupied) arr[i++].id = id;
+        return slots::lowestFreeId(arr);
+    }
+};
+
+TEST_P(LowestFreeIdTest, MatchesForBothSentinels)
+{
+    const auto &c = GetParam();
+    if (c.expectedFree < 0) {
+        EXPECT_EQ(run<Rec>(c.occupied), Rec::NO_ID);
+        EXPECT_EQ(run<RecZero>(c.occupied), RecZero::NO_ID);
+    } else {
+        EXPECT_EQ(run<Rec>(c.occupied), static_cast<uint8_t>(c.expectedFree));
+        EXPECT_EQ(run<RecZero>(c.occupied), static_cast<uint8_t>(c.expectedFree));
+    }
+}
+
+INSTANTIATE_TEST_SUITE_P(
+    Scenarios, LowestFreeIdTest,
+    ::testing::Values(FreeIdCase{"Empty_ReturnsOne", {}, 1},
+                      FreeIdCase{"SkipsUsedPrefix", {1, 2}, 3},
+                      FreeIdCase{"ReusesLowGap", {2, 3}, 1},
+                      FreeIdCase{"ReusesMiddleGap", {1, 3, 4}, 2},
+                      FreeIdCase{"UsesFullCapacity", {1, 2, 3, 4, 5}, 6},
+                      FreeIdCase{"Full_ReturnsSentinel", {1, 2, 3, 4, 5, 6}, -1}),
+    [](const ::testing::TestParamInfo<FreeIdCase> &info) { return info.param.name; });
+
+// ── firstEmptySlot ────────────────────────────────────────────────────────────
+
+TEST(SlotArrayTest, FirstEmptySlot_EmptyArray_ReturnsFirst)
+{
+    Rec arr[CAP];
+    fill(arr, {});
+    EXPECT_EQ(slots::firstEmptySlot(arr), &arr[0]);
+}
+
+TEST(SlotArrayTest, FirstEmptySlot_ReturnsFirstHole)
+{
+    Rec arr[CAP];
+    fill(arr, {1, 3}); // slots 0,1 used; slot 2 is the first hole
+    EXPECT_EQ(slots::firstEmptySlot(arr), &arr[2]);
+}
+
+TEST(SlotArrayTest, FirstEmptySlot_FullArray_ReturnsNull)
+{
+    Rec arr[CAP];
+    fill(arr, {1, 2, 3, 4});
+    EXPECT_EQ(slots::firstEmptySlot(arr), nullptr);
+}
+
+// ── allocate-until-full cycle ─────────────────────────────────────────────────
+// Drives both helpers the way a controller's add*() does: for each of CAP
+// allocations, take the lowest free id, place it in the first empty slot, and
+// confirm exactly CAP distinct ids (1..CAP) fit before the array reports full.
+TEST(SlotArrayTest, AllocateUntilFull_FillsEverySlotThenReportsFull)
+{
+    Rec arr[CAP];
+    fill(arr, {});
+    std::set<uint8_t> seen;
+    for (uint8_t n = 0; n < CAP; n++) {
+        uint8_t id = slots::lowestFreeId(arr);
+        ASSERT_NE(id, Rec::NO_ID) << "ran out of ids after " << static_cast<int>(n) << " allocations";
+        Rec *slot = slots::firstEmptySlot(arr);
+        ASSERT_NE(slot, nullptr) << "ran out of slots after " << static_cast<int>(n) << " allocations";
+        slot->id = id;
+        EXPECT_TRUE(seen.insert(id).second) << "duplicate id " << static_cast<int>(id);
+    }
+    EXPECT_EQ(seen.size(), static_cast<size_t>(CAP));
+    // Array is now full: both helpers must report exhaustion.
+    EXPECT_EQ(slots::lowestFreeId(arr), Rec::NO_ID);
+    EXPECT_EQ(slots::firstEmptySlot(arr), nullptr);
+}
+
+} // namespace