ioBroker.harvia-fenix

Hier geht es zur deutschen Version der Dokumentation.

An ioBroker adapter to integrate and control your Harvia Fenix sauna control unit via the MyHarvia cloud infrastructure.

For more information about Harvia and their sauna control units, please visit the official Harvia website.

⚠️ CRITICAL SAFETY WARNING & DISCLAIMER

Remote operation of a sauna heater is subject to strict safety regulations! According to the European safety standard EN 60335-2-53 in conjunction with EN 60335-1, fire protection measures are mandatory for remote control setups. The sauna cabin must be equipped with an approved door sensor or a safety switch-off system. This ensures that the heater cannot be started remotely or via a timer if a flammable object (e.g., a towel) has been left on or near the heater.

• No Liability: The developer of this adapter assumes absolutely no responsibility, warranty, or liability for any damages, fires, injuries, or legal issues resulting from the use or misconfiguration of this software. You operate this integration entirely at your own risk.
• Trademarks: Harvia and MyHarvia 2 are registered trademarks of Harvia Group. This adapter is an independent, community-driven open-source project and is neither officially endorsed, sponsored, nor supported by Harvia.

Installation

The adapter is available in the official ioBroker repository. You can install it directly via the ioBroker Admin web interface.

Via ioBroker Admin

1. Open your ioBroker web interface in a browser (e.g. 192.168.1.33:8081).
2. Click on the Adapters tab.
3. Type "harvia-fenix" in the filter.
4. Click on the three dots and then on the "+" symbol of the Harvia Fenix adapter to add an instance.

Setup

Additional to the adapter installation you must configure the adapter instance with your MyHarvia account details.

Prerequisites

1. Node.js >= 22
2. A registered account within the official MyHarvia 2 smartphone application.
3. Your valid login credentials:
   • Email Address
   • Password

Note: We recommend setting up a separate account for ioBroker in the Harvia 2 app and using those login credentials in the instance.

ioBroker Configuration

1. Open your ioBroker interface in a browser (e.g. 192.168.1.33:8081).
2. Navigate to Tab Instances and click the settings icon of your harvia-fenix.0 instance.
3. Enter your Email Address and Password of your MyHarvia account.
4. If you leave the Device ID field empty, the adapter will automatically search for devices linked to your account upon startup. It will use the first device it finds as the active unit.
5. Adjust optional parameters: Poll Interval (seconds), Minimum/Maximum Target Temperature Limits (°C), and Maximum Heating Duration (minutes).
6. Click on Save & Close.

Device Configuration & Multi-Device Support

Automatic Discovery

If you leave the Device ID field in the adapter settings empty, the adapter will automatically search for devices linked to your account upon startup. It will use the first device it finds as the active unit. The detected ID will be printed to the ioBroker log.

Manual Device ID

For most users with a single sauna, automatic discovery is sufficient. However, it is recommended to copy the detected ID from the log and paste it into the configuration to ensure a stable connection to the specific hardware.

Multiple Saunas

If your MyHarvia account manages multiple control units (e.g. one at home and one in a vacation cottage):

1. Create a separate instance of the adapter for each sauna (e.g. harvia-fenix.0 and harvia-fenix.1).
2. Manually enter the specific Device ID for each unit in its respective instance configuration. This allows you to monitor and control both saunas independently with their own set of datapoints.

Shared / Guest Accounts & The Partner ID

🟢 Default Scenario (Primary Account / Sauna Owner)

If you configure the adapter using the primary MyHarvia account (the account that initially registered the sauna in the mobile app):

• Leave both Device ID and Partner ID empty in the configuration.
• The adapter will automatically discover and connect to your sauna on startup.

🟡 Shared / Guest Account Scenario (e.g. Dedicated ioBroker Account)

If the sauna was shared from the owner's account to a secondary guest account via the MyHarvia 2 app, Harvia's automatic discovery endpoint returns an empty device list ({"devices":[]}) for guest tokens.

In this scenario, you must manually specify both the Device ID and the Owner's Partner ID in the adapter settings:

The 60-Second Method to Obtain Both IDs:

1. In the adapter configuration, temporarily enter the login credentials of the Primary/Owner Account and click Save.
2. Open the ioBroker log. The adapter connects immediately and prints lines containing both IDs:
   • Found device: ... (ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) ➡️ This is your Device ID.
   • Using partner ID from user token: ORG/prod:0:6656 ➡️ This is your Partner ID (typically ORG/prod:0:6656 or ORG/prod:0:6656:0).
3. Copy both values.
4. Re-open the configuration, switch back to your Guest Account credentials, paste the copied Device ID and Partner ID into their respective optional fields, and click Save & Close.

The guest account can now control the shared sauna directly and reliably!

Compatibility Note

• Supported: Harvia Fenix control units managed via the MyHarvia 2 mobile application.
• NOT Supported: Harvia Xenio series (e.g. Xenio WiFi / CX001WIFI). The Xenio series relies on a legacy hardware ecosystem and uses the older "MyHarvia for Xenio" app, which is fundamentally incompatible with the API utilized by this adapter.

Usage

The adapter maps your sauna's cloud states into structured ioBroker datapoints under harvia-fenix.0.*.

Available Datapoints

Intelligent Features & Automations

1. Adaptive Heating Prognosis & Anomaly Detection

• Learned Heating Duration (estimatedHeatingTimeRemaining & info.avgHeatingRate):
  The adapter learns the heating rate of your cabin (°C per minute). During an active session, it blends historical performance with live temperature progression to calculate an accurate remaining heating time.
• Bidirectional Anomaly Detection (info.heatingAnomaly, info.heatingAnomalyType, info.heatingAnomalyDesc):
  After at least 10 minutes of active heating, the adapter compares the live heating rate against the learned historical average:
  • Too slow (too_slow): If live heating drops below 50% of average (e.g. door left open or heating element failure), info.heatingAnomaly switches to true.
  • Too fast (too_fast): If live heating exceeds 180% of average (e.g. temperature sensor displaced, heat pocket at sensor, or sticking relay), info.heatingAnomaly switches to true.
  • info.heatingAnomalyDesc provides human-readable diagnostic details for push alerts or dashboards.

2. Notifications (Push Triggers)

The adapter automatically calculates the heating progress and provides indicator datapoints specifically designed for triggering push notifications (e.g. via Telegram, Pushover, or 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 });
});

Note: These states will automatically reset to false when the heater is turned off or when a new heating session starts.

Troubleshooting

Common API Errors & Status Messages in errorMsg

• Action blocked (403 Forbidden). Remote start authorization (Safety Loop) at panel might not be active.
  • Cause: The European safety standard requires that remote starting can only be activated if the safety loop/door sensor is closed and remote start has been physically armed at the sauna panel.
  • Solution: Close the sauna door and press the Remote Start / Fernstart button on your physical Harvia control panel. The remote icon on the screen must be active. Once done, you can control the sauna via the adapter.
• Cloud lock: Device busy, command discarded. (Logged as debug)
  • Cause: Harvia's API rate-limits commands if they are sent in rapid succession (e.g. rapid clicking in the UI) to protect the hardware.
  • Solution: Wait a few seconds between commands. The adapter automatically discards commands that are sent too quickly to prevent API blocking.

To-Do

• Program automatic cold beverage reminder timed for the post-sauna cooldown 🍺❄️
• Design AI-powered robotic towel-waving assistant for the ultimate Aufguss 🧖‍♂️🪣

Changelog

WORK IN PROGRESS

• (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

0.4.0 (2026-08-13)

• (meistermopper) Add adaptive heating duration prognosis and anomaly detection
• (meistermopper) Add dev script shortcut for dev-server watch in package.json
• (meistermopper) Clarify Partner ID and guest account setup instructions
• (meistermopper) Document adaptive heating prognosis and anomaly detection
• (meistermopper) Add strict privacy and anonymization rule to AGENTS.md
• (meistermopper) Clean up To-Do list and add fun future wishlist items

0.3.2 (2026-08-11)

• (meistermopper) Use absolute GitHub URLs for language switching links in README files
• (meistermopper) Remove latest repository and translation badges from README files
• (meistermopper) Mark stable repository addition as completed in To-Do list
• (meistermopper) Remove direct npm installation instructions from README files
• (dependabot) Bump axios from 1.18.1 to 1.19.0
• (meistermopper) Center adapter logo in README files
• (meistermopper) Add Weblate translation status badge to README files
• (meistermopper) Add npm run translate step to release-before-commit script
• (meistermopper) Replace static latest badge with dynamic iobroker.live badge

0.3.1 (2026-08-04)

• (meistermopper) Update GitHub Actions in auto-translate workflow to v7
• (meistermopper) Add Git commit and push authorization rule to AGENTS.md
• (meistermopper) Add auto-translate workflow for automatic i18n translations
• (meistermopper) Add missing CHANGELOG_OLD link to README files
• (meistermopper) Fix untranslated news entries for 0.2.8 in io-package.json
• (meistermopper) Add common.news translation rule to AGENTS.md
• (meistermopper) Remove redundant npm badge and move Test and Release badge after NPM banner

License

MIT License

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

See the LICENSE file for the full license text.