feat: add timezone support for schedules and dim schedule feature

[ChuckBuilds]

• Fix timezone handling in _check_schedule() to use configured timezone instead of system time (addresses schedule offset issues)
• Add dim schedule feature for automatic brightness dimming:
  • New dim_schedule config section with brightness level and time windows
  • Smart interaction: dim schedule won't turn display on if it's off
  • Supports both global and per-day modes like on/off schedule
• Add set_brightness() and get_brightness() methods to DisplayManager for runtime brightness control
• Add REST API endpoints: GET/POST /api/v3/config/dim-schedule
• Add web UI for dim schedule configuration in schedule settings page

Summary by CodeRabbit

Release Notes

New Features

• Automatic display dimming based on scheduled time periods with adjustable brightness levels (0-100%)
• Support for both global scheduling and per-day overrides with custom start/end times for each weekday
• Web interface controls for configuring and managing dim schedules with timezone-aware operation
• Enhanced brightness management with per-day scheduling flexibility

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@ChuckBuilds has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 9 minutes and 36 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

A new dimming schedule feature is introduced, enabling timezone-aware brightness control based on configurable time windows. Configuration, API endpoints, backend brightness logic, and web UI components are added to support global and per-day dimming schedules.

Changes

Cohort / File(s)	Summary
Configuration config/config.template.json	New dim_schedule configuration object with enabled flag, brightness level, mode selection, and time windows for global or per-day dimming overrides.
Display Brightness Control src/display_manager.py	Added set_brightness(brightness: int) and get_brightness() public methods to control and read display brightness with clamping and fallback handling.
Display Controller Logic src/display_controller.py	Introduced _check_dim_schedule() method with timezone-aware brightness calculation; integrated into main loop alongside existing schedule checks; added brightness state tracking and resilience for invalid timezones and times.
API Endpoints web_interface/blueprints/api_v3.py	Added GET/POST endpoints for /config/dim-schedule with comprehensive validation logic for global and per-day modes, time format checking, and at-least-one-day enforcement for per-day configuration.
Web Interface web_interface/blueprints/pages_v3.py, web_interface/templates/v3/partials/schedule.html	Extended schedule template route to pass dim_schedule_config and normal_brightness; added new "Dim Schedule Settings" UI form with brightness slider, date/time picker widget, and response handler for form submission feedback.

Sequence Diagram(s)

sequenceDiagram
participant User
participant Client as Browser
participant API as API Endpoint
participant ConfigMgr as Config Manager
participant Controller as Display Controller
participant Manager as Display Manager
participant Hardware as Hardware Matrix
User->>Client: Save Dim Schedule
Client->>API: POST /config/dim-schedule
API->>API: Validate mode & times
alt Global Mode
API->>API: Validate start/end times
API->>API: Remove per-day settings
else Per-Day Mode
API->>API: Validate per-day times<br/>(Mon-Sun)
API->>API: Ensure ≥1 day enabled
end
API->>ConfigMgr: Update config atomically
ConfigMgr->>ConfigMgr: Write dim_schedule
API-->>Client: Success response
Client-->>User: Show notification
Note over Controller: Main Loop (continuous)
Controller->>Controller: _check_dim_schedule()
Controller->>Controller: Calculate brightness<br/>from schedule & timezone
alt Display Active & Dimmed
Controller->>Manager: set_brightness(target)
Manager->>Manager: Clamp 0-100
Manager->>Hardware: matrix.brightness = value
Hardware-->>Manager: Return success
Manager-->>Controller: Boolean result
Controller->>Controller: Log brightness change
end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Poem

🐰 Beneath the moonlit web we code,
A dimmer path for nighttime's mode,
With timezone whispers, brightness flows,
From dusk 'til dawn, the schedule glows,
Per-day precision, soft and true—
Bright days ahead, and dimmer nights for you! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main changes: adding timezone support for schedules and introducing a dim schedule feature. Both aspects are clearly present in the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 92.86% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/schedule-timezone-and-dim-schedule

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/display_controller.py`:
- Around line 546-627: The dim-schedule mode string comparison in
_check_dim_schedule only recognizes "per-day" so configs using "per_day" are
ignored; update the mode handling in _check_dim_schedule to treat both "per-day"
and "per_day" (e.g., normalize mode = mode.replace('_','-') or check for both
values) so use_per_day becomes True when either form is present, ensuring
day_config (days_config[current_day]) is honored and per-day start_time/end_time
are applied.
In `@web_interface/blueprints/api_v3.py`:
- Around line 405-411: The code currently casts data.get('dim_brightness')
directly to int which raises ValueError/TypeError for empty or non-numeric
input; update the parsing for dim_brightness to validate first (e.g., check for
None/empty and that the value is numeric or can be parsed) and wrap the int
conversion in a try/except that catches ValueError/TypeError, returning
error_response(ErrorCode.VALIDATION_ERROR, "dim_brightness must be an integer
between 0 and 100", status_code=400) if parsing fails or if the resulting int is
outside 0–100; keep the existing branch that returns the validation error when
the numeric range check fails.

🧹 Nitpick comments (2)

src/display_manager.py (1)

177-215: Tighten exception handling and include stack traces in brightness accessors.

Both methods catch broad Exception, and get_brightness() swallows errors silently. Narrowing to expected exception types and logging with stack traces will make hardware issues diagnosable; adding a small fail-fast validation for brightness prevents type errors from leaking into the driver.

♻️ Proposed refactor

 def set_brightness(self, brightness: int) -> bool:
@@
- try:+ try:
if self.matrix is None:
logger.warning("Cannot set brightness in fallback mode")
return False
+ try:+ brightness = int(brightness)+ except (TypeError, ValueError):+ logger.warning("Invalid brightness value '%s' (expected 0-100)", brightness)+ return False+
# Clamp to valid range
brightness = max(0, min(100, brightness))
@@
- except Exception as e:- logger.error(f"Error setting brightness: {e}")+ except (AttributeError, ValueError, TypeError, RuntimeError) as e:+ logger.exception("Error setting brightness: %s", e)
return False
@@
def get_brightness(self) -> int:
@@
- except Exception:- return -1+ except (AttributeError, ValueError, TypeError, RuntimeError):+ logger.exception("Error getting brightness")+ return -1

As per coding guidelines, validate inputs and handle errors early (Fail Fast principle), catch specific exceptions, and include stack traces in error logs.

web_interface/blueprints/api_v3.py (1)

356-383: Handle config-load failures explicitly and log with context

Line 378 catches Exception, which hides config-load issues and makes Pi debugging harder. Please catch config-related exceptions explicitly and log with a [DIM SCHEDULE] context tag; keep a narrow fallback for truly unexpected errors.

🔧 Suggested adjustment

 def get_dim_schedule_config():
"""Get current dim schedule configuration"""
+ from src.exceptions import ConfigError
try:
if not api_v3.config_manager:
return error_response(
ErrorCode.CONFIG_LOAD_FAILED,
'Config manager not initialized',
status_code=500
)
@@
- except Exception as e:- return error_response(- ErrorCode.CONFIG_LOAD_FAILED,- f"Error loading dim schedule configuration: {str(e)}",- status_code=500- )+ except (ConfigError, json.JSONDecodeError, OSError, PermissionError) as e:+ logger.exception("[DIM SCHEDULE] Failed to load config")+ return error_response(+ ErrorCode.CONFIG_LOAD_FAILED,+ f"Error loading dim schedule configuration: {e}",+ status_code=500+ )+ except Exception:+ logger.exception("[DIM SCHEDULE] Unexpected error loading dim schedule configuration")+ return error_response(+ ErrorCode.CONFIG_LOAD_FAILED,+ "Unexpected error loading dim schedule configuration",+ status_code=500+ )

As per coding guidelines: Catch specific exceptions, not bare except: statements; Use structured logging with context (e.g., "[NHL Recent]") for logging messages; Implement comprehensive logging for remote debugging on Raspberry Pi.