From e7ea5567256dd47c418c97c225082514e45162fb Mon Sep 17 00:00:00 2001 From: Geza Husi Date: Fri, 29 Nov 2019 12:46:41 +0100 Subject: [PATCH 1/3] Adding documentation of MDNS --- content/firmwareapi/pycom/network/mdns.md | 147 ++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 content/firmwareapi/pycom/network/mdns.md diff --git a/content/firmwareapi/pycom/network/mdns.md b/content/firmwareapi/pycom/network/mdns.md new file mode 100644 index 0000000..0983f58 --- /dev/null +++ b/content/firmwareapi/pycom/network/mdns.md @@ -0,0 +1,147 @@ +--- +title: "MDNS" +aliases: + - firmwareapi/pycom/network/mdns.html + - firmwareapi/pycom/network/mdns.md + - chapter/firmwareapi/pycom/network/mdns +--- +This class provides an interface to use the MDNS functionality. + +## Quick Usage Example + +Example for advertising own services: + +```python +import time +from network import MDNS +# As a first step connection to network should be estbalished, e.g. via WLAN + +# Initialize the MDNS module +MDNS.init() +# Set the hostname and instance name of this device +MDNS.set_name(hostname = "my_hostname", instance_name = "my_instance") +# Add a TCP service to advertise +MDNS.add_service("_http", MDNS.PROTO_TCP, 80) +# Add an UDP service to advertise +MDNS.add_service("_myservice", MDNS.PROTO_UDP, 1234, txt= (("board","esp32"),("u","user"),("p","password"))) + + +# Wait some time and remove 1 service +time.sleep(60) +# Remove a service, it will not be advertised +MDNS.remove_service("_http", MDNS.PROTO_TCP) + +``` + +Example for querying: + +```python +import time +from network import MDNS +# As a first step connection to network should be estbalished, e.g. via WLAN + +# Initialize the MDNS module +MDNS.init() + +# Perform a query for 2000 ms +q = MDNS.query(2000, "_http", MDNS.PROTO_TCP) + +# Print out query's result +if q is not None: + for elem in q: + print(elem.instance_name()) + print(elem.hostname()) + print(elem.addr()) + print(elem.port()) + print(elem.txt()) + +``` + +## Constructor + +### class network.MDNS() + +Initializes the MDNS module. + +## Methods + +#### MDNS.deinit() + +Deinitializes the MDNS module and removes all registered services. + +#### MDNS.set_name(\*, hostname=None, instance_name=None) + +Sets the hostname and instance name of this device to be advertised. + +Arguments are: + +* `hostname` is the hostname to set +* `instance_name` is the instance name to set + +#### MDNS.add_service(service_type, proto, port, \*, txt) + +Adds a service to the MDNS module which will be advertised. + +Arguments are: + +* `service_type` is the type of the offered service, e.g.: _http, _ftp or can be custom. +* `proto` is the Layer 4 protocol (TCP or UDP), can be `MDNS.PROTO_TCP` or `MDNS.PROTO_UDP` +* `port` is the port number +* `txt` is the TXT entries to be placed into the advertisement. The TXT entry is a (key, value) tuple, several TXT entries can be included in an advertisement, in that case this must be given as a list of tuples. + +#### MDNS.remove_service(service_type, proto) + +Removes a service from the MDNS module so it will not be advertised anymore. + +Arguments are: + +* `service_type` is the type of the service, e.g.: _http, _ftp or can be custom. +* `proto` is the Layer 4 protocol (TCP or UDP), can be `MDNS.PROTO_TCP` or `MDNS.PROTO_UDP` + +#### MDNS.query(timeout, service_type, proto, \*, instance_name=None) + +Performs a query with the given parameters. + +Arguments are: + +* `timeout` is the timeout value in miliseconds to be waited for the results +* `service_type` is the type of the service to be queried, e.g.: _http, _ftp or can be custom. +* `proto` is the Layer 4 protocol (TCP or UDP), can be `MDNS.PROTO_TCP` or `MDNS.PROTO_UDP` +* `instance_name` is the instance name of the service to be queried + +If service found, the function returns with List of `MDNS_Query` objects. + +## MDNS_Query class + +The `MDNS_Query` aggregates all the properties of an entry of a successfull query session: +* `hostname` is the hostname of the host advertising the service +* `instance_name` is the instance_name of the service +* `addr` is the IPv4 address belonging to the service +* `port` is the port number belonging to the service +* `txt`is the TXT entries from the advertisement. The TXT entry is a (key, value) tuple, several TXT entries can be included in an advertisement. + +#### MDNS_Query.hostname() + +Returns with the hostname of the queried service. + +#### MDNS_Query.instance_name() + +Returns with the instance name of the queried service. + +#### MDNS_Query.addr() + +Returns with the IPv4 address of the queried service. + +#### MDNS_Query.port() + +Returns with the port of the queried service. + +#### MDNS_Query.txt() + +Returns with the TXT entries of the queried service. + +## Constants + +* TCP and UDP protocol types: `MDNS.PROTO_TCP`, `MDNS.PROTO_UDP` + + From ce79b1270bf5cac66e8123a22996da2d16851209 Mon Sep 17 00:00:00 2001 From: Geza Husi Date: Fri, 29 Nov 2019 16:20:51 +0100 Subject: [PATCH 2/3] Addressing review comments --- content/firmwareapi/pycom/network/mdns.md | 31 +++++++++++------------ 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/content/firmwareapi/pycom/network/mdns.md b/content/firmwareapi/pycom/network/mdns.md index 0983f58..483869d 100644 --- a/content/firmwareapi/pycom/network/mdns.md +++ b/content/firmwareapi/pycom/network/mdns.md @@ -25,10 +25,9 @@ MDNS.add_service("_http", MDNS.PROTO_TCP, 80) # Add an UDP service to advertise MDNS.add_service("_myservice", MDNS.PROTO_UDP, 1234, txt= (("board","esp32"),("u","user"),("p","password"))) - -# Wait some time and remove 1 service +# Wait some time time.sleep(60) -# Remove a service, it will not be advertised +# Remove a service, it will no longer be advertised MDNS.remove_service("_http", MDNS.PROTO_TCP) ``` @@ -46,7 +45,7 @@ MDNS.init() # Perform a query for 2000 ms q = MDNS.query(2000, "_http", MDNS.PROTO_TCP) -# Print out query's result +# Print out the query's result if q is not None: for elem in q: print(elem.instance_name()) @@ -73,7 +72,7 @@ Deinitializes the MDNS module and removes all registered services. Sets the hostname and instance name of this device to be advertised. -Arguments are: +The arguments are: * `hostname` is the hostname to set * `instance_name` is the instance name to set @@ -82,43 +81,43 @@ Arguments are: Adds a service to the MDNS module which will be advertised. -Arguments are: +The arguments are: -* `service_type` is the type of the offered service, e.g.: _http, _ftp or can be custom. +* `service_type` is the type of the offered service, e.g.: _http, _ftp or can be custom service * `proto` is the Layer 4 protocol (TCP or UDP), can be `MDNS.PROTO_TCP` or `MDNS.PROTO_UDP` * `port` is the port number -* `txt` is the TXT entries to be placed into the advertisement. The TXT entry is a (key, value) tuple, several TXT entries can be included in an advertisement, in that case this must be given as a list of tuples. +* `txt` is the TXT entries to be placed into the advertisement. The TXT entry is a (key, value) tuple and several TXT entries can be included in an advertisement. In that case, 'txt' must be given as a list of tuples. #### MDNS.remove_service(service_type, proto) Removes a service from the MDNS module so it will not be advertised anymore. -Arguments are: +The arguments are: -* `service_type` is the type of the service, e.g.: _http, _ftp or can be custom. +* `service_type` is the type of the service, e.g.: _http, _ftp or can be custom service * `proto` is the Layer 4 protocol (TCP or UDP), can be `MDNS.PROTO_TCP` or `MDNS.PROTO_UDP` #### MDNS.query(timeout, service_type, proto, \*, instance_name=None) Performs a query with the given parameters. -Arguments are: +The arguments are: -* `timeout` is the timeout value in miliseconds to be waited for the results -* `service_type` is the type of the service to be queried, e.g.: _http, _ftp or can be custom. +* `timeout` is the timeout value in milliseconds to wait to receive the results +* `service_type` is the type of the service to be queried, e.g.: _http, _ftp or can be custom service * `proto` is the Layer 4 protocol (TCP or UDP), can be `MDNS.PROTO_TCP` or `MDNS.PROTO_UDP` * `instance_name` is the instance name of the service to be queried -If service found, the function returns with List of `MDNS_Query` objects. +If the service is found then the function returns with a list of `MDNS_Query` objects. ## MDNS_Query class -The `MDNS_Query` aggregates all the properties of an entry of a successfull query session: +The `MDNS_Query` aggregates all of the properties of a successful query session entry: * `hostname` is the hostname of the host advertising the service * `instance_name` is the instance_name of the service * `addr` is the IPv4 address belonging to the service * `port` is the port number belonging to the service -* `txt`is the TXT entries from the advertisement. The TXT entry is a (key, value) tuple, several TXT entries can be included in an advertisement. +* `txt` is the TXT entries from the advertisement. The TXT entry is a (key, value) tuple, and several TXT entries can be included in an advertisement. #### MDNS_Query.hostname() From b6115358e4daf8c4ed6b6217cf05577973c3797f Mon Sep 17 00:00:00 2001 From: Geza Husi Date: Fri, 29 Nov 2019 16:41:41 +0100 Subject: [PATCH 3/3] Correct review findings round 2 --- content/firmwareapi/pycom/network/mdns.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/firmwareapi/pycom/network/mdns.md b/content/firmwareapi/pycom/network/mdns.md index 483869d..2986ccd 100644 --- a/content/firmwareapi/pycom/network/mdns.md +++ b/content/firmwareapi/pycom/network/mdns.md @@ -25,8 +25,9 @@ MDNS.add_service("_http", MDNS.PROTO_TCP, 80) # Add an UDP service to advertise MDNS.add_service("_myservice", MDNS.PROTO_UDP, 1234, txt= (("board","esp32"),("u","user"),("p","password"))) -# Wait some time +# Give the other devices time to discover the services offered time.sleep(60) + # Remove a service, it will no longer be advertised MDNS.remove_service("_http", MDNS.PROTO_TCP) @@ -70,7 +71,7 @@ Deinitializes the MDNS module and removes all registered services. #### MDNS.set_name(\*, hostname=None, instance_name=None) -Sets the hostname and instance name of this device to be advertised. +Sets the hostname and instance name of the device that is going to be advertised. The arguments are: