ESP32-Ethernet-Kit A V1.2

Esp32-Ethernet-Kit

The ESP32-Ethernet-Kit A V1.2 is an Espressif development board built around the ESP32, featuring a wired 10/100 Ethernet port via the on-board IP101GRI PHY connected to the ESP32’s internal EMAC over RMII.

The espp::Esp32EthernetKit component provides a singleton hardware abstraction for initializing the Ethernet interface in either DHCP client or DHCP server mode.

DHCP client (default): the ESP32 requests an IP address from an upstream router or switch. The on_link_up callback fires once the DHCP lease is granted.

DHCP server: the ESP32 assigns IP addresses to connected hosts. The interface uses a static IP (default 192.168.4.1/24, configurable via espp::Esp32EthernetKit::ServerConfig). The on_link_up callback fires immediately when the cable is connected. An optional on_client_assigned callback fires each time a DHCP lease is issued to a client.

Warning

GPIO0 / REF_CLK conflict. GPIO0 is both the RMII REF_CLK input (driven by the on-board 50 MHz oscillator) and the ESP32 BOOT strapping pin. Pressing BOOT while Ethernet is active briefly pulls the clock line to GND, disrupting the 50 MHz clock and corrupting active traffic. Do not use GPIO0 as a runtime input while Ethernet is active.

RMII pin mapping (fixed via ESP32 IO_MUX; cannot be reassigned):

Signal	GPIO	Notes
REF_CLK in	0	External 50 MHz oscillator (V1.2)
TX_EN	21	IO_MUX — fixed
TXD0	19	IO_MUX — fixed
TXD1	22	IO_MUX — fixed
CRS_DV	27	IO_MUX — fixed
RXD0	25	IO_MUX — fixed
RXD1	26	IO_MUX — fixed
MDC	23	GPIO matrix — reconfigurable
MDIO	18	GPIO matrix — reconfigurable
PHY_RST	5	Active-low

Official board documentation:

ESP32-Ethernet-Kit Example
- Hardware
- How to build and flash

API Reference

Header File

components/esp32-ethernet-kit/include/esp32-ethernet-kit.hpp

Classes

class Esp32EthernetKit : public espp::BaseComponent 

Board Support Package (BSP) for the Espressif ESP32-Ethernet-Kit A V1.2.

This class provides a singleton interface to the board’s Ethernet peripheral:

10/100 Ethernet via the internal ESP32 EMAC and an IP101GRI RMII PHY

RMII pin mapping (fixed in the ESP32 IO_MUX; cannot be changed). REF_CLK is driven by an external 50 MHz oscillator (EMAC_CLK_EXT_IN):

Signal	GPIO
REF_CLK	0
TX_EN	21
TXD0	19
TXD1	22
CRS_DV	27
RXD0	25
RXD1	26
MDC	23
MDIO	18
PHY_RST	5

The class is a singleton and can be accessed via get().

Example

Get Instance

  auto &board = espp::Esp32EthernetKit::get();

DHCP Server

  espp::Esp32EthernetKit::ServerConfig srv_cfg;
  ip4addr_aton(CONFIG_EXAMPLE_ETH_SERVER_IP, reinterpret_cast<ip4_addr_t *>(&srv_cfg.ip_info.ip));
  ip4addr_aton(CONFIG_EXAMPLE_ETH_SERVER_NETMASK,
               reinterpret_cast<ip4_addr_t *>(&srv_cfg.ip_info.netmask));
  ip4addr_aton(CONFIG_EXAMPLE_ETH_SERVER_GW, reinterpret_cast<ip4_addr_t *>(&srv_cfg.ip_info.gw));
  srv_cfg.on_client_assigned = [&](esp_ip4_addr_t ip, std::array<uint8_t, 6> mac) {
    logger.info("Client assigned {}.{}.{}.{} (mac {:02x}:{:02x}:{:02x}:{:02x}:{:02x}:{:02x})",
                esp_ip4_addr1_16(&ip), esp_ip4_addr2_16(&ip), esp_ip4_addr3_16(&ip),
                esp_ip4_addr4_16(&ip), mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
  };
  bool eth_ok = board.initialize_ethernet({
      .mode = DhcpMode::SERVER,
      .server_config = srv_cfg,
      .on_link_up = [&]() { logger.info("Ethernet link up"); },
      .on_link_down = [&]() { logger.warn("Ethernet link down"); },
      .on_got_ip =
          [&](esp_ip4_addr_t ip) {
            logger.info("DHCP server up at {}.{}.{}.{}", esp_ip4_addr1_16(&ip),
                        esp_ip4_addr2_16(&ip), esp_ip4_addr3_16(&ip), esp_ip4_addr4_16(&ip));
          },
      .on_lost_ip = [&]() { logger.warn("Ethernet lost IP"); },
  });

DHCP Client

  bool eth_ok = board.initialize_ethernet({
      .mode = DhcpMode::CLIENT,
      .on_link_up = [&]() { logger.info("Ethernet link up"); },
      .on_link_down = [&]() { logger.warn("Ethernet link down"); },
      .on_got_ip =
          [&](esp_ip4_addr_t ip) {
            logger.info("DHCP lease acquired: {}.{}.{}.{}", esp_ip4_addr1_16(&ip),
                        esp_ip4_addr2_16(&ip), esp_ip4_addr3_16(&ip), esp_ip4_addr4_16(&ip));
          },
      .on_lost_ip = [&]() { logger.warn("Ethernet lost IP"); },
  });

Public Types

enum class DhcpMode

DHCP operating mode for the Ethernet interface.

Values:

enumerator CLIENT: DHCP client — acquire an IP from an upstream server (default)

enumerator SERVER: DHCP server — assign IPs to hosts connected to this interface.

using client_ip_callback_t = std::function<void(esp_ip4_addr_t ip, std::array<uint8_t, 6> mac)>: Callback invoked (SERVER mode only) each time the DHCP server assigns an IP address to a connected client.

using EthernetLinkCallback = std::function<void()>: Callback invoked when the Ethernet link state changes (comes up or goes down) or when the IP address is lost.

Note

Runs in the ESP-IDF event-loop task context — return quickly, do not block.

using EthernetIpCallback = std::function<void(esp_ip4_addr_t ip)>

Callback invoked when the interface obtains an IPv4 address.

Note

Runs in the ESP-IDF event-loop task context — return quickly, do not block.

Param ip:: The assigned IPv4 address.

Public Functions

bool initialize_ethernet(const EthernetConfig &config)

Initialize the Ethernet interface (EMAC + IP101GRI RMII PHY).

Note

Requires the ESP-IDF default event loop. The BSP creates it if needed.

Parameters:: config – Ethernet configuration (DHCP mode, callbacks). All fields have defaults so EthernetConfig{} gives a plain DHCP-client interface with no callbacks.
Returns:: True if Ethernet was successfully initialized and started.

bool initialize_ethernet()

Initialize Ethernet with default configuration (DHCP client mode).

Returns:: True if Ethernet was successfully initialized and started.

inline bool is_ethernet_connected() const

Check whether the interface has a usable IP address (DHCP lease granted in CLIENT mode, or link is up in SERVER mode).

Returns:: True if the interface is connected with a valid IP.

inline esp_ip4_addr_t ethernet_ip() const

Get the most recently acquired IPv4 address (0 if none).

Returns:: The IPv4 address.

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns:: A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters:: tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns:: The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters:: level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters:: level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns:: The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters:: rate_limit – The rate limit to use for the logger

Public Static Functions

static inline Esp32EthernetKit &get()

Access the singleton instance.

Returns:: Reference to the singleton instance

struct EthernetConfig

Configuration for the Ethernet interface.

Public Members

DhcpMode mode = {DhcpMode::CLIENT}: DHCP operating mode (CLIENT or SERVER).

ServerConfig server_config = {}: Static IP / DHCP server settings — only used when mode == SERVER.

EthernetLinkCallback on_link_up = {nullptr}: Called when the physical link comes up (cable connected + negotiated).

EthernetLinkCallback on_link_down = {nullptr}: Called when the physical link goes down (cable disconnected).

EthernetIpCallback on_got_ip = {nullptr}: Called when the interface is assigned an IPv4 address. CLIENT mode: fired by the DHCP lease. SERVER mode: fired immediately when the link comes up (static IP).

EthernetLinkCallback on_lost_ip = {nullptr}: Called when the interface loses its IPv4 address (DHCP lease loss in CLIENT mode, or link-down in SERVER mode).

struct ServerConfig

Static IP configuration used when operating as a DHCP server. Leave ip_info zero-initialised to use the built-in defaults (192.168.4.1 / 255.255.255.0 / gw 192.168.4.1).

Public Members

esp_netif_ip_info_t ip_info {.ip = 0, .netmask = 0, .gw = 0}: IP / netmask / gateway; zero → 192.168.4.1/24.

client_ip_callback_t on_client_assigned{nullptr}: Called each time a client is assigned an IP.