Max Gramser
bc2a754706
Dark mode is a new switch under Brightness on the screen's settings page, in the Screen settings of ESP Screens and as switch.<screen>_dark_mode in Home Assistant, so an automation can turn it on at bedtime. The screen changes look at once, open cards and an alert included, and keeps it after a restart. The design stays the same: a black page, graphite cards with a hairline, soft white text, Home Assistant's state colours where they tell something, and pastel card colours as deeper versions of themselves. Every colour the firmware chooses now lives in components/smart_display/ theme.h: roles with a light and a dark value, the named card colours and Home Assistant's state colours. The board profiles give widgets colourless shared styles that theme.h fills, so a change of look refills those styles and draws again what code painted by state. The light look is unchanged apart from merges below one panel step. Dark mode costs 440 bytes of static RAM on the CYD, and the LVGL tree of the host build is 416 bytes smaller; tests keep colours out of every other file. Comparing a screen that switched looks with one that booted in it also found two older bugs, now fixed: a settings switch that was on showed its knob at the left whenever its page was drawn, and the sun card's sunlit area turned orange after a palette change. Firmware 0.2.54. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
85 lines
5.6 KiB
Markdown
85 lines
5.6 KiB
Markdown
# Colours and Dark mode
|
|
|
|
Every colour the screens choose themselves lives in one file, `components/smart_display/theme.h`
|
|
(firmware 0.2.54+). Dark mode is a second value for each of them, not a second design: the
|
|
layout, the fonts and the sizes stay exactly as they are. This page says how the colours reach
|
|
the glass and what a new colour takes.
|
|
|
|
## The model
|
|
|
|
| Part | What it is | Where |
|
|
|---|---|---|
|
|
| Role | What a colour is for (`PAGE`, `CARD`, `INK`, `MUTED`, `KEY_PRESSED`, ...), with a light and a dark value | `theme::ROLES`, the table at the top of `theme.h` |
|
|
| Swatch | A named card colour a tile or an alert can pick (`red` ... `gray`), light and dark | `theme::SWATCHES` |
|
|
| State colour | Home Assistant's colour for a state (the amber of a light that is on), the same in both looks | `theme::ha` |
|
|
| Paint | A shared LVGL style filled from roles: `card` is a card's background, hairline and text | `theme::Paint`, `theme::PAINTS` |
|
|
| Look | `theme::dark`, set by `theme::set_dark()` from the Dark mode setting | `settings_screen::dark_mode` |
|
|
|
|
The light values are the design as it has always been; `tests/test_theme.cpp` pins the main ones.
|
|
The dark values follow a few rules: a black page, graphite cards (`#1A1A1A`) with a hairline,
|
|
soft white text (`#DADADA`) and greys for secondary words, Home Assistant's state colours
|
|
unchanged, their tints a little stronger over graphite, and a grey whose red, green and blue land
|
|
on the same step of the RGB565 panel, so it stays grey on both boards.
|
|
|
|
## How a colour reaches the glass
|
|
|
|
- **Board profiles** write no colour. A widget names a paint, `styles: paint_card`, or a style that
|
|
carries one (`style_page`, `style_tile`, `style_room`, ...). The style definitions have no colour;
|
|
`on_boot` sets `theme::paints` to the list of `theme::fill(id(style), Paint::...)` calls and runs it. The list is
|
|
code in flash, not a table in RAM, and `theme::set_dark()` runs it again.
|
|
Scripts that colour a widget by state ask for a role: `theme::color(selected ? theme::ACCENT_BRIGHT : theme::CARD)`.
|
|
- **Firmware** asks for roles: `theme::color(theme::INK)`, `theme::hex(theme::MUTED)`, the
|
|
`detail_text(..., theme::SUBTLE)` and `detail_shape(..., theme::TRACK, ...)` overloads. A widget
|
|
that lives as long as the screen and never changes colour by state takes a paint too:
|
|
`lv_obj_add_style(obj, theme::style(theme::Paint::knob), LV_PART_KNOB)`.
|
|
- **State colours** pass through a helper on their way to the glass:
|
|
`state()` (Home Assistant's greys become the dark greys), `foreground()` (a glyph, a line or words:
|
|
deep colours are lifted in dark), `tint()` (the pale circle, a halo, a slider track), `icon()`
|
|
(a tile's icon), `surface()` and `outline()` (a card's own colour and hairline), `key_on()` (keys
|
|
inside a card of any colour) and `fill_opacity()` (the area under a graph).
|
|
|
|
## A change of look
|
|
|
|
`settings_screen::set("dark_mode", ...)` stores the setting in its own preference (`DRK1`), runs
|
|
`apply_screen_settings`, and that calls `theme::set_dark()`. A look the screen already has costs
|
|
nothing. A real change runs `theme::paints`, refills the firmware's own paints, tells LVGL once, and calls
|
|
`theme::redraw`, set in `on_boot`, which draws again what code painted by state:
|
|
|
|
- `runtime_tiles::restyle()`: every tile's palette, the top bar's icons, and an open card, in place;
|
|
- `light_controls::restyle()`, `settings_screen::restyle()`;
|
|
- an alert that is up (`theme::surface(id(alert_card_color))`), and the climate card and its mode
|
|
picker when they are open.
|
|
|
|
Everything happens in the same pass, so no frame shows half of each look. At boot `set_dark()`
|
|
runs before the first frame.
|
|
|
|
A redraw has to give exactly what a first draw gives, whatever came before it. Two things that did
|
|
not were found by comparing a screen that switched with one that booted in that look: a position
|
|
worked out from coordinates LVGL had not laid out yet (they read 0 until its next pass: use the size
|
|
you set), and a palette pass that overwrote a colour the sun path had chosen itself.
|
|
|
|
## Adding a colour
|
|
|
|
1. **A role**: one line in `enum Role` and one row in `ROLES`, in the same order (the tests read
|
|
both). The light value is the design; choose the dark value on a render, not in the table.
|
|
2. **In firmware code**: `theme::color(theme::YOUR_ROLE)`. Never `lv_color_hex(0x...)`.
|
|
3. **In a board profile**: the widget takes a paint. For a new combination add it to `enum class
|
|
Paint` and `PAINTS`, a colourless `- id: paint_<name>` in the `style_definitions` of both profiles,
|
|
and `theme::fill(id(paint_<name>), Paint::<name>);` in their `theme::paints` list. Then
|
|
`python3 tools/generate_packages.py`.
|
|
4. **Something drawn once and kept that changes colour by state**: set it where the state is drawn,
|
|
and make sure the redraw above reaches that code.
|
|
5. A local colour always wins over a paint: an object that takes a paint must not also get a local
|
|
colour for the same property and part.
|
|
|
|
## Checks
|
|
|
|
- `tests/test_theme.cpp`: the light design, contrast of the text roles on every surface and swatch in
|
|
both looks, neutral dark greys, and the helpers.
|
|
- `tests/test_theme.py`: no colour outside `theme.h` (the light's colour picker and the value card's
|
|
colour wheel keep their hues), every paint defined, filled once and used, and the look applied at
|
|
boot, after a change and in the redraw.
|
|
- Renders of the host build in both looks (see `docs/RELEASING.md`, Compatibility 0.2.63): the light
|
|
look pixel for pixel against the previous firmware, a screen that boots dark against one that
|
|
switched, and every card opened in light and switched while open against the same card opened in dark.
|