feat(cec): rewrite HDMI-CEC on the kernel uABI, fix passthrough, add a display schedule

[vpetersson-bot]

Issues Fixed

Fixes #3267 (display power permanently CEC error on mainline-KMS Pis) and closes #1178 (scheduled display power). Supersedes #3273, which fixed a subset of the passthrough problem.

⚠️ Read this first

This cannot be verified end to end: no testbed has a CEC-capable display. See "What I could not verify". It no longer changes device passthrough at all — see below.

Description

Rewrites HDMI-CEC on the kernel CEC uABI (/dev/cec*), moves the hardware access into the viewer so balena is supported, and adds a scheduled display on/off.

Why not libcec. Measured on the Pi 5 testbed, libcec 7.0.0 enumerates the kernel adapter as com port Linux and treats a positional /dev/cecN as a Pulse-Eight serial port. cec-client -s -d 1 -p 1 /dev/cec1 fails with Couldn't lock the serial port after 11.07 s, having transmitted nothing. Autodetect works (3.2 s) but picks whichever adapter it finds first — a coin toss on a board with two HDMI outputs. It also collapses "no adapter", "no HDMI link" and "display present but not CEC-capable" into one error, which is what made #3267 unactionable.

The kernel API answers both questions directly, with no dependency at all.

Fleet probe (CEC_ADAP_G_CAPS / G_PHYS_ADDR / G_CONNECTOR_INFO, all 0.0–0.1 ms):

Board	nodes	driver	phys addr	DRM connector
Pi 2 armhf	cec0	vc4_hdmi	1.0.0.0 live	card0/35
Pi 3 A+ armhf	cec0	vc4_hdmi	f.f.f.f	card0/35
Pi 3 B+ arm64	cec0	vc4_hdmi	f.f.f.f	card0/35
Pi 4 arm64	cec0, cec1	vc4_hdmi-0/-1	f.f.f.f ×2	card1/35, card1/44
Pi 5 arm64	cec0, cec1	vc4_hdmi-0/-1	1.0.0.0 live, f.f.f.f	card1/35, card1/44
Rock Pi 4	cec0	dwhdmi-rockchip	f.f.f.f	card0/54
x86	none	—	—	—

Two things this settles: the "Pi 1-4 uses vchiq closed firmware" premise is dead (the Pi 2 runs vc4_hdmi with a live CEC link while its containers get only /dev/vchiq), and adapter→HDMI-port mapping is discoverable, so nothing needs to hardcode /dev/cec0.

What changed

• New lib/cec.py — pure stdlib ioctl; no subprocess, no native library, no core-dump workaround. Every operation fans out across all adapters with a live link, because a device can have two monitors attached and powering down only the first would leave the other lit.

• diagnostics.py — the CEC half is now a thin translation layer; the str | bool values the v2 /info API exposes are deliberately unchanged.

• libcec removed — cec==0.2.8, libcec7, cec-utils, libcec-dev.

• The viewer owns the hardware, so balena works. /dev/cec* is reachable from the viewer container on every board and every deployment, because it is privileged: true in all three compose templates. anthias-server and anthias-celery ask it over the existing Redis request-reply bus (lib/cec_client.py) — the same mechanism the v1 current_asset_id endpoint uses.

  Device passthrough cannot support balena: the compose file is baked into the release from a workstation, nothing on-device can enumerate the host's adapters, and a statically listed node that turns out to be absent stops the container from starting. Routing through the viewer means no devices: entries are needed for server/celery on any board, which also deletes the OTA-upgrade risk an earlier revision of this PR carried, along with the $DEVICE_TYPE case that left pi2/pi3/pi3-64/pi4-64 on a useless vchiq.

• New lib/display_power.py + a per-minute beat task — daily on/off schedule with day-of-week selection, sending CEC and the viewer's local blank/unblank so it works on plain monitors too.

• Settings UI + v2 API. A "Display schedule" section reusing the .weekday-picker pill chips the asset and bulk-edit modals already use for choosing days, so both places in the product that pick weekdays look identical. DeviceSettingsViewV2 GET/PATCH expose the same four fields, since it and the HTML form are documented mirrors — with validators that normalise HH:MM and the weekday list so the beat can never read something unparsable. The API returns 400 on a bad value rather than the form's keep-previous-and-toast: a client that explicitly sent a field should be told it was wrong.

Bugs found while building this. On hardware: a failed logical-address claim surfaced as "no peer" (reintroducing #3267's conflation); and CEC_ADAP_S_LOG_ADDRS returns EBUSY on an already-configured adapter, which libcec leaves behind after every probe — without the clear-first fix, CEC would have failed on every device upgrading from the libcec build while passing every test.

In review: the adapter claimed LA 5 (Audio System) instead of LA 4, because CEC_LOG_ADDR_TYPE_PLAYBACK is 3 (not 4) and CEC_OP_ALL_DEVTYPE_PLAYBACK is 0x10 (not 0x08) — three constants from different enumerations in linux/cec.h. A TV seeing an audio system appear commonly enables ARC and mutes its own speakers. Also: concurrent CEC users trampled each other (now serialised, with CecBusyError so the scheduler retries instead of latching — an in-process mutex suffices since only the viewer drives the hardware), and the scheduler's state key outlived the viewer's in-process blank flag (now expires, so a viewer restart mid-off-period can't leave the screen lit until morning).

Device testing

lib/cec.py overlaid alone (md5-matched to the commit) into the real server container:

Board	result
Pi 5	2 adapters, correct connector mapping, live=[cec0], no-peer in 606 ms; claims LA 4, mask 0x0010 (matches cec-ctl --playback)
Rock Pi 4	1 adapter, no-link, 0 ms
Pi 4	no node in container, no-adapter, 0 ms
x86	no CEC hardware, no-adapter, 0 ms

End to end through the Redis bus, overlaying the branch onto both containers and restarting the viewer:

Board	result
Pi 4	anthias-server has no /dev/cec* at all; cec_available() True, get_display_power() → 'No CEC display detected' in 79 ms. Viewer logged CEC: 2 adapter(s) present: /dev/cec0 (f.f.f.f), /dev/cec1 (f.f.f.f). This is the balena situation exactly.
Pi 5	live link; real transmits at 430 ms — identical to direct device access, so the bus hop costs nothing. Correct not acknowledged message from the non-CEC monitor.
Pi 2	viewer reports a live 1.0.0.0 physical address and transmits in 465 ms. That board could never have worked through the server.

Overlay provenance: the pinned testbed images are fbe83e9, older than this branch's base, so the overlay of src/anthias_viewer/__init__.py and diagnostics.py also carried the unrelated changes from #3224, #3240, #3271 and #3272 to those files. Both containers were restored to the pinned image afterwards and verified clean.

What I could not verify

• No CEC-capable display exists in the fleet — every rig is a desktop monitor that NACKs. Enumeration, adapter selection, link detection, NACK handling, EBUSY recovery, logical-address claim and timing are measured on real hardware; an actual TV powering on or off is not.
• No real OTA upgrade was run, and no balena device was available. The design needs no device wiring, so an upgrade cannot fail on a missing node any more, but the balena path itself is unexercised — CEC there rests on privileged: true granting /dev/cec*, which is verified on the docker-compose path and is the same container flag balena honours.
• CEC now depends on the viewer being up. A crash-looping viewer makes display power report an error. That was already true of the local blank/unblank fallback, and a wedged viewer is a much louder problem than display power.
• USB CEC dongles are untested. A Pulse-Eight adapter should bind pulse8-cec and appear as a normal /dev/cecN, but no dongle was available — this is the one place dropping libcec carries real risk.

Documentation

website/content/docs/display-schedule.md — a new user-facing page covering what actually reaches the screen (CEC and local blanking, so a plain monitor is not left lit), the field reference with defaults, the overnight-window semantics (an on-period belongs to the day it starts), the v2 API path, and the ~10-minute re-assertion that overrides a manual toggle. It also flags the weekday-numbering mismatch against asset scheduling — Mon=0 here, Mon=1 in play_days — which the UI hides behind identical day chips but an API client hits directly. Cross-linked from the asset-scheduling page.

Checklist

• I have performed a self-review of my own code.
• New and existing unit tests pass locally and on CI with my changes.
• I have done an end-to-end test for Raspberry Pi devices.
• I have tested my changes for x86 devices.
• I added a documentation for the changes I have made (when necessary).

The two device boxes are deliberately unticked, despite the integrated run above. The full software path was exercised on real Pi hardware — real anthias-server process → real Redis bus → real viewer service → real CEC adapter — but the thing the feature exists to do, a display actually powering on and off, cannot be observed without a CEC-capable TV, and no OTA upgrade or balena device was available.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 87.66603% with 65 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (master@8de6fe7). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/anthias_server/lib/cec.py	76.36%	63 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##             master    #3277   +/-   ##
=========================================
  Coverage          ?   90.49%           
=========================================
  Files             ?       79           
  Lines             ?     8932           
  Branches          ?      950           
=========================================
  Hits              ?     8083           
  Misses            ?      626           
  Partials          ?      223           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR rewrites Anthias’ HDMI-CEC integration to use the Linux kernel CEC uABI (/dev/cec* via ioctl) and moves hardware access into the viewer service, enabling CEC on deployments where the server/celery containers cannot access device nodes (notably balena). It also introduces a scheduled display on/off feature (with local blanking fallback) plus UI, API, docs, and tests.

Changes:

• Replace libcec-based subprocess probing with a pure-stdlib kernel CEC implementation and a server→viewer Redis request/reply client.
• Add a daily display power schedule (weekday selection + overnight semantics), exposed in Settings UI and the v2 device-settings API, backed by a per-minute Celery task.
• Remove libcec dependencies and device passthrough wiring from compose templates and upgrade/deploy scripts.

Reviewed changes

Copilot reviewed 32 out of 36 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
website/content/docs/display-schedule.md	Adds user documentation for the new display schedule and its semantics.
website/content/docs/asset-scheduling.md	Cross-links asset scheduling docs to the new display schedule docs.
uv.lock	Removes the cec (libcec Python wrapper) dependency from lockfile groups.
tools/image_builder/utils.py	Drops libcec build/runtime dependency references in image builder context.
tools/image_builder/main.py	Removes cec-utils/libcec7 from base apt deps and documents the new kernel-uABI approach.
tests/test_template_views.py	Extends settings-page tests for display schedule rendering and form round-trips; uses shared isolated-conf fixture.
tests/test_display_power.py	Adds unit tests for schedule parsing, on/off decision logic, and application behavior (CEC + blanking).
tests/test_diagnostics.py	Updates diagnostics tests for the new CEC status mapping and viewer-mediated behavior.
tests/test_celery_tasks.py	Adds Celery task tests for the per-minute display schedule tick and its Redis state/TTL behavior.
tests/test_cec.py	Adds tests for kernel CEC uABI constants, adapter behavior, aggregation, and bus locking.
tests/test_cec_client.py	Adds tests for the server→viewer CEC request/reply client and availability fact key.
tests/test_app.py	Updates integration tests/fixtures to skip CEC UI checks without real hardware (no more fake /dev/vchiq).
src/anthias_viewer/init.py	Implements viewer-side CEC command handlers and publishes CEC availability to Redis at startup.
src/anthias_server/settings.py	Adds persisted settings defaults for display schedule fields.
src/anthias_server/lib/display_power.py	Implements schedule parsing/decision logic and applies power via local blanking + viewer-driven CEC.
src/anthias_server/lib/diagnostics.py	Replaces libcec subprocess logic with a mapping layer over the new kernel/uABI + viewer client.
src/anthias_server/lib/cec.py	Introduces the pure-stdlib kernel CEC ioctl implementation with adapter fan-out and bus serialization.
src/anthias_server/lib/cec_client.py	Adds the server-side Redis request/reply client to invoke viewer-owned CEC operations and read availability.
src/anthias_server/celery_tasks.py	Adds a per-minute Celery beat task to enforce the display schedule and updates display-power polling behavior.
src/anthias_server/app/views.py	Persists display schedule fields from the settings form with normalization and validation.
src/anthias_server/app/templates/settings.html	Adds the “Display schedule” section UI (toggle, times, weekday picker).
src/anthias_server/app/static/sass/_styles.scss	Makes weekday chips keyboard/screen-reader accessible (visually-hidden inputs + focus ring).
src/anthias_server/app/page_context.py	Provides schedule fields and weekday options to the settings template; parses stored day list consistently.
src/anthias_server/api/views/v2.py	Exposes schedule fields via GET/PATCH on the v2 device-settings endpoint.
src/anthias_server/api/views/mixins.py	Updates display-power endpoint fast-fail comment to match new “no adapter” semantics.
src/anthias_server/api/tests/test_v2_endpoints.py	Adds v2 API tests for schedule fields and validation behavior.
src/anthias_server/api/serializers/v2.py	Adds schedule fields and validators (time normalization and weekday list validation).
pyproject.toml	Removes cec dependency and mypy ignore entry for that module.
docker-compose.yml.tmpl	Removes /dev/vchiq passthrough; documents viewer-owned CEC model.
docker-compose.balena.yml.tmpl	Removes /dev/vchiq passthrough; documents viewer-owned CEC model for balena.
docker-compose.balena.dev.yml.tmpl	Removes /dev/vchiq passthrough; documents viewer-owned CEC model for balena dev.
conftest.py	Moves _isolated_settings_conf fixture to shared conftest for cross-file reuse and isolation.
bin/upgrade_containers.sh	Removes old device-rewrite logic and deletes stale CEC override file during upgrade.
bin/deploy_to_balena.sh	Removes board-specific /dev/vchiq stripping since templates no longer bind-mount it.
bin/balena_ota_deploy.sh	Removes board-specific /dev/vchiq stripping since templates no longer bind-mount it.
.github/workflows/build-balena-disk-image.yaml	Updates workflow comment to reflect removal of the vchiq strip step.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 32 out of 36 changed files in this pull request and generated no new comments.

Suppressed comments (4)

src/anthias_server/lib/display_power.py:64

• Same as above: the warning-level log on parse failure can be hit by API validation paths (400s) and by the per-minute scheduler if a bad value is ever persisted, which risks flooding logs. Downgrading to debug (or not logging here) would keep warnings for actionable faults.

        second = int(parts[2]) if len(parts) == 3 else 0
        parsed = time(hour, minute, second)
    except (TypeError, ValueError):
        logger.warning('Ignoring malformed display-power time %r', value)
        return None

website/content/docs/display-schedule.md:139

• The docs imply the System Info card only reports No CEC display detected, No CEC adapter, or CEC error, but the code can also report Mixed when multiple attached displays disagree about power state (e.g., one on and one standby). Mentioning Mixed here would prevent operators treating it as an error or being surprised by an undocumented status string.
  src/anthias_server/lib/display_power.py:52
• parse_hhmm() logs a warning for malformed values, but it is called from request validation and from a once-per-minute Celery task. A persistent bad value (or a client sending bad input) could spam warning logs; consider downgrading this to debug (or leaving logging to the caller) so invalid user/config input doesn't become operational noise.

This issue also appears on line 60 of the same file.

    parts = str(value).strip().split(':')
    if len(parts) not in (2, 3):
        logger.warning('Ignoring malformed display-power time %r', value)
        return None

src/anthias_server/lib/display_power.py:157

• The comment says “Blank first” but the code sends unblank first when on=True. Updating the wording to reflect “send local blank/unblank first” will avoid confusion when reading the control flow.

    # Blank first, and unconditionally. It is the layer that works
    # everywhere, and doing it before CEC means a contended bus (below)
    # still leaves the screen in the right visual state.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Copilot reviewed 32 out of 36 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/anthias_server/lib/cec_client.py:150

• set_power() ignores the viewer's 'error' field. When the viewer hits a real CEC/IO error it replies with {'acknowledged': 0, 'attempted': 0, 'error': ...}; returning (0, 0) here makes callers mis-report the failure as "no CEC link" (or similar) and discards the actual reason. Treat 'error' as a hard failure and raise ViewerUnavailableError so UI/toasts and the scheduler can surface the real problem and retry appropriately.

    command = 'display_on' if on else 'display_off'
    reply = _ask(command, COMMAND_TIMEOUT_MS)
    if reply.get('busy'):
        # The viewer had another CEC operation in flight and skipped
        # this one. Nothing was transmitted.
        raise ViewerUnavailableError('viewer CEC bus was busy')
    return int(reply.get('acknowledged', 0)), int(reply.get('attempted', 0))