my little airport =)

3 min read

ADR-009: T-Display boards use family-owned selectable variants

Date: 2026-07-27

Status: Accepted

Context

v0.3.0 needs one named ESP-IDF target for firmware configure, compile, and link evidence. The selected development hardware is the non-touch LILYGO T-Display S3 sold by Robotistan as product 23746.

T-Display is also a product family whose board generations do not share a chip target, display bus, geometry, or GPIO map. A board family boundary must let platform integration select one coherent variant without spreading product names or conditional pin definitions through the firmware app, frontend, or Core.

The selected S3 vendor record names an ESP32-S3R8, 16 MB flash, 8 MB OPI PSRAM, and a 170 by 320 ST7789 panel.

Decision

T-Display family ownership lives under boards/t_display. Consumers include the stable pet_board_t_display/board.h contract and link pet::board_t_display.

PET_T_DISPLAY_VARIANT is the build-time selector. Each declared variant owns:

  • one unique variant header containing board facts
  • CMake metadata mapping the variant to its required ESP-IDF chip target
  • its own documentation and verification status

The default and only implemented variant for this release is s3, stored under boards/t_display/variants/s3. It maps to ESP-IDF esp32s3. Undeclared variants are configuration errors and carry no support claim.

The release build baseline is ESP-IDF v6.0.2 with its bundled Xtensa GCC 15.2.0 toolchain. The firmware foundation remains outside the hosted composition registry because ESP-IDF owns its toolchain and project build. Direct idf.py commands are the build authority for the selected variant.

The S3 variant records vendor-documented facts. It does not claim that display, buttons, PSRAM, flash size, power control, or any other board facility was exercised on hardware.

Consequences

The active release architecture, E20, and its PBIs distinguish the stable T-Display family boundary from the selected s3 variant. The current release claim remains limited to an ESP-IDF cross-compile for that variant.

A future classic ESP32 T-Display variant can join the same family without moving consumers or pretending that its target, bus, geometry, and pins match S3. It becomes selectable only after its header, target metadata, build integration, and evidence exist.

ESP-IDF build evidence can establish cross-compile-tested status for a selected variant. It cannot establish hardware runtime support.

Alternatives considered

Use one undifferentiated T-Display board contract. Rejected because common names would conceal variant-specific chip targets, transports, geometry, and pins.

Create an unrelated top-level board component for every T-Display generation. Rejected because consumers need a stable family selection boundary and should not encode each product generation in their own build logic.

Declare unimplemented variants in advance. Rejected because a selectable value implies a build contract. New variants are added only with their configuration and evidence.

Add firmware to the hosted composition registry. Rejected for this release because the registry selects hosted app and frontend compositions, while ESP-IDF owns a separate SDK toolchain build.

References

Graph View