FAQ

Frequently Asked Questions (FAQ)

Home Connect
Apple HomeKit
Compatibility and Integration
- Third-party Platforms and API Limitations
- Plugin Installation and Configuration
  - Why do I get an npm ERR! ENOTEMPTY error when installing or updating the plugin?
  - Why do configuration settings revert or cause programs[0].name is missing errors?

Home Connect

Home Connect or SingleKey ID Authorisation Issues

Why is the plugin not starting or failing to show an authorisation URL?

If the plugin does not provide an authorisation URL or fails to load, it is usually due to a configuration error in config.json preventing Homebridge from identifying the platform.

First, check the Homebridge logs for [HomeConnect] Initialising HomeConnect platform.... If this line is missing, the plugin is not being loaded. Common causes include:

Incorrect Nesting: Ensure the HomeConnect platform block is a separate top-level item within the platforms array and not accidentally nested inside another plugin's configuration.
Missing Client ID: The plugin requires the clientid property to be set. If missing, it will log an error and stop initialisation.
Manual Editing Errors: Structural JSON errors are common during manual editing. It is recommended to use the Settings button on the Plugins page of the Homebridge Config UI X to manage configuration.

Why does authorisation fail with `invalid_request`, `invalid content type`, or `request rejected by client authorization authority`?

These errors are returned when the provided Client ID is not recognised or is improperly formatted. Check the following:

Incorrect Format: The Client ID must be exactly 64 hexadecimal characters. Ensure no extra spaces, quotes, or hidden characters were included when copying the ID from the developer portal.
Propagation Delay: New applications created in the Home Connect Developer Portal are not always active immediately. It can take up to an hour for a new Client ID to propagate to the production authorisation servers. Try again later.
Production vs Simulator Credentials: The default "API Web Client" credentials provided in the portal are for the appliance simulator only. If you are using these for testing, you must set "simulator": true in your configuration. If you are connecting physical appliances, you must create a new application in the developer portal to obtain a production Client ID.

Why does authorisation fail with `invalid_client`, `grant_type is invalid`, `unauthorized_client`, `client has limited user list`, or `client not authorized for this oauth flow`?

These errors are returned by the Home Connect API and indicate a configuration mismatch or synchronisation delay in the Home Connect Developer Portal:

Ensure the Client ID in your Homebridge configuration matches the portal exactly, and that the application is configured as follows:

OAuth Flow: Must be set to Device Flow. This setting is fixed at the time of application creation; if it was set incorrectly to Authorization Code Grant Flow, the API will return client not authorized for this oauth flow (grant_type). You must delete the application and create a new one with Device Flow selected.
Home Connect user account for testing: This must exactly match the email address used for your Home Connect mobile app. Check this in both your global profile and within the specific application's settings.
Success Redirect: Leave blank or ensure it is a valid URL. Mismatches here can trigger unauthorized_client errors.
Security Settings: Ensure One Time Token Mode, Proof Key for Code Exchange (PKCE), and Sync to China (unless in China) are all disabled.

If the configuration is correct but errors persist, try deleting and recreating the application in the developer portal to reset its state.

Why does the authorisation link expire or fail with an `expired_token` or `invalid code` error?

Authorisation links and their associated device codes have a limited validity period. If this window is exceeded, the Home Connect API will return errors such as expired_token, the code entered is invalid or has expired, or Device authorization session not found.

If the authorisation fails:

Propagation Delay: New applications created in the Home Connect Developer Portal are not always active immediately. It can take up to an hour for a new Client ID to propagate to the production authorisation servers. Try again later.
Check for Stale Links: Ensure you are using the most recent URL from the Homebridge logs or the plugin configuration UI.
Wait for Auto-Retry: The plugin handles these errors by waiting 60 seconds before automatically generating a new authorisation attempt. Restarting Homebridge is not typically required unless the auto-retry fails repeatedly.
Single Use: The device_code is invalidated as soon as it is successfully used. Do not attempt to reuse old authorisation URLs.

Why does authorisation fail with `access_denied`, `device authorization session has expired`, or `login session expired`?

These errors typically occur during the login process and are caused by account verification requirements or bugs in the SingleKey ID authorisation flow:

Account State: Ensure your SingleKey ID account is fully active. Open the official Home Connect mobile app and check for pending tasks, such as verifying your email address, migrating from an old Home Connect account to SingleKey ID, or accepting updated terms of use. The account must be fully functional in the official app before the plugin can authorise. It is sometimes necessary to log out of the app and log back in again to trigger account migration to complete.
Internationalisation Bug: A server-side bug can cause the authorisation to fail if your browser's preferred language is not English. This often prevents the password prompt from appearing or returns a raw JSON error immediately after entering your username. To resolve this, go to your browser settings and move English (en or en-GB) to the top of your preferred language list. You can revert this setting once the plugin has been authorised.

To complete the process:

Obtain the URL from the logs (e.g. https://api.home-connect.com/security/oauth/device_verify?user_code=XXXX-XXXX).
Open the URL in a browser with the language workaround applied.
Sign in with the account used in the official app and approve the request. The plugin will detect completion and save the tokens automatically.

Why does authorisation fail with a `403 Forbidden` error?

A 403 Forbidden error during the POST /security/oauth/device_authorization request indicates that the Home Connect API servers are explicitly rejecting the connection from your network. This is typically caused by regional geo-blocking or service restrictions implemented by the provider (for example, in Russia).

This is a network-level restriction imposed by the service provider and cannot be bypassed by the plugin. Users in affected regions may experience similar connectivity issues with the official Home Connect app unless a VPN is used.

How do I configure the plugin for a Home Connect account in Mainland China?

Home Connect appliances registered in Mainland China operate on a separate infrastructure and require specific configuration in both the Developer Portal and the plugin to comply with regional data residency requirements:

Log in to the Home Connect Developer Portal and ensure your application has the Sync to China option enabled.
In the Homebridge UI, locate the plugin settings and set the Server Location to China.
If you are configuring the plugin manually via config.json, add "china": true to the plugin configuration object.

This configuration ensures the plugin uses the dedicated api.home-connect.cn endpoint. Note that the China Mainland server may use different login credentials, such as a mobile number, which is supported once the plugin is directed to the correct regional endpoint.

Home Connect API Errors

Why does the log show `429 Too Many Requests`, `1000 calls in 1 day reached`, or a message like `Waiting ... before issuing Home Connect API request`?

The Home Connect API enforces very strict rate limits. Exceeding any of these triggers a 429 Too Many Requests error and a lockout for up to 24 hours. The plugin handles this by pausing all API requests until the retry-after time returned by the API, displaying a countdown in the logs.

Most limits reset after 1 or 10 minutes, but there is also a daily quota of 1,000 requests. It is common to encounter these limits during the initial discovery phase after installation or an update as the plugin retrieves metadata for all appliances. Certain conditions can cause these limits to be reached rapidly:

Frequent Homebridge Restarts or Initial Discovery: The plugin must issue a significant number of API requests to discover features, supported programs, and configuration options for every appliance. Frequent restarts during setup or troubleshooting quickly consume the daily allowance. Ensure Homebridge is stable and consider running this plugin in its own child bridge.
Unstable Appliance Connectivity: When an appliance disconnects and reconnects to Wi-Fi, the plugin issues several API requests to re-synchronise state. Check your logs for repeated DISCONNECTED or CONNECTED messages and improve Wi-Fi coverage for that appliance. Note that appliance Wi-Fi hardware is often lower quality than that found in smartphones and can be susceptible to interference from internal components like compressors.
Multiple API Clients: Using the same Client ID across multiple Homebridge instances or other third-party integrations shares these limits. Create a separate application for each use.
High HomeKit Activity: Automations that trigger rapid state changes or frequent manual control through HomeKit contribute to hitting the limit.
Large Number of Appliances: Each additional appliance increases the baseline volume of status updates and initialisation requests. Users with many appliances are more susceptible to reaching the daily quota during periods of high activity or following restarts.

No manual intervention is required; the plugin will automatically resume communication once the Home Connect servers lift the block.

Why does my appliance show a `409 Conflict` error?

The Home Connect API uses 409 Conflict errors for a variety of failures that result in a request being rejected. Common sub-errors include:

SDK.Error.HomeAppliance.Connection.Initialization.Failed: This indicates that the appliance is not connected to the Home Connect cloud servers. Note that the official Home Connect app may still function by communicating directly via your local Wi-Fi network, whereas this plugin is restricted to using the official cloud API. To troubleshoot:
1. In the official app, navigate to the appliance's Settings > Network and ensure all three connection stages (appliance-app, appliance-cloud, and app-cloud) are green.
2. Test the official app while your phone's Wi-Fi is disabled; if it fails to control the appliance over cellular data, the issue is with the appliance's cloud connection.
3. Power cycle the appliance or restart your router to refresh the connection to the Home Connect servers.
4. Check the Home Connect Server Status (unofficial) for outages.
SDK.Error.InvalidSettingState: This occurs when a setting is currently read-only or unavailable. It is often caused by inconsistencies in the API regarding power state capabilities (common with fridges, freezers, and hobs). It can also indicate that Remote Start or Remote Control has been disabled in the appliance's physical settings menu. While the API usually returns specific errors like BSH.Common.Error.RemoteControlNotActive, some appliances (particularly coffee makers) return SDK.Error.InvalidSettingState instead. On other appliances, it frequently indicates a maintenance message is displayed on the physical screen (e.g. "Change water filter" or "Descaling required") that requires manual confirmation before remote control can resume.
SDK.Error.UnsupportedProgram: This occurs when you attempt to start a program that is not exposed via the official Home Connect API for your specific model. The official app and physical control panel often support programs that have not yet been made available to third-party integrations. This is a platform limitation that should be reported to Home Connect support.
SDK.Error.WrongOperationState: This indicates that the appliance is in an incorrect state for the requested operation, such as attempting to start a program while another is already running or if the appliance is currently performing a self-cleaning cycle.
SDK.Error.ProgramNotAvailable: This indicates that the appliance is in a state where it cannot provide its list of available programs or start them. This occurs when an appliance is currently running an active cycle, being operated manually via its physical controls, or experiencing transient communication issues. Certain maintenance programs like DrumClean may also be reported as unavailable due to firmware restrictions.
BSH.Common.Error.400.BadRequest: This often indicates an attempt to stop a program that is already stopped. This typically occurs when multiple program switches are grouped into a single tile in the Home app, resulting in them all being toggled together.

For details of other 409 errors, refer to the Home Connect API Errors documentation.

Why does starting the Silence program on my dishwasher fail or return a `409 Conflict` error?

The error 409 Conflict (specifically SDK.Error.WrongOperationState) occurs when trying to activate a silence feature while a cycle is already running. This is due to the technical distinction the Home Connect API makes between programs and options:

Programs (e.g. Dishcare.Dishwasher.Program.NightWash): These are complete cleaning cycles. Only one program can be active at a time; the API will reject an attempt to start a new program while another is already in progress.
Options (e.g. Dishcare.Dishwasher.Option.SilenceOnDemand): These are modifiers for a program. The 30-minute silence feature in the official Home Connect app is typically implemented as a program option, not a standalone program.

The plugin supports including these options when you start a program via HomeKit. However, it does not support changing options dynamically once a cycle has already begun. This is a deliberate design choice because the API does not generally permit dynamic modification of options mid-cycle and provides no clear indication of which specific options are safe to change. Furthermore, there is no reliable way to map dynamic, mid-cycle option changes into the standard HomeKit service and characteristic model.

To use the silence feature, you must either start the dedicated NightWash program when the appliance is idle or include the relevant option at the time the primary program is initially triggered.

Why does my appliance show as `Not Responding` in the Home app when turned off?

The physical power button on some Home Connect appliances (most commonly washing machines and tumble dryers) disconnects power from their internal Wi-Fi module. When this occurs, the Home Connect API cannot distinguish between the appliance being switched off, disconnected from the mains, or losing its internet connection.

The API does not provide any indication of whether an appliance supports a soft power off state that maintains a network connection. Hence, it is not possible for the plugin to identify whether an appliance that the API reports as DISCONNECTED has been intentionally switched off or has lost contact with the Home Connect servers. The plugin prioritises technical accuracy and reports this state as SERVICE_COMMUNICATION_FAILURE, which the Apple Home app displays as Not Responding.

If you prefer the appliance to show as Off rather than Not Responding when unreachable, you can enable the experimental Disconnected as Off feature in the plugin configuration.

Reporting a communication failure remains the default as it is the standard and correct HomeKit behaviour for an unreachable accessory. Most Home Connect appliances (like ovens or dishwashers) do maintain Wi-Fi connectivity when switched off, so reporting Not Responding for those that disconnect correctly distinguishes them from appliances that remain reachable.

Why does the power button not work or return a `BSH.Common.Error.WriteRequest.Busy` error?

The Busy error is returned by the Home Connect cloud when an appliance cannot process a command, often because it requires physical interaction (e.g. filling a water tank or closing a door). If you encounter this error, check the physical display of the appliance or the official Home Connect app to see if a manual action is required. This issue may also be caused by a transient issue with the Home Connect cloud service itself; check the Home Connect Server Status (unofficial) for recent issues.

Failure to power certain ovens on or off is a known bug in the Home Connect API affecting specific models. If the appliance is physically ready but the power command is rejected, this is an external platform limitation. You should report such issues to Home Connect Developer Support with your appliance's E-Nr (part number).

What do `Gateway Timeout`, `Proxy Error`, or `Timeout on Home Connect subsystem` messages mean?

Errors such as SDK.Error.504.GatewayTimeout (often logged as Timeout on Home Connect subsystem) or Proxy Error indicate that the Home Connect cloud servers are experiencing internal issues, high latency, or have unexpectedly terminated the event stream.

These are server-side problems within the Home Connect infrastructure and cannot be resolved by the plugin. The official Home Connect mobile application may remain functional because it often uses different communication paths or internal API endpoints not exposed to third-party integrations.

What you can do:

Check the Home Connect Server Status (unofficial) for known outages.
Wait for automatic recovery (typically 5-30 minutes).
If the issue persists for hours, restart Homebridge to force a fresh connection.

Why does the log show `Home Connect subsystem not available` or a `503` error?

The error Home Connect API error: Home Connect subsystem not available [503] indicates a server-side maintenance issue or infrastructure outage. This is not a fault with the plugin or your local configuration. The issue is typically transient and is usually resolved by the Home Connect team within a few hours. Check the Home Connect Server Status (unofficial) for recent issues.

What you can do:

Check the Home Connect Server Status (unofficial) for recent issues.
Verify if the official Home Connect mobile app is functional; while outages often affect both, the app may sometimes remain functional due to using a local network connection to the appliance or different cloud API endpoints.
If the issue persists for an extended period, you may wish to contact Home Connect support directly.

Why am I seeing network errors like `EAI_AGAIN`, `ENOTFOUND`, `ETIMEDOUT`, or `ENETUNREACH`?

These are standard networking errors indicating a DNS name resolution failure or loss of internet connectivity. This means your Homebridge host is unable to resolve the IP address for api.home-connect.com (or api.home-connect.cn for users in China).

To resolve this, ensure your Homebridge server has a stable internet connection and check the following:

Diagnostic Commands: Test DNS resolution using dig api.home-connect.com or nslookup api.home-connect.com from the same system.
DNS Provider: Try manually setting a public DNS provider (such as Google's 8.8.8.8 or Cloudflare's 1.1.1.1) in your operating system's network configuration.
Network Filtering: Verify that local firewall or DNS filtering (like Pi-hole) is not blocking requests to the Home Connect API or AWS endpoints.

If using Docker:

Address DNS/IPv6: Problems frequently arise when IPv6 is enabled but not correctly routed. Try disabling IPv6 for the container using --sysctl net.ipv6.conf.all.disable_ipv6=1 or forcing a specific DNS provider using --dns 1.1.1.1.
Network Mode: Consider switching the container to host network mode to bypass Docker's internal bridge networking.

The plugin will automatically attempt to reconnect once the network connection is restored.

Why is the log flooded with errors during a Home Connect outage?

When the Home Connect API experiences an outage, the plugin may rapidly log attempts to restart the event stream. This is expected behaviour designed to ensure the most reliable recovery possible.

State Consistency: The plugin relies on the event stream for real-time updates. Frequent reconnection attempts minimise the risk of missing appliance events and ensure synchronisation as soon as the service resumes.
Diagnostic Integrity: Detailed logs of every connection attempt and the specific error returned are vital for diagnosing intermittent platform failures and developing workarounds.
API Rate Limits: The plugin is optimised to stay within rate limits even during outages. Introducing artificial delays adds complexity that could interfere with the normal recovery process.

While this produces more log data during an outage, it ensures the plugin recovers without manual intervention.

Why does my multi-cavity oven show a `BSH.Common.Error.InvalidUIDValue` error?

This error typically occurs with multi-cavity appliances where only the main oven supports Home Connect functionality. If the Home Connect API continues to advertise the secondary oven despite it lacking remote capabilities, queries for its programs will fail with BSH.Common.Error.InvalidUIDValue.

The plugin handles this gracefully by ignoring the error and disabling program control for the unsupported cavity. This is an issue with the Home Connect API's device enumeration, which is occasionally addressed by manufacturer server-side updates.

How can I refresh appliance capabilities or resolve stale program information?

If an appliance program stops responding, fails to start, or reflects outdated capabilities (possibly due to a firmware update or server glitch), or if you need to force the plugin to re-discover all possible values for a program or option (e.g. to debug unrecognised keys), you can force a data refresh:

HomeKit Identify: Activating the Identify method for the accessory forces the plugin to refresh supported programs and rebuild the configuration schema. This can be triggered via third-party HomeKit apps such as Eve (labelled as ID). This also triggers a comprehensive query and logging of available programs and options.
Clear Plugin Cache: If issues persist, you can delete the cached appliance data:
- Stop Homebridge.
- Navigate to the plugin's persistent cache directory (typically ~/.homebridge/homebridge-homeconnect/persist).
- Do not delete the file named 94a08da1fecbb6e8b46990538c7b50b2 which contains your authorisation token. Deleting this will require you to re-authorise.
- Delete all other files in that directory. These contain cached capabilities and will be regenerated automatically.
- Start Homebridge to fetch fresh data from the Home Connect API.

Local/Remote Control

Why does my appliance show `No Response` when I try to start a program?

To protect your safety and prevent your appliance from starting unexpectedly, Remote Start must be physically enabled on the appliance itself before remote control is permitted. This is a security-related hardware restriction that cannot be activated or overridden via the Home Connect API or this plugin.

Most appliances require you to press a physical button to enable this mode. The activation typically remains valid for a limited period or until the appliance door is opened. If you attempt to start a program via HomeKit when Remote Start is disabled, the plugin intentionally reports an error to HomeKit, which the Apple Home app displays as No Response. This is a deliberate design choice; reporting "Success" instead would be misleading, as the appliance would not actually start, and Siri or the Home app would incorrectly indicate that the appliance is running.

This plugin exposes the appliance's Remote Start status via the Program Mode characteristic on the power Switch service. It is not shown in the Home app, but can be viewed or used to gate automations in third-party apps like Eve.

What does `LockedByLocalControl` or "Local Intervention" mean?

If you see an error like Request cannot be performed temporarily! due to local actuated user intervention [BSH.Common.Error.LockedByLocalControl], it means the appliance is currently being operated via its physical buttons or knobs. This is a restriction built into the appliance firmware and the Home Connect API; it cannot be bypassed by the plugin.

To prevent conflicting commands and ensure safety, the Home Connect API blocks all remote control while a user is physically interacting with the appliance. While this lockout usually clears a few seconds after you stop touching the controls, some appliances may maintain the lockout for a longer period during certain maintenance cycles or until a specific manual interaction is completed.

This plugin exposes the appliance's Local Control status via the Program Mode characteristic on the power Switch service. It is not shown in the Home app, but can be viewed or used to gate automations in third-party apps like Eve.

Why does my appliance report `Control scope has not been authorised` or `insufficient_scope`?

This error occurs because the Home Connect API requires specific authorisation scopes to control Oven or Hob programs. While these were previously restricted to business partners, they were made available to independent developers in March 2021. If you authorised the plugin's connection to Home Connect prior to this, your token will not include the necessary permissions.

To resolve this, you must force a re-authorisation:

Stop Homebridge.
Delete the cached token file in the plugin's persistent storage directory (usually ~/.homebridge/homebridge-homeconnect/persist/94a08da1fecbb6e8b46990538c7b50b2).
Restart Homebridge.
Follow the authorisation link provided in the logs or Homebridge UI to sign in again.

Note that the FridgeFreezer-Images scope remains restricted to approved business partners and is not supported by this plugin. The Home Connect API documentation describes it as requiring an "Additional Partner Agreement".

Why is there a delay when controlling appliances via HomeKit?

The Home Connect API is inherently slow, typically taking 1 to 2 seconds to complete a single request. Furthermore, Home Connect imposes strict rate limits, such as a maximum of 5 program starts per minute. To ensure reliability and avoid being blocked, the plugin serialises multiple characteristic changes (e.g. simultaneously turning on a light and adjusting brightness) into sequential API calls. Additional delays are inserted if the API indicates that a rate limit has been exceeded. This results in a noticeable but necessary lag between the HomeKit command and the appliance's physical response.

Why does my appliance fail to start when using the switch in the Home app?

For most appliances this plugin exposes multiple Switch services to HomeKit, including Power, Active Program, and individual programs. By default, the Apple Home app often groups these separate services into a single accessory tile. Toggling this combined tile attempts to activate all underlying switches simultaneously, which results in conflicting requests and a No Response error.

For example, if a dishwasher tile is toggled, HomeKit might try to turn on power and start multiple programs at once. This is particularly problematic for coffee machines, which require significant start-up time for heating and rinsing; sending a "Power On" and "Start Program" command at the same instant will usually result in an error from the appliance as it is not yet ready.

To resolve this, you should configure the Home app to display these services individually:

Open the accessory settings for the appliance in the Home app.
Select Show as Separate Tiles.
Control the Power switch first, wait for the machine to complete its start-up sequence (if applicable), and then activate the desired program switch.

Why does my appliance frequently show `Disconnected (setting On error status)`?

Frequent transitions between Connected and Disconnected states usually indicate transient communication interruptions between the plugin and the Home Connect cloud. This plugin relies entirely on the manufacturer's cloud-based API; if the connection between the appliance and the cloud, or the cloud and the plugin, is interrupted, the device must be reported as disconnected.

Common causes include:

API Instability: The official Home Connect servers occasionally experience maintenance or instability, which can interrupt the event stream. You can check the current status on the Unofficial Home Connect Server Status page.
Wi-Fi Signal Strength: If the API servers are stable, the appliance itself may be losing its connection to your local network. Check the official Home Connect app's network settings for the appliance; it should consistently show three green lines.
Internet Connection: Intermittent drops in your internet connection will disrupt the persistent event stream required for real-time updates.

The plugin is designed to handle these interruptions by automatically attempting to reconnect. If your appliance transitions between states frequently but eventually restores its connection, it is almost certainly due to one of these environmental factors rather than a plugin bug.

Programs and Options

Why does the log show `Unexpected fields`, `(unrecognised)` values, or TypeScript-like code blocks?

The plugin performs strict validation on data from the Home Connect API to ensure reliability. Because the API often deviates from its official documentation, or because new appliance models and firmware introduce undocumented features, the plugin includes a diagnostic mechanism to identify identifiers it does not yet recognise. When the plugin encounters these values, it generates a technical diagnostic block in the log, formatted as TypeScript code and delimited by rows of = characters. This helps the maintainer update the plugin's internal schema and map features to HomeKit services.

If you observe these messages:

Update the plugin: Ensure you are running the latest version, as support for new values is added frequently.
Report the values: Wait approximately two minutes for the plugin to batch the data. Locate the URL provided in the log message immediately following the code block and click it to open a pre-populated GitHub issue.
Provide the snippet: Paste the entire technical diagnostic block from the log (including the = separators) into the Log File field of the issue template.

Please do not attempt to guess or suggest theoretical values; the maintainer only adds verified values observed from actual appliance behaviour. Once added, the warning will disappear and the features will be correctly mapped where appropriate.

Why are some appliance features, programs, or options missing, unavailable, or absent from the configuration UI?

The plugin dynamically discovers the capabilities of each appliance by querying the Home Connect API. Several factors can cause features to be missing from HomeKit, appear as currently unavailable in the logs, or be absent from the configuration UI:

Private API Limitations: The official Home Connect app and certain partners (like IFTTT) use a private API with functionality not available to third-party developers. If a program or feature is missing from the official public API documentation, the plugin cannot access it.
Appliance Settings: Some programs, such as Sabbath mode, often require being explicitly enabled in the physical appliance settings menu before they are exposed via the API.
Hardware Restrictions: Certain models, such as Neff ovens with rotary dials, cannot be powered on remotely via the public API. This can prevent the plugin from discovering the full range of supported options during its initialisation routine.
Program Specifics: Maintenance cycles (such as drum cleaning, rinsing, or descaling) and user-defined programs are frequently restricted or not advertised with full configuration options via the public Home Connect API.
Operational Status: A program may be reported as supported but currently unavailable if the appliance is powered off, busy, a cycle is already running, a door is open, or required consumables (salt, rinse aid, water, detergent, coffee beans) are missing.
Incomplete Discovery: The plugin performs a discovery routine to identify supported options (like temperature ranges or durations). If this process fails due to an API glitch or a busy appliance, the plugin may cache an incomplete list of capabilities. These options will then be missing from both HomeKit and the plugin configuration UI until the cache is cleared.

If a program is unexpectedly missing, try powering the appliance on, manually selecting it on the physical panel, and leaving it idle for one minute. Then, trigger the plugin to re-read details using the HomeKit Identify method. If the API continues to refuse access, contact Home Connect Developer Support.

Why does the log say a selected program is not supported by the Home Connect API?

This warning typically occurs in two different contexts:

Monitor-Only Programs: Some appliances support maintenance cycles (such as rinsing, drum cleaning, or descaling) and user-configured favourites that the API allows the plugin to monitor but not control remotely. The plugin logs these when they are detected but cannot be started via HomeKit.
Startup Timing: You may see a transient warning during Homebridge startup or after clearing the cache. This happens if an appliance reports a program selection event before the plugin has finished loading the full list of supported programs from the API.

This is often a known inconsistency in the Home Connect API's behaviour. When the plugin identifies this discrepancy, it deliberately avoids querying the API for further details to prevent invalid requests that would unnecessarily consume your daily API rate limit quota. In these cases, the messages are often cosmetic and the plugin will automatically refresh necessary details once initialisation is complete.

Why is my appliance stuck at `Waiting for features to finish initialising`, showing as `Not Responding`, or displaying unresponsive tiles?

The plugin discovers appliance capabilities during startup and caches them. This process can fail if the appliance is offline, busy, or has an open door. Technical issues such as API instability, missing consumables, or transient server errors can also cause discovery to fail. When initialisation stalls, the log typically includes messages like Waiting for ... features to finish initialising or Appliance initialisation is taking longer than expected.

Several factors can contribute to this state:

Cloud versus Local Connectivity: The official Home Connect app can communicate using the local network. However, this plugin relies entirely on the cloud-based public API. An appliance may appear functional in the official app via a local connection while being disconnected from the cloud servers. If the public API reports the device as disconnected, the plugin will wait for a valid response before configuring HomeKit services.
Stale HomeKit Accessories: HomeKit caches accessory definitions from previous successful sessions. If the plugin fails to complete initialisation, it cannot update these definitions. This results in the Home app displaying numerous unresponsive tiles that do not reflect your current configuration.

To resolve this, perform the following diagnostic steps:

Check the Home Connect Server Status: Visit the unofficial status page to rule out platform-wide outages.
Perform the Mobile Data Test: Disable Wi-Fi on your mobile device and attempt to control the appliance via the official Home Connect app using cellular data. If this fails, the appliance is not correctly connected to the cloud servers.
Verify App Connectivity Status: Within the official Home Connect app, check the appliance's network settings. A fully functional connection is typically indicated by three green lines.
Confirm Consumables and Maintenance: Verify that all maintenance requirements (cleaning, descaling, refills) are met and the door is closed.
Power Cycle: Disconnect the appliance from the mains power (unplug it or turn off the circuit breaker) for at least 30 seconds to force its internal firmware to re-register with the cloud servers.
Restart Homebridge: Once the appliance has reconnected, restart Homebridge to trigger a fresh initialisation sequence.
Delete Cache Files: If the issue persists, stop Homebridge and delete the appliance's cache files in ~/.homebridge/homebridge-homeconnect/persist. These files are named with an MD5 hash of your appliance's Home Connect ID (HaID) followed by cache. Do not delete the authorisation file 94a08da1fecbb6e8b46990538c7b50b2.
Refresh Connection: As a last resort, remove the appliance from the Home Connect app and re-add it to your home network.

Why do I see an `InvalidStepSize` or `SDK.Error.InvalidOptionValue` error?

The Home Connect API requires that certain values follow strict increments. If a value is provided that is not an exact multiple of the required step size, the API will return a validation error even if the value falls within the permitted minimum and maximum range.

The plugin attempts to mitigate this by providing dropdown menus or adding the required step size to the field description in the Homebridge UI. When manually entering values, ensure they align with the increments specified in the configuration interface. Using the up/down arrows in the Homebridge UI will typically snap the value to the correct step.

Why are Pause and Resume features missing or inconsistent?

Experimental support for pausing and resuming programs is implemented via the HomeKit Active characteristic, but there are several limitations:

App Support: Apple's native Home app does not display the pause/resume controls for most appliance types. You must use a third-party app like Eve or Home+ to access these functions.
API Inconsistency: Support for these commands varies significantly between firmware versions. Many appliances do not support PauseProgram via the public API despite documentation suggesting otherwise. Others may support pausing but not resuming.

The plugin dynamically detects supported commands for each specific appliance. If the options do not appear in a compatible third-party app, it indicates your hardware or firmware does not support the feature via the public API.

Why doesn't the plugin automatically turn on my coffee machine when I start a beverage program?

The plugin does not implement automated sequencing, such as powering on an appliance and waiting for it to be ready before starting a program, for several reasons:

HomeKit Feedback and Timeouts: The plugin is designed to wait for an API response before confirming success to HomeKit. This ensures that when using Siri, you receive immediate feedback if a command fails. A multi-step sequence (Power On -> Wait -> Start Program) would exceed HomeKit's response timeout or require reporting success prematurely, hiding subsequent failures from the user.
State Reporting Inconsistency: Different coffee machine models report power and readiness inconsistently. Some allow starting a program from an Off state, while others require an explicit On command and a specific 'Ready' state.
Maintenance Cycles: Many machines perform an automatic rinse when powered on. Automating drink selection immediately after power-on could result in coffee being dispensed into rinse water, or could fail because the user has not yet placed a cup.
Device Behaviour: Many other appliances automatically power on when a program command is received via the API, making additional sequencing unnecessary for those models.

If your model requires manual power-on, you should use the Apple Shortcuts app to create a sequence (e.g. Turn On -> Wait -> Start Drink) tailored to your appliance's behaviour.

Why is the `Active Program` switch failing or unavailable in HomeKit?

The generic Active Program switch relies on the Home Connect API reporting which program is currently selected on the physical appliance via BSH.Common.Root.SelectedProgram events.

Several factors limit its reliability:

API Event Dependency: Many appliances (especially washers and dryers) do not consistently generate selection events. If the plugin does not know which program is selected, it cannot send the required identifier to the API to start the machine.
Scenes and Automations: If the plugin cannot determine the selected program, HomeKit may treat the switch as read-only or prevent it from triggering within scenes to avoid inconsistent states.

To ensure reliable automation, it is recommended to use specific named program switches (e.g. Cotton, Eco 50) instead of the generic Active Program switch. These explicitly define the program to be started and do not depend on the appliance's current physical selection state.

How can I trigger the Identify function in the Eve app?

To trigger the Identify mechanism within the Eve app:

Navigate to the Rooms tab and locate the appliance.
Tap the name of the appliance to open the detailed view (do not tap a toggle or slider).
Tap the appliance name or the small arrow at the top of the screen, just below the Edit button.
Tap the ID button that appears next to the settings cog.

This will trigger the identification sequence on the physical appliance and force the plugin to refresh its cached data.

How can I enable dishwasher options like Half Load, Extra Dry, or Efficient Dry in HomeKit?

Home Connect distinguishes between global settings (like Child Lock) and program-specific options (like HalfLoad, ExtraDry, or EfficientDry / EcoDry).

Because these are program options rather than independent settings, they must be configured as part of a specific program's execution and are not exposed as standalone HomeKit switches. By default, the plugin creates a HomeKit Switch for each program using its default settings. To use specific options, you must configure a Custom list of programs and options in the plugin settings and explicitly define the desired options for each switch.

Why does my appliance turn on automatically, switch off immediately, or Homebridge startup stall?

To identify an appliance's specific programs and valid option ranges, the plugin must perform a discovery routine. Many appliances only report this data via the API when they are powered on and the specific program is selected.

This discovery phase typically occurs upon the first successful authorisation of the plugin, after manually deleting persistent cache files, or when the Identify mechanism is triggered. During this process:

Power On: The appliance switches on automatically. If it has an automatic rinsing cycle (common with coffee machines), the plugin will wait up to two minutes for it to finish.
Iteration: The plugin briefly selects each available program in sequence to fetch supported options.
Restoration: Once complete, the plugin restores the appliance to its original state (usually Off or Standby).

This typically happens only once during initial setup or after a cache deletion. Results are cached in the plugin's persist directory. If this happens every time Homebridge restarts, check the logs for errors like 409 Conflict or SDK.Error.WrongOperationState, which suggest discovery failed because the appliance was busy or the door was open. If no cache exists and the appliance is offline, startup will stall until a connection is established.

Which settings are used for programs started without specific options?

When a program is started without explicit option configuration, the plugin does not specify any parameters in the Home Connect API request. In these cases, the Home Connect servers or the appliance itself determines the values, typically defaulting to the factory settings or the last values used on the physical interface. This behaviour is intended to mirror selecting a program manually on the appliance without making adjustments.

To view the default values for each program option, enable Debug Logging, use the HomeKit Identify function, and check the debug log. Specific options such as coffee strength or beverage volume can be customised in the plugin configuration, most easily through the Homebridge UI interface.

How can I change the default duration or temperature for oven programs?

When started remotely via the API, oven programs must have a defined duration. If no duration is provided, the Home Connect API typically defaults to 60 seconds. The API does not currently support starting an oven program without a duration or with a value representing infinity.

To resolve this, use the Custom list of programs and options in the plugin settings to explicitly set a Duration (for example, 3600 seconds) for your oven switches. This ensures the oven remains on until the timer expires or you manually stop it.

Why is the scheduled start time for my appliance program not being honoured?

The plugin does not perform internal time zone processing or use the location settings from your Home Connect account. Instead, it relies entirely on the local time zone of the server running Node.js and Homebridge. If a scheduled program, such as one using BSH.Common.Option.StartInRelative, triggers at an unexpected time, it is likely that your server is configured to a different time zone (often UTC/GMT by default).

To resolve this:

Verify your server's current time zone configuration. On most Linux distributions, you can use the timedatectl command.
Ensure the operating system or container environment is set to your correct local time zone.
If you cannot change the system-wide settings, you can explicitly set the time zone for the Homebridge process by configuring the TZ environment variable (for example, TZ=Europe/London).

How can I reduce the number of switches created for appliance programs?

By default, the plugin creates individual Switch services for every supported program. For complex appliances, this can clutter the HomeKit interface. You can modify this behaviour in the plugin configuration via Homebridge UI:

No individual program switches: Enable this option in the appliance settings to hide all program switches. This does not affect state monitoring or basic power controls.
Custom list of programs and options: Use this to manually define which specific programs appear in HomeKit, and the options to use with each.
A switch to start each appliance program (default): Advertise all available programs using default options.

What does the log message `Using expired cache result` mean?

The plugin maintains a local cache of appliance program details because the Home Connect API only allows this information to be retrieved reliably when a program is selected on the physical appliance but not yet running. The plugin considers this cache expired if the program has not been selected for more than 24 hours.

When the plugin requires these details but cannot refresh them (because a different program is currently selected), it will use the last known data and log this message. This is normal behaviour and not a functional failure; the plugin will continue using the historical data until the program is next selected and a refresh becomes possible.

Why does setting my hood fan to `Auto` in the Home app not immediately turn it on?

The plugin prioritises the Active characteristic (the power state) over the TargetFanState (Manual/Auto). When the fan is off, selecting Auto in HomeKit saves the preference within the plugin, but it typically only takes effect once the fan is subsequently switched to On (for example, by adjusting the speed slider or toggling the power).

This design choice is driven by several factors:

API Limitations: Many Home Connect hoods do not report current fan speed when operating in automatic mode. This makes it difficult for the plugin to provide accurate feedback to HomeKit.
Hardware Variations: Different manufacturers implement automatic modes differently. Some require the fan to be explicitly Active before an automatic program can be engaged.
HomeKit Specification: The Apple HomeKit Accessory Protocol (HAP) does not define whether setting a fan to Auto should implicitly power it on.

If your hood does not respond when you toggle Auto, ensure the fan is also switched to On. Note that because many hoods do not report speed in this mode, the Home app may display an incorrect or outdated speed percentage while the automatic program is running.

Why does the plugin log unrecognised status values like `Undefined`, `MainsOff`, or `Unknown`?

Certain Home Connect appliances or firmware versions may report non-standard power states such as BSH.Common.EnumType.PowerState.Undefined or BSH.Common.EnumType.PowerState.MainsOff. These values are typically the result of firmware quirks or transient states during specific operations that do not conform to the standard API specification.

To ensure plugin stability and correct HomeKit operation, the plugin treats both of these values as equivalent to Off.

Why is the power off function unavailable for my washing machine or dryer?

The ability to turn an appliance off is determined by the Home Connect API and the specific hardware. According to the official Home Connect API documentation, laundry appliances (washers, dryers, and washer-dryers) typically only support an On power state; they do not support being switched to Off or Standby remotely. This is likely due to these appliances using a physical power switch that also interrupts power to the Home Connect Wi-Fi module, instead of using a soft standby mode like other Home Connect devices.

You can verify the capabilities of your specific appliance by checking the Homebridge logs during startup. The plugin queries each appliance for its supported power states and will log Cannot be switched off if the hardware only permits the On state via the API.

How do I disable the Power switch for my appliance and what are the consequences?

The Power switch service can be disabled for individual appliances to reduce UI clutter in HomeKit by adding "Power": false to the features object within the appliance configuration.

Users should be aware of several technical consequences:

Dependent features are disabled: Several features and characteristics are hosted on the Power switch service. Disabling it will implicitly disable functionality including Remote Control, Child Lock, ProgramMode, SetDuration, and LockPhysicalControls. Whilst the Apple Home app does not expose these features, they are shown in third-party apps (such as Eve) and may be used by automations.
Reduced status feedback: HomeKit has fewer data points to trigger status updates. If a transient error occurs (such as a duplicate start command), the accessory may show a No Response status that persists until the program completes, as there are fewer characteristic updates to clear the error state.
HomeKit UI glitches: Removing a service from an existing accessory can confuse the Home app cache. If labels disappear or tiles merge incorrectly after disabling the Power switch, remove the accessory or child bridge from Homebridge and re-add it to flush the HomeKit cache.

Appliance Status and Connectivity

Why does my appliance status appear stuck or show as offline in HomeKit?

The plugin relies on a real-time Server-Sent Events (SSE) stream from the Home Connect API to receive status updates. Because the Home Connect API enforces extremely restrictive rate limits, the plugin does not perform regular polling; it only fetches the full status when it first starts or following a reconnection to the event stream.

The API sends a KEEP-ALIVE event approximately every 55 seconds. The plugin monitors this and will automatically re-establish the stream if no activity is detected for 120 seconds. If status changes (like a dishwasher finishing or a door opening) are not appearing in HomeKit, the stream may have stalled.

To troubleshoot:

Enable the Log Debug as Info plugin option to see all raw events received from the API. If no events are logged when you interact with the appliance, the issue resides with the Home Connect platform or appliance.
Ensure the appliance has successfully reconnected to Wi-Fi after being powered on; many devices have a delay before they re-establish a cloud connection.
Restart Homebridge to force the plugin to subscribe to a fresh event stream.
Ensure your network configuration does not prematurely terminate long-lived TCP connections.

Why is my appliance unresponsive or reported as offline in Homebridge but working in the official app?

The official Home Connect mobile app communicates with appliances via a local network connection or a private interface to the Home Connect cloud servers. All third-party integrations, including this plugin, are restricted to the public cloud API. It is possible for an appliance to be controllable in the official app while its public API connection has stalled, causing it to appear Disconnected or stuck with log messages such as Appliance initialisation is taking longer than expected or Waiting for features to finish initialising.

To diagnose and resolve this:

Test Cellular Connection: Disable Wi-Fi on your mobile device to force the official Home Connect app to use cellular data. If the appliance becomes unresponsive in the app, the issue is with its connection to the Home Connect servers.
Verify Network Stages: In the official app settings, check the Network section. Ensure all three connection stages (appliance-app, appliance-cloud, and app-cloud) are active, typically indicated by three green lines.
Power Cycle: Disconnect the appliance from the mains power for at least 30 seconds. This forces the appliance firmware to re-register its session with the cloud servers and usually restores the public API connection.
Restart Homebridge: Force the plugin to attempt a fresh initialisation after the appliance has reconnected.

Most connectivity issues are transient and will resolve once the appliance cloud service stabilises. You can also check the Home Connect Server Status (unofficial) for platform-wide outages.

Why do my appliances remain visible in the Home app when they are turned off or offline?

The plugin synchronises accessories based on the list of appliances registered to your Home Connect account. As long as an appliance is associated with your account in the Home Connect API, it will persist in HomeKit. Being unreachable or powered off does not trigger the removal of the accessory from HomeKit, but the Home app will display it as No Response. Dynamically adding and removing appliances from HomeKit based on their connectivity would result in loss of user configuration, such as their name, location, scenes, and automations.

If you observe inconsistent behaviour, such as devices unexpectedly appearing or disappearing, this may be due to a synchronisation issue within HomeKit or the Homebridge cache. This can often be resolved by removing the bridge from the Home app, clearing the Homebridge cache files, and then re-adding the bridge.

Why does the log show a program running or time remaining when my appliance is off?

The plugin reflects the real-time status and events reported by the Home Connect API servers. If the logs indicate that a program is active or shows a countdown while the appliance is idle, it means the plugin is receiving these specific events from the Home Connect cloud service. This is typically caused by a server-side state mismatch or a delay in the event stream where old status updates are delivered late.

To resolve this, try the following:

Start and then manually stop a program using the official Home Connect app or the physical appliance interface to reset the server state.
Power cycle the appliance at the mains to force a reconnection and state refresh.
Use a third-party HomeKit app such as Eve to inspect technical characteristics like Active and Remaining Time for more detail than the standard Apple Home app.

This is a transient server-side or firmware issue that cannot be corrected by the plugin itself.

Why does my dishwasher trigger a `Program Finished` event when it reconnects?

Some Bosch dishwasher models appear to re-broadcast the BSH.Common.Event.ProgramFinished event when re-establishing a connection to the Home Connect cloud after being offline. The plugin maps events from the API directly to HomeKit triggers; therefore, these re-broadcasts are passed through as button presses or notifications. This is a quirk of the appliance firmware or API event handling rather than a defect in the plugin itself.

Why is the log filling up with oven `Event STATUS` temperature messages?

These events are generated whenever the Home Connect servers report a change in the appliance's internal temperature. Home Connect appliances, such as ovens, typically remain in a standby state rather than being fully powered off unless disconnected from the mains. In this state, the appliance continues to monitor internal sensors and communicates changes to the Home Connect servers.

The plugin logs all status information reported by the API. There is no configuration option within the plugin to suppress specific status messages. To prevent them from cluttering your main logs, it is recommended to run the plugin in a separate Homebridge Child Bridge. This isolates the plugin's output and ensures that high-volume events do not obscure logs from other plugins.

Why does the log periodically show `Found X appliances (0 added, 0 removed)`?

This message is generated by the plugin's periodic polling of the Home Connect API to discover any new or removed appliances. This ensures that changes to your Home Connect account are reflected in Homebridge without requiring a manual restart.

There are plans to replace this polling mechanism with a more efficient event-based approach using PAIRED and DEPAIRED events from the Home Connect event stream. Once this enhancement is implemented, these log messages will only be generated when an appliance is actually added or removed from the account.

Why is the dishwasher door control read-only in HomeKit?

The Home Connect API currently restricts door control functionality to specific appliance categories, such as certain oven and fridge/freezer models. For dishwashers, even if they are equipped with hardware to automatically open the door (e.g. at the end of a cleaning cycle), the API only supports monitoring the door state.

In HomeKit, the Door service for dishwashers is therefore read-only. It will correctly indicate whether the door is open or closed and provide status updates when manually operated, but it cannot be used to trigger the door to open. This is a limitation of the Home Connect API rather than the plugin itself.

Why does my refrigerator or freezer show as open in HomeKit even when it is closed?

This behaviour is often caused by firmware or API bugs on certain refrigeration appliance models. The appliance incorrectly reports the generic BSH.Common.Status.DoorState as Open even when physically closed.

To troubleshoot and potentially work around this:

Expose individual door services: In the appliance-specific settings within the plugin configuration (available in v1.9.1 and later), disable the generic Door feature and instead enable the specific compartment door features. These specific keys (such as Freezer Door, Refrigerator Door, Chiller Left Door, Chiller Right Door, or Flex Compartment Door) often report the correct state even when the aggregate status is broken.
Enable debug logging: Use the Log Debug as Info option to see the raw values being returned by the Home Connect API. This confirms if the plugin is receiving BSH.Common.EnumType.DoorState.Open or Refrigeration.Common.EnumType.Door.States.Open from the API server while the door is physically closed.
Firmware updates: Home Connect has acknowledged this issue for certain models and is releasing firmware updates. Ensure your appliance firmware is up to date. If the problem persists despite current firmware, you can contact Home Connect Customer Service with your appliance's model number and the email address associated with your Home Connect account to request assistance.

Can I programmatically access data from the unofficial Home Connect status page?

No. The unofficial Home Connect Server Status page is provided solely for manual diagnostic purposes and is integrated into the plugin configuration UI. There is no public API for this data. The maintainer does not support or allow programmatic scraping or frequent polling of the status page for use in third-party scripts or automations; such activity may result in the requesting IP being blocked.

Why do Home Connect appliances disappear or lose their Favourites status in the Home app?

The plugin creates HomeKit accessories based on the list of appliances provided by the Home Connect API. These accessories should remain visible in the Home app even when the physical device is switched off or disconnected from Wi-Fi.

If accessories spontaneously disappear, reappear, or lose their HomeKit configuration (e.g. room assignments, custom names, scenes, or automations), it is usually due to one of the following:

Home Connect API Instability: If the API temporarily fails to report an appliance during a synchronisation check, the plugin may remove the corresponding accessory from HomeKit. When the API later reports the appliance again, the plugin recreates it as a new accessory. Because HomeKit treats this as a brand-new device, all previous configurations are lost.
HomeKit Cache Issues: Local database corruption within the Apple Home app or Homebridge can lead to inconsistent UI behaviour where devices appear to vanish or move.

To resolve these issues:

Check the Home Connect API status to rule out cloud service disruptions.
If the behaviour is persistent, perform a clean reset of the integration. This involves removing the affected accessories (or the entire bridge) from the Home app, stopping Homebridge, and deleting the persist and accessories cache files before restarting and re-pairing.

Apple HomeKit

HomeKit Accessories, Services, and Characteristics

Why does the Apple Home app not show the remaining time or detailed status for my appliance?

The plugin exposes the Remaining Duration characteristic and other status information to HomeKit for all supported appliances, typically on the Active Program switch service.

However, the Apple Home app only displays this information for specific accessory types defined in the HomeKit Accessory Protocol (HAP) specification, such as Irrigation System and Valve services. While a Valve service might appear applicable to "wet" appliances like dishwashers or washing machines, it is semantically inappropriate for many other Home Connect types that also report remaining time, such as ovens, dryers, or coffee machines. The maintainer has explicitly decided against using these semantically incorrect service types to force compatibility with the Apple Home app UI, as this would result in a confusing and inaccurate representation of the appliance within the HomeKit ecosystem.

To view the remaining time, or use other characteristics that the Apple Home app hides, you must use a third-party HomeKit application (such as Eve, Home+, or Controller for HomeKit). Look for the Remaining Duration characteristic on the Active Program switch service. These applications support the full range of standard HomeKit characteristics and allow them to be used in automations.

Why are the power and program switches for my appliance in a random order in HomeKit?

The HomeKit Accessory Protocol (HAP) does not provide a robust or well-defined way for plugins to enforce the display order of multiple services within a single accessory. While the plugin exposes several services, such as the power Switch, various program control Switch services, and event Stateless Programmable Switch services, individual HomeKit apps determine how to order them.

Although HAP includes a Service Label Index characteristic, it is specifically intended for ordering Stateless Programmable Switch services and is not officially supported or respected by apps for other service types. Technical attempts to influence the order—such as marking the power switch as a Primary service or using Linked services to group controls—have proven inconsistent across different applications. In some cases, these changes actually made the Apple Home app's ordering less predictable. Most third-party HomeKit apps, such as Eve, Home+, and Hesperus, allow users to manually reorder services or characteristics for an accessory within their own interfaces. If you require a specific order, it is recommended to use the manual reordering features provided by these third-party apps.

Why do disabled services still appear or remain unresponsive in HomeKit?

The plugin allows for granular control over which services are exposed to HomeKit. However, HomeKit is designed for accessories with a static set of services. When you modify your features configuration to remove a service, it can lead to stale "No Response" entries or disappearing service labels.

This occurs for two main reasons:

Homebridge caching: As a dynamic platform plugin, Homebridge saves the state of accessories to disk. On startup, it restores this state before the plugin applies the current configuration. If a feature was recently disabled, it may briefly appear until the plugin logs Removing obsolete service "...".
HomeKit and iCloud synchronisation: HomeKit maintains an internal cache across home hubs (Apple TV or HomePod) and iOS devices. Syncing changes via iCloud can be unreliable, leading to persistent display bugs.

Disabling the Power switch ("Power": false) is particularly likely to cause issues because the plugin uses this service as a way to trigger HomeKit to refresh the accessory state. Without this service any error conditions are more likely to persist until appliance state updates other services.

To resolve persistent issues:

Wait: Cache synchronisation often resolves within a few hours.
Verify Logs: Check for Removing obsolete service messages.
Restart Homebridge: This triggers a fresh advertisement of the current state.
Reboot Home Hubs: Restarting the active Apple TV or HomePod can force a refresh.
Sign out of iCloud: On the home hub, sign out and back in to force a full resynchronisation.
Clear Cache or Re-add: Clear Homebridge cached accessories for the appliance. If this fails, remove and re-add the bridge (note: this deletes associated automations and scenes).

The plugin avoids using workarounds like randomising service identifiers to force updates, as this would break existing HomeKit automations and scenes.

Why is temperature control not supported for fridges, freezers, or ovens?

The HomeKit Accessory Protocol (HAP) only defines standard temperature services (Heater Cooler, Temperature Sensor, and Thermostat) for environmental climate control. Using these for appliances introduces significant issues with Siri voice control and HomeKit logic:

Siri confusion: Siri may conflate the appliance's internal temperature with the ambient room temperature.
Incorrect voice responses: Asking "what is the temperature in the kitchen?" might report the fridge's setpoint instead of the room temperature, or incorrectly incorporate it into a reported range.
Unintended control: A command to "set the kitchen to 21 degrees" might inadvertently attempt to adjust the appliance settings.

To maintain the integrity of voice control, this plugin exposes fridge and freezer modes (such as Super, Eco, Vacation, and Fresh modes) as individual Switch services instead of temperature controls. The plugin will only adopt new HomeKit services if Apple introduces specific appliance-grade definitions that do not conflict with ambient climate controls.

Why is my appliance door appearing as a `Door` service or security device instead of a `Contact Sensor`?

The plugin uses the Door service to represent appliance doors by design, as this is the most semantically accurate HomeKit service for the hardware. While many appliances only provide a read-only door status, the Home Connect API supports Open Door and Partly Open Door commands for specific high-end models. The Door service allows for both status monitoring and active control. Using a simpler sensor-based service, such as a Contact Sensor, would prevent the plugin from supporting remote door opening on appliances that offer it.

Because Apple Home categorises all Door services as security-related accessories, you may see the appliance grouped with locks, garage doors, or sensors, and receive automatic notifications when the door state changes. This is standard HomeKit behaviour and cannot be changed by the plugin. If this behaviour is not desired, you have two options:

Disable notifications: Within the Apple Home app, navigate to Home Settings > Doors and toggle off notifications for the specific appliance door.
Disable the service: You can completely hide the Door service within the plugin configuration for that appliance.

Why does my fridge-freezer only show a single door status for all compartments?

The Home Connect API originally only provided a single combined door status for all appliances. The API was extended in August 2023 to report separate status for each door of refrigeration appliances. When this plugin was subsequently extended to support a HomeKit Door service for each physical door, the default configuration was selected to match the previous behaviour, i.e. with only a single Door service per appliance. The individual door statuses can be enabled via the plugin's configuration.

Why can I not set the alarm timer or `AlarmClock` setting on my appliance?

HomeKit does not currently define services or characteristics with the correct semantics for a general-purpose appliance alarm timer. Mapping this functionality to existing, unrelated HomeKit services or characteristics would result in incorrect behaviour and cause issues when using Siri.

To maintain HomeKit consistency and ensure reliable voice control, the plugin does not support setting the BSH.Common.Setting.AlarmClock timer. This feature will only be considered if Apple introduces suitable HomeKit definitions that match the behaviour of appliance timers.

Why do multiple services or programs appear with identical names in the Apple Home app?

If multiple program switches appear with identical generic names (such as "Dryer"), this is typically caused by the Apple Home app's display logic rather than the plugin itself. To resolve this:

Force-quit and restart the Apple Home app to see if the names refresh.
If names remain identical, open the settings for an individual switch in the Home app and delete the prefix or appliance name from the name field. This often reveals the unique name (e.g. "Cotton Eco") that was previously hidden.
Manually rename the switch to your preference if necessary.

Why can I not see or control the child lock for my appliance in the Apple Home app?

The plugin supports the child lock setting (internally BSH.Common.Setting.ChildLock) by mapping it to the standard HomeKit Lock Physical Controls characteristic on the appliance's Power Switch service.

However, the official Apple Home app does not currently display or provide controls for this specific characteristic on many appliance types. To view the status or toggle the child lock, you must use a third-party HomeKit app such as Eve, Home+, or Controller for HomeKit.

Why is the hood boost mode a separate switch instead of part of the fan speed control?

The plugin represents Home Connect hood functionality using a combination of a Fan service for speed control and a Switch service for the boost mode. This design reflects the different behaviours of these features in the appliance firmware:

Standard Speeds and Intensive Mode: These are mapped to the HomeKit fan speed percentage steps. The highest fan speeds correspond to intensive mode, which runs for a fixed period (e.g. 6 minutes) before automatically reverting to a specific lower speed.
Boost Mode: On supported models, the Boost option provides a higher fan speed for a very short duration (e.g. 20 seconds). Unlike intensive mode, when the boost period ends, the hood returns to the previous speed setting.

Because HomeKit fan speed controls represent a linear progression, incorporating a mode that reverts to an arbitrary previous state is not natively supported by the speed slider. Exposing Boost as a separate Switch better represents this hardware behaviour and allows it to be activated independently of the current speed. This Switch can be hidden in the plugin configuration if it is not required.

Why is hood fan speed controlled using percentages instead of discrete levels?

The HomeKit Accessory Protocol (HAP) defines the Rotation Speed characteristic as a percentage (0–100%). To maintain compatibility with Siri voice commands such as "low", "medium", and "high", the plugin maps the appliance's discrete speed levels (e.g. stages 1 to 4) to specific percentage values (e.g. 25%, 50%, 75%, and 100%).

Direct control using discrete level numbers is not supported by the HomeKit fan service specification. Using percentages ensures that the fan works correctly with standard HomeKit sliders and provides consistent voice control across all Apple devices.

Can the physical hood control buttons on a Home Connect hob be used to trigger HomeKit automations?

No, the physical buttons on a hob designed to control a hood (fan and light) cannot be exposed to HomeKit. The Home Connect API does not currently emit any events or status updates when these physical buttons are pressed, meaning the plugin cannot detect the interaction.

Manufacturers typically design these buttons to communicate directly with compatible appliances using proprietary appliance-to-appliance protocols. Because these interactions are handled internally, they are not broadcast to the API event stream monitored by the plugin. If you wish to see this supported, you would need to request that Home Connect support expose these button presses as API events. You can monitor the Home Connect API documentation for updates to available event types.

Why is support for Home Connect robot vacuum cleaners limited?

HomeKit only supports Robot Vacuum Cleaners (RVC) via the Matter protocol. Whilst Matter support has recently been incorporated into Homebridge, this plugin only supports the HomeKit Accessory Protocol (HAP), which limits functionality to simple controls like switches. The maintainer of this plugin has developed Matterbridge plugins to integrate other brands of RVC with HomeKit (e.g. matterbridge-dyson-robot for Dyson 360 Eye, 360 Heurist, and 360 Vis Nav), but has no plans to do that with Home Connect RVCs such as the Roxxter and Spotless series:

The maintainer does not own the specific hardware required for testing and development.
Implementing Matter support is significantly more complex than the current HAP-based architecture.

Users should expect only basic status and control for these devices. Advanced features, such as specific cleaning modes, suction power settings, and mopping controls, are not easily mapped to existing HomeKit service types without causing issues with Siri or creating an inaccurate representation in the Apple Home app.

Why are appliance lights mapped as lightbulbs instead of switches?

The Home Connect API defines appliance lights (such as internal refrigerator lights or hood lighting) as settings that often include more than just simple on/off functionality. These can support Brightness, ColorTemperature, or Color depending on the specific model. The plugin uses the HomeKit Lightbulb service to allow for the full range of hardware capabilities to be exposed to HomeKit.

Many models, particularly hoods, have a hardware-enforced minimum brightness of 10%. The Home Connect API reflects this limitation; dragging the brightness slider below this threshold in HomeKit will typically turn the light off entirely rather than dimming it further.

A side effect of the lightbulb mapping is that Siri will include these appliance lights when you issue commands to turn off the lights in a specific room. If you do not want an appliance light to be controlled or grouped with your room lighting, you should disable that specific service in your Homebridge configuration.

Why is the colour temperature on my hood inverted?

Some hood models (such as the Siemens LC91KLT60) do not implement colour temperature control in compliance with the official Home Connect API documentation.

The Cooking.Hood.Setting.ColorTemperaturePercent setting is documented as 0% = warm light and 100% = cold light. The plugin follows this mapping to provide granular control in HomeKit. However, certain appliances (such as the Siemens LC91KLT60) interpret these values inversely. If your appliance is affected, you will need to reverse the settings in your HomeKit automations and scenes.

How are Home Connect air conditioners represented and controlled in HomeKit?

Home Connect air conditioners are exposed to HomeKit using a Thermostat service for temperature control and a Fan service for airflow. There are several limitations and specific mappings due to differences between the HomeKit Accessory Protocol (HAP) and the Home Connect API:

Missing Sensor Data: The Home Connect API does not currently expose ambient room temperature or humidity measurements for air conditioners. Consequently, the Current Temperature characteristic in HomeKit cannot reflect actual room conditions.
Thermostat State Mapping: Because HomeKit thermostat states (Off, Heat, Cool, Auto) do not align perfectly with appliance programs, the plugin uses the following logic:
- Target Heating/Cooling State Off maps to Fan or ActiveClean programs (fan-only operation).
- Target Heating/Cooling State Cool maps to Cool or Dry programs.
- Target Heating/Cooling State Heat maps to the Heat program.
- Target Heating/Cooling State Auto maps to the Auto program.
Program Selection: To avoid overriding custom settings, the plugin preserves the appliance's currently selected program if it is compatible with the state selected in HomeKit. If incompatible, it defaults to the first matching program supported by that specific model.

In addition to the thermostat controls, the plugin also supports controlling the power state, fan speed, and automatic or manual fan modes.

Notifications & Events

Why does my appliance appear as `Stateless Programmable Switch` buttons with numeric labels?

Home Connect communicates many appliance states (such as a coffee maker's "Drip tray full", a washing machine's "iDos fill level poor", or a dishwasher's "Salt low" alert) as transient events rather than persistent, queryable states. When an event occurs, it triggers an instantaneous "Single Press" on a Stateless Programmable Switch service. This mapping allows these events to be used as HomeKit automation triggers.

This design is necessary for several reasons:

API Limitations: The Home Connect API often does not allow the plugin to poll the current state of these alerts (e.g. after a reboot or reconnection). Because the actual state cannot be reliably determined at startup, using a persistent sensor (like a Contact Sensor) could lead to incorrect status displays if a "cleared" event was missed while the plugin was offline.
Inconsistent Reporting: The API does not consistently report when an event condition clears. While some appliances might send an "off" status, others simply stop sending the "present" event with no standard timeout defined.
Protocol Compliance: The HomeKit Accessory Protocol (HAP) defines sensors like Contact Sensor for continuous states. Mapping a momentary event to these services is technically incorrect.

The Apple Home app only displays numeric labels (e.g. "Button 1") for these services. This is a design limitation of the Home app; while the HomeKit framework allows for descriptive labels (visible in third-party apps like Eve or Home+), Apple's interface defaults to generic numbering. To identify what each button represents, check the Homebridge logs during startup. These events can be disabled per appliance in the plugin configuration if they are not required.

Why does the Home app show two (or more) tiles for one appliance?

This is a characteristic of how the Apple Home app handles different types of HomeKit services. Each Home Connect appliance is exposed as a single HomeKit Accessory, but that accessory contains multiple Services to provide different functionality.

The Apple Home app defaults to grouping most service types onto a single tile, but it typically places Stateless Programmable Switch services on a separate second tile. While you can toggle Show as Separate Tiles in the accessory settings to split them further, the Home app currently does not provide a way to merge these notification switches into the primary appliance tile.

Note that this is purely a user interface display characteristic. Other HomeKit apps, such as Eve or Home+, may group these services differently. This grouping also has no effect on Siri voice control, which interacts with the underlying services directly. If you do not use these events for automations, you can disable them in the plugin configuration to prevent the extra tile from appearing.

How do I get notifications for events like a program finishing?

The HomeKit Accessory Protocol (HAP) does not support arbitrary notifications or a dedicated "program finished" sensor type. HomeKit only allows notifications for a limited set of pre-defined sensor types, such as Motion Sensor, Smoke Sensor, or Contact Sensor. Implementing a workaround by using these existing types would result in a poor user experience; for example, a user would receive a "smoke detected" alert when a dishwasher finishes, which is misleading and technically incorrect.

To receive notifications, you have two main options:

Official Home Connect App: This is the most reliable method for detailed, text-based push notifications.
HomeKit Automations: You can trigger a notification indirectly by having the button event toggle a homebridge-dummy accessory (such as a Contact Sensor) which does support native alerts.

How can I disable HomeKit notifications for door events?

Door notifications for appliances like fridges or freezers are managed by the Apple Home app on a per-device basis. To disable them:

Open the Apple Home app.
Tap the ... icon at the top of the screen and select Home Settings.
Navigate to the Doors section.
Locate the specific appliance accessory and toggle off Activity Notifications.

Note that this setting must be configured separately on each iPhone or iPad where you want to silence the notifications. Alternatively, you can use the per-appliance configuration options in the plugin to remove the Door service entirely if you do not require its state information in HomeKit.

Siri

How do I control my hood fan speed using Siri?

Siri maps fan speeds to specific percentages:

Low is 25%
Medium is 50%
High is 100%

The plugin maps these percentages to the closest available physical fan settings of your hood. You can use commands like Hey Siri, set the hood fan to medium or Hey Siri, set the hood fan to 100%. Note that numeric settings like set fan to 1 are not supported by Siri for HomeKit fan services.

Compatibility and Integration

Third-party Platforms and API Limitations

Is this plugin compatible with HOOBS?

This plugin is designed and tested for vanilla Homebridge with Homebridge Config UI X. While it may function on HOOBS, it is not officially supported and users may encounter limitations.

Support policy for HOOBS users:

Contact HOOBS Support: Your first point of contact should be HOOBS Support for platform-specific issues.
Verify on Vanilla Homebridge: Before opening an issue, you must verify that the problem persists on a standard Homebridge installation.
No HOOBS-Specific Fixes: Bug reports or feature requests specifically for HOOBS compatibility or its configuration interface will not be accepted.

Will there be a Home Assistant version of this plugin?

No. This plugin is specifically designed for Homebridge to provide HomeKit integration for Home Connect appliances. The maintainer does not use Home Assistant and has no plans to develop or maintain a version for that platform.

For Home Assistant users, there are alternative community-maintained integrations available for Home Connect appliances.

Why are features available in the official app or IFTTT missing from this plugin?

This plugin is restricted by the capabilities of the public Home Connect API. The official Home Connect app and some official partners like IFTTT often utilise private or internal APIs to provide functionality that is not exposed to independent third-party developers.

If a specific program, option, or setting is not documented in the official Home Connect API documentation, it cannot be supported by this plugin. If you require these features, you should contact Home Connect Developer Support directly to request their addition to the public API.

Direct integration with IFTTT to bridge these gaps has been declined to maintain plugin stability and avoid architectural complexity. The maintainer's rationale includes technical constraints such as increased code complexity, the user burden of manually creating IFTTT applets, and interface clutter in HomeKit. For users requiring IFTTT-specific functionality, such as triggering automations from Hood Favourite buttons, it is recommended to use a dedicated plugin like homebridge-ifttt alongside this one.

Plugin Installation and Configuration

Why do I get an `npm ERR! ENOTEMPTY` error when installing or updating the plugin?

This is an error produced by the npm package manager rather than a fault within the plugin code. It typically occurs when npm attempts to rename or remove a directory during an update but fails because the target directory is not empty, a file is being held open by another process, or there are permission issues.

To resolve this issue:

Stop the Homebridge service to ensure no processes are actively using the plugin files.
Locate the temporary directory identified in the error log (for example, /usr/local/lib/node_modules/.homebridge-homeconnect-XXXXXXXX).
Manually delete that temporary directory and the existing homebridge-homeconnect directory if necessary.
Attempt to install the plugin again using the Homebridge Config UI or the command npm install -g homebridge-homeconnect@latest.

This error is often transient and may also be resolved by simply restarting the host system or retrying the installation via the Homebridge Config UI interface.

Why do configuration settings revert or cause `programs[0].name is missing` errors?

This behaviour is typically caused by updates to the Homebridge UI underlying form rendering engine (specifically the ng-formworks library) that introduced breaking changes in how conditional configuration schemas are processed. This can result in settings reverting to default values, appearing blank, or causing the plugin to fail to start with errors such as programs[0].name is missing. Even if the plugin has been updated to a version containing compatibility workarounds, existing configuration files may still contain invalid fragments.