Skip to content

FAQ

Jump to bottom
github-actions edited this page Mar 7, 2026 · 20 revisions

Frequently Asked Questions (FAQ)

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 appear 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, verify your configuration:

  • Incorrect Nesting: Ensure the HomeConnect platform block is a 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.

Why does authorisation fail with invalid_request 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 Credentials: The default "API Web Client" credentials provided in the portal are for the appliance simulator only. 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, or client has limited user list - user not assigned to client?

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

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

  • Home Connect user account for testing: This must exactly match the email address used for your Home Connect mobile app.
  • OAuth Flow: Device Flow.
  • Success Redirect: Leave blank (or set to a valid URL).
  • One Time Token Mode: Disabled.
  • Proof Key for Code Exchange: Disabled.
  • Sync to China: Disabled, unless you are using the Home Connect servers in China.

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 error?

Authorisation links and their associated device codes are only valid for a limited time. If this window is exceeded, or if a link is used more than once, the Home Connect API will return expired_token or the code entered is invalid or has expired.

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.
  • 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 can be caused by account verification issues or a known bug in the Home Connect authorisation servers:

  • Account Verification: Ensure your SingleKey ID account is fully configured. It is often necessary to log out of the official Home Connect mobile app and log back in to accept updated terms of use or verify the account, ensuring that you accept all necessary agreements.
  • Internationalisation Bug: A bug in the Home Connect and SingleKey ID servers can cause authorisation to fail if your browser's preferred language is set to a locale other than English. This often results in a login session expired error or prevents the password prompt from appearing after the username is entered. To resolve this set your web browser's preferred language to English (en). Refresh the page and attempt the authorisation again. You can revert these settings once the plugin has successfully obtained its tokens.

To complete the process once initialised:

  1. Find the URL in the logs (e.g. https://api.home-connect.com/security/oauth/device_verify?user_code=XXXX-XXXX).
  2. Open the full URL in a browser and sign in with the SingleKey ID account used in the official Home Connect mobile app.
  3. Approve the request. The plugin will automatically detect completion and save the tokens.

Why does authorisation fail with a 403 Forbidden error?

This error typically indicates that the Home Connect API is geo-blocked in your region (for example, in Russia). This results in a 403 Forbidden response when the plugin attempts to connect to authorisation endpoints such as POST /security/oauth/device_authorization. This is a restriction imposed by the service provider or regional network infrastructure 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 use a dedicated regional API endpoint (api.home-connect.cn) and require specific configuration both in the Developer Portal and the plugin:

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

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 limits 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 (e.g. Waiting 5 hours 23 minutes before issuing Home Connect API request).

Most of the limits reset after either 1 or 10 minutes, but there is also a daily quota of 1,000 requests. While the plugin manages requests efficiently, certain conditions can cause these limits to be reached rapidly:

  1. Frequent Homebridge Restarts: Each time the plugin starts, it must issue multiple API requests to discover the features, programs, and current state of every connected appliance. Frequent restarts during configuration or due to system instability will quickly consume the daily allowance. Check your Homebridge log for frequent restarts. If this is the issue then ensure Homebridge is stable, avoid unnecessary reboots, and (if possible) run this plugin in its own child bridge.
  2. Unstable Appliance Connectivity: When an appliance disconnects and reconnects to your Wi-Fi, the plugin must issue several API requests to re-synchronise its state. A single appliance with an unreliable network connection can trigger enough CONNECTED events to exhaust the quota. Check your logs for repeated DISCONNECTED or CONNECTED messages. If found, improve the Wi-Fi coverage for that specific appliance. Note that appliance Wi-Fi hardware is often lower quality than that found in smartphones or laptops.

Why does my appliance show a 409 Conflict error?

The Home Connect API uses 409 Conflict errors for a wide variety of failures that result in a request being rejected. The error message usually provides more details of the specific reason. Some of the more common cases are:

  • 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.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 is returned when you attempt to start a program that the API considers unavailable for remote execution. This may be due to appliance settings, safety features (e.g. local control active), or firmware bugs.

  • 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 toggle together.

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

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

The physical power button on some Home Connect appliances (mostly commonly washing machines and tumble dryers) also 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 for other reasons. The plugin prioritises technical accuracy, so reports this as SERVICE_COMMUNICATION_FAILURE to HomeKit, which the Apple Home app displays as Not Responding.

Faking a "Power Off" state when the appliance is unreachable would misrepresent the appliance's true status. If the appliance does actually have connectivity problems then it may be powered on. Most Home Connect appliances do maintain Wi-Fi connectivity when switched off, so reporting SERVICE_COMMUNICATION_FAILURE correctly distinguishes between power off and failure to connect to the Home Connect servers.

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 or Proxy Error messages in the log mean?

Errors such as SDK.Error.504.GatewayTimeout 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 public API used by third-party integrations often experiences these issues independently of the official Home Connect mobile app. The plugin is designed to handle these interruptions by automatically attempting to re-establish the connection once the servers are responsive again.

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. When this happens, the official Home Connect mobile application may also fail to connect. 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.

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

These are all standard networking errors indicating a DNS name resolution failure. This means your local system or Homebridge host is unable to resolve the IP address for the Home Connect API servers (api.home-connect.com). This is usually caused by a transient loss of internet connectivity, a local router performing a reboot, or network misconfiguration.

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

  1. Diagnostic Commands: Test DNS resolution from a shell on the same system using dig api.home-connect.com or nslookup api.home-connect.com.
  2. DNS Provider: If your system is configured to use your router as its DNS server via DHCP, 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.
  3. Network Filtering: Verify if any local firewall or DNS filtering (like Pi-hole or AdGuard Home) is blocking requests to api.home-connect.com or its underlying Amazon Web Services (AWS) endpoints.

If you are using a Docker container then perform these diagnostics within the container environment, and additionally try:

  1. Address DNS/IPv6: Problems frequently arise when IPv6 is enabled but not correctly routed. Try the following:
    • Disable IPv6 for the container using --sysctl net.ipv6.conf.all.disable_ipv6=1.
    • Force the container to use a specific DNS provider by adding --dns 1.1.1.1 to your docker run command.
    • Ensure any host firewall rules are not blocking outbound traffic from the container network.
  2. Network Mode: Consider switching the container to host network mode to bypass Docker's internal bridge networking if issues persist.

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 a service outage, the plugin may rapidly log attempts to restart the event stream.

This is expected behaviour. The plugin is designed to recover automatically as soon as the service resumes.

Technical rationale:

  1. State Consistency: The plugin relies on the event stream for real-time updates. Frequent reconnection attempts ensure the plugin synchronises with your appliances as soon as the service resumes, minimising stale data in HomeKit.
  2. Diagnostic Integrity: Detailed logs of every connection attempt and the specific error returned (e.g. Service Temporarily Unavailable) are vital for diagnosing complex or intermittent API failures.
  3. API Rate Limits: The plugin is optimised to stay within rate limits. Introducing manual delays or 'wait' logic adds complexity that could interfere with the normal recovery process.

While this results in a high volume of logs during an outage, it ensures the plugin recovers as reliably as possible 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.

Why does starting the Silence program on my dishwasher fail?

Some dishwasher appliances offer two ways to reduce noise: a dedicated Silence program (e.g. Dishcare.Dishwasher.Program.NightWash) and a Silence on Demand option (Dishcare.Dishwasher.Option.SilenceOnDemand) that modifies the operation of other programs.

The Home Connect API restricts appliances to one active program at a time. If you attempt to start the NightWash program while another program is already running, the API returns a 409 Conflict error with SDK.Error.WrongOperationState.

This plugin supports configuration of program options to be used when starting a new program, including the SilenceOnDemand option for programs that support it. However, it does not implement mapping of program options to dedicated HomeKit services to enable changing them for a program that is already running. This is a deliberate design choice because the API does not clearly signal which options are valid to modify dynamically, and there is no appropriate way to map these temporary, time-limited behaviours to the standard HomeKit service model.

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 allowed
  • This cannot be set via the API
  • Some appliances automatically expire Remote Start after a period of time or when you open the appliance door

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. Reporting "Success" instead would be misleading, as the appliance would not actually start.

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. This lockout usually clears a few seconds after you stop touching the controls, although 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, they were made available to independent developers in March 2021. If you authorised the plugin's connection to Home Connect prior to this then force a re-authorisation:

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

Note that FridgeFreezer-Images scope remains restricted and hence 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: Controls the standby state of the machine.
  • Active Program: Starts or stops the currently selected program.
  • Individual Programs: Start (or select) a specific named program.
  • Modes: Any settings that the appliance supports, such as SabbathMode or SuperModeFreezer.

By default, the Apple Home app may group these separate services into a single tile. Toggling this combined tile attempts to activate all switches simultaneously, which results in conflicting requests. The plugin attempts to detect and ignore such invalid actions.

For example: If your dishwasher has a Power switch, an Active Program switch, and three individual program switches (Eco, Intensive, Quick), toggling the combined tile tries to turn on power and start all three programs at once; an impossible operation.

To resolve this, you should configure the Home app to display these services individually using the Home app's Show as Separate Tiles option.

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.

  • API Instability: The Home Connect servers occasionally experience maintenance or instability. You can check the current status on the Home Connect Server Status page.
  • Local Network: Weak Wi-Fi signals or intermittent internet drops can cause the appliance to lose its cloud heartbeat.

When these disconnections occur, the plugin logs the event and updates the HomeKit status to reflect that the device is unreachable. This is a reporting of the appliance's actual cloud state and cannot be resolved via plugin code changes.

Programs and Options

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

The plugin includes a diagnostic mechanism to identify data from the Home Connect API that it does not yet recognise. This frequently occurs because the API implementation deviates from official documentation, or because new appliance models or firmware introduce undocumented features, programs, or options.

While unrecognised values usually do not prevent the plugin from functioning, the specific feature may be missing or unavailable in HomeKit until it is added to the plugin's internal schema. When this happens, the plugin generates a technical diagnostic block in the log file, delimited by lines of = characters and containing comments marked // (unrecognised). This helps the maintainer update the plugin's definitions and map the missing information to HomeKit services.

If you observe these messages:

  1. Update the plugin: Ensure you are running the latest version, as support for new values is added frequently.
  2. 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.
  3. Provide the snippet: Paste the entire technical diagnostic block from the log (including the = separators) into the Log File field of the issue template.

Once these identifiers are added to the plugin, the warning will disappear and the corresponding features will be correctly mapped to HomeKit.

Why are some appliance features, programs, or options missing or unavailable?

There are several reasons why features may be missing from the plugin or appear as currently unavailable or advertised by appliance currently unavailable in the logs:

  • 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 other 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.
  • 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 (like temperature or spin speed) via the public Home Connect API.
  • Operational Status: A program may be reported as supported but currently unavailable if the appliance is busy, a cycle is already running, a door is open, or required consumables (water, detergent) are missing. This is a dynamic status provided by the Home Connect API based on the physical state of the machine.

If a program is unexpectedly missing, try powering the appliance on, manually selecting the affected program on the physical control panel, and leaving it idle for one minute. Then, trigger the plugin to re-read the details by using the HomeKit Identify method or restarting Homebridge. If the API continues to refuse access, you can request inclusion via Home Connect Developer Support.

Why are fan controls missing for my integrated venting hob?

Extractor fans integrated into hobs (venting hobs) are not exposed by the Home Connect API as controllable features.

The Home Connect API is architected to support a single active program per appliance. Devices that support multiple simultaneous programs are exposed by the API as multiple appliances, e.g. the two cavities of dual ovens. The extractor fan in hood appliances operate as programs (e.g. Cooking.Common.Program.Hood.Automatic), so a hob with an integrated fan would need to expose a separate hood appliance for it to be controllable via the Home Connect API, which is not currently the case. Users affected by this should contact the Home Connect developer team to request that the fan be exposed as a separate Hood appliance.

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.

In these cases, the messages are often cosmetic or indicate a limitation of the Home Connect service rather than a fault with the plugin. The plugin will automatically fetch or refresh necessary details once initialisation is complete.

Why is my appliance stuck during initialisation, showing as Not Responding, or missing all options?

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 or missing consumables (e.g. low salt or a full drip tray) can also cause discovery to fail. When this occurs the log typically includes messages like Waiting for ... features to finish initialising or Appliance initialisation is taking longer than expected.

Note that the official Home Connect app uses a private API and may still appear to show the appliance as online while the public API used by this plugin reports it as offline. To resolve this, perform the following diagnostic steps:

  1. Check the Home Connect Server Status: Visit the unofficial status page to rule out platform-wide outages.
  2. 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 the official app shows the device as offline or cannot control it, the issue lies with the appliance's connection to the Home Connect cloud servers.
  3. Confirm Consumables and Maintenance: Verify that all maintenance requirements (cleaning, descaling, refills) are met.
  4. Power Cycle: Disconnect the appliance from the mains power for 30 seconds to force its internal firmware to re-register with the cloud servers.
  5. Delete Cache Files: If the issue persists, stop Homebridge and delete the appliance's cache files in ~/.homebridge/homebridge-homeconnect/persist (filenames are MD5 hashes; do not delete the authorisation file 94a08da1fecbb6e8b46990538c7b50b2).
  6. 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.

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 technical reasons:

  • HomeKit Response Timeouts: HomeKit requires a rapid response when a characteristic is updated. Waiting for a power-on sequence or rinse cycle would exceed the allowed time, causing HomeKit to report a timeout error.
  • State Reporting Inconsistency: Different models report their power state and readiness inconsistently. Some may not reliably indicate when they are ready to receive a program command.
  • User Feedback: To avoid timeouts, the plugin would have to report success immediately. If the subsequent background sequence failed (e.g. the water tank is empty), the user would receive no feedback in HomeKit or via Siri.
  • Device Behaviour: Many 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 before a beverage can be requested, you should use the Apple Shortcuts app or HomeKit automations to create a sequence (e.g. Turn On → Wait → Start Drink).

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 the BSH.Common.Root.SelectedProgram event. There are several limitations to this:

  • API Event Dependency: Many appliances (especially washers and dryers) do not consistently generate events for program selection. If the plugin cannot determine which program is selected, toggling the switch will result in an Error: No program selected in the logs.
  • HomeKit UI Restrictions: If the plugin cannot reliably set the state of a switch due to these API limitations, HomeKit apps may prevent the switch from being used in scenes or automations to avoid inconsistent states.

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

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

To trigger the Identify mechanism within the Eve app:

  1. Navigate to the Rooms tab and locate the appliance.
  2. Tap the name of the appliance to open the detailed view (do not tap a toggle or slider).
  3. Tap the appliance name or the small arrow at the top of the screen, just below the Edit button.
  4. 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 or Homebridge startup stall?

To learn an appliance's specific options, the plugin must select each program via the API. Many appliances only report valid option ranges when the power is on and that specific program is selected.

If the plugin does not have a valid cache, it will attempt to turn the appliance on, iterate through all available programs, and then restore the appliance to its original state. This should only happen once. If it occurs every time Homebridge restarts, discovery may be failing with a 409 Conflict (e.g. BSH.Common.Setting.PowerState currently not available or writable) because the appliance is busy, in an incompatible state, or the door is 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?

If a program is started without custom options, the Home Connect server uses the appliance defaults. These are usually the factory defaults or the settings used the last time that program was run manually.

To view these default values, enable Debug Logging and use the Identify function. The plugin will output a detailed list of every default value currently reported by the API to the Homebridge log.

Why do my oven programs only run for one minute?

When started remotely via the API, oven programs must have a defined duration. If no duration is provided by the plugin, the Home Connect API typically defaults to a value of 60 seconds.

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:

  1. Verify your server's current time zone configuration. On most Linux distributions, you can use the timedatectl command.
  2. Ensure the operating system or container environment is set to your correct local time zone.
  3. 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. To simplify the interface, change the Program Switches configuration for the appliance:

  • No individual program switches: Hide all program switches.
  • A switch to start each appliance program (default): Advertise all available programs to HomeKit using default options.
  • Custom list of programs and options: Explicitly define which programs appear in HomeKit, and the options to use with each.

What does the log message Using expired cache result mean?

The plugin caches technical details about appliance programs, such as valid temperature ranges or spin speeds, because the Home Connect API only allows this information to be retrieved reliably when a program is selected but not yet running. The plugin considers this cache expired if the program has not been selected on the appliance for more than 24 hours.

When the plugin requires these details but cannot refresh them from the API (because a different program is currently selected), it will use the last known data and log this message. This is expected behaviour and does not indicate a functional failure; it simply signifies that the plugin is relying on historical data for a program that has not been used recently.

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 some hoods do not report speed in this mode, the Home app may display an incorrect speed percentage while the automatic program is running.

Why does the plugin log unrecognised PowerState values like Undefined or MainsOff?

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 bugs in the appliance firmware or the Home Connect cloud servers, as they 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.

Appliance Status

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. If this stream is interrupted or the backend stops sending events, the plugin cannot update HomeKit.

The API sends a KEEP-ALIVE event approximately every 55 seconds; if the plugin detects no activity for 120 seconds, it will automatically re-establish the stream. In some cases, the connection may remain technically active while the Home Connect backend stops distributing actual state change events, either due to events not being received from the appliance or internal errors within the cloud infrastructure.

To troubleshoot:

  1. 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.
  2. Restart Homebridge to force the plugin to subscribe to a fresh event stream.
  3. Ensure your network configuration does not prematurely terminate long-lived TCP connections.

Why is my appliance unresponsive in Homebridge but working in the Home Connect app?

The official Home Connect mobile app can communicate with appliances via the local Wi-Fi network when your phone is on the same network. In contrast, this plugin and all third-party integrations must use the public Home Connect cloud API. It is possible for an appliance to have a working local connection but a stalled cloud connection.

To diagnose this, disable Wi-Fi on your mobile device to force the Home Connect app to use a cellular (remote) connection. If the appliance becomes unresponsive in the app while on cellular data, the issue lies with the appliance's connection to the Home Connect servers rather than the plugin. You can often resolve this by power cycling the appliance. If problems persist check the Home Connect Server Status (unofficial) for 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 behaviour is typically caused by:

  1. A server-side state mismatch or backlog within the Home Connect infrastructure.
  2. A delay in the event stream where old status updates are delivered late.
  3. A bug in the appliance firmware or the cloud API representation of that specific model.

To resolve this, try starting and then stopping a manual program using the official Home Connect app or the physical appliance interface to reset the server state. 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 my Homebridge 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. Most ovens remain in a standby state after use where they continue to monitor and report cooling progress.

The plugin logs all status information reported by the API. To prevent these messages 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 appears because the plugin periodically polls 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 functionality for dishwasher appliances to monitoring-only. Remote control of the door is limited by the API to specific oven and fridge/freezer models, and even then, it is dependent on the specific appliance hardware. For dishwashers, the Door service in HomeKit is read-only; it will correctly indicate whether the door is open or closed, 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.

Can I use data from the Home Connect status page for automations or scripts?

No. The unofficial Home Connect Server Status page is provided solely for manual diagnostic purposes to help users identify if connectivity issues are platform-wide. There are no plans to provide an API for third-party use or automated scripts. Automated scraping or frequent polling of the status page is unsupported and may result in the requesting IP being blocked.

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 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. These services are semantically inappropriate for most Home Connect appliances, and using them would create an inconsistent architectural model and break existing automations.

To view the remaining time or use it for automations, 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 displaying a wider range of standard HomeKit characteristics that Apple's own app hides.

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 can I not hide certain switches, or why do they remain visible or unresponsive after being disabled?

The main Switch service for the appliance power is fundamental to the plugin's architecture and cannot be disabled. Most other services can be individually enabled or disabled for each appliance within the plugin configuration. This includes the Active Program switch, though disabling it removes other functionality that may not be obvious:

  1. Status Indicators: The On, Status Active, and Status Fault characteristics which indicate the current operational state.
  2. Program Control: The ability to start, stop, pause, and resume the active program.
  3. Time Remaining: The Remaining Duration characteristic.

If services remain visible in HomeKit (often appearing as "unresponsive") after you have configured them to be hidden, it is likely due to HomeKit's internal caching and synchronisation mechanisms rather than the plugin itself. When a feature is disabled, the plugin removes the service from the accessory definition, but HomeKit may retain a stale cached version across multiple hubs or iCloud-synced devices. To resolve persistent stale entries, try these steps in order:

  • Check the logs: Verify the plugin is removing the service. You may see a message such as Removing obsolete service "Internal Light" if the service was restored from the Homebridge cache but is now disabled.
  • Restart Homebridge: This triggers a fresh configuration update to HomeKit.
  • Wait: Allow several hours for iCloud synchronisation to reconcile the state across all your devices.
  • Reboot the Home Hub: Restart your primary Apple TV or HomePod.
  • Reset iCloud: Sign out of iCloud on the Home Hub and sign back in.
  • Remove the bridge: As a last resort, remove the Homebridge bridge from HomeKit and re-add it.

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 several issues with Siri voice control:

  • 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 internal setting instead of the room temperature.
  • Unintended control: Commands to adjust the room temperature might inadvertently change 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.

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. Mapping these to a Door service allows the plugin to expose this control functionality where supported; on other models, it remains a read-only sensor.

Because Apple Home categorises all Door services as security-related accessories, you may see the appliance grouped with locks 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:

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

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 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.

Why do multiple program switches appear with identical names in the 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:

  1. Force-quit and restart the Apple Home app to see if the names refresh.
  2. 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 action often reveals the unique program name (e.g. "Cotton Eco") that was previously hidden.
  3. 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:

  1. Standard Speeds and Intensive Mode: These are mapped to the HomeKit fan speed percentage steps. The highest fan speeds correspond to intensive mode, which run for a fixed period (e.g. 6 minutes) before automatically reverting to a specific lower speed.
  2. 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.

Can the 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 are not exposed through the Home Connect API. The API does not provide any events or status updates when these buttons are pressed, which means the plugin cannot detect the interaction or expose it to HomeKit. This is a limitation of the Home Connect platform and appliance firmware rather than the plugin. Manufacturers typically design these buttons to communicate directly with compatible Home Connect hoods rather than broadcasting their state to the cloud API.

Why can I only control power and fan speed for my Home Connect air conditioner?

The Home Connect API currently provides extremely limited support for air conditioning units. While basic operations like power and fan speed are available, the API lacks several critical capabilities required for a full HomeKit Thermostat or HeaterCooler service:

  • Ambient Temperature and Humidity: There is currently no API endpoint to read the current room temperature or humidity.
  • Temperature Setpoints: Although some internal keys exist, they are not officially supported for control via the public API.
  • Mode Selection: Selection of cooling, heating, or auto programs is not fully exposed for external control.

Consequently, the plugin exposes air conditioners as a power Switch (to toggle between On and Standby) and a Fan (to control fan speed and toggle between manual and automatic modes). Adjusting the target temperature or switching between heat and cool modes must be done via the physical remote or the official Home Connect 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 and appliance type.

The plugin uses the HomeKit Lightbulb service for these features because:

  • A Switch service does not support the brightness or colour controls provided by the Home Connect API.
  • It maintains a consistent mapping across all appliance types where lighting is a feature (e.g. extractor hoods and refrigerators).
  • It allows for the full range of hardware capabilities, such as dimming, to be exposed to HomeKit.

A side effect of this 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.

Notifications & Events

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

Home Connect communicates many appliance states as transient events (e.g. "Drip tray full" or "iDos fill level poor") rather than persistent, queryable states. The plugin maps these events to Stateless Programmable Switch services so that they can be used as automation triggers. It is not possible for the plugin to poll the current state (e.g. after a reboot), and many appliances do not reliably generate events when a condition clears.

The Apple Home app only displays numeric labels (Button 1, Button 2) for these services. To see what these represent for your specific appliance, check your Homebridge logs during startup or use a third-party app like Eve or Home+ which displays descriptive labels. If you do not require these events for automations, you can disable them per-appliance in the plugin configuration to prevent them from appearing in the Home app.

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

This is standard Apple Home behaviour. To keep the interface organised, Apple separates different service types into distinct tiles. Specifically, a separate tile is created for the Stateless Programmable Switch services used for event triggers.

While you can toggle Show as Separate Tiles in the accessory settings, Apple does not currently allow these buttons to be merged into the primary appliance tile. If you do not use these events for automations, you can disable them in the plugin configuration to prevent them from appearing in the Home app.

How do I get appliance notifications?

Apple Home only supports native push notifications for specific security-related sensors (Doors, Locks, Smoke, etc.). Most Home Connect events do not fit these categories; forcing them to do so would result in misleading notification text.

To receive notifications for other events, you have two main options:

  • The Official Home Connect App: The most reliable way to get detailed, text-based push notifications.
  • HomeKit Automations: Trigger an action via a Stateless Programmable Switch. You can generate a HomeKit notification indirectly by having the automation toggle a homebridge-dummy 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:

  1. Open the Apple Home app.
  2. Tap the ... icon at the top of the screen and select Home Settings.
  3. Navigate to the Doors section.
  4. 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

Is this plugin compatible with HOOBS?

Yes, but it is not officially supported.

This plugin is designed and tested for vanilla Homebridge with Homebridge Config UI X. If you choose to use HOOBS, you may encounter stability issues or broken features.

Support policy for HOOBS users:

  1. Contact HOOBS Support: Your first point of contact should be HOOBS Support for platform-specific issues.
  2. Verify on Vanilla Homebridge: Before opening an issue, you must verify the problem persists on a standard Homebridge installation.
  3. No HOOBS-Specific Fixes: Bug reports or feature requests specifically for HOOBS compatibility 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 IFTTT or the official app missing from this plugin?

This plugin is restricted by the capabilities of the public Home Connect API. Certain features are available to official partners like IFTTT via private API integrations but are not exposed to third-party developers. If a specific program or option 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 explicitly declined to maintain plugin stability and avoid architectural complexity. The maintainer's rationale includes several key technical and design constraints:

  • Complexity and Maintenance: Implementing a hybrid control system where some actions use the Home Connect API and others use IFTTT would create significant code complexity and "feature creep".
  • User Configuration Burden: Direct integration would rely on users manually creating appropriate IFTTT applets and then precisely configuring this plugin to match, which is prone to user error.
  • Interface Clutter: Adding additional manual switches for IFTTT actions would further clutter the HomeKit interface, making the existing list of program switches more difficult to navigate.
  • Free Plan Limitations: The IFTTT free tier supports a maximum of two applets, and some Home Connect features are only available via a "Pro+" plan, so most users would receive limited benefit.

For users who require IFTTT-specific functionality, such as triggering automations from Hood Favourite button presses, it is recommended to use a dedicated plugin such as homebridge-ifttt alongside this one. This approach keeps the logic for different services separate and more manageable.

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 or a file is being held open by another process.

To resolve this issue:

  1. Stop the Homebridge service to ensure no processes are actively using the plugin files.
  2. Locate the temporary directory identified in the error log (for example, /usr/local/lib/node_modules/.homebridge-homeconnect-XXXXXXXX).
  3. Manually delete that temporary directory and the existing homebridge-homeconnect directory if necessary.
  4. Attempt to install the plugin again.

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.

Copyright © 2019-2026 Alexander Thoukydides

Clone this wiki locally