mirror of
https://github.com/joBr99/nspanel-lovelace-ui.git
synced 2026-02-22 22:18:38 +01:00
add documentation for standalone version
This commit is contained in:
Johannes Braun
25
.github/workflows/docs-standalone-release.yml
vendored
Normal file
25
.github/workflows/docs-standalone-release.yml
vendored
Normal file
@@ -0,0 +1,25 @@
|
|||||||
|
name: docs-standalone-ci
|
||||||
|
|
||||||
|
on:
|
||||||
|
workflow_dispatch:
|
||||||
|
push:
|
||||||
|
branches:
|
||||||
|
- main
|
||||||
|
paths:
|
||||||
|
- docs-standalone/**
|
||||||
|
- .github/workflows/docs-standalone-release.yml
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
deploy:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v6
|
||||||
|
with:
|
||||||
|
fetch-depth: 0
|
||||||
|
- uses: actions/setup-python@v6
|
||||||
|
with:
|
||||||
|
python-version: 3.x
|
||||||
|
- run: pip install mkdocs-material mike
|
||||||
|
- run: git config --global user.name Docs deploy
|
||||||
|
- run: git config --global user.email docs@dummy.bot.com
|
||||||
|
- run: mike deploy --config-file docs-standalone/mkdocs.yml --push --update-aliases standalone
|
||||||
80
docs-standalone/_assets/user.css
Normal file
80
docs-standalone/_assets/user.css
Normal file
@@ -0,0 +1,80 @@
|
|||||||
|
/*.md-header__button.md-logo img {
|
||||||
|
width: unset;
|
||||||
|
}*/
|
||||||
|
|
||||||
|
.md-main__inner {
|
||||||
|
margin-top: unset;
|
||||||
|
}
|
||||||
|
|
||||||
|
.md-nav__title {
|
||||||
|
display: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
/*.md-header,*/ .md-footer {
|
||||||
|
background-color: #333333;
|
||||||
|
}
|
||||||
|
|
||||||
|
.md-footer__inner.md-grid {
|
||||||
|
display: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.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;
|
||||||
|
}
|
||||||
137
docs-standalone/cards.md
Normal file
137
docs-standalone/cards.md
Normal file
@@ -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
|
||||||
|
```
|
||||||
61
docs-standalone/configuration.md
Normal file
61
docs-standalone/configuration.md
Normal file
@@ -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
|
||||||
|
```
|
||||||
45
docs-standalone/connection-modes.md
Normal file
45
docs-standalone/connection-modes.md
Normal file
@@ -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.
|
||||||
77
docs-standalone/entities.md
Normal file
77
docs-standalone/entities.md
Normal file
@@ -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]
|
||||||
|
```
|
||||||
55
docs-standalone/getting-started.md
Normal file
55
docs-standalone/getting-started.md
Normal file
@@ -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`
|
||||||
38
docs-standalone/index.md
Normal file
38
docs-standalone/index.md
Normal file
@@ -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.
|
||||||
59
docs-standalone/mkdocs.yml
Normal file
59
docs-standalone/mkdocs.yml
Normal file
@@ -0,0 +1,59 @@
|
|||||||
|
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
|
||||||
|
|
||||||
|
repo_name: jobr99/nspanel-lovelace-ui
|
||||||
|
repo_url: https://github.com/jobr99/nspanel-lovelace-ui
|
||||||
|
edit_uri: ""
|
||||||
|
|
||||||
|
copyright: "Copyright © 2026 Johannes Braun"
|
||||||
|
|
||||||
|
docs_dir: .
|
||||||
|
|
||||||
|
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
|
||||||
|
- "Screensaver": screensaver.md
|
||||||
|
- "Cards": cards.md
|
||||||
|
- "Entities": entities.md
|
||||||
|
- "Connection Modes": connection-modes.md
|
||||||
|
- "Troubleshooting": troubleshooting.md
|
||||||
57
docs-standalone/screensaver.md
Normal file
57
docs-standalone/screensaver.md
Normal file
@@ -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
|
||||||
|
```
|
||||||
63
docs-standalone/troubleshooting.md
Normal file
63
docs-standalone/troubleshooting.md
Normal file
@@ -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>`
|
||||||
Reference in New Issue
Block a user