Skip to content

Add Waveshare ESP32-S3-Touch-AMOLED-2.06 board port#34

Merged
HermannBjorgvin merged 1 commit into
HermannBjorgvin:mainfrom
samestrin:add-waveshare-amoled-206-board-port
Jul 16, 2026
Merged

Add Waveshare ESP32-S3-Touch-AMOLED-2.06 board port#34
HermannBjorgvin merged 1 commit into
HermannBjorgvin:mainfrom
samestrin:add-waveshare-amoled-206-board-port

Conversation

@samestrin

@samestrin samestrin commented May 23, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a board port for the Waveshare ESP32-S3-Touch-AMOLED-2.06 — a 410×502 watch-form-factor AMOLED kit. The port is a hybrid of the existing ports:

  • CO5300 display + AXP PKEY for PWR (like the 2.16 port)
  • FT3168 touch + fixed orientation (like the 1.8 port)
  • No IO expander — LCD_RESET and TP_RESET are direct GPIOs pulsed in board_init()
  • 32 MB flash with default_32MB.csv partition table

Pin assignments were taken from Waveshare's reference Mylibrary/pin_config.h in their demo repo.

CO5300 col_offset gotcha (worth highlighting)

The 2.06 panel exposes its visible 410-wide viewport at a horizontal offset inside the CO5300's internal RAM. Without passing the right col_offset1 to the Arduino_CO5300 constructor, framebuffer writes land at the wrong columns and a vertical strip of stale boot content shows through on the right edge. Waveshare's library uses col_offset1 = 22; this port uses 23 after fine-tuning for centering on one unit. The 2.16" port doesn't have this issue because its 480×480 viewport fills the controller's RAM. I've added a note to docs/porting/adding-a-board.md so the next CO5300 porter doesn't lose an afternoon to this.

Rebased onto current main

This branch was originally cut before the sound HAL, the hold-to-pair gesture, and the BLE supervision-timeout fix landed. It's now rebased onto current main, which required three additions to the port beyond the original hardware bring-up:

  • sound.cppmain.cpp now calls sound_hal_init/tick/play_reset unconditionally, so the port wouldn't link without it. The 2.06 does have an ES8311 codec on the shared I2C bus, but the amp path is unverified on this board, so this no-ops (same posture as the C6 1.8 port). The shared chime.cpp engine is ready to wire up once someone tests it on this hardware.
  • power.cpp — added power_hal_pwr_long_pressed() / power_hal_pwr_released() for hold-to-pair, mirroring the 2.16's AXP PKEY implementation (LONG + POSITIVE IRQs, plus the 8s press-off bump).
  • platformio.ini — picked up the PPCP connection-parameter flags from fix(windows): end the BLE reconnect churn — widen supervision timeout (2s→6s) + crash-proof the daemon #106 so this board doesn't ship with the Windows supervision-timeout churn.

An earlier revision of this PR also tweaked flash-mac.sh to take an optional env argument. #30 fixed that same footgun more strictly on main, so that change is dropped — this PR no longer touches flash-mac.sh.

Test plan

Verified on hardware (pre-rebase build):

  • Display renders correctly with col_offset1 = 23 — splash animation centered, no edge artifacts
  • AXP2101 PMU init OK, battery percent reads correctly
  • QMI8658 IMU init OK (rotation disabled — watch enclosure is fixed orientation)
  • FT3168 touch — basic events fire (tap-to-toggle splash) and coordinates are accurate (BLE reset zone hit-area works)
  • BLE pairs as "Clawdmeter", daemon (macOS) connects and pushes usage data successfully

Verified post-rebase:

  • pio run -e waveshare_amoled_206 builds clean (1.34 MB, 10.2% of the app partition, 31.6% RAM)
  • All four existing envs still build (216, 18, 216_c6, 18_c6)

Not yet exercised on hardware:

  • Hold-to-pair on the 2.06. The gesture postdates the original bring-up, so the PKEY LONG/POSITIVE IRQ path hasn't been run on this board. The AXP2101 is the same part at the same address as the 2.16 and the button wires straight to PWRON, so I'd expect it to behave identically — but flagging it rather than implying it was tested. Happy to confirm once I have the device in front of me again.

Photo of the working device available on request.

@HermannBjorgvin

Copy link
Copy Markdown
Owner

Do you have a picture of it running on the device?

@HermannBjorgvin

Copy link
Copy Markdown
Owner

Thanks for the port! I'll merge this once the conflicts are resolved, looks good to me!

@samestrin

Copy link
Copy Markdown
Contributor Author

Waveshare ESP32-S3 Touch AMOLED 2.06

Hybrid of the existing two ports: CO5300 display from the 2.16 port,
FT3168 touch from the 1.8 port, fixed orientation (watch enclosure),
direct-GPIO resets (no IO expander), 32 MB flash, AXP PKEY for PWR.

Key gotcha worth documenting: CO5300 panels expose their visible
viewport at a horizontal offset inside the controller's internal RAM,
and the offset varies per physical panel. The 2.06 panel uses
col_offset1 = 23 (Waveshare's reference library uses 22, ±1 picks
centering empirically). Without it, a vertical strip of stale content
shows through on one edge. Added a note in docs/porting/adding-a-board.md.

Tested end-to-end: display lights up centered, BLE pairs and the daemon
pushes usage data, touch coordinates accurate (verified via the BLE
reset zone, not just the tap-to-toggle event).

Also patches flash-mac.sh to take an env argument so users can't
accidentally flash the wrong env onto a board with multiple defined.
@samestrin
samestrin force-pushed the add-waveshare-amoled-206-board-port branch from b542b09 to 7fd28d9 Compare July 16, 2026 03:21
@HermannBjorgvin
HermannBjorgvin merged commit c3da506 into HermannBjorgvin:main Jul 16, 2026
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