ioBroker.harvia-fenix

Hier geht es zur deutschen Version der Dokumentation.

Адаптер ioBroker для интеграции и управления блоком управления сауны Harvia Fenix через облачную инфраструктуру MyHarvia.

Для получения более подробной информации о компании Harvia и ее блоках управления сауной, пожалуйста, посетите официальный сайт Harvia .

⚠️ ВАЖНОЕ ПРЕДУПРЕЖДЕНИЕ О БЕЗОПАСНОСТИ И ОТКАЗ ОТ ОТВЕТСТВЕННОСТИ

Дистанционное управление нагревателем для сауны подлежит строгим правилам безопасности! В соответствии с европейским стандартом безопасности EN 60335-2-53 в сочетании с EN 60335-1 , для систем дистанционного управления обязательны меры противопожарной защиты. Сауна должна быть оборудована сертифицированным датчиком открытия двери или системой аварийного отключения. Это гарантирует, что нагреватель не сможет быть запущен дистанционно или по таймеру, если на нагревателе или рядом с ним оставлен легковоспламеняющийся предмет (например, полотенце).

• Отсутствие ответственности: Разработчик данного адаптера не несет никакой ответственности, не предоставляет никаких гарантий и не несет никакой ответственности за любые убытки, пожары, травмы или юридические проблемы, возникшие в результате использования или неправильной настройки данного программного обеспечения. Вы используете эту интеграцию исключительно на свой страх и риск.
• Торговые марки: Harvia и MyHarvia 2 являются зарегистрированными товарными знаками Harvia Group. Этот адаптер — независимый проект с открытым исходным кодом, разрабатываемый сообществом, и не имеет официальной поддержки, одобрения или спонсорства со стороны Harvia.

Установка

Адаптер доступен в официальном репозитории ioBroker. Вы можете установить его непосредственно через веб-интерфейс администратора ioBroker.

Через ioBroker Admin

1. Откройте веб-интерфейс ioBroker в браузере (например, 192.168.1.33:8081).
2. Перейдите на вкладку «Адаптеры» .
3. Введите "harvia-fenix" в фильтр.
4. Чтобы добавить экземпляр, нажмите на три точки, а затем на символ «+» адаптера Harvia Fenix .

Настраивать

Помимо установки адаптера, необходимо настроить экземпляр адаптера, указав данные вашей учетной записи MyHarvia.

Предварительные требования

1. Node.js >= 22
2. Зарегистрированный аккаунт в официальном приложении MyHarvia 2 для смартфонов.
3. Ваши действительные учетные данные для входа:
   • Адрес электронной почты
   • Пароль

Примечание: Мы рекомендуем создать отдельную учетную запись для ioBroker в приложении Harvia 2 и использовать эти учетные данные для входа в систему.

Конфигурация ioBroker

1. Откройте интерфейс ioBroker в браузере (например, 192.168.1.33:8081).
2. Перейдите на вкладку « Экземпляры» и щелкните значок настроек вашего экземпляра. harvia-fenix.0 пример.
3. Введите свой адрес электронной почты и пароль от учетной записи MyHarvia.
4. Если оставить поле «Идентификатор устройства» пустым, адаптер автоматически выполнит поиск устройств, связанных с вашей учетной записью, при запуске. В качестве активного устройства будет использоваться первое найденное устройство.
5. Настройте дополнительные параметры: интервал опроса (секунды), минимальный/максимальный предел целевой температуры (°C) и максимальная продолжительность нагрева (минуты).
6. Нажмите «Сохранить и закрыть» .

Настройка устройства и поддержка нескольких устройств

Автоматическое обнаружение

Если оставить поле « Идентификатор устройства» в настройках адаптера пустым, адаптер автоматически выполнит поиск устройств, связанных с вашей учетной записью, при запуске. В качестве активного устройства будет использоваться первое найденное устройство. Обнаруженный идентификатор будет выведен в журнал ioBroker.

Ручной идентификатор устройства

Для большинства пользователей с одной сауной достаточно автоматического обнаружения. Однако рекомендуется скопировать обнаруженный ID из журнала и вставить его в конфигурацию, чтобы обеспечить стабильное соединение с конкретным оборудованием.

Несколько саун

Если ваша учетная запись MyHarvia управляет несколькими блоками управления (например, одним дома и одним в дачном домике):

1. Создайте отдельный экземпляр адаптера для каждой сауны (например) harvia-fenix.0 и harvia-fenix.1).
2. В конфигурации соответствующего экземпляра вручную введите идентификатор устройства (Device ID) для каждого блока. Это позволит вам независимо отслеживать и контролировать обе сауны, используя собственный набор параметров.

Общие/гостевые учетные записи и идентификатор партнера

🟢 Сценарий по умолчанию (Основной аккаунт / Владелец сауны)

Если вы настраиваете адаптер, используя основную учетную запись MyHarvia (учетную запись, которая изначально зарегистрировала сауну в мобильном приложении):

• В настройках оставьте поля «Идентификатор устройства» и «Идентификатор партнера» пустыми .
• Адаптер автоматически обнаружит вашу сауну и подключится к ней при включении.

🟡 Сценарий использования общего/гостевого аккаунта (например, выделенный аккаунт ioBroker)

Если доступ к сауне был предоставлен с учетной записи владельца на дополнительную гостевую учетную запись через приложение MyHarvia 2, точка автоматического обнаружения Harvia возвращает пустой список устройств. {"devices":[]}) для гостевых токенов.

В этом случае необходимо вручную указать идентификатор устройства (Device ID) и идентификатор партнера владельца (Wonder's Partner ID) в настройках адаптера:

Способ получения обоих идентификаторов за 60 секунд:

1. В настройках адаптера временно введите учетные данные для входа в систему основной/владельческой учетной записи и нажмите «Сохранить» .
2. Откройте лог ioBroker. Адаптер мгновенно подключается и выводит строки, содержащие оба идентификатора:
   • Found device: ... (ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) ➡️ Это идентификатор вашего устройства .
   • Using partner ID from user token: ORG/prod:0:6656 ➡️ Это ваш партнерский идентификатор (обычно) ORG/prod:0:6656 или ORG/prod:0:6656:0).
3. Скопируйте оба значения.
4. Откройте настройки заново, вернитесь к учетным данным гостевой учетной записи , вставьте скопированные идентификатор устройства и идентификатор партнера в соответствующие необязательные поля и нажмите «Сохранить и закрыть» .

Теперь гостевой аккаунт может напрямую и надёжно управлять общей сауной!

Примечание о совместимости

• Поддерживаются: блоки управления Harvia Fenix , управляемые через мобильное приложение MyHarvia 2 .
• НЕ поддерживается: серия Harvia Xenio (например, Xenio WiFi / CX001WIFI). Серия Xenio использует устаревшую аппаратную экосистему и старое приложение "MyHarvia for Xenio" , которое принципиально несовместимо с API, используемым этим адаптером.

Использование

Адаптер преобразует облачные состояния вашей сауны в структурированные данные ioBroker. harvia-fenix.0.*.

Доступные точки данных

Интеллектуальные функции и автоматизация

1. Адаптивное прогнозирование нагрева и обнаружение аномалий

• Продолжительность нагрева, изученная в ходе исследования (estimatedHeatingTimeRemaining &info.avgHeatingRate):
  Адаптер запоминает скорость нагрева салона (°C в минуту). Во время активной сессии он объединяет исторические данные с динамикой изменения температуры в реальном времени, чтобы точно рассчитать оставшееся время обогрева.
• Двунаправленное обнаружение аномалий (info.heatingAnomaly, info.heatingAnomalyType, info.heatingAnomalyDesc):
  После как минимум 10 минут активного нагрева адаптер сравнивает текущую скорость нагрева с усредненным историческим значением:
  • Слишком медленно (too_slow Если уровень нагрева падает ниже 50% от среднего (например, из-за открытой двери или неисправности нагревательного элемента), info.heatingAnomaly переключается на true.
  • Слишком быстро (too_fast Если температура нагрева превышает 180% от средней (например, смещение датчика температуры, образование теплового кармана у датчика или залипание реле), info.heatingAnomaly переключается на true.
  • info.heatingAnomalyDesc Предоставляет удобочитаемые диагностические данные для push-уведомлений или информационных панелей.

2. Уведомления (push-триггеры)

Адаптер автоматически рассчитывает степень нагрева и предоставляет индикаторные данные, специально разработанные для запуска push-уведомлений (например, через Telegram, Pushover или Alexa):

// Trigger for the 10-minute pre-warning
on({ id: 'harvia-fenix.0.readyNotified10Min', change: 'ne', val: true }, function () {
    const targetTemp = getState('harvia-fenix.0.targetTemp').val;
    sendTo('telegram.0', 'send', { text: `🧖 The sauna will reach its target temperature (${targetTemp}°C) in about 10 minutes.` });
});

// Trigger when the sauna is fully ready
on({ id: 'harvia-fenix.0.targetReachedNotified', change: 'ne', val: true }, function () {
    const targetTemp = getState('harvia-fenix.0.targetTemp').val;
    sendTo('telegram.0', 'send', { text: `♨️ The sauna has reached the target temperature of ${targetTemp}°C and is ready!` });
});

// Trigger on heating anomaly (too slow or too fast)
on({ id: 'harvia-fenix.0.info.heatingAnomaly', change: 'ne', val: true }, function () {
    const desc = getState('harvia-fenix.0.info.heatingAnomalyDesc').val;
    sendTo('telegram.0', 'send', { text: desc });
});

Примечание: Эти состояния будут автоматически сброшены до исходного состояния. false когда обогреватель выключен или когда начинается новый сеанс обогрева.

3. Профили саун (profiles &activeProfile)

• Доступные профили (profiles):
  Отображает предварительно настроенные программы сауны из вашего приложения MyHarvia 2 (например, «Мягкий» , «Уютный» , «Горячий» ) в виде массива JSON, включающего предустановленные целевые температуры и таймеры.
• Профили переключения (activeProfile):
  Данные доступны для чтения/записи с использованием индекса, начинающегося с 0:
  • 0 = мягкий
  • 1 = уютный
  • 2 = горячий
  • Написание числа для activeProfile отправляет запрос на изменение профиля непосредственно в облако Harvia (PATCH /devices/profile), автоматически применяя заданную в профиле целевую температуру и продолжительность сеанса к сауне.
  • Пример (скрипта):

  // Switch to the cozy sauna profile
  setState('harvia-fenix.0.activeProfile', 1);
  

4. Центр мероприятий и безопасности (events.*)

• Система контроля аварийной остановки (events.safetyTripped &events.safetyReason):
  Адаптер отслеживает работу защитных контуров дверей, термопредохранителей и блокировок предохранительных выключателей от службы Harvia Events Service. Если во время обогрева срабатывает активный предохранительный выключатель, events.safetyTripped переключается на true с четким объяснением в events.safetyReason.
• История событий (events.history):
  Сохраняет историю последних 15 событий, связанных с системой, дверями, ошибками и безопасностью, в виде структурированного массива JSON для панелей мониторинга VIS и ведения журналов аудита.

Поиск неисправностей

Типичные ошибки API и сообщения о состоянии в errorMsg

• ** Action blocked (403 Forbidden). Remote start authorization (Safety Loop) at panel might not be active. **
  • Причина: Европейский стандарт безопасности требует, чтобы дистанционный запуск мог быть активирован только в том случае, если защитная петля/датчик двери замкнуты и дистанционный запуск физически активирован на панели управления сауны.
  • Решение: Закройте дверь сауны и нажмите кнопку дистанционного запуска / Fernstart на физической панели управления Harvia. Значок пульта на экране должен быть активен. После этого вы сможете управлять сауной через адаптер.
• ** Cloud lock: Device busy, command discarded.(Записано как отладочная информация)**
  • Причина: API Harvia ограничивает скорость отправки команд, если они отправляются с большой частотой (например, при быстром нажатии кнопок в пользовательском интерфейсе), чтобы защитить оборудование.
  • Решение: Подождите несколько секунд между командами. Адаптер автоматически отбрасывает команды, отправленные слишком быстро, чтобы предотвратить блокировку API.

Задачи

• Программа автоматически напоминала о необходимости выпить прохладительный напиток после сауны 🍺❄️
• Создайте роботизированного помощника с искусственным интеллектом, который будет размахивать полотенцем, для идеального Aufguss 🧖‍♂️🪣

Changelog

WORK IN PROGRESS

• (meistermopper) Document activeProfile standard index mapping (0=mild, 1=cozy, 2=hot)

1.1.0 (2026-09-17)

• (meistermopper) Add Events & Safety Hub with dedicated events channel and states
• (meistermopper) Add safety trip detection, alarm indicators, and sliding history
• (meistermopper) Fix activeProfile endpoint to use PATCH /devices/profile per API spec
• (meistermopper) Document profiles and activeProfile switching behavior in README

1.0.0 (2026-09-17)

• (meistermopper) Add AWS AppSync WebSocket real-time push client
• (meistermopper) Add token refresh via /auth/refresh using refreshToken

0.6.0 (2026-09-16)

• (meistermopper) Add readyAt, readyAtMessage, timeToTargetFormatted states
• (meistermopper) Implement Harvia native 13-interval heating curve calculation
• (meistermopper) Add profiles, activeProfile, and standby time prognosis
• (meistermopper) Increase adapter logo display size in README files to 200px
• (meistermopper) Add breaking change callouts and older tag support to release notes
• (meistermopper) Add automated release notes generator for GitHub releases
• (meistermopper) Add check:repo script and integrate repochecker into test:local
• (meistermopper) Restore email in license copyright lines (S4050, S4051)
• (meistermopper) Fix license section in README to satisfy repo-checker rule W6034

0.5.1 (2026-09-12)

• (meistermopper) Replace adapter logo with custom MyFenix homage logo
• (meistermopper) Update @iobroker/adapter-core to 3.4.3 and @iobroker/testing to 6.2.1
• (meistermopper) Fix Mocha 12 instantiation in unit test runner on Node 22

0.5.0 (2026-09-09)

• (meistermopper) Add bidirectional heating anomaly detection (too slow / fast)
• (meistermopper) Update @alcalzone/release-script-plugin-license to 5.2.2
• (meistermopper) Add Node.js 26 to test matrix

License

MIT License

Copyright (c) 2026 meistermopper meister.mopper@gmail.com

See the LICENSE file for the full license text.