From 101e69bbde1cf7c36737d03b87b7b3884735065d Mon Sep 17 00:00:00 2001 From: Johannes Braun <29555657+joBr99@users.noreply.github.com> Date: Sun, 22 Feb 2026 01:15:08 +0100 Subject: [PATCH] add migration page --- docs-standalone/docs/_assets/user.css | 32 ++++++ docs-standalone/docs/migration-appdaemon.md | 120 ++++++++++++++++++++ docs-standalone/mkdocs.yml | 1 + docs/_assets/user.css | 32 ++++++ docs/config-migration-standalone.md | 75 ++++++++++++ mkdocs.yml | 1 + 6 files changed, 261 insertions(+) create mode 100644 docs-standalone/docs/migration-appdaemon.md create mode 100644 docs/config-migration-standalone.md diff --git a/docs-standalone/docs/_assets/user.css b/docs-standalone/docs/_assets/user.css index 18a03f81..84bddd2c 100644 --- a/docs-standalone/docs/_assets/user.css +++ b/docs-standalone/docs/_assets/user.css @@ -15,6 +15,38 @@ 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. */ diff --git a/docs-standalone/docs/migration-appdaemon.md b/docs-standalone/docs/migration-appdaemon.md new file mode 100644 index 00000000..f53f0e34 --- /dev/null +++ b/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.` 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. diff --git a/docs-standalone/mkdocs.yml b/docs-standalone/mkdocs.yml index 2f8094ae..40b04820 100644 --- a/docs-standalone/mkdocs.yml +++ b/docs-standalone/mkdocs.yml @@ -52,6 +52,7 @@ 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 diff --git a/docs/_assets/user.css b/docs/_assets/user.css index 18a03f81..84bddd2c 100644 --- a/docs/_assets/user.css +++ b/docs/_assets/user.css @@ -15,6 +15,38 @@ 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. */ diff --git a/docs/config-migration-standalone.md b/docs/config-migration-standalone.md new file mode 100644 index 00000000..9781add8 --- /dev/null +++ b/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.` 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/) diff --git a/mkdocs.yml b/mkdocs.yml index cb11bed6..d8074c7d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,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