Skip to content

feat: entity platforms and services (Milestone 2) - #2

Merged
ant1fr merged 6 commits into
mainfrom
feat/entities
Nov 20, 2026
Merged

ant1fr merged 6 commits into
mainfrom
feat/entities

Conversation

@ant1fr

@ant1fr ant1fr commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Summary

Milestone 2: the entity platforms and services, built on the foundation and grounded in the Smart Frame Engine API contract v1.1 (docs/API_CONTRACT.md and docs/openapi.json on upstream main, unchanged since the foundation PR).

Platforms (one device per engine; optional ones appear only when the engine advertises the capability, and are rebuilt automatically if the engine's capabilities change after an update):

Platform Entities
Binary sensor engine connected, frame online, frame charging, image pending delivery, temporary image, quiet hours
Sensor engine version, image source, refresh mode (enum), media title (+ image metadata attributes), ambient context summary (ambient_context), last delivery, frame last seen, frame battery, Wi-Fi signal (disabled by default)
Switch Family Mode (family_mode): reads config.family.enabled, toggles with PUT /api/config then refreshes
Button Refresh image (force_refresh), Wake up frame (frame_wakeup)
Image current frame image: /api/current.jpg, falling back to /api/preview.jpg on 404, cached until sha256/processed_at change

Services (registered from async_setup; each checks the capability before sending anything and raises a translated ServiceValidationError): set_ambient_context and clear_ambient_context (ambient_context), send_title_card (title_card). Limits come from openapi.json (1..10080 minutes, 20 list items, 80/200 characters).

Translations (strings.json, en.json, fr.json) cover entity names, states, services, selectors and exceptions, and a test enforces en/fr key and placeholder parity and that services.yaml, the schemas and the translations agree.

Decisions worth a look

  1. Grounding corrections to the request. The contract defines no "photographer/album" fields: image metadata is source, template, ephemeral, pushed, processed_at, expires_at and a free-form details object, so those are what is exposed. "Active source / mode" is current_image.source plus scheduler.active_rule.source (pinned|smart_mix|last, an enum sensor). ttl_minutes: null ("until cancelled") for title cards is not exposed: omitting it applies the engine's 60-minute default.

  2. Privacy. details can contain people and places. It is visible on the media title sensor but excluded from the recorder (_unrecorded_attributes), and diagnostics now redact details, presence and boost_people.

  3. The "Engine connected" sensor stays available while the engine is down (it reports off instead of going unavailable); everything else goes unavailable.

  4. Services target an engine with an optional config_entry_id (optional when only one is configured) rather than target:. The helper that resolves device targets changed signature across HA versions, and the 2026.1.0 minimum matters.

  5. Version compatibility checked against the HA 2026.1.0 wheel: BinarySensorDeviceClass has no const module there, so it is imported from the package (with a narrow type-checker ignore).

  6. Foundation fixture correction: the foundation tests used an invented telemetry shape; fixed to the real FrameTelemetry/FrameInfo schema (info.battery_percent, ...).

  7. A 401 while pressing a button or calling a service starts reauthentication, not just an error.

  8. Engine rc.3 / contract 1.2 (additive, api_version still 1): the engine version sensor and the device sw_version show status.release (1.0.0-rc.3, matching the git/Docker tag) and fall back to the PEP 440 health.version on older engines. The new smart_mix_kinds capability flag is known (19 flags); nothing else is used.

Verification

Fresh Linux clone of this branch (Python 3.14, HA 2026.10.4):

  • ruff check .: passed
  • ruff format --check .: passed
  • mypy custom_components: passed (strict)
  • pytest: 204 passed (203 before the rc.3 follow-up; the 4-run and per-test-isolation sweeps were done on the 203) (this found and fixed two order-dependent tests)
  • Mutation checks: 12 deliberate breakages (skipped capability checks, no caching, no preview fallback, wrong source for the switch, no reload on capability change, leaking details, ...) are each caught by a test.

Not verified locally: hassfest and HACS run in CI only. Also not exercised against a real engine: all HTTP is mocked from the contract's schemas.

🤖 Generated with Claude Code

ant1fr and others added 6 commits November 19, 2026 15:43
- api: typed frame telemetry (online, battery, charging, rssi, firmware,
  last seen), last delivery details, active refresh rule, image identity
  (sha256 + processed_at) and provider details; naive timestamps are UTC
- coordinator: fetch GET /api/config when the family_mode capability is
  advertised, expose async_action (maps engine errors to translated
  HomeAssistantError / ServiceValidationError and starts reauth on 401),
  and reload the entry when the engine's capability set changes
- diagnostics: redact image details, presence and boost_people (personal
  data) and add family_enabled

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Platforms (capability-gated where the contract defines a flag):
- binary_sensor: engine connected, frame online/charging, delivery pending,
  temporary image, quiet hours
- sensor: engine version, image source, refresh mode (enum), media title,
  ambient context summary (ambient_context), last delivery, frame last
  seen, battery, Wi-Fi signal
- switch: Family Mode (family_mode), reads config.family.enabled
- button: refresh image (force_refresh), wake up frame (frame_wakeup)
- image: current frame image, cached until sha256/processed_at changes,
  falling back to /api/preview.jpg on 404

Services, registered once from async_setup, each checking the engine's
capability and raising a translated ServiceValidationError when missing:
set_ambient_context, clear_ambient_context (ambient_context) and
send_title_card (title_card).

Translations (strings.json, en, fr) cover entities, states, services,
selectors and the new exceptions.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Per-platform tests (states, attributes, categories, availability), image
caching / 404 fallback / change detection, service payloads, schema limits,
capability and target validation, engine error mapping and reauth, entry
reload on capability change, diagnostics redaction, and consistency checks
between services.yaml, the schemas and the translations.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- wait (bounded) for a timer-driven setup instead of relying on
  async_block_till_done, which returns before the first off-loop import of
  a platform's dependencies finishes
- import integration modules at module level in test_metadata so they
  resolve before the test plugin registers its own custom_components

Every test now also passes when run alone in its own process.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Show status.release (the git/Docker tag spelling) for the engine version
and the device sw_version, falling back to the PEP 440 health version on
older engines. Know the new smart_mix_kinds capability flag.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@ant1fr
ant1fr merged commit b6288ec into main Nov 20, 2026
3 checks passed
@ant1fr
ant1fr deleted the feat/entities branch November 20, 2026 08:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant