diff --git a/docs/en/api-guides/lwip.rst b/docs/en/api-guides/lwip.rst index 35c09470adc..1eceef1463b 100644 --- a/docs/en/api-guides/lwip.rst +++ b/docs/en/api-guides/lwip.rst @@ -27,6 +27,8 @@ Some common lwIP app APIs are supported indirectly by ESP-IDF: - Dynamic Host Configuration Protocol (DHCP) Server & Client are supported indirectly via the :doc:`/api-reference/network/esp_netif` functionality. - Domain Name System (DNS) is supported in lwIP; DNS servers could be assigned automatically when acquiring a DHCP address, or manually configured using the :doc:`/api-reference/network/esp_netif` API. + For DNS over HTTPS, see :example:`protocols/dns_over_https`. + .. note:: DNS server configuration in lwIP is global, not interface-specific. If you are using multiple network interfaces with distinct DNS servers, exercise caution to prevent inadvertent overwrites of one interface's DNS settings when acquiring a DHCP lease from another interface. @@ -75,6 +77,10 @@ A number of ESP-IDF examples show how to use the BSD Sockets APIs: - :example:`protocols/sockets/tcp_client` demonstrates how to create a TCP client that connects to a server using a predefined IP address and port. +- :example:`protocols/sockets/tcp_transport_client` demonstrates how to create a TCP client with the ``tcp_transport`` component, including optional SOCKS proxy support. + +- :example:`protocols/http_request` demonstrates a minimal HTTP request over a plain TCP socket using the BSD Sockets API. + - :example:`protocols/sockets/tcp_client_multi_net` demonstrates how to use Ethernet and Wi-Fi interfaces together, connect to both simultaneously, create a TCP client for each interface, and send a basic HTTP request and response. - :example:`protocols/sockets/udp_server` demonstrates how to create a UDP server that receives client connection requests and data. @@ -83,6 +89,12 @@ A number of ESP-IDF examples show how to use the BSD Sockets APIs: - :example:`protocols/sockets/udp_multicast` demonstrates how to use the IPV4 and IPV6 UDP multicast features via the BSD-style sockets interface. +The :doc:`Ethernet driver ` shows the same BSD socket and TCP/IP path over an EMAC-attached interface. Use these reference applications: + +- :example:`ethernet/basic` for driver bring-up, ``esp_netif``, DHCP, and basic IP connectivity. +- :example:`ethernet/iperf` for TCP/UDP throughput measurement on Ethernet. +- :example:`ethernet/ptp` for IEEE 1588 / PTP time synchronization over Ethernet. + Supported Functions ^^^^^^^^^^^^^^^^^^^ @@ -559,7 +571,7 @@ TCP/IP performance is a complex subject, and performance can be optimized toward Maximum Throughput ^^^^^^^^^^^^^^^^^^ -Espressif tests ESP-IDF TCP/IP throughput using the iperf test application: https://iperf.fr/, please refer to :ref:`improve-network-speed` for more details about the actual testing and using the optimized configuration. +Espressif tests ESP-IDF TCP/IP throughput using the iperf test application: https://iperf.fr/, please refer to :ref:`improve-network-speed` for more details about the actual testing and using the optimized configuration. Reference iperf example projects are :example:`wifi/iperf` and :example:`ethernet/iperf`. .. important:: diff --git a/docs/en/api-reference/protocols/icmp_echo.rst b/docs/en/api-reference/protocols/icmp_echo.rst index 5aa1451133a..13b21207ec4 100644 --- a/docs/en/api-reference/protocols/icmp_echo.rst +++ b/docs/en/api-reference/protocols/icmp_echo.rst @@ -114,6 +114,8 @@ Application Examples - :example:`protocols/icmp_echo` demonstrates how to implement a simple ping command line utility to test if a remote host is reachable on the IP network, using ICMP echo request packets. +- :example:`protocols/icmp/pmtu_probe` demonstrates how to probe path MTU with ICMP echo requests and apply the result to the active interface using :cpp:func:`esp_netif_set_mtu`. + API Reference ------------- diff --git a/docs/en/api-reference/protocols/mbedtls.rst b/docs/en/api-reference/protocols/mbedtls.rst index 0920bc9e268..a491e065a1c 100644 --- a/docs/en/api-reference/protocols/mbedtls.rst +++ b/docs/en/api-reference/protocols/mbedtls.rst @@ -176,6 +176,8 @@ Refer to the examples :example:`protocols/https_server/simple` (simple HTTPS ser If you plan to use the Mbed TLS API directly, refer to the example :example:`protocols/https_mbedtls`. This example demonstrates how to establish an HTTPS connection using Mbed TLS by setting up a secure socket with a certificate bundle for verification. +The example :example:`protocols/smtp_client` sends email (including attachments) over SMTP with STARTTLS using the Mbed TLS APIs. + Important Config Options ------------------------ diff --git a/docs/en/api-reference/protocols/mqtt.rst b/docs/en/api-reference/protocols/mqtt.rst index 4b1d2aa3b4d..4c83ca22e04 100644 --- a/docs/en/api-reference/protocols/mqtt.rst +++ b/docs/en/api-reference/protocols/mqtt.rst @@ -26,13 +26,13 @@ Application Examples Two reference examples are available in ESP-IDF: -- MQTT over TLS (certificate bundle): ``examples/protocols/mqtt`` +- MQTT over TLS (certificate bundle): :example:`protocols/mqtt` - Validates the broker with ESP-IDF's certificate bundle (default). - Default broker URI targets ``mqtts://test.mosquitto.org:8886`` (Let's Encrypt chain). - Alternative configuration pins Mosquitto CA and uses ``mqtts://test.mosquitto.org:8883``. -- MQTT 5.0 over TLS (certificate bundle): ``examples/protocols/mqtt5`` +- MQTT 5.0 over TLS (certificate bundle): :example:`protocols/mqtt5` - Uses MQTT v5.0 with TLS and validation via the certificate bundle. - Default broker URI targets ``mqtts://test.mosquitto.org:8886``. diff --git a/docs/en/migration-guides/release-6.x/6.0/protocols.rst b/docs/en/migration-guides/release-6.x/6.0/protocols.rst index 6644764ec5a..1b39c34cd1b 100644 --- a/docs/en/migration-guides/release-6.x/6.0/protocols.rst +++ b/docs/en/migration-guides/release-6.x/6.0/protocols.rst @@ -158,5 +158,5 @@ Breaking change: ESP-MQTT moved to a managed component and example set updated. - Legacy MQTT TLS examples under ``examples/protocols/mqtt/ssl*`` were removed. - New reference examples are available: - - ``examples/protocols/mqtt``: MQTT over TLS. - - ``examples/protocols/mqtt5``: MQTT v5.0 over TLS. + - :example:`protocols/mqtt`: MQTT over TLS. + - :example:`protocols/mqtt5`: MQTT v5.0 over TLS. diff --git a/tools/ci/check_examples_documented.py b/tools/ci/check_examples_documented.py index 910f47acf00..3a80f09b11d 100644 --- a/tools/ci/check_examples_documented.py +++ b/tools/ci/check_examples_documented.py @@ -164,14 +164,6 @@ KNOWN_MISSING = { 'peripherals/usb/host/msc', 'peripherals/usb/host/usb_host_lib', 'peripherals/usb/host/uvc', - # TODO IDF-15383: add :example: references for protocols examples - 'protocols/dns_over_https', - 'protocols/http_request', - 'protocols/icmp/pmtu_probe', - 'protocols/mqtt', - 'protocols/mqtt5', - 'protocols/smtp_client', - 'protocols/sockets/tcp_transport_client', # TODO IDF-15384: add :example: references for wifi examples 'wifi/ftm', 'wifi/wifi_nvs_config',