Program Option Discovery Caching#

Overview#

Program option discovery is the process by which the plugin learns what configurable options (temperature, spin speed, etc.) each appliance program supports. This information is not directly available from the Home Connect API without either passively observing a program's selected state, or actively selecting it first. The plugin implements a layered strategy — passive reading, active selection, and persistent caching — to minimise both API calls and appliance disruption.

The entire mechanism lives in the HasPrograms mixin (src/has-programs.ts), which is composed into every appliance type that supports programs.

Discovery Flow#

Initialisation triggers initPrograms(), which restores any previously cached program details from persistent storage before calling refreshPrograms().

Passive Reading#

updateProgramsWithoutSelecting() calls device.getAvailableProgram(key) via getCached() for each available program that has not yet had its options recorded. This works only when the program is already selected on the appliance — it will succeed for the currently selected program and may succeed for others where the API still returns details.

Active Reading (Select-First)#

updateProgramsSelectFirst() is used when the passive step leaves programs without options. It requires the Control scope and checks that 1:

• The appliance is in Inactive or Ready operation state (no active program).
• LocalControlActive is not set.
• RemoteControlActive is not explicitly false.

For each qualifying program, selectAndGetAvailableProgram() powers the appliance on if needed, selects the target program, then calls getAvailableProgram() which wraps device.getAvailableProgram() with pre/post requireProgramReady() guards. After all programs are read, the original selected program and power state are restored on a best-effort basis.

The autoSelectingPrograms flag suppresses the BSH.Common.Root.SelectedProgram event handler during this phase to avoid re-entrant discovery.

Reactive Updates#

When the user manually selects a program on the appliance, updateSelectedProgram() fires via the BSH.Common.Root.SelectedProgram event. This opportunistically reads and caches the options for that program, marking it as selected: true.

Caching Layers#

In-flight Deduplication + Persistent Cache (getCached)#

All API calls for static appliance data go through getCached() in src/appliance-generic.ts. This method:

1. Prevents duplicate concurrent calls for the same key.
2. Delegates to doCachedOperation(), which checks PersistCache.getWithExpiry() before making an API call.
3. Falls back to an expired cache entry if the API call fails 2.

Cache keys for program option reads are:

Persistent Storage (PersistCache)#

PersistCache (src/persist-cache.ts) backs the cache with node-persist (localStorage-style). Cache entries expire after 24 hours 3 and are also invalidated if:

• The stored entry was written by a different plugin version (semver major/minor mismatch) 4.
• The preferred field (reflecting current configuration) no longer matches 5.

The consolidated program details object (the programs array including discovered options) is separately persisted under the key Program details by savePrograms() after each discovery cycle, so it survives restarts without re-querying.

Program-Level selected Flag#

Within the in-memory programs array, each entry tracks a selected boolean 6. updateCachedProgram() enforces that a selected: true entry (read via active selection) cannot be overwritten by a passive read, protecting higher-quality data.

Failure Modes#

The missingOptionsHelp() method logs actionable recovery steps when any programs are missing options or could not be selected. Key guidance: ensure the appliance is idle with remote control enabled, then manually select each affected program on the appliance. The plugin will detect the selection event and opportunistically read the options. Alternatively, trigger re-discovery by restarting Homebridge or invoking the HomeKit Identify routine 7.

Some programs are legitimately never available — for example, Sabbath programs require a specific appliance setting before they appear 8.

Re-triggering Discovery#

• Restart Homebridge — refreshPrograms(false) runs on every initialisation.
• HomeKit Identify — calls refreshPrograms(true) (active mode, re-reads all programs regardless of the selected flag).
• Manual program selection — triggers updateSelectedProgram() reactively via the BSH.Common.Root.SelectedProgram event.

Key Source Files#