Update copyright year to 2026

Log the resolved entity ID along with the button press event details.

.github/workflows/builder.yaml

@@ -21,7 +21,7 @@ jobs:
       changed: ${{ steps.changed_addons.outputs.changed }}
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Get changed files
         id: changed_files
@@ -68,7 +68,7 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Get information
         id: info
@@ -92,7 +92,7 @@ jobs:
 
       - name: Login to GitHub Container Registry
         if: env.BUILD_ARGS != '--test'
-        uses: docker/login-action@v3.5.0
+        uses: docker/login-action@v3.7.0
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
@@ -100,7 +100,7 @@ jobs:
 
       - name: Build ${{ matrix.addon }} add-on
         if: steps.check.outputs.build_arch == 'true'
-        uses: home-assistant/builder@2025.03.0
+        uses: home-assistant/builder@2025.09.0
         with:
           args: |
             ${{ env.BUILD_ARGS }} \

.github/workflows/codeql-analysis.yml

@@ -43,11 +43,11 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
+      uses: github/codeql-action/init@v4
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -58,7 +58,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v3
+      uses: github/codeql-action/autobuild@v4
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -72,4 +72,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      uses: github/codeql-action/analyze@v4

.github/workflows/docs-dev.yml

@@ -1,28 +0,0 @@
-name: docs-ci
-
-on:
-  workflow_dispatch:
-  push:
-    branches:
-      - dev
-    paths:
-      - docs/*
-      - .github/workflows/docs.yml
-      - mkdocs.yml
-      - HMI/README.md
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-      - run: pip install mkdocs-material mkdocs-video markdown-include mike
-      - run: cp HMI/README.md docs/hmi-serial-protocol.md
-      - run: git config --global user.name Docs deploy
-      - run: git config --global user.email docs@dummy.bot.com
-      - run: mike deploy --push --update-aliases dev

.github/workflows/docs-release.yml

@@ -6,24 +6,51 @@ on:
     branches:
       - main
     paths:
-      - docs/*
+      - docs/**
+      - docs-standalone/**
       - .github/workflows/docs-release.yml
       - mkdocs.yml
+      - docs-standalone/mkdocs.yml
       - HMI/README.md
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: 3.x
-      - run: pip install mkdocs-material mkdocs-video markdown-include mike
+      - run: pip install zensical
       - run: cp HMI/README.md docs/hmi-serial-protocol.md
-      - run: git config --global user.name Docs deploy
+      - run: zensical build --config-file mkdocs.yml
-      - run: git config --global user.email docs@dummy.bot.com
+      - run: mv site _site_main
-      - run: mike set-default stable
+      - run: zensical build --config-file docs-standalone/mkdocs.yml
-      - run: mike deploy --push --update-aliases stable
+      - run: mkdir -p _site/standalone _site/stable
+      - run: cp -a _site_main/. _site/
+      - run: cp -a _site_main/. _site/stable/
+      - run: |
+          if [ -d site-standalone ]; then
+            cp -a site-standalone/. _site/standalone/
+          elif [ -d docs-standalone/site ]; then
+            cp -a docs-standalone/site/. _site/standalone/
+          elif [ -d site ]; then
+            cp -a site/. _site/standalone/
+          elif [ -d docs-standalone/build ]; then
+            cp -a docs-standalone/build/. _site/standalone/
+          elif [ -d build ]; then
+            cp -a build/. _site/standalone/
+          else
+            echo "Standalone docs output not found (tried site-standalone, docs-standalone/site, site, docs-standalone/build, build)."
+            exit 1
+          fi
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: _site
+          force_orphan: true

.github/workflows/hacs-validation.yaml

@@ -11,7 +11,7 @@ jobs:
     name: HACS Action
     runs-on: "ubuntu-latest"
     steps:
-      - uses: "actions/checkout@v4"
+      - uses: "actions/checkout@v6"
       - name: HACS Action
         uses: "hacs/action@main"
         with:

.github/workflows/iobroker-localization.yml

@@ -18,7 +18,7 @@ jobs:
   gen-ioBroker-localization:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         ref: ${{ github.head_ref }}
 
@@ -28,7 +28,7 @@ jobs:
         python HMI/code_gen/localization/iobroker.py
         mv ioBroker_NSPanel_locales.json ioBroker/ioBroker_NSPanel_locales.json
         
-    - uses: stefanzweifel/git-auto-commit-action@v5
+    - uses: stefanzweifel/git-auto-commit-action@v7
       with:
         commit_message: Update iobroker localization file
         #file_pattern: "**.txt"

.github/workflows/lint.yaml

@@ -18,7 +18,7 @@ jobs:
       addons: ${{ steps.addons.outputs.addons_list }}
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: 🔍 Find add-on directories
         id: addons
@@ -33,9 +33,9 @@ jobs:
         path: ${{ fromJson(needs.find.outputs.addons) }}
     steps:
       - name: ⤵️ Check out code from GitHub
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: 🚀 Run Home Assistant Add-on Lint
-        uses: frenck/action-addon-linter@v2.18
+        uses: frenck/action-addon-linter@v2.21
         with:
           path: "./${{ matrix.path }}"

.github/workflows/nextion2text.yml

@@ -24,7 +24,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         ref: ${{ github.head_ref }}
 
@@ -80,7 +80,7 @@ jobs:
         find -name "**.txt"
         rm Nextion2Text.py* ignore-id.py out.txt
         
-    - uses: stefanzweifel/git-auto-commit-action@v5
+    - uses: stefanzweifel/git-auto-commit-action@v7
       with:
         commit_message: ${{ steps.last-commit-message.outputs.msg }} (add nextion2text)
         #file_pattern: "**.txt"

.gitignore

@@ -6,4 +6,31 @@ HMI/Nextion2Text.py
 panels.yaml
 
 # don't add Webstorm project stuff
-.idea
+.idea
+
+# General
+.DS_Store
+__MACOSX/
+.AppleDouble
+.LSOverride
+Icon[
+]
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk

HMI/US/portrait/diff-filtered.txt

@@ -1,4 +1,4 @@
-+++ /dev/fd/62	2024-11-22 20:00:11.734673876 +0000
++++ /dev/fd/62	2025-12-26 19:43:25.803166597 +0000
 +I/n2t-out/Program.s.txt
 ++ HMI/US/portrait/n2t-out/Program.s.txt
 +1 +12,11 @@

README.md

@@ -5,7 +5,7 @@ If you like this project consider buying me a pizza 🍕 <a href="https://paypal
 [![hacs_badge](https://img.shields.io/badge/HACS-Default-41BDF5.svg)](https://github.com/hacs/integration)
 ![hacs validation](https://github.com/joBr99/nspanel-lovelace-ui/actions/workflows/hacs-validation.yaml/badge.svg)
 [![GitHub Release](https://img.shields.io/github/release/joBr99/nspanel-lovelace-ui.svg)](https://github.com/joBr99/nspanel-lovelace-ui/releases)
-![Project Maintenance](https://img.shields.io/maintenance/yes/2024.svg)
+![Project Maintenance](https://img.shields.io/maintenance/yes/2026.svg)
 [![GitHub Activity](https://img.shields.io/github/commit-activity/y/joBr99/nspanel-lovelace-ui.svg)](https://github.com/joBr99/nspanel-lovelace-ui/commits/main)
 
 

apps/nspanel-lovelace-ui/luibackend/controller.py

@@ -151,7 +151,7 @@ class LuiController(object):
         items = self._config.get_all_entity_names()
         apis.ha_api.log(f"gtest123: {items}")
         prefixes = ("navigate.", "delete", "iText")
-        items = [x for x in items if not (x is None or x.startswith(prefixes))]
+        items = set([x for x in items if not (x is None or x.startswith(prefixes))])
         apis.ha_api.log(f"Registering callbacks for the following items: {items}")
         for item in items:
             if apis.ha_api.entity_exists(item):
@@ -206,11 +206,15 @@ class LuiController(object):
             self._pages_gen.generate_timer_detail_page(entity_id, True)
 
     def button_press(self, entity_id, button_type, value):
-        apis.ha_api.log(f"Button Press Event; entity_id: {entity_id}; button_type: {button_type}; value: {value} ")
+        #apis.ha_api.log(f"Button Press Event; entity_id: {entity_id}; button_type: {button_type}; value: {value} ")
+        entity_id_new = entity_id
         if entity_id.startswith('uuid'):
             entity_config = self._config._config_entites_table.get(entity_id)
             if entity_config is not None:
-                entity_id = entity_config.entityId
+                entity_id_new = entity_config.entityId
+        apis.ha_api.log(f"Button Press Event; entity_id: {entity_id}; entity_id_resolved: {entity_id_new}; button_type: {button_type}; value: {value} ")
+        entity_id = entity_id_new
+        
         # internal buttons
         if entity_id == "screensaver" and button_type == "bExit":
             # get default card if there is one

apps/nspanel-lovelace-ui/luibackend/pages.py

@@ -388,11 +388,12 @@ class LuiPagesGen(object):
             entityTypePanel = "text"
             unit = get_attr_safe(entity, "temperature_unit", "")
             rt = None
+            index = item.stype
             if type(item.stype) == str and ":" in item.stype and len(item.stype.split(":")) == 2:
                 spintstr = item.stype.split(":")
                 rt = spintstr[0]
-                item.stype = int(spintstr[1])
+                index = int(spintstr[1])
-            if type(item.stype) == int:
+            if type(index) == int:
                 bits = get_attr_safe(entity, "supported_features", 0b0)
                 if not rt:
                     rt = "daily"
@@ -407,8 +408,8 @@ class LuiPagesGen(object):
                     "weather/get_forecasts", target={"entity_id": entityId}, service_data={"type": rt}
                 )
                 forecast = results.get("result", {}).get("response", {}).get(entityId, {}).get('forecast') or entity.attributes.get('forecast', [])
-                if len(forecast) >= item.stype:
+                if len(forecast) >= index:
-                    day_forecast = forecast[item.stype]
+                    day_forecast = forecast[index]
                     fdate = dp.parse(day_forecast['datetime'])
                     global babel_spec
                     if babel_spec is not None:

docs-standalone/docs/_assets/user.css

@@ -0,0 +1,112 @@
+/*.md-header__button.md-logo img {
+	width: unset;
+}*/
+
+.md-main__inner {
+	margin-top: unset;
+}
+
+.md-nav__title {
+	display: none;
+}
+
+/*.md-header,*/ .md-footer,
+.md-footer-meta {
+	background-color: #333333;
+}
+
+/* Footer contrast fixes for Zensical/Material variants */
+:root {
+	--md-footer-bg-color: #333333;
+	--md-footer-bg-color--dark: #2b2b2b;
+	--md-footer-fg-color: #f2f2f2;
+	--md-footer-fg-color--light: #ffffff;
+	--md-footer-fg-color--lighter: #ffffff;
+}
+
+.md-footer,
+.md-footer-meta,
+.md-footer * {
+	color: #f2f2f2;
+}
+
+.md-footer a,
+.md-footer-meta a,
+.md-footer .md-footer__link {
+	color: #ffffff;
+}
+
+.md-footer a:hover,
+.md-footer-meta a:hover,
+.md-footer .md-footer__link:hover {
+	color: #d9e7ff;
+}
+
+.md-footer .md-icon svg,
+.md-footer-meta .md-icon svg {
+	fill: currentColor;
+}
+
+/* Zensical keeps footer content in the inner/meta containers.
+   Don't hide footer structure, only style it. */
+
+.md-sidebar {
+	padding-top: 0px;
+}
+
+/*.md-sidebar.md-sidebar--primary {
+	position: unset;
+}*/
+
+.md-sidebar.md-sidebar--secondary {
+	padding-top: 10px;
+}
+
+.md-sidebar.md-sidebar--primary .md-sidebar__scrollwrap {
+	/*overflow-y: unset;*/
+	padding-right: 1px;
+	border-right: 1px solid #adadad;
+}
+
+.md-sidebar.md-sidebar--primary .md-sidebar__inner {
+	/*border-right: 1px solid #adadad;*/
+	padding-bottom: 30px;
+}
+.md-sidebar.md-sidebar--secondary .md-sidebar__inner {
+	border-left: 1px solid #adadad;
+}
+
+.md-nav__item .md-nav__list {
+	padding-left: 10px;
+}
+
+.md-content {
+	margin-top: 25px;
+	/*border-left: 1px solid #adadad;
+	border-right: 1px solid #adadad;*/
+}
+
+.md-top {
+	display: none;
+}
+
+.md-typeset hr {
+	border-bottom: 1px solid #adadad;
+}
+
+.md-typeset h1,
+.md-typeset h2,
+.md-typeset h3,
+.md-typeset h4,
+.md-typeset h5 {
+	font-weight: bold;
+}
+
+.md-typeset table:not([class]) td:not(:last-child),
+.md-typeset table:not([class]) th:not(:last-child) {
+	border-right: .05rem solid var(--md-typeset-table-color);
+}
+
+ol li::marker {
+	font-weight: bold;
+}

docs-standalone/docs/cards.md

@@ -0,0 +1,137 @@
+# Cards
+
+## Supported card types
+
+- `cardEntities`
+- `cardGrid`
+- `cardQR`
+- `cardPower`
+- `cardMedia`
+- `cardThermo`
+- `cardAlarm`
+- `cardUnlock`
+
+## Common card keys
+
+key | required | type | description
+-- | -- | -- | --
+`type` | yes | string | Card type.
+`title` | no | string | Card title.
+`key` | no | string | Navigation key used by `navigate.<key>`.
+
+## `cardEntities` and `cardGrid`
+
+```yaml
+- type: cardEntities
+  title: Main
+  key: main
+  entities:
+    - entity: light.kitchen
+    - entity: navigate.settings
+      icon: mdi:cog
+```
+
+- `entities` is required.
+- `cardGrid` auto-switches to `cardGrid2` if more than 6 entities are present.
+
+## `cardQR`
+
+```yaml
+- type: cardQR
+  title: Guest WiFi
+  qrCode: "WIFI:S:myssid;T:WPA;P:mypassword;;"
+  entities:
+    - entity: iText.myssid
+      name: SSID
+      icon: mdi:wifi
+```
+
+Keys:
+
+- `qrCode` optional (default value exists, but set it explicitly)
+- supports optional `entity` / `entities`
+
+## `cardPower`
+
+```yaml
+- type: cardPower
+  title: Energy
+  entities:
+    - entity: sensor.house_power
+    - entity: delete
+    - entity: sensor.solar_power
+```
+
+Notes:
+
+- `entities` is required.
+- `speed` key is accepted in config but currently not applied by the renderer.
+
+## `cardMedia`
+
+```yaml
+- type: cardMedia
+  title: Living Room
+  entity: media_player.living_room
+  entities:
+    - entity: light.ambient
+    - entity: switch.tv_bias_light
+```
+
+Notes:
+
+- Main media entity must exist (`entity` or first generated entity).
+- Additional `entities` are rendered as action buttons on the bottom row.
+
+## `cardThermo`
+
+```yaml
+- type: cardThermo
+  title: Heating
+  entity: climate.downstairs
+  supported_modes: ["heat", "off"]
+```
+
+Keys:
+
+- `entity` required
+- `supported_modes` optional (filters shown HVAC mode buttons)
+
+## `cardAlarm`
+
+```yaml
+- type: cardAlarm
+  title: House Alarm
+  entity: alarm_control_panel.house
+  supported_modes: ["arm_home", "arm_away", "arm_night"]
+```
+
+Keys:
+
+- `entity` required
+- `supported_modes` optional
+
+## `cardUnlock`
+
+```yaml
+- type: cardUnlock
+  title: Admin
+  pin: 1234
+  destination: navigate.admin
+```
+
+Keys:
+
+- `pin` required
+- `destination` required
+
+Typical target in `hiddenCards`:
+
+```yaml
+hiddenCards:
+  - type: cardGrid
+    key: admin
+    title: Admin
+    entities:
+      - entity: switch.maintenance_mode
+```

docs-standalone/docs/configuration.md

@@ -0,0 +1,61 @@
+# Configuration
+
+The runtime reads one YAML file (default: `./panels.yaml`, add-on mode: `/config/panels.yaml`).
+
+## Top-level keys
+
+key | required | type | default | description
+-- | -- | -- | -- | --
+`nspanels` | yes | object | none | Map of panel definitions.
+`home_assistant_address` | recommended | string | none | Home Assistant base URL. In add-on mode it is auto-filled as `http://supervisor` if missing.
+`home_assistant_token` | recommended | string | none | Long-lived token or Supervisor token.
+`mqtt_server` | required in MQTT mode | string | from env | MQTT host.
+`mqtt_port` | required in MQTT mode | int | from env | MQTT port.
+`mqtt_username` | required in MQTT mode | string | from env | MQTT username.
+`mqtt_password` | required in MQTT mode | string | from env | MQTT password.
+`use_ha_api` | optional | any | absent | If present, MQTT input mode is disabled and HA event mode is used.
+`timeZone` | optional | string | `Europe/Berlin` | Global fallback for panel `timeZone`.
+`hiddenCards` | optional | list | `[]` | Global fallback for panel `hiddenCards`.
+
+## Panel keys (`nspanels.<name>`)
+
+key | required | type | default | description
+-- | -- | -- | -- | --
+`panelRecvTopic` | yes | string | none | Receive channel for panel events.
+`panelSendTopic` | yes | string | none | Send channel for panel commands.
+`locale` | yes | string | none | Locale used for translations and date formatting.
+`timeZone` | recommended | string | from top-level `timeZone` | Time zone for clock.
+`timeFormat` | yes | string | none | Python `strftime` format.
+`dateFormat` | yes | string | none | Babel date format (example: `full`, `medium`).
+`model` | optional | string | `eu` | Panel model (`eu`, `us-p`, `us-l`).
+`temp_unit` | optional | string | `celsius` | Thermostat card unit (`celsius` or `fahrenheit`).
+`sleepTimeout` | optional | int | `20` | Seconds before screensaver.
+`sleepBrightness` | optional | int or entity_id | `10` | Screensaver brightness.
+`screenBrightness` | optional | int or entity_id | `100` | Active-screen brightness.
+`sleepTracking` | optional | entity_id | none | Forces sleep brightness to 0 when entity state matches `sleepTrackingZones`.
+`sleepTrackingZones` | optional | list | `["not_home", "off"]` | States that trigger forced dimming.
+`sleepOverride` | optional | object | none | Override sleep brightness when entity is `on`/`true`/`home`.
+`defaultBackgroundColor` | optional | string | `ha-dark` | `ha-dark` or `black`.
+`featExperimentalSliders` | optional | int | `0` | Forwarded in dimmode command.
+`defaultCard` | optional | string | none | Default card when leaving screensaver (`navigate.<key>`).
+`screensaver` | yes | object | none | Screensaver definition.
+`cards` | yes | list | none | Top-level cards.
+`hiddenCards` | optional | list | `[]` | Hidden cards addressable through `navigate.<key>`.
+
+## Brightness behavior
+
+- Integer values are used directly.
+- Entity values read Home Assistant state and cast to number.
+- List/schedule style brightness is not supported in this rewrite.
+
+Example:
+
+```yaml
+sleepBrightness: input_number.nspanel_sleep
+screenBrightness: input_number.nspanel_awake
+sleepTracking: person.john
+sleepTrackingZones: ["not_home", "off"]
+sleepOverride:
+  entity: light.bedroom
+  brightness: 30
+```

docs-standalone/docs/connection-modes.md

@@ -0,0 +1,45 @@
+# Connection Modes
+
+The rewrite supports two panel input/output modes.
+
+## 1) MQTT mode (default)
+
+Enabled when:
+
+- `mqtt_server` is configured
+- `use_ha_api` is not present
+
+Behavior:
+
+- Subscribes to every panel `panelRecvTopic`
+- Expects JSON payload containing `CustomRecv`
+- Publishes commands to `panelSendTopic`
+
+Example receive payload:
+
+```json
+{"CustomRecv":"event,startup,54,eu"}
+```
+
+## 2) Home Assistant API mode (`use_ha_api`)
+
+Enabled when key `use_ha_api` exists in config.
+
+Behavior:
+
+- Subscribes to HA event `esphome.nspanel.data`
+- Routes events by `device_id` (must match configured `panelRecvTopic`)
+- Sends panel commands by calling Home Assistant service:
+  - `<panelSendTopic>_nspanelui_api_call`
+
+Service payload shape:
+
+```yaml
+data: "...panel command..."
+command: 2
+```
+
+## Common to both modes
+
+- Home Assistant websocket connection is used for entity state cache and service calls.
+- UI actions (button presses, sliders, mode selects) are translated to Home Assistant service calls.

docs-standalone/docs/entities.md

@@ -0,0 +1,77 @@
+# Entities
+
+Entities are used in cards and screensaver lists.
+
+## Entity keys
+
+key | required | type | description
+-- | -- | -- | --
+`entity` | yes | string | Home Assistant entity id, or internal entity (`navigate.*`, `delete`, `iText.*`).
+`name` | no | string | Display name override.
+`icon` | no | string or map | Icon override (`mdi:*`), optionally per state.
+`color` | no | `[r,g,b]` or map | Color override, optionally per state.
+`value` | no | string | Value override.
+`font` | no | string | Icon font variant (`small`, `medium`, `medium-icon`, `large`).
+`status` | no | string | Extra status entity for `navigate.*` items.
+`effectList` | no | list | Custom light effect list for detail popup.
+`attribute` | no | string | Weather attribute to display.
+`day` | no | int | Weather daily forecast index.
+`hour` | no | int | Weather hourly forecast index.
+`unit` | no | string | Value suffix.
+
+## Supported Home Assistant domains
+
+- `switch`
+- `input_boolean`
+- `automation`
+- `lock`
+- `input_text`
+- `input_select`
+- `select`
+- `light`
+- `fan`
+- `button`
+- `input_button`
+- `scene`
+- `script`
+- `number`
+- `input_number`
+- `timer`
+- `alarm_control_panel`
+- `vacuum`
+- `media_player`
+- `sun`
+- `person`
+- `climate`
+- `cover`
+- `sensor`
+- `binary_sensor`
+- `weather`
+
+## Internal entities
+
+- `navigate.<key>`: Navigate to card with matching `key`.
+- `navigate.UP`: Navigate back.
+- `delete`: Placeholder/empty slot.
+- `iText.<text>`: Static text entry.
+
+## Template-based values
+
+The rewrite supports Home Assistant template rendering for selected fields when prefixed with `ha:`:
+
+- `icon: "ha:{{ ... }}"`
+- `color: "ha:{{ ... }}"` (must evaluate to JSON RGB list)
+- `value: "ha:{{ ... }}"`
+- `qrCode: "ha:{{ ... }}"`
+
+Example:
+
+```yaml
+- entity: light.kitchen
+  icon:
+    "on": mdi:lightbulb
+    "off": mdi:lightbulb-outline
+  color:
+    "on": [255, 210, 90]
+    "off": [80, 120, 170]
+```

docs-standalone/docs/getting-started.md

@@ -0,0 +1,55 @@
+# Getting Started
+
+## Home Assistant add-on mode
+
+In add-on mode, the container startup script:
+
+- reads MQTT credentials from Home Assistant service discovery
+- sets `CONFIG_FILE=/config/panels.yaml`
+- creates `/config/panels.yaml` from the bundled example if it does not exist
+
+Relevant files:
+
+- `nspanel-lovelace-ui/rootfs/usr/bin/mqtt-manager/run.sh`
+- `nspanel-lovelace-ui/config.yaml`
+
+## Minimal `panels.yaml`
+
+Start with one panel:
+
+```yaml
+home_assistant_address: "http://supervisor"
+home_assistant_token: "SUPERVISOR_TOKEN_OR_LONG_LIVED_TOKEN"
+
+nspanels:
+  kitchen:
+    panelRecvTopic: "tele/tasmota_kitchen/RESULT"
+    panelSendTopic: "cmnd/tasmota_kitchen/CustomSend"
+    locale: "en_US"
+    timeZone: "Europe/Berlin"
+    timeFormat: "%H:%M"
+    dateFormat: "full"
+    screensaver:
+      entities:
+        - entity: weather.home
+    cards:
+      - type: cardEntities
+        title: Main
+        entities:
+          - entity: light.kitchen
+          - entity: switch.coffee_machine
+```
+
+## Important notes
+
+- `cards` and `screensaver` are required per panel.
+- `timeFormat`, `dateFormat`, and `locale` should be set per panel.
+- `panelRecvTopic` / `panelSendTopic` are required.
+
+## Running standalone (outside HA add-on)
+
+If you run this container/process outside Supervisor:
+
+- provide `home_assistant_address` and `home_assistant_token` in YAML
+- provide MQTT values in YAML (`mqtt_server`, `mqtt_port`, `mqtt_username`, `mqtt_password`) or environment
+- set `CONFIG_FILE` if the config is not `./panels.yaml`

docs-standalone/docs/index.md

@@ -0,0 +1,38 @@
+# Overview
+
+This documentation covers the standalone rewrite located in `nspanel-lovelace-ui/`.
+
+It is a Python backend that:
+
+- receives panel input (MQTT mode or Home Assistant API mode)
+- reads Home Assistant state through the websocket API
+- renders cards and screensaver pages
+- sends panel commands back to the device
+
+This docs set is intentionally separate from the AppDaemon docs in `docs/`.
+
+## Rewrite location
+
+- Add-on package: `nspanel-lovelace-ui/`
+- Runtime code: `nspanel-lovelace-ui/rootfs/usr/bin/mqtt-manager/`
+- Example panel config: `nspanel-lovelace-ui/rootfs/usr/bin/mqtt-manager/panels.yaml.example`
+
+## What is supported
+
+- `cardEntities`
+- `cardGrid` (auto-switches to `cardGrid2` when needed)
+- `cardQR`
+- `cardPower`
+- `cardMedia`
+- `cardThermo`
+- `cardAlarm`
+- `cardUnlock`
+- screensaver with status icons and weather forecast entities
+
+## Runtime model
+
+1. Load `panels.yaml`.
+2. Resolve MQTT and Home Assistant connection settings.
+3. Create one thread per panel.
+4. Listen for events and state changes.
+5. Re-render active pages and detail popups when relevant entities change.

docs-standalone/docs/migration-appdaemon.md

@@ -0,0 +1,120 @@
+# Migration from AppDaemon Config
+
+This page explains how to migrate panel configuration from the legacy AppDaemon `apps.yaml` format to the standalone rewrite `panels.yaml` format.
+
+## File and structure changes
+
+Old (AppDaemon):
+
+- panel config lived under `apps.yaml`
+- MQTT and Home Assistant base connection config was split across AppDaemon files (`appdaemon.yaml`, plugin config, and app config)
+
+New (rewrite):
+
+- panel config lives in one file: `panels.yaml` (usually `/config/panels.yaml`)
+- connection values are read from this file and/or environment variables
+
+## Minimal before/after example
+
+Old AppDaemon (`apps.yaml`):
+
+```yaml
+nspanel-1:
+  module: nspanel-lovelace-ui
+  class: NsPanelLovelaceUIManager
+  config:
+    panelRecvTopic: "tele/tasmota_panel/RESULT"
+    panelSendTopic: "cmnd/tasmota_panel/CustomSend"
+    model: eu
+    locale: en_US
+    timeFormat: "%H:%M"
+```
+
+New rewrite (`panels.yaml`):
+
+```yaml
+home_assistant_address: "http://supervisor"
+home_assistant_token: "YOUR_TOKEN"
+
+nspanels:
+  panel-1:
+    panelRecvTopic: "tele/tasmota_panel/RESULT"
+    panelSendTopic: "cmnd/tasmota_panel/CustomSend"
+    model: eu
+    locale: en_US
+    timeZone: "Europe/Berlin"
+    timeFormat: "%H:%M"
+    dateFormat: "full"
+    screensaver:
+      entities:
+        - entity: weather.home
+    cards:
+      - type: cardEntities
+        title: Main
+        entities:
+          - entity: light.kitchen
+```
+
+## Key mapping
+
+Legacy AppDaemon key or concept | Standalone rewrite | Notes
+-- | -- | --
+`module`, `class`, `config` wrapper | removed | Rewrite uses `nspanels.<panel_name>` directly.
+`panelRecvTopic` | `panelRecvTopic` | Same meaning.
+`panelSendTopic` | `panelSendTopic` | Same meaning.
+`model` | `model` | Same meaning (`eu`, `us-p`, `us-l`).
+`locale` | `locale` | Same meaning.
+`timeFormat` | `timeFormat` | Same meaning.
+`timezone` (legacy docs casing) | `timeZone` | Use exact camelCase `timeZone`.
+`dateFormatBabel` / `dateFormat` | `dateFormat` | Rewrite expects `dateFormat`.
+`cards` | `cards` | Same concept.
+`hiddenCards` | `hiddenCards` | Same concept.
+`screensaver` | `screensaver` | Same concept; some legacy theme options are not available.
+`defaultCard` under screensaver usage | `defaultCard` (panel level) | Use as panel-level key in rewrite.
+`temperatureUnit` (card-level legacy usage) | `temp_unit` (panel level) | Rewrite reads panel-level `temp_unit`.
+`sleepBrightness` list schedule | not supported | Rewrite supports integer or entity id, not list-based schedules.
+`screenBrightness` list schedule | not supported | Rewrite supports integer or entity id, not list-based schedules.
+`sleepTracking` | `sleepTracking` | Same concept.
+`sleepTrackingZones` | `sleepTrackingZones` | Same concept.
+`sleepOverride` | `sleepOverride` | Same concept.
+`updateMode` / OTA URL overrides (`displayURL-*`, `berryURL`) | not supported | Rewrite does not implement these legacy update keys.
+`theme`, `dateAdditionalTemplate`, `timeAdditionalTemplate` | not supported | Not implemented in rewrite config.
+
+## Connection config differences
+
+In AppDaemon setups, MQTT and Home Assistant connectivity was mostly configured via AppDaemon plugin settings.
+
+In the rewrite, connectivity is resolved directly by the runtime:
+
+- Home Assistant:
+  - `home_assistant_address`
+  - `home_assistant_token`
+- MQTT (for MQTT mode):
+  - `mqtt_server`, `mqtt_port`, `mqtt_username`, `mqtt_password`
+- Optional mode switch:
+  - set `use_ha_api` to use Home Assistant event mode instead of MQTT receive mode
+
+## Entity-level differences to watch
+
+Some legacy entity config fields are not implemented in the rewrite parser/renderer:
+
+- `state`, `state_not`, `state_template`
+- direct `service.*` action entries with custom `data`
+- `action_name`
+
+Supported and commonly used fields in rewrite:
+
+- `entity`, `name`, `icon`, `color`, `value`, `font`
+- weather-related: `attribute`, `day`, `hour`, `unit`
+- light detail helper: `effectList`
+- navigation helper: `status` for `navigate.*` entities
+
+## Migration checklist
+
+1. Create `/config/panels.yaml` from the rewrite example.
+2. Move each old app entry (`nspanel-1`, `nspanel-2`, ...) into `nspanels`.
+3. Remove `module/class/config` wrappers.
+4. Rename `timezone` to `timeZone`.
+5. Ensure each panel has `dateFormat`, `timeFormat`, `screensaver`, and `cards`.
+6. Replace unsupported scheduled brightness lists with integer/entity-based values.
+7. Remove unsupported legacy-only keys listed above.

docs-standalone/docs/screensaver.md

@@ -0,0 +1,57 @@
+# Screensaver
+
+`screensaver` is a required object in each panel config.
+
+## Keys
+
+key | required | type | default | description
+-- | -- | -- | -- | --
+`type` | no | string | `screensaver` | Layout type (`screensaver` / `screensaver2`).
+`entities` | yes* | list | none | Screensaver entities.
+`entity` | yes* | string | none | Single-entity shortcut.
+`statusIcon1` | no | object | none | Left status icon near date.
+`statusIcon2` | no | object | none | Right status icon near date.
+`doubleTapToUnlock` | no | bool | `false` | Requires double tap when leaving screensaver.
+`sleepTimeout` | no | int | panel `sleepTimeout` | Per-screensaver timeout override.
+
+`*` Provide at least one of `entity` or `entities`.
+
+## Screensaver entities
+
+Screensaver entities use the same entity format as other cards.
+
+For `weather.<entity>` you can also use:
+
+- `attribute` (default `temperature`)
+- `day` (daily forecast index)
+- `hour` (hourly forecast index)
+- `unit` (suffix, default `°C` for temperature-like attributes)
+
+## Example
+
+```yaml
+screensaver:
+  type: screensaver
+  doubleTapToUnlock: true
+  sleepTimeout: 30
+  statusIcon1:
+    entity: binary_sensor.front_door
+    icon:
+      "on": mdi:door-open
+      "off": mdi:door-closed
+    font: medium-icon
+  statusIcon2:
+    entity: sensor.outdoor_temperature
+    icon: mdi:thermometer
+  entities:
+    - entity: weather.home
+      attribute: temperature
+    - entity: weather.home
+      day: 1
+      attribute: temperature
+    - entity: weather.home
+      day: 2
+      attribute: temperature
+    - entity: sensor.indoor_temperature
+      icon: mdi:home-thermometer
+```

docs-standalone/docs/troubleshooting.md

@@ -0,0 +1,63 @@
+# Troubleshooting
+
+## Config does not load
+
+Symptoms:
+
+- no panel output
+- log shows YAML parse error or file missing
+
+Checks:
+
+1. Confirm `CONFIG_FILE` path.
+2. Validate YAML syntax.
+3. Ensure required per-panel keys exist: `panelRecvTopic`, `panelSendTopic`, `locale`, `timeFormat`, `dateFormat`, `screensaver`, `cards`.
+
+## MQTT not connected
+
+Symptoms:
+
+- log repeats MQTT connection retry
+
+Checks:
+
+1. Verify `mqtt_server`, `mqtt_port`, `mqtt_username`, `mqtt_password`.
+2. Verify panel publishes on the same topic as `panelRecvTopic`.
+3. Verify payload includes `CustomRecv` JSON key.
+
+## Home Assistant websocket not connected
+
+Symptoms:
+
+- log repeatedly waits for websocket/auth
+
+Checks:
+
+1. Verify `home_assistant_address` and `home_assistant_token`.
+2. In add-on mode, verify Supervisor token access is available.
+3. Confirm HA is reachable from container network.
+
+## Card does not open or navigate
+
+Checks:
+
+1. For `navigate.<key>`, confirm target card has matching `key`.
+2. For `cardUnlock`, confirm `destination` and `pin` are set.
+3. Confirm card `type` is one of the implemented types.
+
+## Brightness behaves unexpectedly
+
+Checks:
+
+1. If using entity-based brightness, verify entity state is numeric.
+2. Avoid list-based brightness schedules in this rewrite (not supported).
+3. Review interaction between `sleepTracking`, `sleepTrackingZones`, and `sleepOverride`.
+
+## Useful logs to look for
+
+- `Config file not found`
+- `Error while parsing YAML file`
+- `Connected to MQTT Server`
+- `Home Assistant auth OK`
+- `card type ... not implemented`
+- `Not implemented: <button action>`

docs-standalone/mkdocs.yml

@@ -0,0 +1,60 @@
+site_name: NsPanel Lovelace UI Standalone Docs
+site_description: Documentation for the standalone/Home Assistant add-on rewrite in nspanel-lovelace-ui.
+site_author: Johannes Braun
+site_url: https://jobr99.github.io/nspanel-lovelace-ui/standalone
+
+repo_name: jobr99/nspanel-lovelace-ui
+repo_url: https://github.com/jobr99/nspanel-lovelace-ui
+edit_uri: ""
+
+copyright: "Copyright © 2026 Johannes Braun"
+
+docs_dir: docs
+
+theme:
+  name: material
+  palette:
+    accent: blue
+  font:
+    text: "arial, sans-serif"
+    code: monospace
+  features:
+    - navigation.indexes
+    - navigation.sections
+    - navigation.top
+    - navigation.tracking
+    - navigation.expand
+    - search.highlight
+    - search.share
+    - search.suggest
+
+extra_css:
+  - _assets/user.css
+
+markdown_extensions:
+  - admonition
+  - def_list
+  - attr_list
+  - pymdownx.tilde
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.magiclink
+  - toc:
+      permalink: true
+  - codehilite:
+      guess_lang: false
+
+plugins:
+  - search:
+      lang: en
+
+nav:
+  - "Overview": index.md
+  - "Getting Started": getting-started.md
+  - "Configuration": configuration.md
+  - "Migration from AppDaemon": migration-appdaemon.md
+  - "Screensaver": screensaver.md
+  - "Cards": cards.md
+  - "Entities": entities.md
+  - "Connection Modes": connection-modes.md
+  - "Troubleshooting": troubleshooting.md

docs/_assets/user.css

@@ -10,14 +10,46 @@
 	display: none;
 }
 
-/*.md-header,*/ .md-footer {
+/*.md-header,*/ .md-footer,
+.md-footer-meta {
 	background-color: #333333;
 }
 
-.md-footer__inner.md-grid {
+/* Footer contrast fixes for Zensical/Material variants */
-	display: none;
+:root {
+	--md-footer-bg-color: #333333;
+	--md-footer-bg-color--dark: #2b2b2b;
+	--md-footer-fg-color: #f2f2f2;
+	--md-footer-fg-color--light: #ffffff;
+	--md-footer-fg-color--lighter: #ffffff;
 }
 
+.md-footer,
+.md-footer-meta,
+.md-footer * {
+	color: #f2f2f2;
+}
+
+.md-footer a,
+.md-footer-meta a,
+.md-footer .md-footer__link {
+	color: #ffffff;
+}
+
+.md-footer a:hover,
+.md-footer-meta a:hover,
+.md-footer .md-footer__link:hover {
+	color: #d9e7ff;
+}
+
+.md-footer .md-icon svg,
+.md-footer-meta .md-icon svg {
+	fill: currentColor;
+}
+
+/* Zensical keeps footer content in the inner/meta containers.
+   Don't hide footer structure, only style it. */
+
 .md-sidebar {
 	padding-top: 0px;
 }
@@ -77,4 +109,4 @@
 
 ol li::marker {
 	font-weight: bold;
-}
+}

docs/config-migration-standalone.md

@@ -0,0 +1,75 @@
+# Migration to Standalone Rewrite Config
+
+This page compares the legacy AppDaemon `apps.yaml` config with the standalone rewrite `panels.yaml` config.
+
+For the full rewrite docs, including full key descriptions, see:
+
+- [Standalone documentation](https://docs.nspanel.pky.eu/standalone/)
+- [Standalone migration page](https://docs.nspanel.pky.eu/standalone/migration-appdaemon/)
+
+## High-level differences
+
+Old AppDaemon version:
+
+- panel config in `apps.yaml` with `module` / `class` / `config`
+- connectivity partly configured in AppDaemon plugin config (`appdaemon.yaml`)
+
+Standalone rewrite:
+
+- one runtime config file: `/config/panels.yaml`
+- panel definitions under `nspanels`
+- Home Assistant and MQTT connection values resolved directly by the rewrite runtime
+
+## Minimal before/after example
+
+Old (`apps.yaml`):
+
+```yaml
+nspanel-1:
+  module: nspanel-lovelace-ui
+  class: NsPanelLovelaceUIManager
+  config:
+    panelRecvTopic: "tele/tasmota_panel/RESULT"
+    panelSendTopic: "cmnd/tasmota_panel/CustomSend"
+    model: eu
+```
+
+New (`panels.yaml`):
+
+```yaml
+home_assistant_address: "http://supervisor"
+home_assistant_token: "YOUR_TOKEN"
+
+nspanels:
+  panel-1:
+    panelRecvTopic: "tele/tasmota_panel/RESULT"
+    panelSendTopic: "cmnd/tasmota_panel/CustomSend"
+    model: eu
+    locale: en_US
+    timeZone: "Europe/Berlin"
+    timeFormat: "%H:%M"
+    dateFormat: "full"
+    screensaver:
+      entities:
+        - entity: weather.home
+    cards:
+      - type: cardEntities
+        title: Main
+        entities:
+          - entity: light.kitchen
+```
+
+## Important key changes
+
+Legacy key/concept | Rewrite key/concept | Notes
+-- | -- | --
+`module`, `class`, `config` wrapper | removed | Rewrite uses `nspanels.<panel_name>` directly.
+`timezone` | `timeZone` | Casing changed.
+`dateFormatBabel` | `dateFormat` | Use `dateFormat` in rewrite.
+`temperatureUnit` (legacy card-level usage) | `temp_unit` (panel-level) | Rewrite reads `temp_unit` from panel settings.
+brightness schedule lists | not supported | Rewrite supports integer or entity id for brightness values.
+`updateMode` / OTA URL override keys | not supported | Legacy update behavior is not part of rewrite config.
+
+If you are migrating now, use the standalone migration page for the complete mapping:
+
+- [Complete mapping and checklist](https://docs.nspanel.pky.eu/standalone/migration-appdaemon/)

docs/prepare_nspanel.md

@@ -1,65 +1,71 @@
-# Flash Tasmota to your NSPanel
+# Flash Tasmota to Your NSPanel
 
-You need to connect to your nspanel via serial and flash tasmota [tasmota32-nspanel.bin](http://ota.tasmota.com/tasmota32/release/tasmota32-nspanel.bin) to your NSPanel. 
+You need to connect to your NSPanel via serial and flash Tasmota using [tasmota32-nspanel.bin](http://ota.tasmota.com/tasmota32/release/tasmota32-nspanel.bin).  
-You can use the Tasmota Web Installer to do so. [Tasmota Web Installer](https://tasmota.github.io/install/)
+You can use the [Tasmota Web Installer](https://tasmota.github.io/install/) to do so.
 
-Checkout Blakadders Template Repo for more information on flashing, do not use the autoexec.be from this page.
+Check out Blakadder's Template Repo for more information on flashing. **Do not** use the autoexec.be from that page.  
 [NSPanel Page of the Tasmota Template Repository](https://templates.blakadder.com/sonoff_NSPanel.html)
 
-If you prefer EspHome over Tasmota, you can use this thrid party esphome component, which is replacing tasmota and the berry driver of this project.
+If you prefer ESPHome over Tasmota, you can use this third-party ESPHome component, which replaces Tasmota and the Berry driver used in this project.  
-[ESPHome component](https://github.com/sairon/esphome-nspanel-lovelace-ui)
+[ESPHome Component](https://github.com/sairon/esphome-nspanel-lovelace-ui)
 
 
+---
+
 ## Configure Tasmota Template for NSPanel
 
-Configure the NSPanel template for Tasmota. (Go to Configuration and Configure Other and paste the template there, make sure to tick the activate checkbox)
+Configure the NSPanel template for Tasmota. (Go to Configuration > Configure Other, paste the template there, and make sure to tick the Activate checkbox.)
 
 ![tasmota-template-config](img/tasmota-template-config.png)
 
-You can use the following template or copy the one on the [Tasmota Template Repo Site](https://templates.blakadder.com/sonoff_NSPanel.html).
+You can use the following template or copy the one from the [Tasmota Template Repo Site](https://templates.blakadder.com/sonoff_NSPanel.html):
 
-`{"NAME":"NSPanel","GPIO":[0,0,0,0,3872,0,0,0,0,0,32,0,0,0,0,225,0,480,224,1,0,0,0,33,0,0,0,0,0,0,0,0,0,0,4736,0],"FLAG":0,"BASE":1,"CMND":"ADCParam 2,11200,10000,3950 | Sleep 0 | BuzzerPWM 1"}`
+{"NAME":"NSPanel","GPIO":[0,0,0,0,3872,0,0,0,0,0,32,0,0,0,0,225,0,480,224,1,0,0,0,33,0,0,0,0,0,0,0,0,0,0,4736,0],"FLAG":0,"BASE":1,"CMND":"ADCParam 2,11200,10000,3950 | Sleep 0 | BuzzerPWM 1"}
 
-After a reboot of tasmota your screen will light up with the stock display firmware.
+After a reboot of Tasmota, your screen will light up with the stock display firmware.
+
+---
 
 ## Upload Berry Driver to Tasmota
 
-Go to `Consoles` > `Console` in Tasmota and execute the following command:
+Go to Consoles > Console in Tasmota and execute the following command:
 
-```
+Backlog UrlFetch https://raw.githubusercontent.com/joBr99/nspanel-lovelace-ui/main/tasmota/autoexec.be; SetOption151 0; Restart 1
-Backlog UrlFetch https://raw.githubusercontent.com/joBr99/nspanel-lovelace-ui/main/tasmota/autoexec.be; SetOption151 0;Restart 1
-```
 
-This will download the autoexec.be file from the repository and restart tasmota.
+This downloads the autoexec.be file from the repository and restarts Tasmota.
 
-Note: The command is also disabling matter to free up memory, as it's most likely not used by any homeassistant users anyway.
+Note: This command also disables Matter to free up memory, as it's unlikely to be used by most Home Assistant users. (Matter can cause memory issues during flashing of the Nextion screen, but you can re-enable it later if needed.)
-(Matter could cause memory issues during flashing of the Nextion Screen, but you can still enable it if you need to.)
+
+---
 
 ## Flash Firmware to Nextion Screen
 
-Due the limitations of Berry, it's not possible to download the tft file directly from github, so I'm also renting a small server where you can download the file via HTTP.
+Due to the limitations of Berry, it's not possible to download the TFT file directly from GitHub. A small server is available to download the file via HTTP.
 
-Use the one following commands in the tasmota console (not berry console) to flash the latest release from this repository:
+Use one of the following commands in the Tasmota console (not the Berry console) to flash the latest release from this repository:
 
-EU Version: `FlashNextion http://nspanel.pky.eu/lui-release.tft`
+EU Version:  
+FlashNextion http://nspanel.pky.eu/lui-release.tft
 
-US Version Portrait: `FlashNextion http://nspanel.pky.eu/lui-us-p-release.tft`
+US Version Portrait:  
+FlashNextion http://nspanel.pky.eu/lui-us-p-release.tft
 
-US Version Landscape: `FlashNextion http://nspanel.pky.eu/lui-us-l-release.tft`
+US Version Landscape:  
+FlashNextion http://nspanel.pky.eu/lui-us-l-release.tft
 
-After sending the command, the screen should show a progress bar. The flashing progress takes around 5 minutes.
+After sending the command, the screen should show a progress bar. The flashing process takes around 5 minutes.
 
-Note: For the US Version Users - keep in mind that you need to add the model config option to your apps.yaml later, more details on config overview page
+Note for US users: You'll need to add the model config option to your apps.yaml later. More details can be found on the config overview page.
 
+---
 
 <details>
-<summary>Alternatively you can use your own webserver or the one build into HomeAssistant:</summary>
+<summary>Alternatively, you can use your own web server or the one built into Home Assistant:</summary>
 <br>
-Upload the nspanel.tft from the lastest release to a Webserver (for example www folder of Home Assistant) and execute the following command in Tasmota Console. (Development Version: [tft file from HMI folder](HMI/nspanel.tft))
+Upload the nspanel.tft from the latest release to a web server (for example, the www folder of Home Assistant) and execute the following command in the Tasmota Console.  
+(Development version: [TFT file from HMI folder](HMI/nspanel.tft))
 
-**Webserver must be HTTP, HTTPS is not supported, due to limitations of berry lang on tasmota**
+**The web server must be HTTP. HTTPS is not supported due to Berry language limitations in Tasmota.**
 
-`FlashNextion http://ip-address-of-your-homeassistant:8123/local/nspanel.tft`
+FlashNextion http://ip-address-of-your-homeassistant:8123/local/nspanel.tft
 </details>
-
-

mkdocs.yml

@@ -12,7 +12,7 @@ repo_name: jobr99/nspanel-lovelace-ui
 repo_url: https://github.com/jobr99/nspanel-lovelace-ui
 edit_uri: ""
 
-copyright: "Copyright © 2023 Johannes Braun"
+copyright: "Copyright © 2026 Johannes Braun"
 
 docs_dir: docs
 
@@ -42,8 +42,6 @@ extra_css:
 extra:
   analytics:
     provider: custom
-  version:
-    provider: mike
 
 markdown_extensions:
     - admonition
@@ -63,7 +61,6 @@ markdown_extensions:
 plugins:
     - search:
         lang: en
-    - mkdocs-video
 
 nav:
     - "Overview": index.md
@@ -75,6 +72,7 @@ nav:
         - "FAQ": faq.md
     - "Configuration - apps.yaml (Home Assistant)":
         - "Overview": config-overview.md
+        #- "Migration to Standalone Rewrite": config-migration-standalone.md
         - "Screensaver": config-screensaver.md
         - "Cards":
             - "Entities Card": card-entities.md

nspanel-lovelace-ui/config.yaml

@@ -1,6 +1,6 @@
 # https://developers.home-assistant.io/docs/add-ons/configuration#add-on-config
 name: NSPanel Lovelace UI Addon
-version: "4.7.80"
+version: "4.7.85"
 slug: nspanel-lovelace-ui
 description: NSPanel Lovelace UI Addon
 services:

nspanel-lovelace-ui/rootfs/usr/bin/mqtt-manager/ha_cards.py

@@ -475,7 +475,7 @@ class AlarmCard(HACard):
         main_entity = self.entities[0]
         main_entity.render()
 
-        print(main_entity.state)
+        logging.debug("Alarm card state for '%s': %s", main_entity.entity_id, main_entity.state)
 
         icon = get_icon_char("shield-off")
         color = rgb_dec565([255,255,255])

nspanel-lovelace-ui/rootfs/usr/bin/mqtt-manager/ha_control.py

@@ -8,6 +8,8 @@ def wait_for_ha_cache():
     while time.time() < mustend:
         if len(libs.home_assistant.home_assistant_entity_state_cache) == 0:
             time.sleep(0.1)
+    if len(libs.home_assistant.home_assistant_entity_state_cache) == 0:
+        logging.warning("Home Assistant entity cache is still empty after waiting 5 seconds")
     time.sleep(1)
 
 def calculate_dim_values(sleepTracking, sleepTrackingZones, sleepBrightness, screenBrightness, sleepOverride, return_involved_entities=False):
@@ -28,8 +30,8 @@ def calculate_dim_values(sleepTracking, sleepTrackingZones, sleepBrightness, scr
             involved_entities.append(sleepBrightness)
             try:
                 dimmode = int(float(libs.home_assistant.get_entity_data(sleepBrightness).get('state', 10)))
-            except ValueError:
+            except (TypeError, ValueError):
-                print("sleepBrightness entity invalid")
+                logging.exception("sleepBrightness entity '%s' has an invalid state value", sleepBrightness)
 
     if screenBrightness:
         if isinstance(screenBrightness, int):
@@ -44,8 +46,8 @@ def calculate_dim_values(sleepTracking, sleepTrackingZones, sleepBrightness, scr
             involved_entities.append(screenBrightness)
             try:
                 dimValueNormal = int(float(libs.home_assistant.get_entity_data(screenBrightness).get('state', 100)))
-            except ValueError:
+            except (TypeError, ValueError):
-                print("screenBrightness entity invalid")
+                logging.exception("screenBrightness entity '%s' has an invalid state value", screenBrightness)
     # force sleep brightness to zero in case sleepTracking is active
     if sleepTracking:
         if libs.home_assistant.is_existent(sleepTracking):
@@ -69,12 +71,13 @@ def calculate_dim_values(sleepTracking, sleepTrackingZones, sleepBrightness, scr
     else:
         return dimmode, dimValueNormal
 
-def handle_buttons(entity_id, btype, value, entity_config=None):
+def handle_buttons(entity_id, btype, value, entity_config=None, action_context=None):
+    action_context = action_context or {}
     match btype:
         case 'button':
-            button_press(entity_id, value)
+            button_press(entity_id, value, action_context=action_context)
         case 'OnOff':
-            on_off(entity_id, value)
+            on_off(entity_id, value, action_context=action_context)
         case 'number-set':
             if entity_id.startswith('fan'):
                 attr = libs.home_assistant.get_entity_data(entity_id).get('attributes', [])
@@ -82,7 +85,7 @@ def handle_buttons(entity_id, btype, value, entity_config=None):
             service_data = {
                 "value": int(value)
             }
-            call_ha_service(entity_id, "set_value", service_data=service_data)
+            call_ha_service(entity_id, "set_value", service_data=service_data, action_context=action_context)
         case 'up' | 'stop' | 'down' | 'tiltOpen' | 'tiltStop' | 'tiltClose' | 'media-next' | 'media-back' | 'media-pause' | 'timer-cancel' | 'timer-pause' | 'timer-finish':
             action_service_mapping = {
                 'up': 'open_cover',
@@ -99,37 +102,37 @@ def handle_buttons(entity_id, btype, value, entity_config=None):
                 'timer-finish': 'finish',
             }
             service = action_service_mapping[btype]
-            call_ha_service(entity_id, service)
+            call_ha_service(entity_id, service, action_context=action_context)
         case 'timer-start':
             if value:
                 service_data = {
                     "duration": value
                 }
-                call_ha_service(entity_id, "start", service_data=service_data)
+                call_ha_service(entity_id, "start", service_data=service_data, action_context=action_context)
             else:
-                call_ha_service(entity_id, "start")
+                call_ha_service(entity_id, "start", action_context=action_context)
         case 'positionSlider':
             service_data = {
                 "position": int(value)
             }
-            call_ha_service(entity_id, "set_cover_position", service_data=service_data)
+            call_ha_service(entity_id, "set_cover_position", service_data=service_data, action_context=action_context)
         case 'tiltSlider':
             service_data = {
                 "tilt_position": int(value)
             }
-            call_ha_service(entity_id, "set_cover_tilt_position", service_data=service_data)
+            call_ha_service(entity_id, "set_cover_tilt_position", service_data=service_data, action_context=action_context)
         case 'media-OnOff':
             state = libs.home_assistant.get_entity_data(entity_id).get('state', '')
             if state == "off":
-                call_ha_service(entity_id, "turn_on")
+                call_ha_service(entity_id, "turn_on", action_context=action_context)
             else:
-                call_ha_service(entity_id, "turn_off")
+                call_ha_service(entity_id, "turn_off", action_context=action_context)
         case 'media-shuffle':
             suffle = libs.home_assistant.get_entity_data(entity_id).get('attributes', []).get('shuffle')
             service_data = {
                 "shuffle": not suffle
             }
-            call_ha_service(entity_id, "set_value", service_data=service_data)
+            call_ha_service(entity_id, "set_value", service_data=service_data, action_context=action_context)
         case 'volumeSlider':
             pos = int(value)
             # HA wants to have this value between 0 and 1 as float
@@ -137,12 +140,12 @@ def handle_buttons(entity_id, btype, value, entity_config=None):
             service_data = {
                 "volume_level": pos
             }
-            call_ha_service(entity_id, "volume_set", service_data=service_data)
+            call_ha_service(entity_id, "volume_set", service_data=service_data, action_context=action_context)
         case 'speaker-sel':
             service_data = {
                 "volume_level": value
             }
-            call_ha_service(entity_id, "select_source", service_data=service_data)
+            call_ha_service(entity_id, "select_source", service_data=service_data, action_context=action_context)
         # for light detail page
         case 'brightnessSlider':
             # scale 0-100 to ha brightness range
@@ -150,7 +153,7 @@ def handle_buttons(entity_id, btype, value, entity_config=None):
             service_data = {
                 "brightness": brightness
             }
-            call_ha_service(entity_id, "turn_on", service_data=service_data)
+            call_ha_service(entity_id, "turn_on", service_data=service_data, action_context=action_context)
         case 'colorTempSlider':
             attr = libs.home_assistant.get_entity_data(entity_id).get('attributes', [])
             min_mireds = attr.get("min_mireds")
@@ -160,19 +163,19 @@ def handle_buttons(entity_id, btype, value, entity_config=None):
             service_data = {
                 "color_temp": color_val
             }
-            call_ha_service(entity_id, "turn_on", service_data=service_data)
+            call_ha_service(entity_id, "turn_on", service_data=service_data, action_context=action_context)
         case 'colorWheel':
             value = value.split('|')
             color = pos_to_color(int(value[0]), int(value[1]), int(value[2]))
             service_data = {
                 "rgb_color": color
             }
-            call_ha_service(entity_id, "turn_on", service_data=service_data)
+            call_ha_service(entity_id, "turn_on", service_data=service_data, action_context=action_context)
         case 'disarm' | 'arm_home' | 'arm_away' | 'arm_night' | 'arm_vacation':
             service_data = {
                 "code": value
             }
-            call_ha_service(entity_id, f"alarm_{btype}", service_data=service_data)
+            call_ha_service(entity_id, f"alarm_{btype}", service_data=service_data, action_context=action_context)
         case 'mode-preset_modes' | 'mode-swing_modes' | 'mode-fan_modes':
             attr = libs.home_assistant.get_entity_data(entity_id).get('attributes', [])
             mapping = {
@@ -187,7 +190,7 @@ def handle_buttons(entity_id, btype, value, entity_config=None):
                     service_data = {
                         mapping[btype][:-1]: mode
                     }
-                    call_ha_service(entity_id, f"set_{mapping[btype][:-1]}", service_data=service_data)
+                    call_ha_service(entity_id, f"set_{mapping[btype][:-1]}", service_data=service_data, action_context=action_context)
         case 'mode-input_select' | 'mode-select':
             options = libs.home_assistant.get_entity_data(entity_id).get('attributes', []).get("options", [])
             if options:
@@ -195,7 +198,7 @@ def handle_buttons(entity_id, btype, value, entity_config=None):
                 service_data = {
                     "option": option
                 }
-                call_ha_service(entity_id, "select_option", service_data=service_data)
+                call_ha_service(entity_id, "select_option", service_data=service_data, action_context=action_context)
         case 'mode-media_player':
             options = libs.home_assistant.get_entity_data(entity_id).get('attributes', []).get("source_list", [])
             if options:
@@ -203,7 +206,7 @@ def handle_buttons(entity_id, btype, value, entity_config=None):
                 service_data = {
                     "source": option
                 }
-                call_ha_service(entity_id, "select_source", service_data=service_data)
+                call_ha_service(entity_id, "select_source", service_data=service_data, action_context=action_context)
         case 'mode-light':
             options = entity_config.get("effectList", libs.home_assistant.get_entity_data(entity_id).get('attributes', []).get("effect_list", []))
             if options:
@@ -211,13 +214,13 @@ def handle_buttons(entity_id, btype, value, entity_config=None):
                 service_data = {
                     "effect": option
                 }
-                call_ha_service(entity_id, "turn_on", service_data=service_data)
+                call_ha_service(entity_id, "turn_on", service_data=service_data, action_context=action_context)
         case 'tempUpd':
             temp = int(value)/10
             service_data = {
                 "temperature": temp
             }
-            call_ha_service(entity_id, "set_temperature", service_data=service_data)
+            call_ha_service(entity_id, "set_temperature", service_data=service_data, action_context=action_context)
         case 'tempUpdHighLow':
             value = value.split("|")
             temp_high = int(value[0])/10
@@ -226,47 +229,67 @@ def handle_buttons(entity_id, btype, value, entity_config=None):
                 "target_temp_high": temp_high,
                 "target_temp_low": temp_low,
             }
-            call_ha_service(entity_id, "set_temperature", service_data=service_data)
+            call_ha_service(entity_id, "set_temperature", service_data=service_data, action_context=action_context)
         case 'hvac_action':
             service_data = {
                 "hvac_mode": value
             }
-            call_ha_service(entity_id, "set_hvac_mode", service_data=service_data)
+            call_ha_service(entity_id, "set_hvac_mode", service_data=service_data, action_context=action_context)
         case _:
            logging.error("Not implemented: %s", btype)
 
-def call_ha_service(entity_id, service, service_data = {}):
+def call_ha_service(entity_id, service, service_data=None, action_context=None):
+    if service_data is None:
+        service_data = {}
+    action_context = action_context or {}
     etype = entity_id.split(".")[0]
-    libs.home_assistant.call_service(
+    ok = libs.home_assistant.call_service(
         entity_name=entity_id,
         domain=etype,
         service=service,
         service_data=service_data
     )
+    if ok:
+        logging.info(
+            "Panel action forwarded to Home Assistant: panel='%s', action='%s', value='%s', entity='%s', service='%s', data=%s",
+            action_context.get("panel", "unknown"),
+            action_context.get("btype", "unknown"),
+            action_context.get("value"),
+            entity_id,
+            service,
+            service_data,
+        )
+    if not ok:
+        logging.error(
+            "Home Assistant service call failed: entity='%s', service='%s', data=%s",
+            entity_id,
+            service,
+            service_data,
+        )
 
-def button_press(entity_id, value):
+def button_press(entity_id, value, action_context=None):
     etype = entity_id.split(".")[0]
     match etype:
         case 'scene' | 'script':
-            call_ha_service(entity_id, "turn_on")
+            call_ha_service(entity_id, "turn_on", action_context=action_context)
         case 'light' | 'switch' | 'input_boolean' | 'automation' | 'fan':
-            call_ha_service(entity_id, "toggle")
+            call_ha_service(entity_id, "toggle", action_context=action_context)
         case 'lock':
             state = libs.home_assistant.get_entity_data(entity_id).get('state', '')
             if state == "locked":
-                call_ha_service(entity_id, "unlock")
+                call_ha_service(entity_id, "unlock", action_context=action_context)
             else:
-                call_ha_service(entity_id, "lock")
+                call_ha_service(entity_id, "lock", action_context=action_context)
         case 'button' | 'input_button':
-            call_ha_service(entity_id, "press")
+            call_ha_service(entity_id, "press", action_context=action_context)
         case 'input_select' | 'select':
-            call_ha_service(entity_id, "select_next")
+            call_ha_service(entity_id, "select_next", action_context=action_context)
         case 'vacuum':
             state = libs.home_assistant.get_entity_data(entity_id).get('state', '')
             if state == "docked":
-                call_ha_service(entity_id, "start")
+                call_ha_service(entity_id, "start", action_context=action_context)
             else:
-                call_ha_service(entity_id, "return_to_base")
+                call_ha_service(entity_id, "return_to_base", action_context=action_context)
         case _:
             logging.error("buttonpress for entity type %s not implemented", etype)
 
@@ -274,14 +297,14 @@ def button_press(entity_id, value):
     #          apis.ha_api.call_service(entity_id.replace(
     #              'service.', '', 1).replace('.', '/', 1), **entity_config.data)
 
-def on_off(entity_id, value):
+def on_off(entity_id, value, action_context=None):
     etype = entity_id.split(".")[0]
     match etype:
         case 'light' | 'switch' | 'input_boolean' | 'automation' | 'fan':
             service = "turn_off"
             if value == "1":
                 service = "turn_on"
-            call_ha_service(entity_id, service)
+            call_ha_service(entity_id, service, action_context=action_context)
         case _:
             logging.error(
                 "Control action on_off not implemented for %s", entity_id)

nspanel-lovelace-ui/rootfs/usr/bin/mqtt-manager/libs/home_assistant.py

@@ -14,8 +14,9 @@ next_id = 0
 request_all_states_id = 0
 ws_connected = False
 home_assistant_entity_state_cache = {}
-template_cache = {}
+template_cache = {}
-response_buffer = {}
+response_buffer = {}
+nspanel_event_handler = None
 
 
 ON_CONNECT_HANDLER = None
@@ -44,47 +45,64 @@ def register_on_disconnect_handler(handler):
     ON_DISCONNECT_HANDLER = handler
 
 
-def on_message(ws, message):
+def on_message(ws, message):
-    global auth_ok, request_all_states_id, home_assistant_entity_state_cache, response_buffer, template_cache
+    global auth_ok, request_all_states_id, home_assistant_entity_state_cache, response_buffer, template_cache
-    json_msg = json.loads(message)
+    try:
-    if json_msg["type"] == "auth_required":
+        json_msg = json.loads(message)
-        authenticate_client()
+    except json.JSONDecodeError:
-    elif json_msg["type"] == "auth_ok":
+        logging.exception("Failed to parse Home Assistant websocket message as JSON")
-        auth_ok = True
+        return
-        logging.info("Home Assistant auth OK. Requesting existing states.")
+
-        subscribe_to_events()
+    message_type = json_msg.get("type")
-        _get_all_states()
+    if message_type == "auth_required":
-        if ON_CONNECT_HANDLER is not None:
+        authenticate_client()
-            ON_CONNECT_HANDLER()
+    elif message_type == "auth_ok":
-    # for templates
+        auth_ok = True
-    elif json_msg["type"] == "event" and json_msg["id"] in response_buffer:
+        logging.info("Home Assistant auth OK. Requesting existing states.")
-        template_cache[response_buffer[json_msg["id"]]] = {
+        subscribe_to_events()
-            "result": json_msg["event"]["result"],
+        _get_all_states()
-            "listener-entities": json_msg["event"]["listeners"]["entities"]
+        if ON_CONNECT_HANDLER is not None:
-        }
+            ON_CONNECT_HANDLER()
-    elif json_msg["type"] == "event" and json_msg["event"]["event_type"] == "state_changed":
+    # for templates
-        entity_id = json_msg["event"]["data"]["entity_id"]
+    elif message_type == "event" and json_msg.get("id") in response_buffer:
-        home_assistant_entity_state_cache[entity_id] = json_msg["event"]["data"]["new_state"]
+        event = json_msg.get("event", {})
-        send_entity_update(entity_id)
+        listeners = event.get("listeners", {})
-        # rerender template
+        template_cache[response_buffer[json_msg["id"]]] = {
-        for template, template_cache_entry in template_cache.items():
+            "result": event.get("result"),
-            if entity_id in template_cache_entry.get("listener-entities", []):
+            "listener-entities": listeners.get("entities", [])
-                cache_template(template)
+        }
-    elif json_msg["type"] == "event" and json_msg["event"]["event_type"] == "esphome.nspanel.data":
+    elif message_type == "event" and json_msg.get("event", {}).get("event_type") == "state_changed":
-        nspanel_data_callback(json_msg["event"]["data"]["device_id"], json_msg["event"]["data"]["CustomRecv"])
+        event_data = json_msg.get("event", {}).get("data", {})
-    elif json_msg["type"] == "result" and not json_msg["success"]:
+        entity_id = event_data.get("entity_id")
-        logging.error("Failed result: ")
+        if not entity_id:
-        logging.error(json_msg)
+            logging.debug("Received state_changed event without entity_id")
-    elif json_msg["type"] == "result" and json_msg["success"]:
+            return
-        if json_msg["id"] == request_all_states_id:
+        home_assistant_entity_state_cache[entity_id] = event_data.get("new_state")
-            for entity in json_msg["result"]:
+        send_entity_update(entity_id)
-                home_assistant_entity_state_cache[entity["entity_id"]] = entity
+        # rerender template
-        else:
+        for template, template_cache_entry in template_cache.items():
-            if json_msg["id"] in response_buffer and json_msg.get("result"):
+            if entity_id in template_cache_entry.get("listener-entities", []):
-                response_buffer[json_msg["id"]] = json_msg["result"]
+                cache_template(template)
-        return None  # Ignore success result messages
+    elif message_type == "event" and json_msg.get("event", {}).get("event_type") == "esphome.nspanel.data":
-    else:
+        event_data = json_msg.get("event", {}).get("data", {})
-        logging.debug(message)
+        device_id = event_data.get("device_id")
+        custom_recv = event_data.get("CustomRecv")
+        if nspanel_event_handler is None:
+            logging.debug("No NsPanel event handler registered; dropping event for device '%s'", device_id)
+            return
+        nspanel_event_handler(device_id, custom_recv)
+    elif message_type == "result" and not json_msg.get("success"):
+        logging.error("Home Assistant request failed: %s", json_msg)
+    elif message_type == "result" and json_msg.get("success"):
+        if json_msg.get("id") == request_all_states_id:
+            for entity in json_msg.get("result", []):
+                home_assistant_entity_state_cache[entity["entity_id"]] = entity
+        else:
+            if json_msg.get("id") in response_buffer and json_msg.get("result"):
+                response_buffer[json_msg["id"]] = json_msg["result"]
+        return None  # Ignore success result messages
+    else:
+        logging.debug(message)
 
 
 def _ws_connection_open(ws):
@@ -95,20 +113,24 @@ def _ws_connection_open(ws):
         ON_CONNECT_HANDLER()
 
 
-def _ws_connection_close(ws, close_status_code, close_msg):
+def _ws_connection_close(ws, close_status_code, close_msg):
-    global ws_connected
+    global ws_connected
-    ws_connected = False
+    ws_connected = False
-    logging.error("WebSocket connection closed!")
+    logging.error(
-    if ON_DISCONNECT_HANDLER is not None:
+        "WebSocket connection closed (status=%s, message=%s)",
-        ON_DISCONNECT_HANDLER()
+        close_status_code,
+        close_msg,
+    )
+    if ON_DISCONNECT_HANDLER is not None:
+        ON_DISCONNECT_HANDLER()
 
 
 def connect():
     Thread(target=_do_connection, daemon=True).start()
 
 
-def _do_connection():
+def _do_connection():
-    global home_assistant_url, ws, settings
+    global home_assistant_url, ws, settings
     ws_url = home_assistant_url.replace(
         "https://", "wss://").replace("http://", "ws://")
     if settings["is_addon"]:
@@ -117,12 +139,15 @@ def _do_connection():
         ws_url += "/api/websocket"
     ws = websocket.WebSocketApp(F"{ws_url}", on_message=on_message,
                                 on_open=_ws_connection_open, on_close=_ws_connection_close)
-    while True:
+    while True:
-        logging.info(F"Connecting to Home Assistant at {ws_url}")
+        logging.info(F"Connecting to Home Assistant at {ws_url}")
-        ws.close()
+        try:
-        time.sleep(1)
+            ws.close()
-        ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE})
+            time.sleep(1)
-        time.sleep(10)
+            ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE})
+        except Exception:
+            logging.exception("WebSocket connection loop failed")
+        time.sleep(10)
 
 
 def authenticate_client():
@@ -144,9 +169,9 @@ def subscribe_to_events():
     }
     send_message(json.dumps(msg))
 
-def subscribe_to_nspanel_events(nsp_callback):
+def subscribe_to_nspanel_events(nsp_callback):
-    global next_id, nspanel_data_callback
+    global next_id, nspanel_event_handler
-    nspanel_data_callback = nsp_callback
+    nspanel_event_handler = nsp_callback
     msg = {
         "id": next_id,
         "type": "subscribe_events",
@@ -168,11 +193,13 @@ def send_entity_update(entity_id):
     global on_ha_update
     on_ha_update(entity_id)
 
-def nspanel_data_callback(device_id, msg):
+def nspanel_data_callback(device_id, msg):
-    global nspanel_data_callback
+    if nspanel_event_handler is None:
-    nspanel_data_callback(device_id, msg)
+        logging.debug("NsPanel callback invoked before handler was registered")
+        return
+    nspanel_event_handler(device_id, msg)
 
-def call_service(entity_name: str, domain: str, service: str, service_data: dict) -> bool:
+def call_service(entity_name: str, domain: str, service: str, service_data: dict) -> bool:
     global next_id
     try:
         msg = {
@@ -187,9 +214,12 @@ def call_service(entity_name: str, domain: str, service: str, service_data: dict
         }
         send_message(json.dumps(msg))
         return True
-    except Exception as e:
+    except Exception:
-        logging.exception("Failed to call Home Assisatant service.")
+        logging.exception(
-        return False
+            "Failed to call Home Assistant service: %s.%s for %s",
+            domain, service, entity_name
+        )
+        return False
 
 def send_msg_to_panel(service: str, service_data: dict) -> bool:
     global next_id
@@ -203,9 +233,9 @@ def send_msg_to_panel(service: str, service_data: dict) -> bool:
         }
         send_message(json.dumps(msg))
         return True
-    except Exception as e:
+    except Exception:
-        logging.exception("Failed to call Home Assisatant service.")
+        logging.exception("Failed to call Home Assistant panel service: %s", service)
-        return False
+        return False
 
 def execute_script(entity_name: str, domain: str, service: str, service_data: dict) -> str:
     global next_id, response_buffer
@@ -241,13 +271,13 @@ def execute_script(entity_name: str, domain: str, service: str, service_data: di
             else:
                 return response_buffer[call_id]["response"]
         raise TimeoutError("Did not recive respose in time to HA script call")
-    except Exception as e:
+    except Exception:
-        logging.exception("Failed to call Home Assisatant script.")
+        logging.exception("Failed to call Home Assistant script: %s.%s", domain, service)
-        return {}
+        return {}
 
-def cache_template(template):
+def cache_template(template):
-    if not template:
+    if not template:
-        raise Exception("Invalid template")
+        raise ValueError("Invalid template")
     global next_id, response_buffer
     try:
         call_id = next_id
@@ -259,9 +289,9 @@ def cache_template(template):
         }
         send_message(json.dumps(msg))
         return True
-    except Exception as e:
+    except Exception:
-        logging.exception("Failed to render template.")
+        logging.exception("Failed to render template.")
-        return False
+        return False
 
 def get_template(template):
     global template_cache
@@ -299,7 +329,12 @@ def is_existent(entity_id: str):
         return False
 
 
-def send_message(message):
+def send_message(message):
-    global ws, next_id
+    global ws, next_id
-    next_id += 1
+    try:
-    ws.send(message)
+        next_id += 1
+        ws.send(message)
+    except NameError:
+        logging.error("WebSocket client is not initialized; dropping outgoing message")
+    except Exception:
+        logging.exception("Failed sending websocket message to Home Assistant")

nspanel-lovelace-ui/rootfs/usr/bin/mqtt-manager/main.py

@@ -25,53 +25,76 @@ last_settings_file_mtime = 0
 mqtt_connect_time = 0
 has_sent_reload_command = False
 
-logging.basicConfig(level=logging.DEBUG)
+log_level_name = os.getenv("LOGLEVEL", "DEBUG").upper()
+log_level = getattr(logging, log_level_name, None)
+invalid_log_level = not isinstance(log_level, int)
+if invalid_log_level:
+    log_level = logging.DEBUG
+
+logging.basicConfig(
+    level=log_level,
+    format="%(asctime)s %(levelname)s [%(threadName)s] %(name)s: %(message)s",
+)
+if invalid_log_level:
+    logging.warning("Invalid loglevel '%s', defaulting to DEBUG", log_level_name)
 
 def on_ha_update(entity_id):
     global panel_in_queues
     # send HA updates to all panels
     for queue in panel_in_queues.values():
-        queue.put(("HA:", entity_id))
+        try:
+            queue.put(("HA:", entity_id))
+        except Exception:
+            logging.exception("Failed to enqueue HA update for entity '%s'", entity_id)
 
 def on_ha_panel_event(device_id, msg):
     global panel_in_queues
 
     if device_id in panel_in_queues.keys():
         queue = panel_in_queues[device_id]
-        queue.put(("MQTT:", msg))
+        try:
+            queue.put(("MQTT:", msg))
+        except Exception:
+            logging.exception("Failed to enqueue panel event for device '%s'", device_id)
 
 def process_output_to_panel():
     while True:
-        msg = panel_out_queue.get()
+        try:
-
+            msg = panel_out_queue.get()
-        #client.publish(msg[0], msg[1])
+            service = msg[0] + "_nspanelui_api_call"
-        #apis.ha_api.call_service(service="esphome/" + self._api_panel_name + "_nspanelui_api_call", command=2, data=msg)
+            service_data = {
-        service = msg[0] + "_nspanelui_api_call"
+                "data": msg[1],
-        service_data = {
+                "command": 2
-            "data": msg[1],
-            "command":2
             }
-        libs.home_assistant.send_msg_to_panel(
+            libs.home_assistant.send_msg_to_panel(
-            service = service,
+                service=service,
-            service_data = service_data
+                service_data=service_data
-        )
+            )
+        except Exception:
+            logging.exception("Failed to process outgoing panel message")
 
 
 def connect():
     global settings, panel_out_queue
+    ha_is_configured = settings["home_assistant_address"] != "" and settings["home_assistant_token"] != ""
     if "mqtt_server" in settings and not "use_ha_api" in settings:
         MqttManager(settings, panel_out_queue, panel_in_queues)
     else:
         logging.info("MQTT values not configured, will not connect.")
 
     # MQTT Connected, start APIs if configured
-    if settings["home_assistant_address"] != "" and settings["home_assistant_token"] != "":
+    if ha_is_configured:
         libs.home_assistant.init(settings, on_ha_update)
         libs.home_assistant.connect()
     else:
         logging.info("Home Assistant values not configured, will not connect.")
+        return
 
+    wait_seconds = 0
     while not libs.home_assistant.ws_connected:
+        wait_seconds += 1
+        if wait_seconds % 10 == 0:
+            logging.info("Waiting for Home Assistant websocket connection... (%ss)", wait_seconds)
         time.sleep(1)
     if settings.get("use_ha_api"):
         libs.home_assistant.subscribe_to_nspanel_events(on_ha_panel_event)
@@ -97,13 +120,20 @@ def setup_panels():
         panel_thread.start()
 
 def panel_thread_target(queue_in, name, settings_panel, queue_out):
-    panel = LovelaceUIPanel(name, settings_panel, queue_out)
+    try:
+        panel = LovelaceUIPanel(name, settings_panel, queue_out)
+    except Exception:
+        logging.exception("Failed to initialize panel thread for '%s'", name)
+        return
     while True:
-        msg = queue_in.get()
+        try:
-        if msg[0] == "MQTT:":
+            msg = queue_in.get()
-            panel.customrecv_event_callback(msg[1])
+            if msg[0] == "MQTT:":
-        elif msg[0] == "HA:":
+                panel.customrecv_event_callback(msg[1])
-            panel.ha_event_callback(msg[1])
+            elif msg[0] == "HA:":
+                panel.ha_event_callback(msg[1])
+        except Exception:
+            logging.exception("Panel thread '%s' failed while handling queue message", name)
 
 def get_config_file():
     CONFIG_FILE = os.getenv('CONFIG_FILE')
@@ -117,18 +147,27 @@ def get_config(file):
     try:
         with open(file, 'r', encoding="utf8") as file:
             settings = yaml.safe_load(file)
+    except FileNotFoundError:
+        logging.error("Config file not found: %s", file)
+        return False
+    except OSError:
+        logging.exception("Failed reading config file: %s", file)
+        return False
     except yaml.YAMLError as exc:
-        print ("Error while parsing YAML file:")
+        logging.error("Error while parsing YAML file: %s", file)
         if hasattr(exc, 'problem_mark'):
             if exc.context != None:
-                print ('  parser says\n' + str(exc.problem_mark) + '\n  ' +
+                logging.error(
-                    str(exc.problem) + ' ' + str(exc.context) +
+                    "Parser says\n%s\n%s %s\nPlease correct data and retry.",
-                    '\nPlease correct data and retry.')
+                    str(exc.problem_mark), str(exc.problem), str(exc.context)
+                )
             else:
-                print ('  parser says\n' + str(exc.problem_mark) + '\n  ' +
+                logging.error(
-                    str(exc.problem) + '\nPlease correct data and retry.')
+                    "Parser says\n%s\n%s\nPlease correct data and retry.",
+                    str(exc.problem_mark), str(exc.problem)
+                )
         else:
-            print ("Something went wrong while parsing yaml file")
+            logging.exception("Something went wrong while parsing yaml file")
         return False
 
     if not settings.get("mqtt_username"):
@@ -172,10 +211,14 @@ def config_watch():
     project_files.append(get_config_file())
     handler = ConfigChangeEventHandler(project_files)
     observer = Observer()
-    observer.schedule(handler, path=os.path.dirname(get_config_file()), recursive=True)
+    watch_path = os.path.dirname(get_config_file()) or "."
+    observer.schedule(handler, path=watch_path, recursive=True)
     observer.start()
     while True:
-        time.sleep(1)
+        try:
+            time.sleep(1)
+        except Exception:
+            logging.exception("Config watch loop failed")
 
 def signal_handler(signum, frame):
     logging.info(f"Received signal {signum}. Initiating restart...")
@@ -194,4 +237,5 @@ if __name__ == '__main__':
             time.sleep(100)
     else:
         while True:
-          time.sleep(100)
+
+          time.sleep(100)

nspanel-lovelace-ui/rootfs/usr/bin/mqtt-manager/mqtt.py

@@ -19,7 +19,6 @@ class MqttManager:
         self.client.username_pw_set(
             settings["mqtt_username"], settings["mqtt_password"])
         # Wait for connection
-        connection_return_code = 0
         mqtt_server = settings["mqtt_server"]
         mqtt_port = int(settings["mqtt_port"])
         logging.info("Connecting to %s:%i as %s",
@@ -28,9 +27,12 @@ class MqttManager:
             try:
                 self.client.connect(mqtt_server, mqtt_port, 5)
                 break  # Connection call did not raise exception, connection is sucessfull
-            except:  # pylint: disable=bare-except
+            except Exception:  # pylint: disable=broad-exception-caught
                 logging.exception(
-                    "Failed to connect to MQTT %s:%i. Will try again in 10 seconds. Code: %s", mqtt_server, mqtt_port, connection_return_code)
+                    "Failed to connect to MQTT %s:%i. Will try again in 10 seconds.",
+                    mqtt_server,
+                    mqtt_port,
+                )
                 time.sleep(10.)
         self.client.loop_start()
         process_thread = threading.Thread(target=self.process_in_queue, args=(self.client, self.msg_in_queue))
@@ -38,31 +40,52 @@ class MqttManager:
         process_thread.start()
 
     def on_mqtt_connect(self, client, userdata, flags, rc):
+        if rc != 0:
+            logging.error("MQTT connection failed with return code: %s", rc)
+            return
         logging.info("Connected to MQTT Server")
         # subscribe to panelRecvTopic of each panel
         for settings_panel in self.settings["nspanels"].values():
-            client.subscribe(settings_panel["panelRecvTopic"])
+            topic = settings_panel["panelRecvTopic"]
+            result, _ = client.subscribe(topic)
+            if result == mqtt.MQTT_ERR_SUCCESS:
+                logging.debug("Subscribed to panel topic: %s", topic)
+            else:
+                logging.error("Failed to subscribe to panel topic '%s' (result=%s)", topic, result)
 
     def on_mqtt_message(self, client, userdata, msg):
         try:
-            if msg.payload.decode() == "":
+            payload_text = msg.payload.decode('utf-8')
+            if payload_text == "":
+                logging.debug("Ignoring empty MQTT payload on topic: %s", msg.topic)
                 return
             if msg.topic in self.msg_out_queue_list.keys():
-                data = json.loads(msg.payload.decode('utf-8'))
+                data = json.loads(payload_text)
                 if "CustomRecv" in data:
                     queue = self.msg_out_queue_list[msg.topic]
                     queue.put(("MQTT:", data["CustomRecv"]))
+                else:
+                    logging.debug("JSON payload on topic '%s' has no 'CustomRecv' key", msg.topic)
             else:
                 logging.debug("Received unhandled message on topic: %s", msg.topic)
+        except UnicodeDecodeError:
+            logging.exception("Failed to decode MQTT payload as UTF-8 on topic: %s", msg.topic)
+        except json.JSONDecodeError:
+            logging.exception("Failed to parse MQTT JSON payload on topic: %s", msg.topic)
         except Exception:  # pylint: disable=broad-exception-caught
-            logging.exception("Something went wrong during processing of message:")
+            logging.exception("Unexpected error while processing MQTT message on topic: %s", msg.topic)
             try:
                 logging.error(msg.payload.decode('utf-8'))
-            except:  # pylint: disable=bare-except
+            except Exception:  # pylint: disable=broad-exception-caught
                 logging.error(
                     "Something went wrong when processing the exception message, couldn't decode payload to utf-8.")
 
     def process_in_queue(self, client, msg_in_queue):
         while True:
-            msg = msg_in_queue.get()
+            try:
-            client.publish(msg[0], msg[1])
+                msg = msg_in_queue.get()
+                result = client.publish(msg[0], msg[1])
+                if result.rc != mqtt.MQTT_ERR_SUCCESS:
+                    logging.error("Failed publishing message to topic '%s' (rc=%s)", msg[0], result.rc)
+            except Exception:  # pylint: disable=broad-exception-caught
+                logging.exception("Failed processing outgoing MQTT queue message")

nspanel-lovelace-ui/rootfs/usr/bin/mqtt-manager/panel.py

@@ -103,10 +103,13 @@ class LovelaceUIPanel:
         libs.panel_cmd.page_type(self.msg_out_queue, self.sendTopic, "pageStartup")
 
 
-    def schedule_thread_target(self):
+    def schedule_thread_target(self):
-        while True:
+        while True:
-            self.schedule.exec_jobs()
+            try:
-            time.sleep(1)
+                self.schedule.exec_jobs()
+            except Exception:
+                logging.exception("Scheduler execution failed for panel '%s'", self.name)
+            time.sleep(1)
 
     def update_time(self):
         use_timezone = tz.gettz(self.settings["timeZone"])
@@ -200,12 +203,15 @@ class LovelaceUIPanel:
                 return card
         return list(self.cards.values())[0]
 
-    def customrecv_event_callback(self, msg):
+    def customrecv_event_callback(self, msg):
-        logging.debug("Recv Message from NsPanel (%s): %s", self.name, msg)
+        logging.debug("Recv Message from NsPanel (%s): %s", self.name, msg)
-        msg = msg.split(",")
+        msg = msg.split(",")
-        # run action based on received command
+        if len(msg) < 2:
-        if msg[0] == "event":
+            logging.error("Malformed panel message on '%s': %s", self.name, msg)
-            if msg[1] == "startup":
+            return
+        # run action based on received command
+        if msg[0] == "event":
+            if msg[1] == "startup":
                 # TODO: Handle Update Messages
                 self.update_date()
                 self.update_time()
@@ -226,15 +232,24 @@ class LovelaceUIPanel:
                 self.render_current_page(switchPages=True)
             if msg[1] == "renderCurrentPage":
                 self.render_current_page(requested=True)
-            if msg[1] == "buttonPress2":
+            if msg[1] == "buttonPress2":
-                entity_id = msg[2]
+                if len(msg) < 4:
-                if entity_id == "":
+                    logging.error("Malformed buttonPress2 payload on '%s': %s", self.name, msg)
-                    return
+                    return
-                btype = msg[3]
+                entity_id = msg[2]
-                value = msg[4] if len(msg) > 4 else None
+                if entity_id == "":
-                if btype == "bExit":
+                    return
-                    if entity_id in ["screensaver", "screensaver2"] and self.settings.get("screensaver").get("doubleTapToUnlock") and value == "1":
+                btype = msg[3]
-                        return
+                value = msg[4] if len(msg) > 4 else None
+                entity_config = {}
+                action_context = {
+                    "panel": self.name,
+                    "btype": btype,
+                    "value": value,
+                }
+                if btype == "bExit":
+                    if entity_id in ["screensaver", "screensaver2"] and self.settings.get("screensaver").get("doubleTapToUnlock") and value == "1":
+                        return
 
                     # in case privious_cards is empty add a default card
                     if len(self.privious_cards) == 0:
@@ -249,12 +264,12 @@ class LovelaceUIPanel:
                     return
 
                 # replace iid with real entity id
-                if entity_id.startswith("iid."):
+                if entity_id.startswith("iid."):
-                    iid = entity_id.split(".")[1]
+                    iid = entity_id.split(".")[1]
-                    for e in self.current_card.entities:
+                    for e in self.current_card.entities:
-                        if e.iid == iid:
+                        if e.iid == iid:
-                            entity_id = e.entity_id
+                            entity_id = e.entity_id
-                            entity_config = e.config
+                            entity_config = e.config
 
                 match btype:
                     case 'button':
@@ -271,31 +286,51 @@ class LovelaceUIPanel:
                                     self.privious_cards.append(self.current_card)
                                     self.current_card = self.searchCard(card_iid)
                                     self.render_current_page(switchPages=True)
-                            # send ha stuff to ha
+                            # send ha stuff to ha
-                            case _:
+                            case _:
-                                ha_control.handle_buttons(entity_id, btype, value, entity_config=entity_config)
+                                ha_control.handle_buttons(
+                                    entity_id,
+                                    btype,
+                                    value,
+                                    entity_config=entity_config,
+                                    action_context=action_context,
+                                )
                     case 'cardUnlock-unlock':
                         card_iid = entity_id.split(".")[1]
                         if int(self.current_card.config.get("pin")) == int(value):
                             self.privious_cards.append(self.current_card)
                             self.current_card = self.searchCard(card_iid)
                             self.render_current_page(switchPages=True)
-                    case 'mode-light':
+                    case 'mode-light':
-                        ha_control.handle_buttons(entity_id, btype, value, entity_config=entity_config)
+                        ha_control.handle_buttons(
-                    case _:
+                            entity_id,
-                        ha_control.handle_buttons(entity_id, btype, value)
+                            btype,
+                            value,
+                            entity_config=entity_config,
+                            action_context=action_context,
+                        )
+                    case _:
+                        ha_control.handle_buttons(
+                            entity_id,
+                            btype,
+                            value,
+                            action_context=action_context,
+                        )
 
-            if msg[1] == "pageOpenDetail":
+            if msg[1] == "pageOpenDetail":
-                entity_id = msg[3]
+                if len(msg) < 4:
-                # replace iid with real entity id
+                    logging.error("Malformed pageOpenDetail payload on '%s': %s", self.name, msg)
-                if entity_id.startswith("iid."):
+                    return
-                    iid = entity_id.split(".")[1]
+                entity_id = msg[3]
-                    for e in self.current_card.entities:
+                effectList = None
-                        if e.iid == iid:
+                # replace iid with real entity id
-                            entity_id = e.entity_id
+                if entity_id.startswith("iid."):
-                            effectList = None
+                    iid = entity_id.split(".")[1]
-                            if entity_id.startswith("light"):
+                    for e in self.current_card.entities:
-                                effectList = e.config.get("effectList")
+                        if e.iid == iid:
+                            entity_id = e.entity_id
+                            if entity_id.startswith("light"):
+                                effectList = e.config.get("effectList")
                 if msg[2] == "popupInSel": #entity_id.split(".")[0] in ['input_select', 'media_player']:
                     libs.panel_cmd.entityUpdateDetail2(self.msg_out_queue, self.sendTopic, detail_open(self.settings["locale"], msg[2], entity_id, msg[3], self.msg_out_queue, sendTopic=self.sendTopic, options_list=effectList))
                 else: