mirror of
https://github.com/cassandra/home-information.git
synced 2026-06-11 17:15:38 -04:00
9e3502312e
* Add EventClause operator dispatch and BATTERY_LEVEL low-battery alarm Implements phases 1-4 of #316: Phase 1 — Schema - New EventClauseOperator enum (EQ, LT, LTE, GT, GTE; default EQ). - New EventClause.value_operator_str field (default 'eq'); property + setter sourced from EventClauseOperator. - Migration 0008 with default 'eq' applies to every existing row; backward-compatible by construction. Phase 2 — Matching - EventManager._clause_matches() helper dispatches on the clause's operator. EQ is the historical string equality; LT / LTE / GT / GTE parse both sides as float() and silently no-op on parse failure so a transient malformed reading never raises into the matcher. - Single-line swap at the call site in _create_event_if_detected(). - Boundary tests (LT vs LTE off-by-one, GT vs GTE, non-numeric defensive case). Phase 3 — Factory plumbing - EventManager.create_simple_alarm_event_definition gains optional value_operator parameter (defaults to EQ); written to the clause. - HiModelHelper.create_battery_level_sensor mirrors the alarm-bearing factory pattern (smoke / moisture / CO / gas): with add_default_alarm=True it also wires the threshold alarm. - HiModelHelper.create_battery_level_event_definition with EventClauseOperator.LT, MAINTENANCE event type, INFO/INFO levels, 24-hour dedupe window, threshold default 20 percent. Phase 4 — HA wiring - HA converter's BATTERY_LEVEL branch now uses create_battery_level_sensor with add_default_alarm=add_alarm_events, so every imported `sensor + battery` device gains a low-battery alarm when the integration's add_alarm_events flag is on. Deferred to follow-up: Phase 5 (UI/form work for user-editable threshold clauses); Phase 6 (docs). Alert-grouping behavior (multiple alarms with the same event-type label sharing one Alert bucket) is by design for anti-fatigue; the deceptive Alert title when grouped is a separate UI concern. * Expose EventClause operator in the edit UI and document the pattern Phases 5-6 of #316. UI - EventClauseForm gains a required value_operator_str ChoiceField drawn from EventClauseOperator.choices (defaults to EQ). Form clean() rejects a non-numeric value when operator is non-EQ so users get immediate feedback instead of a clause that silently never fires. - Template adds an input-group for the operator dropdown between entity_state and value, matching the surrounding row pattern. - JS gains Hi.setEventClauseValueOperatorWidget: on operator change to LT / LTE / GT / GTE, swaps the value element to <input type="number" step="any"> preserving the entered value. EQ leaves the existing widget alone so the entity_state-driven choice swap stays authoritative for discrete-state clauses. - Admin's TabularInline picks up the new field automatically. - Existing event-view tests updated to include event-clause-0-value_operator_str='eq' in posted form data. Docs - Augment the existing "Default alarm wiring" section in integration-guidelines.md with one paragraph on the EventClauseOperator pattern for continuous-value thresholds and a pointer to create_battery_level_event_definition. Light touch on purpose; the existing section already covers the discrete pattern and the event-definition modal is slated for a separate UI overhaul. Closes #316. * Address review feedback: form validation test, debug log, template typo - Add focused test for EventClauseForm.clean(): non-numeric value with a numeric operator is rejected; numeric value is accepted. Closes the silent-failure path where a user could otherwise save a clause that never fires (matcher silently no-ops on non-numeric values under numeric operators). - Log threshold clause skips at DEBUG inside _clause_matches's except branch so a misconfigured clause is diagnosable. Kept at DEBUG so transient 'unknown' / 'unavailable' wire values don't spam at higher levels. - Fix pre-existing label for-attribute typo in event_clause_form.html (event_clause_form.entity.id_for_label → entity_state.id_for_label).
Developer Documentation
See the markdown files in this directory for various developer-related documentation.
The code is the best documentation for lower-level details, but there are some higher-level concepts that are useful to help orient developers. This is the place for that high-level, developer-specific documentation.