Migrate ventilation programs from deprecated ventilation.operating.programs API

[lackas]

The Viessmann API deprecated all ventilation.operating.programs.* features with a removal date of 2024-09-15 (already past due). Four methods in PyViCareVentilationDevice.py still use these deprecated paths:

• getVentilationPrograms() — queries ventilation.operating.programs.{program} (line 126)
• getActiveVentilationProgram() — reads ventilation.operating.programs.active (line 137)
• activateVentilationProgram() — sets ventilation.operating.programs.{program} (line 157)
• deactivateVentilationProgram() — sets ventilation.operating.programs.{program} (line 186)

Deprecated features

Feature	Removal date
ventilation.operating.programs.comfort	2024-09-15
ventilation.operating.programs.eco	2024-09-15
ventilation.operating.programs.silent	2024-09-15
ventilation.operating.programs.holiday	2024-09-15
ventilation.operating.programs.forcedLevelFour	2024-09-15
ventilation.operating.programs.levelOne..Four	2024-09-15

Viessmann provided no official migration info, but the replacement API appears to be ventilation.operating.modes.*, which is already present in test data for multiple devices:

• ventilation.operating.modes.active
• ventilation.operating.modes.standard
• ventilation.operating.modes.standby
• ventilation.operating.modes.ventilation
• ventilation.operating.modes.permanent
• ventilation.operating.modes.sensorDriven
• ventilation.operating.modes.filterChange

Found via the deprecation database (PR #707) and check_deprecations.py.

[lackas]

After looking at the test data more closely, this is not a simple path rename. The programs and modes APIs are conceptually different:

Programs (deprecated) represent fan speed levels with volume flow values:

ventilation.operating.programs.levelOne    → {active: bool, volumeFlow: 55 m³/h}
ventilation.operating.programs.levelTwo    → {active: bool, volumeFlow: 129 m³/h}
ventilation.operating.programs.levelThree  → {active: bool, volumeFlow: 185 m³/h}
ventilation.operating.programs.levelFour   → {active: bool, volumeFlow: 240 m³/h}
ventilation.operating.programs.standby     → {active: bool, volumeFlow: 0 m³/h}
ventilation.operating.programs.silent      → {active: bool, defaultRuntime, commands: [activate, deactivate]}
ventilation.operating.programs.forcedLevelFour → {active: bool, defaultRuntime, commands: [activate, deactivate]}
ventilation.operating.programs.active      → {value: "levelFour"}  (read-only current program)

Modes (replacement) represent operating modes with different control semantics:

ventilation.operating.modes.active         → {value: "sensorOverride", commands: [setMode]}
ventilation.operating.modes.ventilation    → {active: bool}
ventilation.operating.modes.permanent      → {active: bool, commands: [setLevel]}
ventilation.operating.modes.sensorDriven   → {active: bool}
ventilation.operating.modes.sensorOverride → {active: bool}
ventilation.operating.modes.filterChange   → {active: bool}
ventilation.operating.modes.standard       → (on some devices)
ventilation.operating.modes.standby        → (on some devices)

The current fan level is available in ventilation.operating.state:

ventilation.operating.state → {demand: "...", level: "levelFour", reason: "..."}

So the migration requires redesigning the ventilation control interface — you set a mode first (via modes.active setMode), then set a level within that mode (via modes.permanent setLevel). The affected methods would need new signatures, not just updated paths.

Data sourced from VitoairFs300E.json and Vitocal111S.json test fixtures.