Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 20 additions & 20 deletions pyhap/resources/services.json
Original file line number Diff line number Diff line change
Expand Up @@ -127,9 +127,9 @@
"Name"
],
"RequiredCharacteristics": [
"StatusLowBattery",
"BatteryLevel",
"ChargingState"
"ChargingState",
"StatusLowBattery"
],
"UUID": "00000096-0000-1000-8000-0026BB765291"
},
Expand Down Expand Up @@ -227,12 +227,12 @@
"Name"
],
"RequiredCharacteristics": [
"SelectedRTPStreamConfiguration",
"SetupEndpoints",
"StreamingStatus",
"SupportedVideoStreamConfiguration",
"SupportedAudioStreamConfiguration",
"SupportedRTPConfiguration",
"SupportedVideoStreamConfiguration"
"SelectedRTPStreamConfiguration",
"StreamingStatus",
"SetupEndpoints"
],
"UUID": "00000110-0000-1000-8000-0026BB765291"
},
Expand Down Expand Up @@ -455,10 +455,10 @@
"WaterLevel"
],
"RequiredCharacteristics": [
"Active",
"CurrentRelativeHumidity",
"CurrentHumidifierDehumidifierState",
"TargetHumidifierDehumidifierState",
"CurrentRelativeHumidity"
"Active"
],
"UUID": "000000BD-0000-1000-8000-0026BB765291"
},
Expand All @@ -479,13 +479,13 @@
"OptionalCharacteristics": [
"Identifier",
"InputDeviceType",
"TargetVisibilityState"
"TargetVisibilityState",
"Name"
],
"RequiredCharacteristics": [
"ConfiguredName",
"InputSourceType",
"IsConfigured",
"Name",
"CurrentVisibilityState"
],
"UUID": "000000D9-0000-1000-8000-0026BB765291"
Expand Down Expand Up @@ -577,8 +577,8 @@
"Name"
],
"RequiredCharacteristics": [
"Mute",
"Volume"
"Volume",
"Mute"
],
"UUID": "00000112-0000-1000-8000-0026BB765291"
},
Expand Down Expand Up @@ -711,8 +711,8 @@
"TargetTiltAngle"
],
"RequiredCharacteristics": [
"CurrentSlatState",
"SlatType"
"SlatType",
"CurrentSlatState"
],
"UUID": "000000B9-0000-1000-8000-0026BB765291"
},
Expand Down Expand Up @@ -813,13 +813,13 @@
"TargetMediaState",
"Name",
"PictureMode",
"PowerModeSelection"
"PowerModeSelection",
"RemoteKey"
],
"RequiredCharacteristics": [
"Active",
"ActiveIdentifier",
"ConfiguredName",
"RemoteKey",
"SleepDiscoveryMode"
],
"UUID": "000000D8-0000-1000-8000-0026BB765291"
Expand Down Expand Up @@ -955,8 +955,8 @@
],
"RequiredCharacteristics": [
"CurrentPosition",
"PositionState",
"TargetPosition"
"TargetPosition",
"PositionState"
],
"UUID": "0000008B-0000-1000-8000-0026BB765291"
},
Expand All @@ -972,8 +972,8 @@
],
"RequiredCharacteristics": [
"CurrentPosition",
"PositionState",
"TargetPosition"
"TargetPosition",
"PositionState"
],
"UUID": "0000008C-0000-1000-8000-0026BB765291"
}
Expand Down
71 changes: 45 additions & 26 deletions scripts/gen_hap_types.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down
1 change: 1 addition & 0 deletions scripts/hap_manual_overrides.json
Original file line number Diff line number Diff line change
Expand Up @@ -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:",
Expand Down
122 changes: 122 additions & 0 deletions tests/test_gen_hap_types.py
Original file line number Diff line number Diff line change
@@ -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
55 changes: 55 additions & 0 deletions tests/test_loader.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading