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. On Linux
, mDNS is provided by avahi and is usually installed by default.
mDNS Properties¶
hostname
: the hostname that the device will respond to. If not set, thehostname
will be read from the interface. Example:my-esp32
will resolve tomy-esp32.local
default_instance
: friendly name for your device, likeJhon'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.proto
: (required) protocol that the service runs on, prepended with underscore. Example:_tcp
or_udp
port
: (required) network port that the service runs oninstance
: friendly name for your service, likeJhon'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: protocols/mdns.
API Reference¶
Header File¶
Functions¶
-
esp_err_t
mdns_init
(tcpip_adapter_if_t tcpip_if, mdns_server_t **server)¶ Initialize mDNS on given interface.
- Return
- ESP_OK on success
- ESP_ERR_INVALID_ARG when bad tcpip_if is given
- ESP_ERR_INVALID_STATE when the network returned error
- ESP_ERR_NO_MEM on memory error
- ESP_ERR_WIFI_NOT_INIT when WiFi is not initialized by eps_wifi_init
- Parameters
tcpip_if
: Interface that the server will listen onserver
: Server pointer to populate on success
-
void
mdns_free
(mdns_server_t *server)¶ Stop and free mDNS server.
- Parameters
server
: mDNS Server to free
-
esp_err_t
mdns_set_hostname
(mdns_server_t *server, const char *hostname)¶ Set the hostname for mDNS server.
- Return
- ESP_OK success
- ESP_ERR_INVALID_ARG Parameter error
- ESP_ERR_NO_MEM memory error
- Parameters
server
: mDNS Serverhostname
: Hostname to set
-
esp_err_t
mdns_set_instance
(mdns_server_t *server, const char *instance)¶ Set the default instance name for mDNS server.
- Return
- ESP_OK success
- ESP_ERR_INVALID_ARG Parameter error
- ESP_ERR_NO_MEM memory error
- Parameters
server
: mDNS Serverinstance
: Instance name to set
-
esp_err_t
mdns_service_add
(mdns_server_t *server, const char *service, const char *proto, uint16_t port)¶ Add service to mDNS server.
- Return
- ESP_OK success
- ESP_ERR_INVALID_ARG Parameter error
- ESP_ERR_NO_MEM memory error
- Parameters
server
: mDNS Serverservice
: service type (_http, _ftp, etc)proto
: service protocol (_tcp, _udp)port
: service port
-
esp_err_t
mdns_service_remove
(mdns_server_t *server, const char *service, const char *proto)¶ Remove service from mDNS server.
- Return
- ESP_OK success
- ESP_ERR_INVALID_ARG Parameter error
- ESP_ERR_NOT_FOUND Service not found
- ESP_FAIL unknown error
- Parameters
server
: mDNS Serverservice
: service type (_http, _ftp, etc)proto
: service protocol (_tcp, _udp)
-
esp_err_t
mdns_service_instance_set
(mdns_server_t *server, const char *service, const char *proto, const char *instance)¶ Set instance name for service.
- Return
- ESP_OK success
- ESP_ERR_INVALID_ARG Parameter error
- ESP_ERR_NOT_FOUND Service not found
- ESP_ERR_NO_MEM memory error
- Parameters
server
: mDNS Serverservice
: service type (_http, _ftp, etc)proto
: service protocol (_tcp, _udp)instance
: instance name to set
-
esp_err_t
mdns_service_txt_set
(mdns_server_t *server, const char *service, const char *proto, uint8_t num_items, const char **txt)¶ Set TXT data for service.
- Return
- ESP_OK success
- ESP_ERR_INVALID_ARG Parameter error
- ESP_ERR_NOT_FOUND Service not found
- ESP_ERR_NO_MEM memory error
- Parameters
server
: mDNS Serverservice
: service type (_http, _ftp, etc)proto
: service protocol (_tcp, _udp)num_items
: number of items in TXT datatxt
: string array of TXT data (eg. {“var=val”,”other=2”})
-
esp_err_t
mdns_service_port_set
(mdns_server_t *server, const char *service, const char *proto, uint16_t port)¶ Set service port.
- Return
- ESP_OK success
- ESP_ERR_INVALID_ARG Parameter error
- ESP_ERR_NOT_FOUND Service not found
- Parameters
server
: mDNS Serverservice
: service type (_http, _ftp, etc)proto
: service protocol (_tcp, _udp)port
: service port
-
esp_err_t
mdns_service_remove_all
(mdns_server_t *server)¶ Remove and free all services from mDNS server.
- Return
- ESP_OK success
- ESP_ERR_INVALID_ARG Parameter error
- Parameters
server
: mDNS Server
-
size_t
mdns_query
(mdns_server_t *server, const char *service, const char *proto, uint32_t timeout)¶ Query mDNS for host or service.
- Return
- the number of results found
- Parameters
server
: mDNS Serverservice
: service type or host nameproto
: service protocol or NULL if searching for hosttimeout
: time to wait for answers. If 0, mdns_query_end MUST be called to end the search
-
size_t
mdns_query_end
(mdns_server_t *server)¶ Stop mDNS Query started with timeout = 0.
- Return
- the number of results found
- Parameters
server
: mDNS Server
-
size_t
mdns_result_get_count
(mdns_server_t *server)¶ get the number of results currently in memoty
- Return
- the number of results
- Parameters
server
: mDNS Server
-
const mdns_result_t *
mdns_result_get
(mdns_server_t *server, size_t num)¶ Get mDNS Search result with given index.
- Return
- the result or NULL if error
- Parameters
server
: mDNS Servernum
: the index of the result
-
esp_err_t
mdns_result_free
(mdns_server_t *server)¶ Remove and free all search results from mDNS server.
- Return
- ESP_OK success
- ESP_ERR_INVALID_ARG Parameter error
- Parameters
server
: mDNS Server
Structures¶
-
struct
mdns_result_s
¶ mDNS query result structure
Public Members
-
const char *
host
¶ hostname
-
const char *
instance
¶ instance
-
const char *
txt
¶ txt data
-
uint16_t
priority
¶ service priority
-
uint16_t
weight
¶ service weight
-
uint16_t
port
¶ service port
-
struct ip4_addr
addr
¶ ip4 address
-
struct ip6_addr
addrv6
¶ ip6 address
-
const struct mdns_result_s *
next
¶ next result, or NULL for the last result in the list
-
const char *
Type Definitions¶
-
typedef struct mdns_server_s
mdns_server_t
¶
-
typedef struct mdns_result_s
mdns_result_t
¶ mDNS query result structure