WESP32 + Rust + Ethernet: esp_eth_new_netif_glue() Returns NULL

[wuertele]

I hope this is the right forum!
Hardware and Environment:

Board: WESP32 (ESP32-based board with Ethernet)
Toolchain: Rust set up on macOS following https://docs.esp-rs.org/book, using esp-idf-sys 0.36, esp-idf-svc 0.50

Problem: I’m attempting to bring up the wired Ethernet interface on a WESP32 board in a Rust application. I am using the Rust crates esp-idf-sys and esp-idf-svc to call into the ESP-IDF APIs. I’ve followed the usual pattern (similar to the C examples):

1. Create an esp_eth_mac_t via esp_eth_mac_new_esp32().
2. Create an esp_eth_phy_t via esp_eth_phy_new_rtl8201().
3. Construct an esp_eth_config_t and pass it to esp_eth_driver_install().
4. Call esp_eth_new_netif_glue(eth_handle).

However, esp_eth_new_netif_glue() keeps returning NULL.

Attempts So Far:

1. If I set stack_input: None in the esp_eth_config_t, the result is still NULL when I call esp_eth_new_netif_glue().

2. If I provide a manual bridging function that calls esp_netif_receive(), it also fails.

3. I have discovered that in my esp_idf_sys bindings, the esp_eth_config_t::stack_input expects a function signature of:

   esp_err_t (*stack_input)(esp_eth_handle_t eth_handle, uint8_t *buffer, uint32_t length, void *priv);

   But the netif function esp_netif_receive() has a different signature and expects a pointer to esp_netif_t. So simply forwarding directly to esp_netif_receive() is incorrect.
   In C, the ETH_DEFAULT_CONFIG(mac, phy) macro automatically sets stack_input to _eth_default_input, but that macro is not exposed in my Rust bindings.

What I Suspect:

The built-in IDF function _eth_default_input is normally what “glues” the Ethernet driver handle to the netif. But because I can’t set stack_input to _eth_default_input (not exposed in Rust) and my version of IDF apparently doesn’t fill it in automatically, the pointer remains NULL inside the driver. Then esp_eth_new_netif_glue() sees stack_input is NULL and returns NULL itself.

Questions

1. Has anyone successfully gotten WESP32 Ethernet working in Rust without the ETH_DEFAULT_CONFIG macro? If so, how did you set up the stack_input callback?
2. Is there a known workaround to access _eth_default_input or otherwise replicate that bridging logic so esp_netif_receive() is called properly?
3. Is there a simpler solution, like an alternative function in the IDF that auto-populates stack_input?

Here's my current initialization function. Thank you for any pointers or advice!

pub fn configure_ethernet() -> Result<EspNetif, anyhow::Error> {

let eth_mac_config = eth_mac_config_t {
    sw_reset_timeout_ms: 100,
    rx_task_stack_size: 2048,
    rx_task_prio: 15,
    flags: 0,
};

let eth_esp32_emac_config = eth_esp32_emac_config_t {
    smi_mdc_gpio_num: 16,
    smi_mdio_gpio_num: 17,
    interface: eth_data_interface_t_EMAC_DATA_INTERFACE_RMII,
    clock_config: eth_mac_clock_config_t {
        rmii: eth_mac_clock_config_t__bindgen_ty_2 {
            clock_mode: esp_idf_sys::emac_rmii_clock_mode_t_EMAC_CLK_EXT_IN, // External clock input
            clock_gpio: 0, // GPIO0 as clock input
        },
    },
    dma_burst_len: eth_mac_dma_burst_len_t_ETH_DMA_BURST_LEN_32,
};

let mac = unsafe { esp_eth_mac_new_esp32(&eth_esp32_emac_config as *const _, &eth_mac_config) };
if mac.is_null() {
    panic!("Failed to initialize Ethernet MAC");
}
println!("Initialized Ethernet MAC");

let phy_config = eth_phy_config_t {
    phy_addr: 0,
    reset_timeout_ms: 100,
    autonego_timeout_ms: 4000,
    reset_gpio_num: -1,
};

//let phy = unsafe { esp_eth_phy_new_lan87xx(&phy_config) };
let phy = unsafe { esp_eth_phy_new_rtl8201(&phy_config) };
if phy.is_null() {
    panic!("Failed to initialize Ethernet PHY");
}
println!("Initialized Ethernet PHY");

// Configure Ethernet
let eth_config = esp_eth_config_t {
    mac,
    phy,
    check_link_period_ms: 2000,
    stack_input: None,
    on_lowlevel_init_done: None,
    on_lowlevel_deinit_done: None,
    read_phy_reg: None,
    write_phy_reg: None,
};

let mut eth_handle: esp_eth_handle_t = ptr::null_mut();

let res = unsafe { esp_eth_driver_install(&eth_config, &mut eth_handle) };
if res != ESP_OK || eth_handle.is_null() {
    panic!("Failed to install Ethernet driver: {}", res);
}
println!("Installed Ethernet driver, eth_handle: {:p}", eth_handle);

// Call esp_eth_new_netif_glue and store the returned glue handle
let glue: esp_eth_netif_glue_handle_t = unsafe { esp_eth_new_netif_glue(eth_handle) };
// Check if the glue handle is null (indicating a failure)
if glue.is_null() {
    println!("Glue creation failed. eth_handle: {:p}", eth_handle);
    panic!("Failed to create netif glue. Verify driver installation and eth_handle validity.");
    // HERE IS WHERE MY CODE PANICS
}
println!("Got a non-null glue handle");

// Pass the glue handle to esp_netif_attach
let eth_netif = EspNetif::new(NetifStack::Eth)?;
let res = unsafe { 
    esp_netif_attach(
        eth_netif.handle(), // Pass the raw handle directly
        glue as *mut c_void, // Cast glue to *mut c_void
    ) 
};
if res != ESP_OK {
    panic!("esp_netif_attach failed with error: {}", res);
}
println!("Attached Ethernet netif");

let res = unsafe { esp_eth_start(eth_handle) };
if res != ESP_OK {
    panic!("Failed to start Ethernet");
}
println!("Started Ethernet");

Ok(eth_netif)

}

[ivmarkov]

We have a safe Rust wrapper for the ethernet driver in esp-idf-svc. Why not just using it?

[wuertele]

Thank you! I did not realize this wrapper was available. I tried using it and found that the EthDriver::new_rmii(...) constructor has strict type-level constraints that each RMII signal must be a specific GPIO pin, but some pins for the Wesp32 do not match. According to https://wesp32.com/files/wESP32-Product-Brief.pdf the SMI MDC is 16 and the SMI MDIO pin is 17:

• Ethernet PHY type is RTL8201 from revision 7 boards onward and LAN8720 for older revisions
• PHY interface is RMII
• PHY address is 0
• Clock mode is GPIO0 external input
• PHY power/reset pin is disabled (set to -1)
• SMI MDC pin is 16, SMI MDIO pin is 17

Would you recommend copying the implementation of new_rmii into my program as something like new_rmii_wesp32, or should I fork the crate to remove the compile time pin restrictions?

[ivmarkov]

Before taking any big moves I strongly suggest to try the example on your firmware and see if that works. The pins that cannot be changed are the same on all "boards" because the restriction comes from the esp32 chip itself. Those that can be changed in rhe driver also can be changed in principle.

So if a hard-coded pin appears different on your board, you are either confusing esp32 "gpio" number vs board pin number, or the board documentation is wrong, or our hard-coded pin is wrong and then it has to be changed for all boards. But given that people had confirmed the example works, I doubt a bit the latter is the case.

[wuertele]

The wESP32-product-brief.pdf is very specific, and I am used to specifying GPIO 16 and 17 in ESPHome on this device, so I suspect that the documentation is correct. But I went ahead and tried the example on my hardware. Here is my call to new_rmii:

    let eth_driver = EthDriver::new_rmii(
        peripherals.mac,
        /* rmii_rdx0   */ pins.gpio25,
        /* rmii_rdx1   */ pins.gpio26,
        /* rmii_crs_dv */ pins.gpio27,
        /* rmii_mdc was opins.gpio16 */ pins.gpio23,
        /* rmii_mdio was pins.gpio17  */ pins.gpio22,
        /* rmii_tx_en  */ pins.gpio21,
        /* rmii_txd0   */ pins.gpio19,
        /* rmii_txd1   */ pins.gpio18,
        // Tell the driver we have an external 50MHz clock on GPIO0:

        // was RmiiClockConfig::<gpio::Gpio0, _, _>::Input(pins.gpio0),
        esp_idf_svc::eth::RmiiClockConfig::<gpio::Gpio0, gpio::Gpio16, gpio::Gpio17>::OutputInvertedGpio17(
            pins.gpio17,
        ),

        // No dedicated reset pin on wESP32:
        // was None,
        Some(pins.gpio5),

        // The wESP32 is known to use RTL8201
        // If your board uses LAN87xx, substitute RmiiEthChipset::LAN87XX instead.
        RmiiEthChipset::RTL8201,
        // The PHY address is typically 0 for wESP32:
        Some(0),
        sys_loop.clone(),
    )?;
    let eth = EspEth::wrap(eth_driver)?;

This compiles fine but when deployed to the wESP32, the serial console log outputs this error:

I (572) wifi_test: Starting up...
E (762) rtl8201: rtl8201_init(174): wrong chip ID
E (762) esp_eth: esp_eth_driver_install(229): init phy failed
I (762) esp_idf_svc::eventloop: System event loop dropped
I (762) esp_idf_svc::nvs: NvsDefault dropped
Error: ESP_FAIL

[ivmarkov]

I tried using it and found that the EthDriver::new_rmii(...) constructor has strict type-level constraints that each RMII signal must be a specific GPIO pin, but some pins for the Wesp32 do not match.
According to https://wesp32.com/files/wESP32-Product-Brief.pdf the SMI MDC is 16 and the SMI MDIO pin is 17:

I just looked at our driver source code, and it is actually not true that rmii_mdc and rmii_mdio are hard-coded. In fact, these two, and the optional RST pin are the only 3 configurable pins (putting aside the clk conf). They are configurable, so you can put your gpio 16 and 17 there. Perhaps the example was for another board where these were different.

• Clock mode is GPIO0 external input

But then why:

// was RmiiClockConfig::<gpio::Gpio0, _, _>::Input(pins.gpio0),
        esp_idf_svc::eth::RmiiClockConfig::<gpio::Gpio0, gpio::Gpio16, gpio::Gpio17>::OutputInvertedGpio17(
            pins.gpio17,
        ),

it should be pins.gpio0 there.

Also:

// No dedicated reset pin on wESP32:
        // was None,
        Some(pins.gpio5),

This ^^^ ideally should be none, rather than gpio5, because you say:

• PHY power/reset pin is disabled (set to -1)

[wuertele]

The changes you point out are actually how I tried using this the first time. This is what I tried:

    // Make sure to configure ethernet in sdkconfig and adjust the parameters below for your hardware
    let eth_driver = EthDriver::new_rmii(
        peripherals.mac,
        /* rmii_rdx0   */ pins.gpio25,
        /* rmii_rdx1   */ pins.gpio26,
        /* rmii_crs_dv */ pins.gpio27,
        /* rmii_mdc    */ pins.gpio16,
        /* rmii_mdio   */ pins.gpio17,
        /* rmii_tx_en  */ pins.gpio21,
        /* rmii_txd0   */ pins.gpio19,
        /* rmii_txd1   */ pins.gpio22,
        // Tell the driver we have an external 50MHz clock on GPIO0:
        RmiiClockConfig::<gpio::Gpio0, _, _>::Input(pins.gpio0),
        // No dedicated reset pin on wESP32:
        None,
        // The wESP32 is known to use RTL8201
        // If your board uses LAN87xx, substitute RmiiEthChipset::LAN87XX instead.
        RmiiEthChipset::RTL8201,
        // The PHY address is typically 0 for wESP32:
        Some(0),
        sys_loop.clone(),
    )?;
    let eth = EspEth::wrap(eth_driver)?;

This was the error cargo gave me:

error[E0271]: type mismatch resolving `<Gpio17 as Peripheral>::P == Gpio22`
   --> src/main.rs:78:27
    |
72  |     let eth_driver = EthDriver::new_rmii(
    |                      ------------------- required by a bound introduced by this call
...
78  |         /* rmii_mdio   */ pins.gpio17,
    |                           ^^^^^^^^^^^ expected `Gpio22`, found `Gpio17`
    |
note: required by a bound in `EthDriver::<'d, RmiiEth>::new_rmii`
   --> /Users/dave/.cargo/registry/src/index.crates.io-6f17d22bba15001f/esp-idf-svc-0.50.0/src/eth.rs:354:37
    |
348 |     pub fn new_rmii(
    |            -------- required by a bound in this associated function
...
354 |         _rmii_txd1: impl Peripheral<P = gpio::Gpio22> + 'd,
    |                                     ^^^^^^^^^^^^^^^^ required by this bound in `EthDriver::<'d, RmiiEth>::new_rmii`

For more information about this error, try `rustc --explain E0271`.

[ivmarkov]

But rmii_mdc and rmii_mdio are not next to each other in the driver constructor function. Look at it again (I pasted the link).

[ivmarkov]

BTW, since None can be difficult to express in Rust when the Option type is generic, you might e.g. use turbofish for the "None" RST pin:

Option::<gpio::AnyIOPin>::None

[wuertele]

Oh! Thank you for pointing that out, somehow I mis-ordered those parameters. And your advice about turbofishing the None was right on the money, I was confused about that. Now my code compiles, and appears to be bringing up the Ethernet (testing on an actual link TBD...)