Skip to content

feat: add M5Stack PaperS3 simple-config preset (panel-IC 3004) - #111

Merged
jonasniesner merged 1 commit into
OpenDisplay:mainfrom
AsLY4:feat/m5-papers3-preset
Sep 12, 2026
Merged

jonasniesner merged 1 commit into
OpenDisplay:mainfrom
AsLY4:feat/m5-papers3-preset

Conversation

@AsLY4

@AsLY4 AsLY4 commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Adds the M5Stack PaperS3 (ESP32-S3, 4.7" 960×540 ED047TC1-class parallel e-paper, 16-gray capable) as a complete device preset, plus its two panel entries.

Firmware support merged in OpenDisplay/Firmware#159 and shipped in release 2.26.5: panel-IC 3004 maps to FastEPD BB_PANEL_M5PAPERS3. This is the toolbox-side counterpart — no new firmware binary and no new manifest, it reuses the existing bin/esp32-s3-N16R8_full.json.

Changes

  • simple-config-presets.jsondriverBoards: m5-papers3 (index 31); displays: m5-papers3-960x540 (44, mono) and m5-papers3-960x540-4gray (45, color_scheme 6), identical apart from the colour scheme.
  • simple-config-id-registry.json — the three matching id → index appends.
  • config.yamlpanel_ic_type 3004 (m5papers3_960x540) and minor_version 4 → 5, mirroring the protocol-side @since 1.5 backward-compatible enum addition.

connectorPins uses a new private token 1047, so the board and its two panels only offer each other — same approach as the Inkplate entries (1010 / 1052). The board follows inkplate-5v2 for the parallel-panel shape (all displayPins 0xff, panel pin map lives in the firmware) and the reTerminal entries for powerDefaults.

.github/scripts/validate-simple-config-presets.py passes locally: simple-config OK: 87 presets; id/index registry stable.

Hardware validation

Every value comes from a physical PaperS3 driven through a 24-scenario acceptance run (MONO and GRAY16 rendering over direct and pipe writes, GT911 touch telemetry, buzzer, battery telemetry, deep sleep with timer wake and image retained, plus a full erase → reflash → reconfigure → first image run). Points worth a reviewer's attention:

  • The dataBus block is mandatory on this board. Without an explicit I²C block (SCL 42 / SDA 41, 400 kHz) the firmware falls back to Wire.begin() on GPIO 8/9 — which are EPD data lines here — and rendering corrupts into column artefacts. This was the hardest-won finding of the bring-up.
  • Touch flags = 0x6 (SWAP_XY | INVERT_Y): the GT911 reports portrait-native axes; this maps them to the 960×540 landscape, corner-verified on hardware.
  • i2c_addr_7bit = 0xff for GT911 auto-probe (0x5D then 0x14, board-revision dependent; 0x5D on the validated unit). The schema documents 0/0xFF as auto-detect, though this is the first preset to use it.
  • voltage_scaling_factor = 0xa1 (161): validated to −3.2 % against the Li-ion 4.20 V charge plateau (the enclosure exposes no measurement point).
  • dataBus.pullups = 0x0 — unlike the reTerminal entries, this board has external I²C pullups; and buzzerConfig.flags = 0x0 because enable_pin is unused here.

manufacturer_id is 0 (diy) with the name "M5Stack PaperS3", so the name-split path advertises manufacturer M5Stack / model PaperS3 — no manufacturer enum change needed.

Two things for you to decide

1. powerDefaults are skipped on mains power. mergeSimpleConfigToFull() applies a board's powerDefaults only when power_mode !== '2' (index.html:3826-3828). The PaperS3's sensible default is mains/always-on (usb), so its battery ADC (GPIO 3, scaling 161, capacity_estimator 1) is dropped in exactly the default configuration — even though the hardware reports battery voltage fine on USB power. The values do apply as soon as a user picks a battery option.

This isn't PaperS3-specific: it affects any board with a battery ADC selected on USB power (reterminal-e1003 has the same hole). I left defaultPower: "usb" with the powerDefaults block intact rather than guess. Happy to either relax that guard so only the sleep-related fields are skipped on mains (one line, here or separately), or add a device-specific powerOptions entry carrying the ADC inline — though that spends a permanent registry index and adds a row to every board's dropdown. Your call.

2. Sequencing with the hosted firmware. bin/firmware-version.json currently pins 2.26.4 (synced 2026-09-02), while PaperS3 support ships in 2.26.5. Until the sync lands, a user flashing from the toolbox would get a firmware without the 3004 mapping and then apply a config it cannot drive. Nothing to edit here — just worth merging this after the firmware sync, or triggering it first.

Happy to reshape any of this.

Adds the M5Stack PaperS3 (ESP32-S3, 4.7" 960x540 ED047TC1-class parallel
e-paper, 16-gray capable) as a driverBoard plus its two panel entries,
following the Inkplate pattern for FastEPD parallel panels.

Firmware support merged in OpenDisplay/Firmware#159 and shipped in
release 2.26.5 (panel-IC 3004 -> BB_PANEL_M5PAPERS3). No new binary or
manifest: reuses the existing esp32-s3-N16R8_full.json.

- simple-config-presets.json: m5-papers3 (index 31), m5-papers3-960x540
  (44, mono) and m5-papers3-960x540-4gray (45, color_scheme 6)
- simple-config-id-registry.json: the three matching id -> index appends
- config.yaml: panel_ic_type 3004 (m5papers3_960x540) and minor_version
  4 -> 5, mirroring the protocol-side backward-compatible enum addition

Every value comes from a physical unit driven through a 24-scenario
acceptance run.
@AsLY4
AsLY4 requested a review from jonasniesner as a code owner September 9, 2026 09:16
@jonasniesner
jonasniesner merged commit 7f845d9 into OpenDisplay:main Sep 12, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants