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 classic LILYGO T-Display sold by Robotistan as product 23453. The non-touch T-Display S3 was the first selection, but that board never arrived, so the classic board is the only T-Display the project owns.

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 classic vendor record names an ESP32, 4 MB flash, no PSRAM, and a 135 by 240 ST7789 panel on an SPI bus.

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 classic, stored under boards/t_display/variants/classic. It maps to ESP-IDF esp32. 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 classic variant records vendor-documented facts. It does not claim that display, buttons, flash size, battery sensing, 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 classic variant. The current release claim remains limited to an ESP-IDF cross-compile for that variant.

Replacing the selected variant proved the boundary. The change stayed inside boards/t_display, platforms/esp_idf, and the documents that name the hardware, because no consumer had encoded a chip target, bus, geometry, or pin of its own.

A later T-Display S3 variant can join the same family without moving consumers or pretending that its target, bus, geometry, and pins match the classic board. 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