feat(esp32-ethernet-kit): Add BSP component for esp32-ethernet-kit official development board

[guo-max]

Description

bsp for Esp32-Ethernet-kit-A-v1.2

Motivation and Context

Lots of rtps_embedded example use this board to test. Better to have a bsp for it.

How has this been tested?

Tested with the esp32-ethernt-kit-A-V1.2 as a DHCP server and connect it to a ethernet switch. Connect another dhcp client to the switch and this dev-kit (dhcp Server) should assign a new ip to the client.

Screenshots (if appropriate, e.g. schematic, board, console logs, lab pictures):

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Update
• Hardware (schematic, board, system design) change
• Software change

Checklist:

• My change requires a change to the documentation.
• I have added / updated the documentation related to this change via either README or WIKI

Software

• I have added tests to cover my changes.
• I have updated the .github/workflows/build.yml file to add my new test to the automated cloud build github action.
• All new and existing tests passed.
• My code follows the code style of this project.

Hardware

• I have updated the design files (schematic, board, libraries).
• I have attached the PDFs of the SCH / BRD to this PR
• I have updated the design output (GERBER, BOM) files.

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

Pull request overview

Adds a new ESPP Board Support Package (BSP) component for the Espressif ESP32-Ethernet-Kit A V1.2, including documentation and an example project, to make it easier to bring up Ethernet in DHCP client or DHCP server mode on this commonly used test board.

Changes:

• Introduces the new components/esp32-ethernet-kit component implementing Ethernet init + DHCP client/server support.
• Adds an ESP-IDF example app (with Kconfig options) demonstrating client/server modes.
• Integrates the board/component into the documentation set (Sphinx pages + Doxygen inputs/example paths).

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
doc/en/dev_boards/espressif/index.rst	Adds the new board page to the Espressif dev boards toctree.
doc/en/dev_boards/espressif/esp32_ethernet_kit.rst	New board documentation page describing DHCP modes, warnings, and pin mapping.
doc/en/dev_boards/espressif/esp32_ethernet_kit_example.md	Adds doc page that includes the example README.
doc/Doxyfile	Registers the new component header and example for Doxygen/Sphinx API integration.
components/esp32-ethernet-kit/src/esp32-ethernet-kit.cpp	Implements Ethernet bring-up, event handling, and DHCP client/server behavior.
components/esp32-ethernet-kit/include/esp32-ethernet-kit.hpp	Public BSP API for initializing Ethernet and receiving link/IP callbacks.
components/esp32-ethernet-kit/README.md	Component-level README documenting capabilities and usage snippets.
components/esp32-ethernet-kit/idf_component.yml	ESP Component Manager manifest for publishing/consuming the component.
components/esp32-ethernet-kit/CMakeLists.txt	Component build registration and dependencies for ESP-IDF.
components/esp32-ethernet-kit/example/CMakeLists.txt	Example project CMake configuration wiring in repository components.
components/esp32-ethernet-kit/example/sdkconfig.defaults	Example defaults enabling Ethernet + PHY and related settings.
components/esp32-ethernet-kit/example/README.md	Example README with build/flash instructions.
components/esp32-ethernet-kit/example/main/CMakeLists.txt	Example “main” component registration for ESP-IDF build.
components/esp32-ethernet-kit/example/main/Kconfig.projbuild	Kconfig options for selecting DHCP mode and server static IP parameters.
components/esp32-ethernet-kit/example/main/esp32_ethernet_kit_example.cpp	Example app demonstrating DHCP client or DHCP server operation.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (5)

doc/Doxyfile:108

• The Doxyfile EXAMPLE_PATH list is intended to be kept sorted; this new entry is currently out of order relative to the other esp32-* board examples (and also leaves esp32-p4-function-ev-board before esp32-timer-cam). Reorder this local block to keep the list consistent and easier to maintain.

  $(PROJECT_PATH)/components/esp32-timer-cam/example/main/esp_timer_cam_example.cpp \
  $(PROJECT_PATH)/components/esp32-ethernet-kit/example/main/esp32_ethernet_kit_example.cpp \
  $(PROJECT_PATH)/components/esp32-p4-function-ev-board/example/main/esp32_p4_function_ev_board_example.cpp \

doc/Doxyfile:260

• The Doxyfile INPUT list is intended to be kept sorted; this new header entry is currently out of order relative to the other esp32-* board headers (and also leaves esp32-p4-function-ev-board before esp32-timer-cam). Reorder this local block to keep the list consistent and easier to maintain.

  $(PROJECT_PATH)/components/esp32-timer-cam/include/esp32-timer-cam.hpp \
  $(PROJECT_PATH)/components/esp32-ethernet-kit/include/esp32-ethernet-kit.hpp \
  $(PROJECT_PATH)/components/esp32-p4-function-ev-board/include/esp32-p4-function-ev-board.hpp \

components/esp32-ethernet-kit/src/esp32-ethernet-kit.cpp:179

• esp_netif_init() returns ESP_ERR_INVALID_STATE if the netif stack was already initialized elsewhere (e.g. another component called it first). Treating that as fatal makes initialize_ethernet() fail in valid application setups. Other code in this repo (e.g. components/wifi/include/wifi.hpp) treats ESP_ERR_INVALID_STATE as a no-op/success for init calls.

  ret = esp_netif_init();
  if (ret != ESP_OK) {
    logger_.error("esp_netif_init failed: {}", esp_err_to_name(ret));
    return false;
  }

components/esp32-ethernet-kit/idf_component.yml:20

• idf_component.yml dependency format for idf is inconsistent with other components in this repo (they use the nested version: key). Using idf: ">=5.0" may not be accepted by the IDF Component Manager and can break publishing/build tooling.

dependencies:
  idf: ">=5.0"
  espp/base_component: ">=1.0"

components/esp32-ethernet-kit/idf_component.yml:11

• This PR adds a new component + example, but the repository’s CI/publishing lists don’t include it yet. build.yml's matrix includes other BSP examples (e.g. components/esp32-timer-cam/example, components/esp32-p4-function-ev-board/example) but not components/esp32-ethernet-kit/example, and upload_components.yml includes other BSP components (e.g. components/esp32-timer-cam, components/esp32-p4-function-ev-board) but not components/esp32-ethernet-kit. Without those updates, the example won’t be built in CI and the component won’t be included in the upload workflow.

documentation: "https://esp-cpp.github.io/espp/dev_boards/espressif/esp32_ethernet_kit.html"
examples:
  - path: example
tags:

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (9)

doc/Doxyfile:109

• The new entry was added in the middle of the existing list, but the EXAMPLE_PATH section is now out of alphabetical order (esp32-* entries are not sorted). This makes future merges/conflict resolution harder and violates the repo’s “keep Doxyfile entries alphabetically sorted” convention.

  $(PROJECT_PATH)/components/encoder/example/main/encoder_example.cpp \
  $(PROJECT_PATH)/components/esp32-timer-cam/example/main/esp_timer_cam_example.cpp \
  $(PROJECT_PATH)/components/esp32-ethernet-kit/example/main/esp32_ethernet_kit_example.cpp \
  $(PROJECT_PATH)/components/esp32-p4-function-ev-board/example/main/esp32_p4_function_ev_board_example.cpp \
  $(PROJECT_PATH)/components/esp-box/example/main/esp_box_example.cpp \

doc/Doxyfile:261

• The INPUT list is no longer in alphabetical order after adding the new header entry (esp32-* headers are not sorted). Please keep this section sorted to match the convention used elsewhere in the repo.

  $(PROJECT_PATH)/components/encoder/include/encoder_types.hpp \
  $(PROJECT_PATH)/components/esp32-timer-cam/include/esp32-timer-cam.hpp \
  $(PROJECT_PATH)/components/esp32-ethernet-kit/include/esp32-ethernet-kit.hpp \
  $(PROJECT_PATH)/components/esp32-p4-function-ev-board/include/esp32-p4-function-ev-board.hpp \
  $(PROJECT_PATH)/components/esp-box/include/esp-box.hpp \

components/esp32-ethernet-kit/src/esp32-ethernet-kit.cpp:276

• esp_netif_init() commonly returns ESP_ERR_INVALID_STATE when the netif layer has already been initialized by the application (similar to how you already handle esp_event_loop_create_default). Treating that as a hard error can make initialize_ethernet() fail in otherwise-valid apps.

  ret = esp_netif_init();
  if (ret != ESP_OK) {
    return fail("esp_netif_init failed", ret);
  }

components/esp32-ethernet-kit/README.md:27

• In DHCP client mode, the code invokes on_link_up on ETHERNET_EVENT_CONNECTED (link up), and invokes on_got_ip on IP_EVENT_ETH_GOT_IP (lease granted). This paragraph currently says on_link_up fires once the lease is granted, which is inconsistent with the implementation and the EthernetConfig field docs.

The `on_link_up` callback fires once the DHCP lease is granted.

components/esp32-ethernet-kit/README.md:36

• This snippet calls initialize_ethernet with a callback + mode parameter, but the actual API takes a single EthernetConfig argument. Updating the example to match the struct-based API prevents compile errors for users following the README.

board.initialize_ethernet(
    [](esp_ip4_addr_t ip) {
      // called when lease is acquired
    },
    espp::Esp32EthernetKit::DhcpMode::CLIENT); // default — can be omitted

components/esp32-ethernet-kit/README.md:67

• This DHCP-server example uses the old multi-argument initialize_ethernet call signature. The implementation expects a single EthernetConfig argument (with .mode and .server_config set).

board.initialize_ethernet(
    [](esp_ip4_addr_t ip) {
      // called when link is up (static IP is already known)
    },
    DhcpMode::SERVER,

components/esp32-ethernet-kit/README.md:22

• This README describes initialize_ethernet as taking a DhcpMode parameter, but the public API in esp32-ethernet-kit.hpp exposes initialize_ethernet(const EthernetConfig&) (plus a no-arg default). Keeping the README aligned with the actual API avoids copy/paste usage errors.

This issue also appears in the following locations of the same file:

• line 27
• line 32
• line 63

`initialize_ethernet` accepts a `DhcpMode` parameter (default `CLIENT`).

doc/en/dev_boards/espressif/esp32_ethernet_kit.rst:17

• The DHCP client description says on_link_up fires once the DHCP lease is granted, but the implementation triggers on_link_up on link-up and on_got_ip when the lease is granted. This documentation mismatch can lead users to wire callbacks incorrectly.

**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.

components/esp32-ethernet-kit/idf_component.yml:10

• This PR adds a new component + example, but CI configuration doesn’t currently reference components/esp32-ethernet-kit at all (no entry in .github/workflows/build.yml matrix, and no entry in .github/workflows/upload_components.yml components: list). Without those updates, the example won’t be built in CI and the registry dry-run won’t validate/publish the new component.

examples:
  - path: example

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (4)

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

• ServerConfig::ip_info uses a designated initializer assigning integers to esp_netif_ip_info_t subfields (.ip = 0, etc.). Since the implementation later accesses ip_info.ip.addr, these fields are structs, so this initializer is likely ill-formed in C++ and can break compilation. Use value-initialization ({}) to zero the whole struct instead.

  struct ServerConfig {
    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{

components/esp32-ethernet-kit/src/esp32-ethernet-kit.cpp:276

• esp_netif_init() can legally return ESP_ERR_INVALID_STATE when the netif stack is already initialized (e.g. by other networking components). Treating that as a hard failure makes initialize_ethernet() unexpectedly fail in multi-component apps.

  ret = esp_netif_init();
  if (ret != ESP_OK) {
    return fail("esp_netif_init failed", ret);
  }

components/esp32-ethernet-kit/example/main/esp32_ethernet_kit_example.cpp:35

• The example ignores the return value of ip4addr_aton(...). If the user enters an invalid IP/netmask/gateway in Kconfig, srv_cfg.ip_info may contain zeros/garbage and the example will behave unexpectedly. Validate the inputs and fall back to defaults (all-zero ip_info) when parsing fails.

  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));

components/esp32-ethernet-kit/CMakeLists.txt:10

• This PR adds a new component + example, but it doesn’t add the corresponding CI entries (example build matrix in .github/workflows/build.yml and component list entry in .github/workflows/upload_components.yml). Without those, the new BSP won’t be built/tested in CI or published consistently with other components.

idf_component_register(
  INCLUDE_DIRS "include"
  SRC_DIRS "src"
  REQUIRES
    "base_component"
    "esp_eth"
    "esp_netif"
    "esp_event"
  REQUIRED_IDF_TARGETS "esp32"
  )