From 9e55c585f989256f8a6d104a37b31ab267631c90 Mon Sep 17 00:00:00 2001 From: eigger Date: Wed, 9 Sep 2026 22:40:52 +0900 Subject: [PATCH] feat(door): add door_event event entity for pass-through timestamps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit door_status stays at the same value on every pass, so HA never moves last_changed and the logbook cannot show when the door was actually used. An event entity's state is the timestamp of the last occurrence, so a repeated event_type still updates it, and it is not restored across HA restarts — no stale "entering" coming back after a reboot. Both entities are derived from the same advertisement: door_status for the current state, door_event for when it happened. heartbeat: 60s lets the same event_type fire again after 60s, which is once per pass in practice. Also teach scripts/validate.py the event platform, mirroring the app's ConfigValidator rules: event_types required (error), map values missing from event_types, absent decode.map, numeric metadata, and a publish rule whose on_change_only suppresses repeats (warnings). The inherited publish rule (sensor > device > defaults) is now threaded down to sensor validation. Requires HassBle 1.5.0 or newer — event_types is a new key and older versions parse config.yaml in strict mode. Co-Authored-By: Claude Opus 5 --- README.ko.md | 2 +- README.md | 2 +- config.yaml | 20 +++++++++++++++++++ scripts/validate.py | 48 ++++++++++++++++++++++++++++++++++++++------- 4 files changed, 63 insertions(+), 9 deletions(-) diff --git a/README.ko.md b/README.ko.md index bf270bf..05200e0 100644 --- a/README.ko.md +++ b/README.ko.md @@ -409,7 +409,7 @@ obd: ```yaml sensors: - key: temperature # 필수 — 기기 내 고유 키 - platform: sensor # sensor | binary_sensor | text_sensor + platform: sensor # sensor | binary_sensor | text_sensor | event device_class: temperature # HA device_class (선택) unit: "°C" state_class: measurement # measurement | total | total_increasing diff --git a/README.md b/README.md index da3ca3a..4ab7ac9 100644 --- a/README.md +++ b/README.md @@ -360,7 +360,7 @@ Each item in the `sensors` list defines one HA entity. ```yaml sensors: - key: temperature # Required — unique key within the device - platform: sensor # sensor | binary_sensor | text_sensor + platform: sensor # sensor | binary_sensor | text_sensor | event device_class: temperature # HA device_class (optional) unit: "°C" state_class: measurement # measurement | total | total_increasing diff --git a/config.yaml b/config.yaml index 892d4bf..ea1041e 100644 --- a/config.yaml +++ b/config.yaml @@ -183,6 +183,26 @@ devices: "1": "entered" # 0x01 인증 완료 (entering과 동일 → 전환 노이즈 제거) "64": "exiting" # 0x40 "0": "idle" # 0x00 + # 통과 "시각"을 남기는 이벤트 엔티티 — 상태값이 마지막 발생 시각이라 같은 event_type이 + # 반복돼도 매번 갱신되고, HA 재시작 때 복원되지 않아 묵은 값이 되살아나지 않는다. + # door_status(현재 상태)와 병행: 같은 광고에서 두 엔티티를 뽑는다. + - key: door_event + platform: event + event_types: [entering, entered, exiting, idle] + icon: mdi:door-open + source_field: manufacturer_data + length: 6 + publish: + heartbeat: 60s # 같은 event_type이어도 60초 지났으면 재발화 = 통과마다 1회 + decode: + offset: 4 + length: 1 + type: uint8 + map: + "65": "entering" + "1": "entered" + "64": "exiting" + "0": "idle" # ────────────────────────────────────────────────────────────── # Path C: OBD (ELM327) over BLE diff --git a/scripts/validate.py b/scripts/validate.py index 26b5c78..8897ce1 100644 --- a/scripts/validate.py +++ b/scripts/validate.py @@ -13,7 +13,7 @@ import yaml VALID_SOURCES = {"advertisement", "gatt_notify", "obd"} VALID_INSTANCE_MODES = {"mac", "shared"} VALID_SOURCE_FIELDS = {"service_data", "manufacturer_data", "raw"} -VALID_PLATFORMS = {"sensor", "binary_sensor", "text_sensor"} +VALID_PLATFORMS = {"sensor", "binary_sensor", "text_sensor", "event"} VALID_DATA_TYPES = { "int8", "uint8", "int16", "uint16", "int32", "uint32", "float32", "timestamp", "string" @@ -61,7 +61,7 @@ KNOWN_ADVERTISE_PHASE_KEYS = { "state", "duration", "payload" } KNOWN_SENSOR_KEYS = { - "key", "name", "platform", "device_class", "unit", "state_class", "icon", + "key", "name", "platform", "event_types", "device_class", "unit", "state_class", "icon", "entity_category", "accuracy_decimals", "source_field", "length", "min_length", "decode", "preset", "mode", "pid", "formula", "update_interval", "pre_commands", "publish" @@ -148,7 +148,8 @@ def validate_decode(decode: Any, path: str, res: ValidationResult): res.error(f"{path}.map", "map must be a dictionary (key: value)") -def validate_sensor(sensor: Any, device_source: str, path: str, res: ValidationResult): +def validate_sensor(sensor: Any, device_source: str, path: str, res: ValidationResult, + inherited_publish: Optional[Dict[str, Any]] = None): if not isinstance(sensor, dict): res.error(path, "Sensor must be an object") return @@ -164,6 +165,7 @@ def validate_sensor(sensor: Any, device_source: str, path: str, res: ValidationR res.error(f"{path}.platform", f"Invalid platform '{platform}'. Must be one of {sorted(list(VALID_PLATFORMS))}") is_text = platform == "text_sensor" + is_event = platform == "event" unit = sensor.get("unit") state_class = sensor.get("state_class") if isinstance(state_class, str) and state_class.lower() == "none": @@ -171,7 +173,34 @@ def validate_sensor(sensor: Any, device_source: str, path: str, res: ValidationR device_class = sensor.get("device_class") accuracy_decimals = sensor.get("accuracy_decimals") - if is_text: + if is_event: + event_types = sensor.get("event_types") + if not isinstance(event_types, list) or not event_types: + res.error(f"{path}.event_types", + "platform=event requires a non-empty 'event_types' list — HA rejects the declaration without it") + event_types = [] + decode_map = (sensor.get("decode") or {}).get("map") + if isinstance(decode_map, dict): + undeclared = sorted({str(v) for v in decode_map.values()} - {str(t) for t in event_types}) + if undeclared: + res.warning(f"{path}.event_types", + f"decode.map value(s) {undeclared} missing from event_types — HA drops those events") + elif sensor.get("decode") is not None: + res.warning(f"{path}.decode", + "platform=event without decode.map — the raw decoded value becomes the event_type and will be dropped") + if unit is not None or state_class is not None or accuracy_decimals is not None: + res.warning(f"{path}.unit", "unit/state_class/accuracy_decimals are ignored for event") + if device_class in NUMERIC_DEVICE_CLASSES: + res.warning(f"{path}.device_class", + f"device_class='{device_class}' is numeric but platform is event — HA event supports doorbell/button/motion") + publish = sensor.get("publish", inherited_publish) or {} + heartbeat = publish.get("heartbeat") if isinstance(publish, dict) else None + on_change_only = publish.get("on_change_only", True) if isinstance(publish, dict) else True + if on_change_only and not (isinstance(heartbeat, str) and _DURATION_RE.match(heartbeat.strip())): + res.warning(f"{path}.publish", + "on_change_only suppresses repeats of the same event_type — " + "set publish.heartbeat (or on_change_only: false) to fire on every occurrence") + elif is_text: if unit is not None: res.warning(f"{path}.unit", f"unit='{unit}' is ignored for text_sensor") if state_class is not None: @@ -462,7 +491,8 @@ def validate_control(control: Any, device_source: str, gatt: Optional[dict], obd res.error(f"{path}.command", f"Select control missing command key for option '{opt}'") -def validate_device(device: Any, path: str, res: ValidationResult): +def validate_device(device: Any, path: str, res: ValidationResult, + defaults_publish: Optional[Dict[str, Any]] = None): if not isinstance(device, dict): res.error(path, "Device must be an object") return @@ -522,7 +552,8 @@ def validate_device(device: Any, path: str, res: ValidationResult): res.error(f"{path}.sensors", "sensors must be a list") else: for idx, s in enumerate(sensors): - validate_sensor(s, source, f"{path}.sensors[{idx}]", res) + validate_sensor(s, source, f"{path}.sensors[{idx}]", res, + device.get("publish", defaults_publish)) controls = device.get("controls", []) if not isinstance(controls, list): @@ -556,19 +587,22 @@ def validate_config_file(filepath: str) -> ValidationResult: if version != 1: res.warning("version", f"Schema version is {version}, expected 1") + defaults_publish: Optional[Dict[str, Any]] = None if "defaults" in data: defaults = data["defaults"] if not isinstance(defaults, dict): res.error("defaults", "defaults must be an object") elif "publish" in defaults: validate_publish(defaults["publish"], "defaults.publish", res) + if isinstance(defaults["publish"], dict): + defaults_publish = defaults["publish"] devices = data.get("devices", []) if not isinstance(devices, list): res.error("devices", "devices must be a list") else: for idx, dev in enumerate(devices): - validate_device(dev, f"devices[{idx}]", res) + validate_device(dev, f"devices[{idx}]", res, defaults_publish) return res