diy-layout-creator/diylc/docs/plans/maker-peripherals.md

# Maker Peripherals — `Displays & Outputs`

Status: **13 components shipped**, in the as-yet-unreleased `6.7.0` block of
`diylc-core/src/main/resources/update.xml`.
Scope: `diylc-library`, package `org.diylc.components.displays`.
Companion: `maker-board-roadmap.md`, which covers `org.diylc.components.micro`.

Nothing in this package has been in a release, so defaults, control-point counts and serialized
field names can still be changed freely. **That stops the moment 6.7.0 ships.**

## 1. What is in the palette

| Class | Variants | Other properties |
|---|---|---|
| `CharacterLCD` | 16x2, 20x4 × I2C backpack, parallel HD44780 | Backlight Color, Screen |
| `OLEDDisplay` | 0.96" SSD1306 128x64, 0.91" SSD1306 128x32, 1.3" SH1106 128x64 × I2C, 7-pin SPI, 6-pin SPI | Pixel Color, Screen |
| `TFTDisplay` | 2.8" / 2.4" ILI9341, 0.96" / 1.8" ST7735, 1.54" ST7789, 1.28" GC9A01 round | Screen |
| `Nokia5110LCD` | single part (PCD8544 84x48) | Backlight Color, Screen |
| `SevenSegmentDisplay` | 1-digit 0.56", 4-digit 0.36", 4-digit 0.56", 4-digit TM1637 module | Common, Punctuation, LED / Board / Body colour |
| `LEDMatrix` | MAX7219 single 8x8, compact 8x8, 4-in-1 32x8, 8-in-1 64x8 | Dot Color |
| `LEDBarGraph` | 8, 10, 12 segments | Orientation, body / border colour |
| `WS2812BBreakout` | single LED | — |
| `WS2812BStick` | 8 LEDs | — |
| `WS2812BJewel` | 7 LEDs | — |
| `WS2812BRing` | 12, 16, 24 LEDs | — |
| `WS2812BStrip` | 30 / 60 / 144 LED·m⁻¹ × 1–144 LEDs | — |
| `WS2812BPanel` | Adafruit 8x8 NeoMatrix | — |

Twelve extend `AbstractMakerBoard`. `LEDBarGraph` is the exception: a DIP-outline part, so it
follows `DIL_IC` on `AbstractLabeledComponent` with its own transformer and inherits none of the
maker helpers. It is still in this category because that is where someone looks for a bar graph.

## 2. Conventions this package follows

These are the rules worth knowing before touching anything here. Most were learned by getting them
wrong once.

**Variants.** A `Version`-style enum on the existing class where the footprint family is shared; a
new class where it is not. The test is structural, not cosmetic: `WS2812BJewel` is a separate class
from `WS2812BRing` because it is a disc rather than an annulus, with a centre LED and its own pad
arrangement — five variant-specific structures is a different part.

**Figures live on the variant.** Hardcoded `Size` constants and `String[]` arrays in the component
class, per-variant wherever a variant changes them. No pin-definition resource, and no pixel
literals in `draw()` — every dimension derives from a `Size`.

**A different silkscreen is not a variant; a different pin count is.** The same two pads on an
SSD1306 carry the clock and data lines in both interfaces — the module's BS jumpers choose the
protocol, not the pins — so `SCL`/`SCK`/`CLK`/`D0` are one pin and `SDA`/`MOSI`/`D1` are another,
and boards that print them differently are the same board. Node names pick one spelling and move on.
A 6-pin SPI board is the opposite case: its chip select is tied low on the PCB rather than brought
out, so it cannot share a bus, and that is a variant because it reaches the netlist.

**Say whether a figure is measured or derived.** Active areas computed from a nominal diagonal at a
panel's aspect ratio are derivations, and are commented as such so nothing is built on them. Where a
part's own measurement contradicts a derivation the measurement wins and carries its own field — but
check first that it really contradicts it. A supplied figure sitting within half a millimetre of
what an existing rule already produces is more likely a reading than a departure, and has twice
turned out to be one; query it before it earns a mechanism.

**Orientation is sourced per variant, never standardised.** Which edge a board's header leaves by is
a fact about the part. Control point zero is always the leftmost pin, so with the pin order fixed a
top header and a bottom header are mirror images, not the same board turned round. `TFTDisplay`
divides three and three, and every constant states its own edge — the short constructor takes the
flag too, so none can inherit a default. Standardising this family onto one orientation was tried
and had to be undone: it had moved two boards away from the truth.

**Do not let one property stand in for another.** `isRound()` was serving as "the header is at the
bottom" and broke the moment a rectangular board had a bottom header; `isDualRow()` was serving as
"this is a bare package". Carry both questions explicitly even while the answers agree.

**Pins are drawn and covered, never skipped.** `drawPinHeader` is what registers a conductive area,
so a header hidden under a module or a moulding is drawn first and painted over. Leaving the call
out looks identical and silently drops those pins from continuity and the netlist.

**Silk where it fits, nowhere else.** Pin names go through `getSilkPinLabel`, so a name is written
once. A row with no clear strip beside it gets no labels rather than crowded ones — the matrix's
covered rows, the LCD's I2C backpack and the TFTs' SD rows all go unlabelled deliberately. A
`SILK_NAMES` array exists only where the node name is actively wrong on the board, not merely long.

**The glass prints the part's own spec.** `Display.VALUE` puts the variant string on the lit area,
generated from the properties rather than typed, carrying no prose and no language. `Display.NONE`
gives the unpowered part. No invented demo content, ever.

**BOM.** Every class sets `bomPolicy = SHOW_ONLY_TYPE_NAME` and returns the variant string from
`getVariantLabel()`, because `BomMaker` groups rows on type name plus value — without it every
variant of a class collapses into one line and the BOM cannot say which part to buy.

**Shared arrays are shared by identity.** Where two variants have the same pinout they reference one
array constant and the test asserts `assertSame`, so a correction to one reaches both. Two copies
that happen to match would pass every name check and drift the day one is corrected.

**Nested types at the bottom of the file.** Where a variant needs more than a couple of extra
figures they go into a nested value class rather than onto the enum constructor —
`OLEDDisplay.Layout`, `TFTDisplay.Glass`, `SevenSegmentDisplay.Module`. A constructor past about
fifteen arguments is the signal.

## 3. Figures that are not measurements

Kept visible so no one mistakes them for sourced data and builds on them.

- **`SevenSegmentDisplay` digit widths** — 8.1 mm on both 0.56" packages (unverified) and 5.2 mm on
  the 0.36" (inferred from the 0.56" ratio, so resting on an unchecked figure). **Deliberately left
  as inferences:** they size the drawn glyph and nothing else, and the glyph is already a declared
  departure from the package at `DIGIT_DRAW_SCALE` 0.88. An error here is cosmetic and bounded,
  unlike a wrong pin array.
- **`SevenSegmentDisplay.Module` hole figures** — 1.778 and 1.524 mm, which are the 14 and 12 pixel
  offsets the class drew before they were figures at all, converted exactly so the drawing did not
  change.
- **`Nokia5110LCD`** — the 3.5 mm clearance from the bottom edge to the pin row.
- **`WS2812BStrip`** — tape width (10 mm / 12 mm) is a stated norm rather than a measurement, and
  the end-pad lead-in derives from the pad and package footprints.
- **`TFTDisplay`** — the SD rows' horizontal placement is centred across the board by derivation;
  only their offset from the edge was given.
- **`OLEDDisplay`** — the 6-pin SPI boards borrow the 7-pin boards' outlines. A 6-pin module is a
  PCB of its own with one fewer pad, and nothing but its outline would say whether it matches.

## 4. Testing

Per-class tests in `diylc-library/src/test/java/org/diylc/components/displays/`, using
`MakerBoardTestSupport` (`assertRow`, `assertRowSpacing`, `assertBoardSize`, `assertDrawsCleanly`,
`assertScreenTextIsDrawn`, `renderPixels`).

What these tests are for, beyond the obvious count-and-dimension checks:

- **Assert relationships, not transcriptions.** A board is exactly as wide as its modules; a glass
  clears the mounting holes; no hole is drilled where a pad is; a lit area that is measured really
  does disagree with the rule it replaced. A test that restates the constant passes while the
  component is wrong.
- **No duplicate node names,** on every variant. The cost is legibility, not connectivity: nodes are
  identified by component and control point index and the netlist graph is keyed on position, so two
  pads named `GND` stay two nodes that merely print the same, and a reader cannot tell which one a
  connection reached. They are invisible on the canvas too, since `getDisplayPinLabel` cuts the
  suffix off and both silk as `GND`. `Teensy` is the one board that still repeats a bare name.
- **A drawing smoke test** over every variant, state and orientation.
- When a refactor is meant to change nothing, **render before and after and compare pixels.** The
  `digitCount` work was verified that way, and it caught a sub-pixel hole shift the unit tests
  missed.

`MakerComponentsTest` carries the generic discovery and icon coverage. A class ships by moving from
`unreleasedMakerComponentClasses` to `releasedMakerComponentClasses` and uncommenting its
`@ComponentDescriptor`.

## 5. Release

The slice is worth shipping on its own: it is archetype-complete, part of it (7-segment, character
LCD, bar graph, addressable strips) reaches builds with no microcontroller in them, and the slices
after it are large and differently shaped, so batching would mean a much later and far less
reviewable release. A release is also the only validation loop that reaches people who own the
parts.

### 5.1 What shipping makes permanent

Only this list needs checking beforehand, because only this list is a contract afterwards:

- class names, and serialized field names and types
- **control-point counts**
- **control-point positions relative to point 0** — these are stored per instance, so moving a pin
  relative to the body misplaces every wire in an existing file

Everything else is fixable in a later release without breaking a file: bezel placement, colours,
silk, hole positions, digit widths. Every figure in §3 falls here, which is why none of them blocks
a release.

### 5.2 Pre-release checklist

1. **Audit the pin layout of all 13** — count, node names, and each pin's position relative to the
   body. Not the cosmetics; those are §5.1's second list.
2. **Settle `TFTDisplay`'s 2.8" SD row.** It is the least verified thing in the package: the row was
   added on the argument that the "(Touch + SD)" label implied a missing header, and its 3.0 mm
   offset was read from "the same offset as the bottom row" rather than measured. Four control
   points that become permanent.
3. **Re-check `TFTDisplay` generally.** It is where the churn concentrated — both ILI9341s went
   14 to 18 control points, and the 0.96", 1.8" and 1.54" each had every pin move relative to the
   body when their orientation was corrected.
4. **Render a contact sheet of all 13 and look at it.** Cheap, and it caught several real errors
   that the unit tests passed straight over.

Regression samples (§6.3) are deliberately *not* on this list. They protect against future change,
which is what a released contract makes dangerous — so they are the first task after shipping, not
a blocker on it.

### 5.3 Release notes

One `NEW_FEATURE` per palette entry in the `6.7.0` block, part name then variant list. **A released
block is never edited.** A new variant of a component that is new in the same block goes onto that
component's existing line rather than being logged as an `IMPROVEMENT` — there is no earlier release
for it to improve on.

## 6. Next steps

### 6.1 Parts worth adding, ranked by how often they appear in builds

1. **1.3" 240x240 ST7789**, and the 1.14" and 2.0" ST7789 the Pico ecosystem buys. `TFTDisplay` now
   absorbs offset panels, either header edge and second rows, so each is one `Controller` constant.
   Needs per board: outline, header offset and edge, pin names in printed order, hole inset and
   drill, bezel height, and whether the lit area is centred or measured.
2. **MAX7219 8-digit 7-segment module** — the clock and counter staple, and this package already
   models a MAX7219 cascade for the matrix. Unblocked: `DisplayType` now carries digit count, pin
   array and module board figures, so this is a constant.
3. **6-digit TM1637 and 2-digit 0.56"** — the rest of the clock and thermometer range. Same.
4. **E-paper, 1.54" / 2.13" / 2.9" SSD1680.** Once judged niche; that call is stale, as ESP32 badge
   builds and the Waveshare and Good Display modules made it ordinary. The flexible-cable mounting
   is real new drawing work, which is the only reason it is not higher.
5. **WS2812B 16x16 and flexible 8x32 matrices** — the one addressable form the package lacks.
6. **The bare WS2812B 5050 LED**, as against a breakout. People solder these directly.
7. **16x4 character LCD.** Also the RGB-backlight 1602, which is *not* the free colour default it
   looks like: it is an 18-pin part whose three backlight anodes are real pins, so it is an
   `LCDInterface` constant with its own array.
8. **Nixie tubes — IN-12, IN-14, B7971.** The strongest audience overlap on this list: DIYLC already
   has a `Tubes` category, and the people in it build Nixie clocks.
9. **2.42" SSD1309 OLED**, 14- and 16-segment alphanumeric, HT16K33 backpacks. Real, second tier.

Explicitly rejected: a tint property on `TFTDisplay`. A 240x320 colour panel has no tint to set, and
offering one invites a drawing that says something false about the hardware.

### 6.2 The "& Outputs" half of the name is unfulfilled

Every member of this category emits light. **There is no analog panel meter, no VU meter, no speaker
or driver, and no magic-eye tube anywhere in the library** — `misc/Buzzer` and
`electromechanical/PilotLampHolder` are the whole non-display output range.

This is a bigger gap than anything in §6.1, and it reaches the audience DIYLC already has: a VU
meter and a loudspeaker appear in amp and effect builds containing no microcontroller at all,
`Dial Scale` is already next door in `misc`, and a moving-coil meter is a simpler drawing than any
display here. Whether these belong in this category or in `Electro-Mechanical` is not an interesting
question; that they are absent is the finding.

### 6.3 Regression coverage — the standing risk

**No `.diy` file among the 1418 in `diylc-regression-data` references `org.diylc.components.micro`
or `org.diylc.components.displays`,** so 23 components have no rendering or netlist baseline. Unit
tests guard the figures we chose; they cannot catch a pin dropping out of the netlist or a component
misbehaving in a real project. Samples were declined for this slice; the case is stronger now that
orientations, pin arrays and geometry have all moved.

### 6.4 Later slices

**`sensors` (9 drafts).** Ship the four that are the unrivalled answer in their function — HC-SR04,
DHT11/22, PIR HC-SR501, MPU6050 — and leave the five commodity KY-style three-pin boards, which
carry most of the sourcing cost for the least distinctiveness. **Do not** collapse the tail into a
parameterised "three-pin sensor module": that is the generic configurable board that was already
built and reverted, and it fails for the same reason — people search the palette for a product name.

**`modules` (21 drafts).** The largest and least homogeneous batch, and the worst geometry drift in
the tree (`ULN2003Driver` has 24 raw pixel offsets, `PCA9685ServoDriver` 22, `L298NMotorDriver` 18).
Split by function rather than shipping as one category. Settle one overlap first: the drafted
`ActiveBuzzerModule` (KY-012) against the existing `misc/Buzzer`.

**`robotics` (4 drafts).** Blocked on an architectural decision, not on part selection.
`AbstractMotor` is a parallel fork of `AbstractMakerBoard`, re-implementing `rotatePoints`,
`drawPins`, `getFinalBorderColor` and `getCachingBounds` plus its own `PIN_COLOR`, `PIN_SIZE` and
silk fonts. Four components do not justify a second hierarchy: either lift the shared behaviour into
a common base or take the duplication deliberately.

**i18n.** Component display names and enum labels are plain strings, absent from
`diylc-swing/src/main/resources/lang/*.txt`, as they are for the shipped boards. No work required
here; noted for a future pass.