295 lines
10 KiB
Markdown
295 lines
10 KiB
Markdown
End-to-end setup for a Waveshare ESP32-S3-ETH board (W5500 ethernet over SPI), using the `std` Rust toolchain (`esp-idf-svc`). By the end you'll have a project that connects to ethernet, gets a DHCP lease, and is structured to build real functionality on top of.
|
||
|
||
This walkthough was AI generated
|
||
|
||
---
|
||
|
||
## 0. Hardware reference
|
||
|
||
Confirm these against your board's silkscreen before wiring anything extra — Waveshare's pin assignments have varied slightly across production batches.
|
||
|
||
|Signal|GPIO|
|
||
|---|---|
|
||
|SCLK|13|
|
||
|MOSI (SDO)|11|
|
||
|MISO (SDI)|12|
|
||
|CS|14|
|
||
|INT|10|
|
||
|RST|9|
|
||
|SPI host|SPI2|
|
||
|SPI clock|20–25 MHz|
|
||
|
||
The W5500 has no burned-in MAC address — you supply one in software (any locally-administered address, e.g. `02:00:00:12:34:56`, works).
|
||
|
||
---
|
||
|
||
## 1. Prerequisites
|
||
|
||
- USB-C cable, board connected to your dev machine.
|
||
- ~5GB free disk space (toolchain + ESP-IDF + submodules).
|
||
- Linux/macOS/WSL. (Windows native works too but paths below assume a POSIX shell.)
|
||
- `git`, a C compiler, `python3`, and standard build tools already on the system (`build-essential` on Debian/Ubuntu, or equivalent).
|
||
|
||
---
|
||
|
||
## 2. Install the Rust + Espressif toolchain
|
||
|
||
```bash
|
||
# Rust itself, if not already installed
|
||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||
|
||
# espup: installs the Xtensa-patched Rust toolchain ESP32-S3 needs
|
||
cargo install espup
|
||
cargo install ldproxy
|
||
espup install
|
||
|
||
# Load the Xtensa toolchain into your shell (needed every new shell)
|
||
. $HOME/export-esp.sh
|
||
```
|
||
|
||
Add the `. $HOME/export-esp.sh` line to your shell rc file (`.bashrc`/`.zshrc`/`config.fish`) so you don't have to re-run it manually every session.
|
||
|
||
Verify the Xtensa target is present:
|
||
|
||
```bash
|
||
rustc --print target-list | grep xtensa
|
||
```
|
||
|
||
You should see `xtensa-esp32s3-none-elf` and similar in the output.
|
||
|
||
---
|
||
|
||
## 3. Scaffold the project
|
||
|
||
Use `esp-idf-template`, **not** `esp-generate` — the latter scaffolds `no_std`/`esp-hal` projects, which have no W5500/ethernet driver and no standard HTTP server story.
|
||
|
||
```bash
|
||
cargo install cargo-generate
|
||
cargo generate esp-rs/esp-idf-template cargo
|
||
```
|
||
|
||
You'll be prompted interactively. Answers for this board/use case:
|
||
|
||
|Prompt|Answer|Why|
|
||
|---|---|---|
|
||
|Project name|your choice||
|
||
|MCU|`esp32s3`|matches this board|
|
||
|Configure advanced options?|Yes|need to reach the STD toggle below|
|
||
|STD support|**Yes**|pulls in `esp-idf-svc`; without this you're back on `no_std`|
|
||
|ESP-IDF version|`v5.3.4`|most stable match to current esp-idf-svc/hal crates; avoid `master`|
|
||
|Use git (not crates.io) esp-idf-* crates|**false**|crates.io releases are stable and documented; git HEAD drifts underneath you|
|
||
|Installation location of managed ESP-IDF|**global**|shared across projects, avoids re-downloading ~1–2GB per project|
|
||
|Configure Dev Containers?|false|flashing real hardware over USB is simpler done natively|
|
||
|Configure Wokwi simulation?|false|Wokwi doesn't model the W5500/ethernet peripheral|
|
||
|Add CI files?|false|add later if/when you push to GitHub|
|
||
|
||
This produces:
|
||
|
||
```
|
||
your-project/
|
||
├── .cargo/config.toml
|
||
├── Cargo.toml
|
||
├── build.rs
|
||
├── rust-toolchain.toml
|
||
├── sdkconfig.defaults
|
||
└── src/main.rs
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Confirm the generated build target
|
||
|
||
Open `.cargo/config.toml` and confirm:
|
||
|
||
```toml
|
||
[build]
|
||
target = "xtensa-esp32s3-espidf"
|
||
```
|
||
|
||
If this is missing or wrong, `cargo build` will silently try to compile for your host machine instead of the chip and fail with `Unsupported target 'x86_64-unknown-linux-gnu'` (or similar). The template sets this correctly by default — just verify it.
|
||
|
||
---
|
||
|
||
## 5. Configure sdkconfig.defaults
|
||
|
||
Edit `sdkconfig.defaults` (created empty or near-empty by the template) to include:
|
||
|
||
```
|
||
CONFIG_ETH_SPI_ETHERNET_W5500=y
|
||
CONFIG_ESP_MAIN_TASK_STACK_SIZE=8000
|
||
CONFIG_HTTPD_MAX_REQ_HDR_LEN=1024
|
||
```
|
||
|
||
The first line is required — without it, ESP-IDF doesn't build the W5500 driver component in at all, and your ethernet code will fail to link or fail at runtime. The other two are reasonable general-purpose values (headroom for the main task stack, generous HTTP header limit if you add a server later).
|
||
|
||
---
|
||
|
||
## 6. Configure Cargo.toml
|
||
|
||
Replace the `[dependencies]` section with at minimum:
|
||
|
||
```toml
|
||
[dependencies]
|
||
esp-idf-svc = { version = "0.51", features = ["std"] }
|
||
anyhow = "1"
|
||
log = "0.4"
|
||
```
|
||
|
||
Add more crates as your project needs them — see the companion note on porting non-embedded dependencies if you're bringing code over from another platform.
|
||
|
||
---
|
||
|
||
## 7. First build (this installs ESP-IDF itself)
|
||
|
||
```bash
|
||
cargo build --release
|
||
```
|
||
|
||
The **first** build does a lot of one-time work: downloads ESP-IDF, sets up a Python virtualenv, installs `xtensa-esp-elf`, `esp-clang`, `cmake`, `ninja`, and more. Expect this to take 10–20+ minutes and several GB of downloads. Subsequent builds are fast.
|
||
|
||
### Known first-build failure points
|
||
|
||
These are common enough to check for proactively rather than debug blind:
|
||
|
||
**a) `esp-clang: error while loading shared libraries: libxml2.so.2`** Rolling-release Linux distros (Arch-based, etc.) ship a newer libxml2 soname than the pinned esp-clang binary expects. Fix:
|
||
|
||
```bash
|
||
ldconfig -p | grep libxml2 # find your installed version, e.g. libxml2.so.16
|
||
sudo ln -s /usr/lib/libxml2.so.16 /usr/lib/libxml2.so.2 # adjust path/version to match
|
||
sudo ldconfig
|
||
ls -la /usr/lib/libxml2.so.2
|
||
```
|
||
The final command should show a symlink of libxml2.so.2 to libxml2.so.16
|
||
|
||
**b) `Missing esp-mqtt submodule` / CMake `git_submodule_check` errors** The managed ESP-IDF checkout needs its git submodules initialized (several components are submodules even if your project doesn't use them):
|
||
|
||
```bash
|
||
cd .embuild/espressif/esp-idf/v5.3.4
|
||
git submodule update --init --recursive
|
||
cd -
|
||
cargo build --release
|
||
```
|
||
|
||
If that's still broken, delete and let it re-clone fresh: `rm -rf .embuild/espressif/esp-idf/v5.3.4`.
|
||
|
||
A successful build ends with a normal `Compiling <your-project>` / `Finished release` output.
|
||
|
||
---
|
||
|
||
## 8. Write a minimal ethernet-only main.rs
|
||
|
||
This is the "ready for proper code" checkpoint — confirms SPI, the W5500, and DHCP all work before you build real functionality on top:
|
||
|
||
```rust
|
||
use std::thread;
|
||
use std::time::Duration;
|
||
|
||
use esp_idf_svc::eth::{BlockingEth, EspEth, EthDriver, SpiEthChipset};
|
||
use esp_idf_svc::eventloop::EspSystemEventLoop;
|
||
use esp_idf_svc::hal::peripherals::Peripherals;
|
||
use esp_idf_svc::hal::prelude::*;
|
||
use esp_idf_svc::hal::spi::{config::DriverConfig, Dma, SpiDriver};
|
||
use log::info;
|
||
|
||
fn main() -> anyhow::Result<()> {
|
||
esp_idf_svc::sys::link_patches();
|
||
esp_idf_svc::log::EspLogger::initialize_default();
|
||
|
||
let peripherals = Peripherals::take()?;
|
||
let sysloop = EspSystemEventLoop::take()?;
|
||
let pins = peripherals.pins;
|
||
|
||
let spi_driver = SpiDriver::new(
|
||
peripherals.spi2,
|
||
pins.gpio13, // SCLK
|
||
pins.gpio11, // MOSI
|
||
Some(pins.gpio12), // MISO
|
||
&DriverConfig {
|
||
dma: Dma::Auto(4096), // required — default (no DMA) can't move full ethernet frames
|
||
..Default::default()
|
||
},
|
||
)?;
|
||
|
||
let eth_driver = EthDriver::new_spi(
|
||
spi_driver,
|
||
pins.gpio10, // INT
|
||
Some(pins.gpio14), // CS
|
||
Some(pins.gpio9), // RST
|
||
SpiEthChipset::W5500,
|
||
20.MHz().into(),
|
||
Some(&[0x02, 0x00, 0x00, 0x12, 0x34, 0x56]), // locally-administered MAC
|
||
None, // default PHY address
|
||
sysloop.clone(),
|
||
)?;
|
||
|
||
let eth = EspEth::wrap(eth_driver)?;
|
||
let mut eth = BlockingEth::wrap(eth, sysloop)?;
|
||
|
||
info!("Starting eth...");
|
||
eth.start()?;
|
||
info!("Waiting for DHCP lease...");
|
||
eth.wait_netif_up()?;
|
||
|
||
let ip_info = eth.eth().netif().get_ip_info()?;
|
||
info!("Got IP: {:?}", ip_info);
|
||
|
||
loop {
|
||
thread::sleep(Duration::from_secs(1));
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. Flash and verify
|
||
|
||
```bash
|
||
cargo install espflash # one-time, if not already installed
|
||
cargo build --release
|
||
espflash flash --monitor target/xtensa-esp32s3-espidf/release/<your-project-name>
|
||
```
|
||
|
||
If Linux user needs permission for port access:
|
||
```shell
|
||
sudo usermod -aG uucp $USER # Arch Systems
|
||
|
||
sudo usermod -aG dialout $USER # Debian Systems
|
||
```
|
||
Then reboot.
|
||
|
||
Watch the serial monitor. Success looks like:
|
||
|
||
```
|
||
I (...) esp_idf_svc::eth: Driver initialized
|
||
I (...) hello_eth: Starting eth...
|
||
I (...) hello_eth: Waiting for DHCP lease...
|
||
I (...) hello_eth: Got IP: ...
|
||
```
|
||
|
||
If it hangs after "Waiting for DHCP lease..." with repeating `w5500.mac: w5500_spi_write failed` / `w5500_spi_read failed` errors in the log, the SPI bus doesn't have DMA enabled — double check the `Dma::Auto(4096)` line in step 8 is present.
|
||
|
||
If it hangs with no errors at all and no IP, check physically: ethernet cable plugged into a live switch/router port, link LED on the RJ45 jack lit.
|
||
|
||
---
|
||
|
||
## 10. You're ready to build on this
|
||
|
||
At this point you have a project that: builds for the correct target, links the W5500 driver, brings up ethernet, and gets a DHCP lease. From here, typical next additions:
|
||
|
||
- An HTTP server (`esp_idf_svc::http::server::EspHttpServer`)
|
||
- GPIO for LEDs/buttons/sensors (`esp_idf_svc::hal::gpio::PinDriver`)
|
||
- SPI/I2C peripherals sharing the bus alongside the W5500 (own CS pin, same or different SPI host)
|
||
- Async networking (`tokio`, `async-nats`, etc.) — needs additional rustflags and feature trimming; see the note on porting non-embedded async code if relevant to your project
|
||
|
||
---
|
||
|
||
## Quick-reference: build error → fix
|
||
|
||
|Error|Cause|Fix|
|
||
|---|---|---|
|
||
|`Unsupported target 'x86_64-unknown-linux-gnu'`|`.cargo/config.toml` target missing/wrong, or Xtensa toolchain not loaded in shell|Check `target = "xtensa-esp32s3-espidf"`; re-run `. $HOME/export-esp.sh`|
|
||
|`esp-clang: ... libxml2.so.2`|Host libxml2 soname mismatch|Symlink to your installed version (§7a)|
|
||
|`Missing esp-mqtt submodule` / CMake errors|Managed ESP-IDF checkout missing submodules|`git submodule update --init --recursive` in the IDF checkout (§7b)|
|
||
|`txdata transfer > host maximum` / w5500 read/write failures|SPI DMA disabled|`Dma::Auto(4096)` in `DriverConfig`|
|
||
|`EthDriver::new_spi` argument/type errors|API differs across esp-idf-svc versions|Match the compiler's reported signature exactly, not older examples/tutorials|
|
||
|No W5500 driver at runtime|`CONFIG_ETH_SPI_ETHERNET_W5500=y` missing from sdkconfig.defaults|Add it, rebuild| |