Skip to content

Fix swapped W5500 clk/miso pins on Waveshare ESP32-S3-ETH#1621

Merged
bdraco merged 1 commit into
mainfrom
fix-waveshare-s3-eth-pinout
Jun 20, 2026
Merged

Fix swapped W5500 clk/miso pins on Waveshare ESP32-S3-ETH#1621
bdraco merged 1 commit into
mainfrom
fix-waveshare-s3-eth-pinout

Conversation

@bdraco

@bdraco bdraco commented Jun 20, 2026

Copy link
Copy Markdown
Member

What does this implement/fix?

A device generated from the Waveshare ESP32-S3-ETH board failed to bring up its onboard W5500 at boot:

w5500.mac: W5500 version mismatched, expected 0x04, got 0x00
emac_w5500_init(883): verify chip ID failed

The board manifest had clk_pin: GPIO12 and miso_pin: GPIO13, but Waveshare's pinout is SCLK GPIO13 and MISO GPIO12. With MISO listening on the SCLK line the chip-ID read came back all-zeros, so ethernet never initialized. This swaps the two pins (and the matching occupied_by pin annotations) and regenerates the catalog. MOSI/CS/INT/RST and 25MHz were already correct.

The transposition slipped through because both pins are valid GPIOs, so esphome config accepted it; only flashing real hardware surfaced it. Verified against Waveshare's ETH_DHCP pin table and confirmed on hardware (W5500 now initializes, link plus DHCP).

Related issue or feature (if applicable):

Reported via hardware flash; introduced in #1602.

Types of changes

  • Bugfix (non-breaking change which fixes an issue) — bugfix
  • New feature (non-breaking change which adds functionality) — new-feature
  • Enhancement to an existing feature — enhancement
  • Breaking change (fix or feature that would cause existing functionality to not work as expected) — breaking-change
  • Refactor (no behaviour change) — refactor
  • Documentation only — docs
  • Maintenance / chore — maintenance
  • CI / workflow change — ci
  • Dependencies bump — dependencies

Frontend coordination

  • No frontend change needed
  • Companion frontend PR: esphome/device-builder-frontend#

Checklist

  • The code change is tested and works locally.
  • Pre-commit hooks pass (ruff, codespell, yaml/json/python checks).
  • Tests have been added or updated under tests/ where applicable.
  • components.index.json / definitions/components/*.json have not been hand-edited (regenerate via script/sync_components.py if a sync is needed).
  • Architecture-level changes are reflected in docs/ARCHITECTURE.md and/or docs/API.md.

@github-actions github-actions Bot added the bugfix Bug fix label Jun 20, 2026
The board manifest had clk_pin GPIO12 and miso_pin GPIO13, but Waveshare's pinout is SCLK GPIO13 and MISO GPIO12. With MISO listening on the SCLK line the W5500 chip-ID read returned 0x00 ("version mismatched, expected 0x04, got 0x00") and ethernet never came up. Swap the two pins (and the matching pin annotations) and regenerate the catalog. The transposition passed esphome config because both are valid GPIOs; only flashing real hardware surfaced it.
@bdraco bdraco force-pushed the fix-waveshare-s3-eth-pinout branch from 3d07015 to e56b4a1 Compare June 20, 2026 04:40
@bdraco bdraco marked this pull request as ready for review June 20, 2026 04:41
Copilot AI review requested due to automatic review settings June 20, 2026 04:41
@esphbot

esphbot commented Jun 20, 2026

Copy link
Copy Markdown
Contributor

PR Review — Fix swapped W5500 clk/miso pins on Waveshare ESP32-S3-ETH

Correct, hardware-verified pin swap. Merge-ready.

  • Swaps clk_pin GPIO12→GPIO13 and miso_pin GPIO13→GPIO12 to match Waveshare's documented ETH_DHCP pinout (SCLK GPIO13, MISO GPIO12), fixing the W5500 chip-ID read failure.
  • Change is internally consistent across all three generated artifacts: manifest.yaml featured_components + pin occupied_by annotations, board_bodies/waveshare-esp32-s3-eth.json, and the regenerated featured_components.index.json (omitted from diff but listed as changed; current main still carries the old GPIO12/GPIO13 values, confirming the regen is needed and included).
  • Scope is tight and matches the description — only the two transposed pins touched, MOSI/CS/INT/RST/clock_speed untouched. Correctly labeled bugfix, no frontend change.
  • No test added, but the failure mode (two valid GPIOs that esphome config accepts) is not catchable without real hardware, as the PR notes; script/validate_definitions.py covers manifest structure, not electrical correctness.


Checklist

  • Change internally consistent across generated artifacts
  • Matches documented hardware pinout
  • Generated catalog regenerated, not hand-edited
  • Correct single PR label
  • Scope matches description

Automated review by Kōan (Claude) HEAD=e56b4a1 37s

@esphbot esphbot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No blocking issues found.

@bdraco bdraco merged commit fb8a8d3 into main Jun 20, 2026
13 of 19 checks passed
@bdraco bdraco deleted the fix-waveshare-s3-eth-pinout branch June 20, 2026 04:42
@codspeed-hq

codspeed-hq Bot commented Jun 20, 2026

Copy link
Copy Markdown

Merging this PR will not alter performance

✅ 27 untouched benchmarks


Comparing fix-waveshare-s3-eth-pinout (e56b4a1) with main (221a033)

Open in CodSpeed

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Fixes an incorrect SPI pin mapping in the Waveshare ESP32-S3-ETH board definition so generated configs can reliably initialize the onboard W5500 Ethernet controller at boot.

Changes:

  • Swap W5500 clk_pin and miso_pin values in the Waveshare ESP32-S3-ETH board manifest to match the vendor pinout.
  • Update the corresponding pins[].occupied_by annotations for GPIO12/GPIO13.
  • Regenerate the board body JSON so the shipped catalog reflects the corrected pins.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated no comments.

File Description
esphome_device_builder/definitions/boards/waveshare-esp32-s3-eth/manifest.yaml Corrects W5500 CLK/MISO pin assignments and updates pin-occupancy annotations.
esphome_device_builder/definitions/board_bodies/waveshare-esp32-s3-eth.json Regenerated board body to reflect the corrected featured-component fields and pin labels.

@github-actions github-actions Bot locked and limited conversation to collaborators Jun 21, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

bugfix Bug fix

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants