esp-protocols/docs/mdns/en/index.rst

mDNS Service
============
`[中文] <https://docs.espressif.com/projects/esp-protocols/mdns/docs/latest/zh_CN/index.html>`_

Overview
--------

mDNS is a multicast UDP service that is used to provide local network service and host discovery.

mDNS is installed by default on most operating systems or is available as separate package. On ``Mac OS`` it is installed by default and is called ``Bonjour``. Apple releases an installer for ``Windows`` that can be found `on Apple's support page <https://support.apple.com/downloads/bonjour%2520for%2520windows>`_. On ``Linux``, mDNS is provided by `avahi <https://github.com/lathiat/avahi>`_ and is usually installed by default.

mDNS Properties
^^^^^^^^^^^^^^^

    * ``hostname``: the hostname that the device will respond to. If not set, the ``hostname`` will be read from the interface. Example: ``my-{IDF_TARGET_PATH_NAME}`` will resolve to ``my-{IDF_TARGET_PATH_NAME}.local``
    * ``default_instance``: friendly name for your device, like ``Jhon's {IDF_TARGET_NAME} Thing``. If not set, ``hostname`` will be used.

Example method to start mDNS for the STA interface and set ``hostname`` and ``default_instance``:

.. highlight:: c

::

    void start_mdns_service()
    {
        //initialize mDNS service
        esp_err_t err = mdns_init();
        if (err) {
            printf("MDNS Init failed: %d\n", err);
            return;
        }

        //set hostname
        mdns_hostname_set("my-{IDF_TARGET_PATH_NAME}");
        //set default instance
        mdns_instance_name_set("Jhon's {IDF_TARGET_NAME} Thing");
    }

mDNS Services
^^^^^^^^^^^^^

mDNS can advertise information about network services that your device offers. Each service is defined by a few properties.

    * ``instance_name``: friendly name for your service, like ``Jhon's E{IDF_TARGET_NAME} Web Server``. If not defined, ``default_instance`` will be used.
    * ``service_type``: (required) service type, prepended with underscore. Some common types can be found `here <http://www.dns-sd.org/serviceTypes.html>`_.
    * ``proto``: (required) protocol that the service runs on, prepended with underscore. Example: ``_tcp`` or ``_udp``
    * ``port``: (required) network port that the service runs on
    * ``txt``: ``{var, val}`` array of strings, used to define properties for your service

Please note:
    1. Self-querying names is not supported in Espressif's mDNS library, a deliberate design choice to simplify implementation, preventing local network pollution and addressing WiFi multicast behavior)
    2. Setting your own hostname is a prerequisite(mandatory) for advertising services or delegating other names.

Example method to add a few services and different properties::

    void add_mdns_services()
    {
        //add our services
        mdns_service_add(NULL, "_http", "_tcp", 80, NULL, 0);
        mdns_service_add(NULL, "_arduino", "_tcp", 3232, NULL, 0);
        mdns_service_add(NULL, "_myservice", "_udp", 1234, NULL, 0);

        //NOTE: services must be added before their properties can be set
        //use custom instance for the web server
        mdns_service_instance_name_set("_http", "_tcp", "Jhon's {IDF_TARGET_NAME} Web Server");

        mdns_txt_item_t serviceTxtData[3] = {
            {"board","{{IDF_TARGET_PATH_NAME}}"},
            {"u","user"},
            {"p","password"}
        };
        //set txt data for service (will free and replace current data)
        mdns_service_txt_set("_http", "_tcp", serviceTxtData, 3);

        //change service port
        mdns_service_port_set("_myservice", "_udp", 4321);
    }

mDNS Query
^^^^^^^^^^

mDNS provides methods for browsing for services and resolving host's IP/IPv6 addresses.

Results for services are returned as a linked list of ``mdns_result_t`` objects.

Example method to resolve host IPs::

    void resolve_mdns_host(const char * host_name)
    {
        printf("Query A: %s.local", host_name);

        struct ip4_addr addr;
        addr.addr = 0;

        esp_err_t err = mdns_query_a(host_name, 2000,  &addr);
        if(err){
            if(err == ESP_ERR_NOT_FOUND){
                printf("Host was not found!");
                return;
            }
            printf("Query Failed");
            return;
        }

        printf(IPSTR, IP2STR(&addr));
    }

Example method to resolve local services::

    static const char * if_str[] = {"STA", "AP", "ETH", "MAX"};
    static const char * ip_protocol_str[] = {"V4", "V6", "MAX"};

    void mdns_print_results(mdns_result_t * results){
        mdns_result_t * r = results;
        mdns_ip_addr_t * a = NULL;
        int i = 1, t;
        while(r){
            printf("%d: Interface: %s, Type: %s\n", i++, if_str[r->tcpip_if], ip_protocol_str[r->ip_protocol]);
            if(r->instance_name){
                printf("  PTR : %s\n", r->instance_name);
            }
            if(r->hostname){
                printf("  SRV : %s.local:%u\n", r->hostname, r->port);
            }
            if(r->txt_count){
                printf("  TXT : [%u] ", r->txt_count);
                for(t=0; t<r->txt_count; t++){
                    printf("%s=%s; ", r->txt[t].key, r->txt[t].value);
                }
                printf("\n");
            }
            a = r->addr;
            while(a){
                if(a->addr.type == IPADDR_TYPE_V6){
                    printf("  AAAA: " IPV6STR "\n", IPV62STR(a->addr.u_addr.ip6));
                } else {
                    printf("  A   : " IPSTR "\n", IP2STR(&(a->addr.u_addr.ip4)));
                }
                a = a->next;
            }
            r = r->next;
        }

    }

    void find_mdns_service(const char * service_name, const char * proto)
    {
        ESP_LOGI(TAG, "Query PTR: %s.%s.local", service_name, proto);

        mdns_result_t * results = NULL;
        esp_err_t err = mdns_query_ptr(service_name, proto, 3000, 20,  &results);
        if(err){
            ESP_LOGE(TAG, "Query Failed");
            return;
        }
        if(!results){
            ESP_LOGW(TAG, "No results found!");
            return;
        }

        mdns_print_results(results);
        mdns_query_results_free(results);
    }

Example of using the methods above::

    void my_app_some_method(){
        //search for {IDF_TARGET_PATH_NAME}-mdns.local
        resolve_mdns_host("{IDF_TARGET_PATH_NAME}-mdns");

        //search for HTTP servers
        find_mdns_service("_http", "_tcp");
        //or file servers
        find_mdns_service("_smb", "_tcp"); //windows sharing
        find_mdns_service("_afpovertcp", "_tcp"); //apple sharing
        find_mdns_service("_nfs", "_tcp"); //NFS server
        find_mdns_service("_ftp", "_tcp"); //FTP server
        //or networked printer
        find_mdns_service("_printer", "_tcp");
        find_mdns_service("_ipp", "_tcp");
    }


Performance Optimization
^^^^^^^^^^^^^^^^^^^^^^^^

Execution Speed
^^^^^^^^^^^^^^^

 - mDNS creates a task with default low priority 1 ``CONFIG_MDNS_TASK_PRIORITY`` (If ``CONFIG_FREERTOS_UNICORE`` enabeled it pinned to CPU0 (``CONFIG_MDNS_TASK_AFFINITY``).
 Please check `Maximizing Execution Speed <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/performance/speed.html>`_ for more details.

Minimizing RAM Usage
^^^^^^^^^^^^^^^^^^^^

- mDNS creates a tasks with stack sizes configured by ``CONFIG_MDNS_TASK_STACK_SIZE``.
Please check `Minimizing RAM Usage <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/performance/ram-usage.html>`_ for more details.

Application Example
-------------------

mDNS server/scanner `example <https://github.com/espressif/esp-protocols/tree/master/components/mdns/examples>`_

API Reference
-------------

.. include-build-file:: inc/mdns.inc