From 8b80d61f5a5540990b66e2328b155799fef6c8ce Mon Sep 17 00:00:00 2001 From: Raphael Hehl <7577984+RaHehl@users.noreply.github.com> Date: Tue, 17 Nov 2026 11:00:42 +0100 Subject: [PATCH] Keep the required characteristics of existing services stable in the catalog The catalog regenerated from plain-metadata.config lists the required characteristics of seven services in another order and lists Name on InputSource and RemoteKey on Television as required. Services instantiate required characteristics in list order, so existing accessories with the default IIDManager got new instance IDs, which HAP requires to stay stable for a pairing. services.json is edited by hand back to the 5.2.0 required lists, so a macOS dry run of the generator should report no changed services. The generator now keeps the previous required list of an existing service in order, adds characteristics the metadata lists as required beyond it as optional, and reports such differences. --- pyhap/resources/services.json | 40 +++++----- scripts/gen_hap_types.py | 71 ++++++++++------- scripts/hap_manual_overrides.json | 1 + tests/test_gen_hap_types.py | 122 ++++++++++++++++++++++++++++++ tests/test_loader.py | 55 ++++++++++++++ 5 files changed, 243 insertions(+), 46 deletions(-) create mode 100644 tests/test_gen_hap_types.py diff --git a/pyhap/resources/services.json b/pyhap/resources/services.json index 46420901..f884bc09 100644 --- a/pyhap/resources/services.json +++ b/pyhap/resources/services.json @@ -127,9 +127,9 @@ "Name" ], "RequiredCharacteristics": [ - "StatusLowBattery", "BatteryLevel", - "ChargingState" + "ChargingState", + "StatusLowBattery" ], "UUID": "00000096-0000-1000-8000-0026BB765291" }, @@ -227,12 +227,12 @@ "Name" ], "RequiredCharacteristics": [ - "SelectedRTPStreamConfiguration", - "SetupEndpoints", - "StreamingStatus", + "SupportedVideoStreamConfiguration", "SupportedAudioStreamConfiguration", "SupportedRTPConfiguration", - "SupportedVideoStreamConfiguration" + "SelectedRTPStreamConfiguration", + "StreamingStatus", + "SetupEndpoints" ], "UUID": "00000110-0000-1000-8000-0026BB765291" }, @@ -455,10 +455,10 @@ "WaterLevel" ], "RequiredCharacteristics": [ - "Active", + "CurrentRelativeHumidity", "CurrentHumidifierDehumidifierState", "TargetHumidifierDehumidifierState", - "CurrentRelativeHumidity" + "Active" ], "UUID": "000000BD-0000-1000-8000-0026BB765291" }, @@ -479,13 +479,13 @@ "OptionalCharacteristics": [ "Identifier", "InputDeviceType", - "TargetVisibilityState" + "TargetVisibilityState", + "Name" ], "RequiredCharacteristics": [ "ConfiguredName", "InputSourceType", "IsConfigured", - "Name", "CurrentVisibilityState" ], "UUID": "000000D9-0000-1000-8000-0026BB765291" @@ -577,8 +577,8 @@ "Name" ], "RequiredCharacteristics": [ - "Mute", - "Volume" + "Volume", + "Mute" ], "UUID": "00000112-0000-1000-8000-0026BB765291" }, @@ -711,8 +711,8 @@ "TargetTiltAngle" ], "RequiredCharacteristics": [ - "CurrentSlatState", - "SlatType" + "SlatType", + "CurrentSlatState" ], "UUID": "000000B9-0000-1000-8000-0026BB765291" }, @@ -813,13 +813,13 @@ "TargetMediaState", "Name", "PictureMode", - "PowerModeSelection" + "PowerModeSelection", + "RemoteKey" ], "RequiredCharacteristics": [ "Active", "ActiveIdentifier", "ConfiguredName", - "RemoteKey", "SleepDiscoveryMode" ], "UUID": "000000D8-0000-1000-8000-0026BB765291" @@ -955,8 +955,8 @@ ], "RequiredCharacteristics": [ "CurrentPosition", - "PositionState", - "TargetPosition" + "TargetPosition", + "PositionState" ], "UUID": "0000008B-0000-1000-8000-0026BB765291" }, @@ -972,8 +972,8 @@ ], "RequiredCharacteristics": [ "CurrentPosition", - "PositionState", - "TargetPosition" + "TargetPosition", + "PositionState" ], "UUID": "0000008C-0000-1000-8000-0026BB765291" } diff --git a/scripts/gen_hap_types.py b/scripts/gen_hap_types.py index 2477baad..58ef84c5 100755 --- a/scripts/gen_hap_types.py +++ b/scripts/gen_hap_types.py @@ -75,11 +75,17 @@ committed catalog for a given UUID (Apple's descriptions drift over time, e.g. "CarbonDioxideDetected" vs "Carbon dioxide Detected", "Slat" vs "Slats"). New UUIDs get a name derived from the description. -- SERVICES: pyhap's Service() auto-instantiates the REQUIRED characteristics - at runtime, so a required->optional demotion in Apple's metadata would - silently strip characteristics from existing accessories. Required stays - Required, Optional lists only ever grow; deliberate removals must go - through serviceOverrides. +- SERVICES: Loader.get_service() (through Service.from_dict()) instantiates + the REQUIRED characteristics in list order, and the default IIDManager + numbers them in that order. Any change to the Required list of an existing + service would strip characteristics from existing accessories or shift + their instance IDs, which HAP requires to stay stable for a pairing. So an + existing service keeps its previous Required list in order, minus + characteristics that no longer exist, and a characteristic the metadata + lists as required beyond it becomes Optional; a differing Required list in + the metadata is reported. Optional lists only ever grow. New services take + Apple's lists as they are. serviceOverrides and serviceAdditions still + replace whole entries; deliberate removals must go through them. - VALID VALUES: when a characteristic has enumerated ValidValues, the numeric min/max/step constraints are dropped. HAP-python clamps values to min/max BEFORE checking ValidValues, so keeping both would turn invalid values into @@ -438,32 +444,45 @@ def resolve(slug_c: str) -> str | None: ) # COMPATIBILITY INHERITANCE from the previously generated catalog: - # pyhap's Service() auto-instantiates the REQUIRED characteristics at - # runtime, so a required->optional demotion in Apple's metadata would - # silently remove characteristics from existing accessories. Apple - # occasionally does this (e.g. FirmwareRevision on AccessoryInformation) - # while the HAP specification still lists them as required. Rule: - # - a characteristic that was Required stays Required; - # - a characteristic that was Optional stays Optional (allowed lists - # only ever grow). + # Loader.get_service() instantiates the REQUIRED characteristics in + # list order and the default IIDManager numbers them in that order, so + # any change to an existing Required list removes characteristics from + # accessories or shifts their instance IDs, which must stay stable for + # a pairing. The metadata lists some required characteristics + # differently from the committed catalog: in another order, as + # optional (e.g. FirmwareRevision on AccessoryInformation) or an + # optional one as required. Rule: + # - the previous Required list is kept in order, minus + # characteristics that no longer exist; + # - a characteristic that was Optional, or that the metadata lists as + # required beyond that list, is Optional (allowed lists only grow). # Genuine removals must be done explicitly via a serviceOverride entry - # in the manual overrides file. + # in the manual overrides file, which replaces the whole entry. prev = existing_services.get(name) if prev and prev.get("UUID") == entry["UUID"]: - # Required characteristics that were demoted to Optional by Apple - # are re-promoted to Required. - for c in prev.get("RequiredCharacteristics", []): - if c not in characteristics or c in entry["RequiredCharacteristics"]: - continue - entry["RequiredCharacteristics"].append(c) - if c in entry["OptionalCharacteristics"]: - entry["OptionalCharacteristics"].remove(c) - # Optional characteristics that were dropped entirely are re-added - # (the allowed list only ever grows). - for c in prev.get("OptionalCharacteristics", []): + apple_required = entry["RequiredCharacteristics"] + required = [ + c + for c in prev.get("RequiredCharacteristics", []) + if c in characteristics + ] + if required != apple_required: + print( + f" ! service {name}: keeping required {required} " + f"(metadata says {apple_required})", + file=sys.stderr, + ) + entry["RequiredCharacteristics"] = required + entry["OptionalCharacteristics"] = [ + c for c in entry["OptionalCharacteristics"] if c not in required + ] + # Optional characteristics the metadata dropped are re-added, then + # the ones it lists as required beyond the kept list; in this order + # a rerun reproduces the committed list. + for c in prev.get("OptionalCharacteristics", []) + apple_required: if ( c in characteristics - and c not in entry["RequiredCharacteristics"] + and c not in required and c not in entry["OptionalCharacteristics"] ): entry["OptionalCharacteristics"].append(c) diff --git a/scripts/hap_manual_overrides.json b/scripts/hap_manual_overrides.json index 2e86af94..e367e850 100644 --- a/scripts/hap_manual_overrides.json +++ b/scripts/hap_manual_overrides.json @@ -14,6 +14,7 @@ "Apple ships them again. NOTE: the generator never removes a required or", "optional characteristic from an existing service - demotions in Apple's", "metadata are ignored by design; use serviceOverrides to remove one deliberately.", + "An existing required list also keeps its order; extra required ones become optional.", "", "characteristicOverrides also carries deliberate corrections of Apple's", "plain-metadata.config, mirroring HAP-NodeJS's CharacteristicOverriding:", diff --git a/tests/test_gen_hap_types.py b/tests/test_gen_hap_types.py new file mode 100644 index 00000000..834ed0f6 --- /dev/null +++ b/tests/test_gen_hap_types.py @@ -0,0 +1,122 @@ +"""Tests for the catalog generator in scripts/gen_hap_types.py.""" + +import pytest + +from scripts.gen_hap_types import ServiceCatalog, ServiceEntry, generate_services + +UUID = "0000008C-0000-1000-8000-0026BB765291" +CHARS = ( + "CurrentPosition", + "HoldPosition", + "Name", + "ObstructionDetected", + "PositionState", + "TargetPosition", +) +REQUIRED = ["CurrentPosition", "TargetPosition", "PositionState"] + + +def _service(required: list[str], optional: list[str]) -> ServiceEntry: + return { + "OptionalCharacteristics": optional, + "RequiredCharacteristics": required, + "UUID": UUID, + } + + +EXISTING = {"WindowCovering": _service(REQUIRED, ["Name"])} + + +def _generate( + required: list[str], + optional: list[str], + existing: ServiceCatalog, + description: str = "Window Covering", +) -> ServiceCatalog: + meta = { + "window-covering": { + "Characteristics": {"Optional": optional, "Required": required}, + "DefaultDescription": description, + "ShortUUID": "0000008C", + } + } + return generate_services( + meta, {c: {} for c in CHARS}, {}, {}, {c: c for c in CHARS}, existing + ) + + +@pytest.mark.parametrize( + ("apple_required", "apple_optional", "optional"), + [ + pytest.param( + ["CurrentPosition", "PositionState", "TargetPosition"], + ["Name"], + ["Name"], + id="reordered", + ), + pytest.param( + ["CurrentPosition", "TargetPosition", "PositionState", "Name"], + [], + ["Name"], + id="promoted", + ), + pytest.param( + [ + "ObstructionDetected", + "CurrentPosition", + "TargetPosition", + "PositionState", + ], + ["Name"], + ["Name", "ObstructionDetected"], + id="new-required", + ), + pytest.param( + ["CurrentPosition", "PositionState"], + ["Name", "TargetPosition"], + ["Name"], + id="demoted", + ), + ], +) +def test_generate_services_keeps_required( + apple_required: list[str], apple_optional: list[str], optional: list[str] +) -> None: + """Test an existing service keeps its required list and order.""" + catalog = _generate(apple_required, apple_optional, EXISTING) + assert catalog == {"WindowCovering": _service(REQUIRED, optional)} + + +def test_generate_services_renamed_service() -> None: + """Test a service the metadata renames keeps its name and required list.""" + apple_required = ["CurrentPosition", "PositionState", "TargetPosition"] + catalog = _generate(apple_required, ["Name"], EXISTING, "Window Coverings") + assert catalog == {"WindowCovering": _service(REQUIRED, ["Name"])} + + +def test_generate_services_new_service() -> None: + """Test a new service takes Apple's lists as they are.""" + catalog = _generate(["PositionState", "CurrentPosition"], ["Name"], {}) + expected = _service(["PositionState", "CurrentPosition"], ["Name"]) + assert catalog == {"WindowCovering": expected} + + +@pytest.mark.parametrize( + ("apple_required", "report"), + [ + pytest.param(REQUIRED, "", id="same"), + pytest.param( + [*REQUIRED, "Name"], + " ! service WindowCovering: keeping required ['CurrentPosition', " + "'TargetPosition', 'PositionState'] (metadata says ['CurrentPosition', " + "'TargetPosition', 'PositionState', 'Name'])\n", + id="promoted", + ), + ], +) +def test_generate_services_reports_required( + capsys: pytest.CaptureFixture[str], apple_required: list[str], report: str +) -> None: + """Test a required list the metadata lists differently is reported.""" + _generate(apple_required, [], EXISTING) + assert capsys.readouterr().err == report diff --git a/tests/test_loader.py b/tests/test_loader.py index a38f1426..d7a950b6 100644 --- a/tests/test_loader.py +++ b/tests/test_loader.py @@ -254,3 +254,58 @@ def test_loader_camera_operating_mode_permissions( """Test the operating mode settings shared with the HKSV 17.99 services.""" char = Loader().get_char(name) assert set(char.properties[PROP_PERMISSIONS]) == permissions + + +# Required characteristics of existing services as shipped up to 5.2.0. A +# service instantiates them in this order and the default IIDManager numbers +# them in that order, so it must not change for existing pairings. +STABLE_REQUIRED = { + "BatteryService": ["BatteryLevel", "ChargingState", "StatusLowBattery"], + "CameraRTPStreamManagement": [ + "SupportedVideoStreamConfiguration", + "SupportedAudioStreamConfiguration", + "SupportedRTPConfiguration", + "SelectedRTPStreamConfiguration", + "StreamingStatus", + "SetupEndpoints", + ], + "HumidifierDehumidifier": [ + "CurrentRelativeHumidity", + "CurrentHumidifierDehumidifierState", + "TargetHumidifierDehumidifierState", + "Active", + ], + "InputSource": [ + "ConfiguredName", + "InputSourceType", + "IsConfigured", + "CurrentVisibilityState", + ], + "Microphone": ["Volume", "Mute"], + "Slat": ["SlatType", "CurrentSlatState"], + "Television": [ + "Active", + "ActiveIdentifier", + "ConfiguredName", + "SleepDiscoveryMode", + ], + "Window": ["CurrentPosition", "TargetPosition", "PositionState"], + "WindowCovering": ["CurrentPosition", "TargetPosition", "PositionState"], +} + + +@pytest.mark.parametrize("name", STABLE_REQUIRED) +def test_loader_service_required_stable(name: str) -> None: + """Test existing services keep their required chars and order.""" + service = Loader().get_service(name) + chars = [char.display_name for char in service.characteristics] + assert chars == STABLE_REQUIRED[name] + + +@pytest.mark.parametrize( + ("name", "char_name"), [("InputSource", "Name"), ("Television", "RemoteKey")] +) +def test_loader_service_newly_required_optional(name: str, char_name: str) -> None: + """Test chars only the metadata lists as required stay optional.""" + optional = Loader().serv_types[name]["OptionalCharacteristics"] + assert char_name in optional