[READ-ONLY] Mirror of https://github.com/jmrplens/kleidos. Kleidos — Hardware BLE password manager for ESP32-S3 (M5StickC Plus2, StickS3, M5Stack Gray, T-Deck, Cardputer)
jmrplens.github.io/kleidos/
Review ADRs and design/brand/hardware docs for accuracy
Remove stale LVGL, M5GFX, M5Unified, and M5RuntimeButtonInput terminology
from design and hardware device docs; all these were retired fleet-wide.
- docs/design/font-integration.md: drop stale "LVGL fonts" and "M5GFX-backed
path" prose; rename T-Deck LVGL column to T-Deck 320x240; update
Implementation Path to reference the direct-HAL renderer and generated AA
fonts instead of M5GFX.
- docs/design/mockups_v2/README.md: replace M5GFX/LVGL typography description
with current direct-HAL + AA atlas pipeline; drop LVGL reference from next
firmware steps.
- docs/design/ui-iteration-handoff.md: remove "LVGL compile/display" label
from T-Deck row; correct T-Deck and CoreS3 SE status lines (LVGL gone, FT6x36
driver owns touch zones, not M5Unified); update checklist step 5.
- docs/hardware/cad-sources/_shared/schema.md: replace M5.Display.setRotation()
with DISPLAY_ROTATION / display::setRotation().
- docs/hardware/devices/m5core-ink.md: replace HAS_M5UNIFIED=1 / M5GFX row in
Firmware table with correct ESP-IDF / epaper_panel_driver facts; update two
migration notes.
- docs/hardware/devices/core2-v13.md: remove M5RuntimeButtonInput and M5Unified
bridge references; reflect current M5TouchButtonInput + FT6x36 reality.
- docs/hardware/devices/cores3-se.md: remove M5Unified touch-zone claim; reflect
M5TouchButtonInput + FT6x36 driver.
- docs/hardware/devices/m5stickc-plus1.md, m5stickc-plus2.md, m5stack-gray.md:
remove "M5Unified adapter/power adapter" wording from HAS_AXP2101 migration
notes; explain the flag selects the AXP-shaped Kleidos driver path.
ADRs (0001, 0002), brand-logos.md, code-style-guide.md, device-mechanics-cad.md,
and the remaining hardware device docs required no changes.
Claude-Session: https://claude.ai/code/session_01Y7Cy1HetRp6TZAUAeekN8X
José M. Requena Plens
(Jul 4, 2026, 12:51 AM +0200)
1ec022f9
c076a887
+51
-51
+15
-17
docs/design/font-integration.md
+15
-17
docs/design/font-integration.md
···
45
45
46
46
## Glyph Subsets
47
47
48
-
The current development renderer uses the bundled Montserrat ASCII-oriented LVGL
49
-
fonts. The later generated-font optimization pass should include only:
48
+
The later generated-font optimization pass should include only:
50
49
51
50
1. All glyphs used by `i18n/strings.csv` for `en`, `es`, `fr`, `de`, and `it`.
52
51
2. Printable ASCII `0x20-0x7E` for credential names, usernames, generated
···
86
85
87
86
Keep role names stable in `display_hal.h`; tune only backend mappings.
88
87
89
-
| Role | Stick 135x240 | Core/Gray 320x240 | T-Deck LVGL | Cardputer 240x135 | Usage |
88
+
| Role | Stick 135x240 | Core/Gray 320x240 | T-Deck 320x240 | Cardputer 240x135 | Usage |
90
89
| --- | ---: | ---: | ---: | ---: | --- |
91
-
| `SMALL` | 8-10 px | 10-12 px | 10/12 px | 8-10 px | captions, footer hints |
92
-
| `BODY` | 12-16 px | 14-16 px | 14/16 px | 10-14 px | labels, rows, text inputs |
93
-
| `HEADING` | 16-18 px | 18-20 px | 20 px | 14-16 px | titles, brand text |
94
-
| `LARGE` | 32-40 px | 40-48 px | 20+ px screen-specific | 24-32 px | PIN digit, hero code |
95
-
| `MONO` | 10-16 px | 12-16 px | 12/14 px until mono exists | 10-14 px | TOTP, counters, data |
90
+
| `SMALL` | 8-10 px | 10-12 px | 10-12 px | 8-10 px | captions, footer hints |
91
+
| `BODY` | 12-16 px | 14-16 px | 14-16 px | 10-14 px | labels, rows, text inputs |
92
+
| `HEADING` | 16-18 px | 18-20 px | 18-20 px | 14-16 px | titles, brand text |
93
+
| `LARGE` | 32-40 px | 40-48 px | 40-48 px | 24-32 px | PIN digit, hero code |
94
+
| `MONO` | 10-16 px | 12-16 px | 12-16 px | 10-14 px | TOTP, counters, data |
96
95
97
96
Dense screens can choose the lower end of a range. Onboarding, PIN, and text
98
97
input screens should use the larger end because they have fewer competing
···
100
99
101
100
## Implementation Path
102
101
103
-
1. Use the M5GFX LVGL Montserrat backend in `text_renderer.cpp` for active
104
-
direct-HAL M5 devices while screenshot-driven UI work is underway.
102
+
1. Use the direct-HAL bitmap renderer in `text_renderer.cpp` for all devices
103
+
while screenshot-driven UI work is underway.
105
104
2. Keep `display::Font::MONO` on the bitmap renderer until JetBrains Mono is
106
105
vendored with license/version metadata or generated reproducibly.
107
-
3. Vendor source fonts under a future `assets/fonts/` directory with their
108
-
licenses and exact versions, or pin a reproducible download step outside the
109
-
firmware build.
110
-
4. Generate optimized C arrays under `src/hal/display/fonts/` from the subset
111
-
reported by `scripts/font_subset_report.py`.
106
+
3. Vendor source fonts under `assets/fonts/` with their licenses and exact
107
+
versions, or pin a reproducible download step outside the firmware build.
108
+
4. Generate optimized C arrays under `src/hal/display/fonts/generated/` from
109
+
the subset reported by `scripts/font_subset_report.py`.
112
110
5. Measure flash deltas with `pio run -e m5stickc_plus2_debug`,
113
-
`pio run -e cardputer_debug`, and `pio run -e tdeck_debug` before replacing
114
-
the development M5GFX-backed path.
111
+
`pio run -e cardputer_debug`, and `pio run -e tdeck_debug` before promoting
112
+
generated AA fonts to the default path.
+8
-8
docs/design/mockups_v2/README.md
+8
-8
docs/design/mockups_v2/README.md
···
28
28
29
29
The firmware currently uses two rendering paths:
30
30
31
-
- Direct display HAL M5GFX variants use `display::Font` roles backed by bundled
32
-
M5GFX LVGL Montserrat data for sans text. Latin-1 text is still folded to
33
-
ASCII for `es`, `fr`, `de`, and `it` until the later optimized subset pass.
34
-
- Direct display HAL no-M5GFX and `MONO` text continue to use the local bitmap
35
-
renderer as a deterministic fallback.
36
-
- LVGL variants use LVGL Montserrat fonts already present in the build.
31
+
- Color (RGB565) panels use `display::Font` roles backed by the direct-HAL
32
+
text renderer. Anti-aliased A4 atlases (generated via `scripts/fonts/convert_fonts.py`)
33
+
are served for named font sizes; the bitmap renderer is the fallback when a
34
+
size is not yet generated.
35
+
- The monochrome e-paper panel (CoreInk) and any board missing an AA atlas
36
+
continue to use the local bitmap renderer as a deterministic fallback.
37
37
38
38
The firmware integration decision is documented in
39
39
[font-integration.md](../font-integration.md): development builds use real
···
84
84
85
85
Next firmware steps:
86
86
87
-
1. Replace screen-local brand mark geometry with a shared helper for direct HAL
88
-
screens and an LVGL equivalent for rich UI screens.
87
+
1. Replace screen-local brand mark geometry with a shared helper for all
88
+
direct-HAL screens.
89
89
2. Add screenshot-driven visual checks per active device family before changing
90
90
interaction-heavy screens.
91
91
3. Keep CoreInk out of all compile/test matrices until unblocked.
+13
-12
docs/design/ui-iteration-handoff.md
+13
-12
docs/design/ui-iteration-handoff.md
···
56
56
| M5StickS3 | portrait direct-HAL validation | `/dev/serial/by-id/usb-Espressif_USB_JTAG_serial_debug_unit_70:04:1D:DC:50:20-if00` |
57
57
| Cardputer ADV | compact keyboard UI iteration | `/dev/serial/by-id/usb-Espressif_USB_JTAG_serial_debug_unit_AC:A7:04:03:A3:A4-if00` |
58
58
| M5Stack CoreS3 SE | 320x240 direct-HAL touch-zone validation | `/dev/serial/by-id/usb-Espressif_USB_JTAG_serial_debug_unit_1C:DB:D4:BA:93:44-if00` |
59
-
| LilyGO T-Deck Plus | LVGL compile/display work only for now | `/dev/serial/by-id/usb-Espressif_USB_JTAG_serial_debug_unit_D0:CF:13:00:6E:20-if00` |
59
+
| LilyGO T-Deck Plus | compile/display work only for now | `/dev/serial/by-id/usb-Espressif_USB_JTAG_serial_debug_unit_D0:CF:13:00:6E:20-if00` |
60
60
| M5Stack Gray | 320x240 direct-HAL orientation/color validation | `/dev/serial/by-id/usb-Silicon_Labs_CP2104_USB_to_UART_Bridge_Controller_023FFF44-if00-port0` |
61
61
62
62
Other hardware is listed in `docs/device-identifiers.md`. CoreInk is explicitly
···
74
74
- CoreS3 SE is the preferred 320x240 direct-HAL contrast target when connected;
75
75
it gives a touch-zone/Core landscape screen without using the T-Deck vault
76
76
runtime path.
77
-
- T-Deck builds with LVGL/Montserrat, but vault runtime review is blocked by a
78
-
known vault/task crash. Do not casually reboot/reflash it unless working on
79
-
that blocker.
77
+
- T-Deck builds through the direct-HAL renderer, but vault runtime review is
78
+
blocked by a known vault/task crash. Do not casually reboot/reflash it unless
79
+
working on that blocker.
80
80
- CoreInk remains blocked.
81
81
- Debug UI-test builds intentionally disable auto-lock, display dimming, and
82
82
deep sleep so hardware stays awake during captures.
···
425
425
-o screenshots/cores3_next/vault_x3.png
426
426
```
427
427
428
-
CoreS3 SE uses M5Unified touch-button zones for BtnA/BtnB/BtnC in the current
429
-
variant. Treat it as a 320x240 direct-HAL layout check first; do not use it as a
430
-
replacement for T-Deck LVGL validation.
428
+
CoreS3 SE uses the Kleidos FT6x36 touch-button driver for BtnA/BtnB/BtnC.
429
+
Treat it as a 320x240 direct-HAL layout check first; do not use it as a
430
+
replacement for T-Deck direct-HAL validation.
431
431
432
432
## T-Deck Notes
433
433
···
437
437
TDECK_PORT=/dev/serial/by-id/usb-Espressif_USB_JTAG_serial_debug_unit_D0:CF:13:00:6E:20-if00
438
438
```
439
439
440
-
T-Deck currently compiles and the display orientation/color issues have been
441
-
fixed. Runtime vault navigation remains blocked by a known vault/task crash, so
442
-
do not use it as the primary UI iteration target unless the task is explicitly
443
-
to debug that crash. Compile validation is still useful:
440
+
T-Deck currently compiles through the direct-HAL renderer; display orientation
441
+
and color issues have been fixed. Runtime vault navigation remains blocked by a
442
+
known vault/task crash, so do not use it as the primary UI iteration target
443
+
unless the task is explicitly to debug that crash. Compile validation is still
444
+
useful:
444
445
445
446
```bash
446
447
pio run -e tdeck_debug
···
512
513
2. Run `pio run -e cardputer_debug` after compact UI changes.
513
514
3. Run `pio run -e sticks3_debug` after shared portrait direct-HAL renderer/UI changes.
514
515
4. Run `pio run -e cores3_se_debug` after shared 320x240 direct-HAL UI changes.
515
-
5. Run `pio run -e tdeck_debug` after shared display, font, LVGL, or state changes.
516
+
5. Run `pio run -e tdeck_debug` after shared display, font, or state changes.
516
517
6. Capture Cardputer at `--scale 1` and `--scale 3` when judging pixelation.
517
518
7. Capture StickS3 and CoreS3 SE when validating shared direct-HAL renderer/menu changes.
518
519
8. Keep CoreInk blocked unless the task is specifically to resume its bring-up.
+3
-3
docs/hardware/devices/core2-v13.md
+3
-3
docs/hardware/devices/core2-v13.md
···
35
35
| Power | — | Left edge | Rect 2.5 × 5.0 | (0, 10.0) | Power |
36
36
| Reset | — | Bottom edge | Rect 2.0 × 3.8 | (40.0, 54.0) | Reset |
37
37
38
-
Touch zones are synthesized by M5Unified `BtnA`/`BtnB`/`BtnC` through `M5RuntimeButtonInput`.
38
+
Touch zones BtnA/BtnB/BtnC are driven by `M5TouchButtonInput` against the FT6x36 driver.
39
39
40
40
## Chips & Peripherals
41
41
···
61
61
| Variant header | [variants/core2_v13/variant.h](../../../variants/core2_v13/variant.h) |
62
62
| Board file | [src/boards/board_core2_v13.cpp](../../../src/boards/board_core2_v13.cpp) |
63
63
| OTA class | 16 MB dual OTA |
64
-
| PMIC | AXP192, via existing `PowerManagerAXP2101` M5Unified bridge |
64
+
| PMIC | AXP192, via `PowerManagerAXP2101` (shares AXP-shaped driver with AXP2101 boards) |
65
65
| IMU | Disabled pending hardware validation |
66
66
67
67
## Pin Map
···
87
87
## Migration Notes
88
88
89
89
- Display reset and backlight are PMIC-controlled (AXP192); do not add direct GPIO paths without an AXP192 facade.
90
-
- Keep M5Unified as touch-button owner until Kleidos has a dedicated FT6336U facade.
90
+
- Touch-button synthesis uses `M5TouchButtonInput` against the FT6x36 driver; no M5Unified dependency.
91
91
- ILI9342C needs inverted colors and `DISPLAY_OFFSET_ROTATION=3` (same as Gray/CoreS3).
92
92
- Core2 v1.3 uses AXP192 and BMI270 — different from Core2 v1.1; re-check schematic before sharing assumptions.
93
93
- Enabling BMI270 requires axis orientation, interrupt behavior, and deep-sleep shutdown to be validated together.
+3
-3
docs/hardware/devices/cores3-se.md
+3
-3
docs/hardware/devices/cores3-se.md
···
33
33
| Power | — | Left edge | Rect 2.5 × 5.0 | (0, 10.0) | Power |
34
34
| Reset | — | Bottom edge | Rect 2.0 × 3.8 | (40.0, 54.0) | Reset |
35
35
36
-
Touch zones BtnA / BtnB / BtnC are synthesized by M5Unified at the bottom of the display.
36
+
Touch zones BtnA / BtnB / BtnC are driven by `M5TouchButtonInput` against the FT6x36 driver at the bottom of the display.
37
37
38
38
## Chips & Peripherals
39
39
···
44
44
| PSRAM | — | — | 8 MB Quad |
45
45
| PMIC | AXP2101 | 0x34 | Battery, power rails, backlight (AXP2101-controlled) |
46
46
| RTC | BM8563 | 0x51 | Battery-backed real-time clock |
47
-
| Touch controller | FT6336U | — | Capacitive touch (via M5Unified initially) |
47
+
| Touch controller | FT6336U | — | Capacitive touch via Kleidos FT6x36 driver |
48
48
| Audio amp | AW88298 | — | I2S amplifier |
49
49
| Microphone | ES7210 | — | MEMS array microphone (front, top-left x=4,y=5 mm) |
50
50
| Camera | OV2640 or equiv. | — | Front face (x=8,y=5 mm) |
···
89
89
90
90
- Display reset and backlight are not GPIO-controlled; do not add LEDC or direct GPIO paths without an AXP2101/AW9523B facade.
91
91
- Shared GPIO35 (LCD DC / SD MISO) requires a deliberate bus plan before enabling `HAS_SDCARD`.
92
-
- Keep M5Unified as the owner of touch-button synthesis until Kleidos has a dedicated FT6336U facade.
92
+
- Touch-button synthesis uses `M5TouchButtonInput` against the FT6x36 driver; no M5Unified dependency.
93
93
- ILI9342C panel needs inverted colors and `DISPLAY_OFFSET_ROTATION=3`.
94
94
95
95
## Sources
+3
-3
docs/hardware/devices/m5core-ink.md
+3
-3
docs/hardware/devices/m5core-ink.md
···
61
61
| PlatformIO envs | Blocked (excluded from imports) |
62
62
| Variant header | [variants/m5core_ink/variant.h](../../../variants/m5core_ink/variant.h) |
63
63
| OTA class | 4 MB no OTA |
64
-
| Framework | `HAS_M5UNIFIED=1`; e-paper via CoreInk DisplayHAL over M5GFX |
64
+
| Framework | ESP-IDF only; e-paper via Kleidos `epaper_panel_driver` |
65
65
| Capacity | 100 credentials, 30 TOTP entries |
66
66
67
67
## Pin Map
···
94
94
- E-paper has no backlight; dimming calls are no-ops; UI must wait for panel refresh before panel sleep.
95
95
- Use `TFT_WHITE` as the paper-clear color and `TFT_BLACK` as ink.
96
96
- 4 MB flash, no OTA; firmware updates are full-flash style.
97
-
- M5GFX selects panel: `0x70` → `Panel_GDEW0154M09`, `0x2F` → `Panel_GDEW0154D67`.
97
+
- The e-paper panel variant is `GDEW0154D67`; driver configured in `src/hal/display/epaper_panel_driver.cpp`.
98
98
99
99
## Sources
100
100
101
101
- [Official M5Stack docs](https://docs.m5stack.com/en/core/coreink)
102
-
- M5Unified/M5GFX board support (`board_M5StackCoreInk`)
102
+
- Kleidos board file: `src/boards/board_m5core_ink.cpp`
+1
-1
docs/hardware/devices/m5stack-gray.md
+1
-1
docs/hardware/devices/m5stack-gray.md
···
84
84
85
85
## Migration Notes
86
86
87
-
- PMIC is IP5306, not AXP2101; the flag reflects the shared M5Unified power adapter only.
87
+
- PMIC is IP5306, not AXP2101; `HAS_AXP2101` selects the shared AXP-shaped driver path used for IP5306 boards.
88
88
- ILI9342C panel requires inverted colors and BGR order (`DISPLAY_OFFSET_ROTATION=3`).
89
89
- Display and SD share SPI pins; keep CS discipline explicit and route shared-bus locking through platform abstractions.
90
90
- No PSRAM in Kleidos map; avoid large framebuffer allocations on this variant.
+1
-1
docs/hardware/devices/m5stickc-plus1.md
+1
-1
docs/hardware/devices/m5stickc-plus1.md
···
91
91
- Display backlight is PMIC-controlled; any display facade must have a backlight-off path before sleep.
92
92
- BtnA GPIO37 is the primary wake source.
93
93
- Debug baud rate validated at 115200 only; do not raise without hardware revalidation.
94
-
- `HAS_AXP2101` flag represents the M5Unified AXP adapter shape (physical chip is AXP192).
94
+
- `HAS_AXP2101` flag selects the AXP-shaped driver path; the physical chip on Plus 1.1 is AXP192.
95
95
96
96
## Sources
97
97
+1
-1
docs/hardware/devices/m5stickc-plus2.md
+1
-1
docs/hardware/devices/m5stickc-plus2.md
···
104
104
## Migration Notes
105
105
106
106
- Power-off: HOLD/GPIO4 must be driven low explicitly before shutdown when USB is not supplying power.
107
-
- `HAS_AXP2101` reflects the M5Unified adapter shape, not a real AXP2101 register map; avoid adding code that assumes AXP2101 registers until the native facade exists.
107
+
- `HAS_AXP2101` selects the AXP-shaped driver path; avoid adding code that assumes AXP2101-specific registers without consulting the AXP2101 data sheet.
108
108
- Official PSRAM is 2 MB; Kleidos disables it — keep RAM use conservative.
109
109
- BLE, display backlight, and WiFi must be stopped before power-off or deep sleep.
110
110