This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests.
215 lines
7.1 KiB
ReStructuredText
215 lines
7.1 KiB
ReStructuredText
mDNS Service
|
|
============
|
|
|
|
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-esp32`` will resolve to ``my-esp32.local``
|
|
* ``default_instance``: friendly name for your device, like ``Jhon's ESP32 Thing``. If not set, ``hostname`` will be used.
|
|
|
|
Example method to start mDNS for the STA interface and set ``hostname`` and ``default_instance``:
|
|
|
|
::
|
|
|
|
mdns_server_t * mdns = NULL;
|
|
|
|
void start_mdns_service()
|
|
{
|
|
//initialize mDNS service on STA interface
|
|
esp_err_t err = mdns_init(TCPIP_ADAPTER_IF_STA, &mdns);
|
|
if (err) {
|
|
printf("MDNS Init failed: %d\n", err);
|
|
return;
|
|
}
|
|
|
|
//set hostname
|
|
mdns_set_hostname(mdns, "my-esp32");
|
|
//set default instance
|
|
mdns_set_instance(mdns, "Jhon's ESP32 Thing");
|
|
}
|
|
|
|
mDNS Services
|
|
^^^^^^^^^^^^^
|
|
|
|
mDNS can advertise information about network services that your device offers. Each service is defined by a few properties.
|
|
|
|
* ``service``: (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
|
|
* ``instance``: friendly name for your service, like ``Jhon's ESP32 Web Server``. If not defined, ``default_instance`` will be used.
|
|
* ``txt``: ``var=val`` array of strings, used to define properties for your service
|
|
|
|
Example method to add a few services and different properties:
|
|
|
|
::
|
|
|
|
void add_mdns_services()
|
|
{
|
|
//add our services
|
|
mdns_service_add(mdns, "_http", "_tcp", 80);
|
|
mdns_service_add(mdns, "_arduino", "_tcp", 3232);
|
|
mdns_service_add(mdns, "_myservice", "_udp", 1234);
|
|
|
|
//NOTE: services must be added before their properties can be set
|
|
//use custom instance for the web server
|
|
mdns_service_instance_set(mdns, "_http", "_tcp", "Jhon's ESP32 Web Server");
|
|
|
|
const char * arduTxtData[4] = {
|
|
"board=esp32",
|
|
"tcp_check=no",
|
|
"ssh_upload=no",
|
|
"auth_upload=no"
|
|
};
|
|
//set txt data for service (will free and replace current data)
|
|
mdns_service_txt_set(mdns, "_arduino", "_tcp", 4, arduTxtData);
|
|
|
|
//change service port
|
|
mdns_service_port_set(mdns, "_myservice", "_udp", 4321);
|
|
}
|
|
|
|
mDNS Query
|
|
^^^^^^^^^^
|
|
|
|
mDNS provides methods for browsing for services and resolving host's IP/IPv6 addresses.
|
|
Results are returned as a linked list of ``mdns_result_t`` objects. If the result is from host query,
|
|
it will contain only ``addr`` and ``addrv6`` if found. Service queries will populate all fields
|
|
in a result that were found.
|
|
|
|
Example method to resolve host IPs:
|
|
|
|
::
|
|
|
|
void resolve_mdns_host(const char * hostname)
|
|
{
|
|
printf("mDNS Host Lookup: %s.local\n", hostname);
|
|
//run search for 1000 ms
|
|
if (mdns_query(mdns, hostname, NULL, 1000)) {
|
|
//results were found
|
|
const mdns_result_t * results = mdns_result_get(mdns, 0);
|
|
//itterate through all results
|
|
size_t i = 1;
|
|
while(results) {
|
|
//print result information
|
|
printf(" %u: IP:" IPSTR ", IPv6:" IPV6STR "\n", i++
|
|
IP2STR(&results->addr), IPV62STR(results->addrv6));
|
|
//load next result. Will be NULL if this was the last one
|
|
results = results->next;
|
|
}
|
|
//free the results from memory
|
|
mdns_result_free(mdns);
|
|
} else {
|
|
//host was not found
|
|
printf(" Host Not Found\n");
|
|
}
|
|
}
|
|
|
|
Example method to resolve local services:
|
|
|
|
::
|
|
|
|
void find_mdns_service(const char * service, const char * proto)
|
|
{
|
|
printf("mDNS Service Lookup: %s.%s\n", service, proto);
|
|
//run search for 1000 ms
|
|
if (mdns_query(mdns, service, proto, 1000)) {
|
|
//results were found
|
|
const mdns_result_t * results = mdns_result_get(mdns, 0);
|
|
//itterate through all results
|
|
size_t i = 1;
|
|
while(results) {
|
|
//print result information
|
|
printf(" %u: hostname:%s, instance:\"%s\", IP:" IPSTR ", IPv6:" IPV6STR ", port:%u, txt:%s\n", i++,
|
|
(results->host)?results->host:"NULL", (results->instance)?results->instance:"NULL",
|
|
IP2STR(&results->addr), IPV62STR(results->addrv6),
|
|
results->port, (results->txt)?results->txt:"\r");
|
|
//load next result. Will be NULL if this was the last one
|
|
results = results->next;
|
|
}
|
|
//free the results from memory
|
|
mdns_result_free(mdns);
|
|
} else {
|
|
//service was not found
|
|
printf(" Service Not Found\n");
|
|
}
|
|
}
|
|
|
|
Example of using the methods above:
|
|
|
|
::
|
|
|
|
void my_app_some_method(){
|
|
//search for esp32-mdns.local
|
|
resolve_mdns_host("esp32-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");
|
|
}
|
|
|
|
Application Example
|
|
-------------------
|
|
|
|
mDNS server/scanner example: :example:`protocols/mdns`.
|
|
|
|
API Reference
|
|
-------------
|
|
|
|
Header Files
|
|
^^^^^^^^^^^^
|
|
|
|
* :component_file:`mdns/include/mdns.h`
|
|
|
|
Macros
|
|
^^^^^^
|
|
|
|
|
|
Type Definitions
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
.. doxygentypedef:: mdns_server_t
|
|
.. doxygentypedef:: mdns_result_t
|
|
|
|
Enumerations
|
|
^^^^^^^^^^^^
|
|
|
|
|
|
Structures
|
|
^^^^^^^^^^
|
|
|
|
.. doxygenstruct:: mdns_result_s
|
|
:members:
|
|
|
|
|
|
Functions
|
|
^^^^^^^^^
|
|
|
|
.. doxygenfunction:: mdns_init
|
|
.. doxygenfunction:: mdns_free
|
|
.. doxygenfunction:: mdns_set_hostname
|
|
.. doxygenfunction:: mdns_set_instance
|
|
.. doxygenfunction:: mdns_service_add
|
|
.. doxygenfunction:: mdns_service_remove
|
|
.. doxygenfunction:: mdns_service_instance_set
|
|
.. doxygenfunction:: mdns_service_txt_set
|
|
.. doxygenfunction:: mdns_service_port_set
|
|
.. doxygenfunction:: mdns_service_remove_all
|
|
.. doxygenfunction:: mdns_query
|
|
.. doxygenfunction:: mdns_query_end
|
|
.. doxygenfunction:: mdns_result_get_count
|
|
.. doxygenfunction:: mdns_result_get
|
|
.. doxygenfunction:: mdns_result_free
|
|
|