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