WLED Stair

Русский и English описания ниже.

RU

Что это

GUI-приложение (Tkinter) для управления WLED через UDP realtime, где позиция подсветки задается источником данных (manual, home_assistant_ws, mqtt).

Что умеет

• Автопоиск WLED устройств по mDNS (_wled._tcp.local).
• Подключение к устройству кликом в списке (Devices).
• Чтение количества LED из /json/info.
• Управление эффектами подсветки по позиции объекта.
• Переключение языка интерфейса: Русский / English.
• Переводы вынесены в /Users/idobryak/OpenAi/projects/wled-stair/wled_stair/i18n/ (en.py, ru.py) с автоподхватом языков.
• Источники данных:
  • manual: ручной слайдер позиции.
  • home_assistant_ws: подписка на Home Assistant WebSocket (/api/websocket).
  • mqtt: подписка на MQTT topic.
• Сохранение настроек в settings.json.
• Секреты (HA token, MQTT password) через системный keychain (keyring) с fallback в settings.json.

Интерфейс (в порядке отображения)

1. Devices

• Список найденных WLED устройств.
• Клик по устройству: подключение.
• Повторный клик по уже подключенному устройству: отключение.

2. Connection

• Поле IP.
• Additional parameters ▸: Port, Timeout (s), UDP Port.

3. INFO

• Status, LEDs, Counted Position, Discovery, Secrets storage.
• Counted Position = src + offset с итоговым clamping в 0..100%.

4. General Settings

• Offset (-50..50)%.
• Effect:
  • Частичная подсветка
  • Подстветка со стороны
  • Подстветка от цента
  • Подстветка к центру
• Для Частичная подсветка: дополнительный параметр LEDs each side.

5. Data Source

• Mode: manual / home_assistant_ws / mqtt.
• Manual Input: Position (0-100%).
• Home Assistant: статус + Last raw/numeric/position, URL, Token, Entity ID, Min/Max, Invert.
• MQTT: статус + Last raw/numeric/position, Host/Port/Topic, Username/Password, TLS, QoS, Min/Max, Invert.

6. Кнопка Save Settings

Поведение источников данных

• Все источники управляют именно позицией (0..100%), не яркостью.
• manual:
  • Позиция 0 и 100 трактуется как отсутствие объекта (подсветка снимается с fade).
• home_assistant_ws:
  • unknown/unavailable/none/null и нечисловые значения считаются неизвестными.
  • Значение вне min..max считается Out of range.
• mqtt:
  • Поддерживаются payload:
    • число (например 123.4)
    • JSON { "value": ... }
    • JSON { "state": ... }
  • unknown/unavailable/none/null и нечисловые значения считаются неизвестными.
  • Значение вне min..max считается Out of range.
• Для сетевых источников (home_assistant_ws, mqtt) отображаются статусы с префиксами:
  • [INFO], [OK], [WARN], [ERROR].

Логика эффектов и анимации

• Плавное включение: примерно 300 ms.
• Плавное выключение: примерно 2000 ms.
• Время развития эффектов (from_side, from_center, to_center): 4000 ms.
• Если источник перестал давать валидную позицию, выход гасится после 3000 ms с fade.
• Ограничение DRGB: максимум 490 LED.

Настройки и безопасность

• Файл настроек: settings.json.
• Для добавления нового языка: создать файл в wled_stair/i18n/ с LANGUAGE_ID и TRANSLATIONS.
• Секреты:
  • System keychain (предпочтительно).
  • settings.json (fallback), если keyring недоступен.
• Legacy-миграция поддерживается:
  • старый блок ha переносится в sources.home_assistant_ws.

Запуск

uv run python main.py

или

python main.py

Лицензия

Проект распространяется под лицензией Apache 2.0. См. LICENSE.

---

EN

What it is

A Tkinter GUI app to control WLED via UDP realtime, where light position is driven by a pluggable data source (manual, home_assistant_ws, mqtt).

Features

• Automatic WLED discovery via mDNS (_wled._tcp.local).
• Click-to-connect device list (Devices).
• LED count loading from /json/info.
• Position-driven lighting effects.
• UI language switch: Russian / English.
• Translations are split into /Users/idobryak/OpenAi/projects/wled-stair/wled_stair/i18n/ (en.py, ru.py) and discovered automatically.
• Data sources:
  • manual: slider-based position.
  • home_assistant_ws: Home Assistant WebSocket subscription (/api/websocket).
  • mqtt: MQTT topic subscription.
• Settings persisted in settings.json.
• Secrets (HA token, MQTT password) stored in system keychain (keyring) with fallback to settings.json.

UI layout (top-to-bottom)

1. Devices

• Discovered WLED devices.
• Click to connect.
• Click connected device again to disconnect.

2. Connection

• IP field.
• Additional parameters ▸: Port, Timeout (s), UDP Port.

3. INFO

• Status, LEDs, Counted Position, Discovery, Secrets storage.
• Counted Position = src + offset, clamped to 0..100%.

4. General Settings

• Offset (-50..50)%.
• Effect:
  • Частичная подсветка
  • Подстветка со стороны
  • Подстветка от цента
  • Подстветка к центру
• For Частичная подсветка: extra LEDs each side control.

5. Data Source

• Mode: manual / home_assistant_ws / mqtt.
• Manual Input: Position (0-100%).
• Home Assistant: status + Last raw/numeric/position, URL, Token, Entity ID, Min/Max, Invert.
• MQTT: status + Last raw/numeric/position, Host/Port/Topic, Username/Password, TLS, QoS, Min/Max, Invert.

6. Save Settings button

Data source behavior

• All sources control position (0..100%), not brightness.
• manual:
  • Positions 0 and 100 are treated as no object present (output fades out).
• home_assistant_ws:
  • unknown/unavailable/none/null and non-numeric states are treated as unknown.
  • Values outside min..max are treated as Out of range.
• mqtt:
  • Supported payloads:
    • number (e.g. 123.4)
    • JSON { "value": ... }
    • JSON { "state": ... }
  • unknown/unavailable/none/null and non-numeric payloads are treated as unknown.
  • Values outside min..max are treated as Out of range.
• For network sources (home_assistant_ws, mqtt), statuses use:
  • [INFO], [OK], [WARN], [ERROR].

Effects and animation timing

• Fade-in time: about 300 ms.
• Fade-out time: about 2000 ms.
• Effect ramp time (from_side, from_center, to_center): 4000 ms.
• If source stops providing valid position, output is released after 3000 ms and faded out.
• DRGB limit: up to 490 LEDs.

Settings and security

• Settings file: settings.json.
• To add a new language: create a file in wled_stair/i18n/ with LANGUAGE_ID and TRANSLATIONS.
• Secrets storage:
  • System keychain (preferred).
  • settings.json (fallback) when keyring is unavailable.
• Legacy migration:
  • old ha block is migrated to sources.home_assistant_ws.

Run

uv run python main.py

or

python main.py

License

Licensed under Apache 2.0. See LICENSE.