Skip to content

controller_matrix.md

Latest commit

 

History

History
83 lines (68 loc) · 5.82 KB

controller_matrix.md

File metadata and controls

83 lines (68 loc) · 5.82 KB

Controller Capability Matrix

This page documents the per-controller capabilities of every display driver shipped with lcdgfx. It is generated from the code-generator templates in tools/templates/lcd/<controller>/<controller>.json (functions.interface_list field) and verified against the auto-generated drivers in src/v2/lcd/<controller>/.

Legend

  • BPP: native bits-per-pixel of the controller's frame data.
  • Resolutions: panel resolutions for which an init sequence is shipped.
  • Bus: data bus types supported by the HAL (SPI, I2C, custom).
  • Rotation: software (sw) or hardware (hw) rotation. sw means the library rotates pixel coordinates before sending; hw means the controller has a memory-access-control register that handles the transform itself.
  • Invert: normalMode() / invertMode() colour-inversion API available.
  • Contrast: setContrast() API available.
  • HW scroll: hardware vertical-scroll register exposed (setStartLine).
  • Flip H/V: flipHorizontal() / flipVertical() API available.
  • FB needed: a software framebuffer (NanoCanvas) is required to use this controller efficiently in some modes (e.g. SH1107 landscape).
  • Status: stable (well-tested, no known correctness bugs); limited (works but has documented constraints); buggy (has open known issues — see notes).

Monochrome OLED / LCD (1 bpp)

Controller BPP Resolutions Bus Rotation Invert Contrast HW scroll Flip H/V FB needed Status Notes
SSD1306 1 64x32, 64x48, 128x32, 128x64 SPI, I2C, custom sw ✅ ✅ ✅ ✅ no stable The reference driver for this library.
SH1106 1 128x64 SPI, I2C sw ✅ ✅ ✅ ✅ no stable SSD1306-compatible command set with column offset.
SH1107 1 128x64, 64x128 SPI, I2C sw ✅ ✅ ✅ ✅ yes (landscape) limited 64x128 landscape rotation requires a software framebuffer (memory layout is page-based on the long axis).
PCD8544 1 84x48 SPI sw — — — — no stable Nokia 5110. No invert / contrast API.

Greyscale OLED (4 bpp)

Controller BPP Resolutions Bus Rotation Invert Contrast HW scroll Flip H/V FB needed Status Notes
SSD1325 4 128x64 SPI, I2C sw — ✅ — — no buggy fillRect has a known nibble-packing issue at odd column boundaries with setColor(0x0F) — see unittest/canvas_tests.cpp.
SSD1327 4 128x128 SPI, I2C sw — ✅ — — no limited printFixedN with BOLD / SIZE_2X is not supported (architectural — the renderer assumes 1-bpp glyphs at this scale).

Colour OLED (8 / 16 bpp)

Controller BPP Resolutions Bus Rotation Invert Contrast HW scroll Flip H/V FB needed Status Notes
SSD1331 8, 16 96x64 SPI hw (setRotation) — ✅ — — no stable Hardware-accelerated drawLine and copyBlock.
SSD1351 16 96x96, 128x128 SPI hw (setRotation) — ✅ — — no stable setOffset() and setRgbMode() available.

Colour TFT (16 bpp, RGB565)

Controller BPP Resolutions Bus Rotation Invert Contrast HW scroll Flip H/V FB needed Status Notes
IL9163 16 128x128, 128x160 SPI hw (setRotation) ✅ — — — no stable Backlight control is the user's responsibility.
ST7735 16 80x160, 128x128, 128x160 SPI hw (setRotation) — — — — no stable setOffset() and setRgbMode() available.
ST7789 16 135x240, 170x320, 240x240 SPI hw (setRotation) ✅ — — — no stable Many panels need INVON for correct colour — the init sequence sets it by default; toggle with normalMode() / invertMode().
ILI9341 16 128x160, 240x320 SPI hw (setRotation + rotateOutput) ✅ — — — no stable SDL emulator rotation fixed in v1.2.0.
ILI9488 16 320x480 SPI hw — — — — no limited Shipped via custom interface — see examples/.

Caveats and conventions

  • All controllers expose a 1-bit "pixel" API (putPixel, drawLine, etc.) as well as the native-depth API. On greyscale / colour controllers the monochrome API maps "black" to 0 and "white" to the maximum native value.
  • Rotation: sw rotation costs CPU on every draw call; hw rotation costs one register write at setup. Mixed-mode rotation is not supported.
  • "Bus" lists what the HAL templates emit. Adding a new bus to a stable controller is usually a matter of editing the JSON template — see tools/templates/lcd/<controller>/<controller>.json.
  • Files in src/v2/lcd/<controller>/ are auto-generated. Edit the templates in tools/templates/lcd/<controller>/ and re-run cd tools && python3 lcd_code_generator.py -c <controller> to regenerate.

How to read this matrix when picking a controller

  • Need rotation in firmware? Pick a colour TFT or SSD1331 / SSD1351 — they have hardware rotation. Mono OLED rotation is software-only and slower.
  • Need contrast control? All OLEDs support it. TFTs do not (use the backlight PWM instead).
  • Need hardware vertical scroll? Only mono OLEDs (SSD1306, SH1106, SH1107) expose setStartLine.
  • Tightest flash / RAM budget (e.g. ATtiny)? Stick with SSD1306 / SH1106. 4-bpp and 16-bpp drivers carry larger init sequences and pixel paths.