Home Connect

Cloud integration with Bosch, Siemens, Neff, Thermador and Gaggenau connected appliances via the Home Connect Developer API (api.home-connect.com). One GEM device row authenticates against one Home Connect end-user account (via OAuth 2.0). Each appliance paired to that account becomes a GEM zone keyed by its haId (a 32-character hex string).

Common appliance classes: dishwashers, ovens, coffee machines, cooktops, washers, dryers, hoods, fridges, freezers, warming drawers.

Prerequisites

• The end-user account must be a real Home Connect account (created in the mobile app), with each appliance already paired to it and showing online in the app.
• A developer application registered at developer.home-connect.com so you have a client_id and client_secret. The application does NOT need the "Client Success" flag — the standard authorization-code flow works.
• A refresh_token obtained by running the OAuth authorization-code flow against the end-user account once. The developer portal has an in-browser helper that produces this token — or use the redirect-URI capture technique described in the Home Connect docs.
• Outbound HTTPS from the GEM server to api.home-connect.com.

Setup

1. Pair every appliance you want to control to the end-user's Home Connect mobile app. Confirm each shows online in the app. Appliances that only appear in the app's "not connected" list cannot be reached by the API.
2. Register a Home Connect developer application. Note the client_id and client_secret.
3. Complete the authorization-code flow once against the end-user account and capture the returned refresh_token. The developer portal's "Authorization" playground is the easiest route.
4. In GEM admin, open System → Devices → Add, pick driver home_connect, and set:
   • OAuth Client ID — from the developer portal.
   • OAuth Client Secret — from the developer portal (stored encrypted).
   • OAuth Refresh Token — from step 3 (stored encrypted).
5. Save the device. The driver exchanges the refresh_token for a short-lived access token (~1 h) on connect and refreshes silently before it expires. Home Connect rotates the refresh_token on each refresh; the driver writes the new value back to the device row so the next restart uses the fresh one.
6. Run get_appliances to list the appliances on the account with their haIds.
7. For each appliance, create a GEM zone with the driver device selected and zone.address set to the haId.

Attributes

Device

Attribute	Type	Required	Notes
client_id	string	yes	OAuth client id from the developer portal.
client_secret	string (secure)	yes	OAuth client secret. Encrypted at rest.
refresh_token	string (secure)	yes	OAuth refresh token. Encrypted; rotated in place on each refresh.
scope	string	no, default IdentifyAppliance Monitor Settings Control	Space-separated OAuth scope string. Adjust if your developer app is restricted.
status_interval	int (ms)	no, default 60000	Poll interval. Minimum 30 000 ms — the Home Connect API bills per request.

Zone

Attribute	Type	Notes
address	string	The 32-char haId. Copy verbatim from get_appliances.

State attributes surfaced by the driver each poll:

Attribute	Type	Notes
state	string	on / off, derived from BSH.Common.Setting.PowerState.
power_state	string	The raw BSH.Common.EnumType.PowerState.* value.
operation_state	string	BSH.Common.EnumType.OperationState.* — Ready, DelayedStart, Run, Pause, ActionRequired, Finished, Error, Aborting.
door_state	string	Open / Closed / Locked.
remote_start_allowed	bool	Whether the physical Remote Start button has been pressed within the ~2 min window. See the note in Known Limitations.
active_program	string	Program key currently running (e.g. Dishcare.Dishwasher.Program.Auto2). Empty when idle.
remaining_seconds	int	Program time remaining.
progress_percent	int	0-100.

Commands

Command	Args	What it does
get_appliances	—	Lists every appliance on the account with haId, brand, type, connected, enumber.
get_status	address	Returns the current /status document for one appliance.
get_active_program	address	Returns the currently active program (or null if idle).
get_available_programs	address	Returns the program keys the current appliance model supports. Use this to feed start_program.
on	address	Writes BSH.Common.Setting.PowerState = On.
off	address	Writes BSH.Common.Setting.PowerState = Off (some appliances map this to Standby).
start_program	address, program_key	Starts the specified program. Requires the Remote Start button to have been pressed on the appliance first.
stop_program	address	Deletes the active program (equivalent to Cancel).
pause_program	address	Sends BSH.Common.Command.PauseProgram. Supported by dishwashers and washers.
resume_program	address	Sends BSH.Common.Command.ResumeProgram.

Zone Address Format

Home Connect haId — a 32-character hex string like BOSCH-SPH1234567-1234567AB1234. Copy it verbatim from get_appliances. Do not URL-encode or lowercase it beforehand.

Known Limitations

• Remote Start is BSH-mandated. For safety reasons every write that starts or resumes a program requires the end-user to physically press the "Remote Start" button on the appliance immediately before the API call — BSH does not allow this to be bypassed. The status flag BSH.Common.Status.RemoteControlStartAllowed is surfaced as remote_start_allowed so scripts can gate the write.
• Program option lists are appliance-model-specific. This driver starts programs with an empty options array — the appliance uses its own defaults. Writing detailed program options (spin speed, temperature, drying level, intensiv-zone, etc.) is a follow-up; the underlying REST endpoint (PUT /programs/active with options: [{key, value}]) supports it.
• Event stream not consumed. Home Connect exposes a server-sent event stream for real-time updates. This driver polls instead — simpler and sufficient for typical UI cadence, at the cost of up to status_interval seconds of delay.
• Fridges, freezers, and hoods often expose telemetry only; do not expect start_program to succeed on them.

Troubleshooting

refresh 400 on connect. The refresh_token has expired or been revoked (BSH revokes them on password change and on inactivity). Regenerate it in the developer portal's Authorization playground and paste the new one into the device row.

start_program returns 409. The Remote Start button was not pressed within the last ~2 minutes. Have the end-user press it and immediately retry. Some appliances distinguish between a Remote Start button and a general Remote Control button — check the appliance manual.

get_appliances returns an empty array. The end-user account has no paired appliances that are online. Open the Home Connect app on the same account and verify.

unknown zone address from a command. zone.address must match a haId returned by get_appliances character-for-character. Watch for stray spaces when pasting.

http 429. You are exceeding the API rate limit. Raise status_interval and reduce the number of ad-hoc get_status / get_active_program calls from macros / the AI assistant.