 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
Multicast DNS/DNS-SD (mDNS) is a protocol that helps in resolving the hostname to IP address in a local network. The mDNS and DNS-SD are protocols designed to augment the traditional DNS service. mDNS provides hostname and service lookup to the nodes on the local network. Each node uses an IPv4 or IPv6 multicast channel to announce services it offers to its neighbors, responds to queries from its neighbors, and sends queries on behalf of its applications. Throughout the document, the term mDNS refers to the services that cover both the mDNS specification and the DNS-SD specification.
The NetX Duo mDNS/DNS-SD Support module defines APIs for creating the mDNS instances, setting domain name, adding mDNS services, performing a one-shot and continuous discovery. A complete list of the available APIs, an example API call, and a short description of each can be found in the following table. A table of status return values follows the API summary table.
NetX Duo mDNS Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_mdns_create | nx_mdns_create(&my_mdns, &my_ip, &my_packet_pool, priority,stack_ptr, sizeof(stack_ptr), "NETX-MDNS-HOST", local_cache_ptr, sizeof(local_cache_ptr), peer_cache_ptr, sizeof(peer_cache_ptr), probing_notify);Creates an mDNS instance on the specific IP instance and associated resources. |
| nx_mdns_delete | nx_mdns_delete(&my_mdns);deletes the mDNS instance and frees its resources. |
| nx_mdns_enable | nx_mdns_enable(&my_mdns, interface_index);Enables mDNS service on a specific physical interface. Once the service is enabled, the mDNS module first probes all its unique service names on the network before responding to queries received on the interface. |
| nx_mdns_disable | nx_mdns_disable(&my_mdns, interface_index);Disables mDNS service on the specific physical interface. Once the service is disabled, the mDNS sends "goodbye" messages for every local service to the network that is attached to the interface, so the neighboring nodes are notified. |
| nx_mdns_cache_notify_set | nx_mdns_cache_notify_set(&my_mdns, cache_full_nofiy_cb);This service installs a user-supplied callback function, which is invoked when either the local service cache or peer service cache becomes full. |
| nx_mdns_cache_notify_clear | nx_mdns_cache_notify_clear(&my_mdns);Clears a user-supplied service cache notify callback function. |
| nx_mdns_domain_name_set | nx_mdns_domain_name_set(&my_mdns, "home");This service sets up the default local domain name. When the mDNS instance is created, the default local domain name is set to ".local". This API allows an application to overwrite the default local domain name. |
| nx_mdns_service_announcement_timing_set | nx_mdns_service_announcement_timing_set(&my_mdns, t, p, k, retrans_interval, period_interval, max_time);This service reconfigures the timing parameters employed by mDNS when sending the service announcements. Publish period starts from t ticks and can be expanded telescopically with 2 to the power of k factor. The number of repetitions per advertisement is p, the interval between each repeated advertisement is interval ticks, and Maximum announcement period is max_time. |
| nx_mdns_service_add | nx_mdns_service_add(&my_mdns, "NETX-SERVICE", "_http._tcp", NX_NULL, NX_NULL, 0, priority, weight, port,is_unique, interface);This API registers a service offered by the application. If the flag is_unique is set, mDNS probes the service name to make sure it is unique on the local network before starting to announce the service on the network. |
| nx_mdns_service_delete | nx_mdns_service_delete(&my_mdns, "NETX-SERVICE", "_http._tcp", NX_NULL);This API deletes a previous registered service. As the service is deleted, "goodbye" messages are sent to the local network so the neighboring nodes are notified. |
| nx_mdns_service_one_shot_query | nx_mdns_service_one_shot_query(&my_mdns, "NETX-SERVICE", "_http._tcp", NX_NULL, service_ptr, wait_option);This service performs a one-shot mDNS query. If the specified service is found in the peer service cache, the first instance is returned. If no services are found in the local peer service cache, the mDNS module issues a query command and waits for a response. |
| nx_mdns_service_continuous_query | nx_mdns_service_continuous_query(&my_mdns,"NETX-SERVICE", "_http._tcp", NX_NULL);This service starts a continuous query. Note that the service returns immediately. After issuing a continuous query, the application may retrieve service records by using the API nx_mdns_service_lookup. |
| nx_mdns_service_query_stop | nx_mdns_service_query_stop(&my_mdns, "NETX-SERVICE", "_http._tcp", NX_NULL);Terminates the previous issued continuous service discovery. |
| nx_mdns_service_lookup | nx_mdns_service_lookup(&my_mdns, "NETX-SERVICE", "_http._tcp", NX_NULL, 0, service_ptr);This service looks up services matching the instance name (if provided) and the type of service in the local peer service cache. |
| nx_mdns_service_ignore_set | nx_mdns_service_ignore_set(&my_mdns, service_mask);This API configures a mask to ignore services specified by the service_mask bitmask. User may optionally use the service_mask to select service types it does not wish to be cached. |
| nx_mdns_service_notify_set | nx_mdns_service_notify_set(&my_mdns, service_mask, service_change_notify);This API configures a service change notify callback function. This callback function is invoked when a service offered by other nodes on the network is added, changed, or is no longer available. |
| nx_mdns_service_notify_clear | nx_mdns_service_notify_clear(&my_mdns);Clear the service change notify callback function. |
| nx_mdns_host_address_get | nx_mdns_host_address_get(&my_mdns, "MDNS-Host", &ipv4_address, ipv6_address, 500);This service performs an mDNS query on host IPv4 and IPv6 addresses. If the address of the specified hostname is found in the peer service cache, the address is returned. If no address is found in the peer service cache, the mDNS module issues A and AAAA type queries and wait for a response. |
| nx_mdns_local_cache_clear | nx_mdns_local_cache_clear(&my_mdns);Clears all entries in the local service cache after sending the Goodbye message. |
| nx_mdns_peer_cache_clear | nx_mdns_peer_cache_clear(&my_mdns);Clears all entries in the peer service cache. |
Status Return Values
| Name | Description |
|---|---|
| NX_MDNS_SUCCESS | mDNS success. |
| NX_MDNS_ERROR | mDNS internal error. |
| NX_MDNS_PARAM_ERROR | mDNS parameters error. |
| NX_MDNS_CACHE_ERROR | The cache size is not enough. |
| NX_MDNS_UNSUPPORTED_TYPE | The unsupported resource record type. |
| NX_MDNS_DATA_SIZE_ERROR | The data size is too big. |
| NX_MDNS_AUTH_ERROR | Attempting to parse too large data. |
| NX_MDNS_PACKET_ERROR | The packet can not add the resource record. |
| NX_MDNS_DEST_ADDRESS_ERROR | The destination address error. |
| NX_MDNS_UDP_PORT_ERROR | The UDP port error. |
| NX_MDNS_NOT_LOCAL_LINK | The message that not originate from the local link. |
| NX_MDNS_EXCEED_MAX_LABEL | The data exceed the max label size. |
| NX_MDNS_EXIST_UNIQUE_RR | At least one unique record in the cache. |
| NX_MDNS_EXIST_SHARED_RR | At least one shared record in the cache. |
| NX_MDNS_EXIST_SAME_QUERY | Exist the same query record in the cache. |
| NX_MDNS_EXIST_SAME_SERVICE | Exist the same service |
| NX_MDNS_NO_RR | No response for a one-shot query |
| NX_MDNS_NO_KNOWN_ANSWER | No known answer for the query |
| NX_MDNS_NAME_MISMATCH | The name mismatch |
| NX_MDNS_NOT_STARTED | mDNS does not start |
| NX_MDNS_HOST_NAME_ERROR | mDNS hostname error |
| NX_MDNS_NO_MORE_ENTRIES | No more entries are found |
| NX_MDNS_SERVICE_TYPE_MISMATCH | The service type mismatch |
| NX_MDNS_NOT_ENABLED | mDNS not enabled |
| NX_MDNS_ALREADY_ENABLED | mDNS already enabled |
NetX Duo mDNS/DNS-SD module manages two internal service caches: the local service cache, and the peer service cache.
Local service cache:
The local service cache stores Resource Records related to services offered by applications running on the node. For incoming queries, if the query matches the service offered, mDNS acknowledges with responses stored in the local service cache. Applications register services by calling the API nx_mdns_service_add(). To remove services, applications use the API nx_mdns_service_delete(), which will, in turn, send "goodbye" messages before removing the corresponding entries in the local service cache.
When a service is added, mDNS maintains at least 3 Resource Records in the local service cache: SRV, PTR, and TXT. Additional PTR Resource Record may be added if the service type includes subtype.
For example, an application registers a service:
*name*._*subtype*._sub._*type*._tcp.local
two PTR Resource Records are added to the local service cache, one for
"*_subtype._*sub*._type._*tcp.local *PTR name.type._*tcp*.*local"
and the other one for
*"_type._*tcp*.*local *PTR name.type._*tcp*.*local"
Peer service cache:
The peer service cache contains mDNS Resource Records received from neighboring nodes. mDNS module collects Resource Records advertised by other nodes on the network, and stores the received information in the peer service cache. When an application queries for information such as host IPv4 or IPv6 addresses, mDNS searches the peer service cache for locally cached responses. When an application queries for services offered by peers, mDNS searches through the cache for related PTR, SRV, TXT, and IPv4/IPv6 address records. The peer service cache also stores queries sent to the node. For example, an application may request a particular service by calling nx_mdns_service_one_shot_query. If the service is not found in the peer service cache, mDNS creates query questions (PTR, SRV, and TXT) in the peer service cache. These query questions will be sent to the network periodically till the service is resolved, or times out. Similarly, the application may use the API nx_mdns_service_continous_query() to request a particular service over a long period of time (application cancels a previously issued continuous query by using the API nx_mdns_service_query_stop()'). To search for a particular service in the peer service cache without sending queries to the network, applications can use the API nx_mdns_serivce_lookup(). This API only searches the resource records in the peer service cache.
Resource Record:
Each Resource Record is stored in a data structure NX_MDNS_RR in the service caches. Strings in Resource Records are of variable length, therefore are not stored in the NX_MDNS_RR structure. The Resource Record contains a pointer to the actual memory location where the string is stored. The string table and the Resource Records share the service cache. Resource Records are stored from the beginning of the service cache, and grow towards the end of the cache. The string table starts from the end of the service cache and grows towards the beginning of the cache. Each string in the string table has a length field and a counter field. When a string is added to the string table, if the same string is already present in the table, the counter value is incremented and no memory is allocated for the string. The service cache is considered full if no more resource records or new strings can be added to the service cache.
There are two ways for an application to find services offered on the local network. It can either issue a specific service look-up through a one-shot query, or it can initiate a continuous query to "monitor" the activities on the network.
One-Shot query:
In the one-short query scenario, the application must specify the service type. mDNS searches through the local service cache and the peer service cache. If a service instance is located, the one-shot query returns with the information found in the Resource Records. If there are no records in the local service cache or peer service cache, mDNS sends out query messages. If the instance name is specified, an ANY type (query the SRV and TXT type) with the specific instance name, in the form of name.type.local, is sent to the local network. If the instance name is not specified, a PTR type of query is sent to the local network. The first complete service received is returned to the caller.
Continuous query:
Continuous query works differently. The typical use case for a continuous query is to monitor the local network for a specific service (for example to constantly look for printing services on the local network). In this case, the application issues a search query (via the API nx_mdns_service_continious_query) for a certain type of service. The caller typically does not wait for a particular response. For queries submitted as continuous queries, the mDNS module transmits the queries periodically with exponentially increasing intervals. To stop the query, an application must use the API nx_mdns_service_query_stop to stop the internal timer in these queries. The query type can be NULL, in which case the query type is set to special PTR type _services._dns-sd._udp.local. This service type is defined by mDNS as a way to discover all services available on the local network. If the instance name is supplied, an ANY type (query the SRV and TXT type) with the specific instance name name.type.local is sent to the local network. If the instance name is NULL, a PTR type of query is sent to the local network, All responses, including responses from unsolicited queries, are recorded in the peer service cache. At a later time, the application uses the API nx_mdns_service_lookup to retrieve specific services from the peer service cache.
The NetX Duo mDNS/DNS-SD requires a packet pool for transmitting mDNS messages; by default, the application must set the packet pool before using mDNS services. This can either be the packet pool used by the IP instance (g_packet_pool0), or it can be a separate packet pool added to the project: Azure RTOS -> NetX Duo -> NetX Duo Packet Pool Instance in NetX Duo mDNS Client.
When mDNS client sends a multicast message/query into the network asking which network participant matches with the hostname, the request goes into the all the participants in the network. The device in the network which matches the request responds to the entire network via multicast. All the participants are informed of the connection between the name and IP address, and can make a corresponding entry in their mDNS cache.
This section describes how to include NetX Duo mDNS/DNS-SD module in an application using the SSP configurator.
To add the NetX Duo mDNS/DNS-SD module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX Duo mDNS/DNS-SD Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_mdns0NetXDuo mDNS/DNS-SD | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetXDuo mDNS/DNS-SD |
When the NetX Duo mDNS/DNS-SD module is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
In the stack above, the NetX Network Driver (or NetX Duo Network Driver in a NetX Duo stack) has not been populated yet. There are multiple possible selections for the Network Driver; they are all not provided so as not to needlessly complicate the figure and the following configuration tables. The available options depend on the MCU target, but some typical options include:
The NetX Duo mDNS/DNS-SD module must be configured by the user for the desired operation. The SSP configuration window automatically identifies (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules for successful operation. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the NetX Duo mDNS/DNS-SD Module
| ISDE Property | Value | Description |
|---|---|---|
| mDNS/DNS-SD Server Support | Enable, Disable Default: Disable | This enables/disables mDNS/DNS-SD server functionality. Without the server functionality, the mDNS/DNS-SD module does not announce services provided by localhost, nor does it respond to mDNS inquiries. |
| mDNS/DNS-SD Client Support | Enable, Disable Default: Enable | This enables/disables mDNS/DNS-SD client functionality. Without the client functionality, mDNS/DNS-SD does not send queries, nor does it maintain mDNS query responses received over the network. |
| Validate address from Received mDNS messages | Enable, Disable Default: Enable | Validates addresses (source address, a destination address, and port numbers) from the received mDNS messages. |
| Verify multicast queries | Enable, Disable Default: Enable | Passive Observation Of Failures, mDNS /DNS_SD client (querier) observes the multicast queries issued by the other hosts on the network. |
| Enable mDNS/DNS-SD generating negative response | Enable, Disable Default: Enable | mDNS /DNS-SD server generates negative responses to queries for which it has legitimate ownership |
| Enable mDNS/DNS-SD IPV6 processing | Enable, Disable Default: Disable | Send/process mDNS message over IPv6 address. |
| Max IPV6 address count | 2 | Maximum IPv6 addresses count of the host. |
| Max string size for host | 64 | Maximum string size for the host name.
|
| Max string size for service | 64 | Maximum string size for service name.
|
| Max string size for Domain | 16 | Maximum string size for the domain name.
|
| Max conflict count for host | 8 | Maximum conflict count for host name or service name |
| TTL value for resource records | 120 | TTL value for resource records with host name, in seconds. |
| TTL value for other records | 4500 | TTL value for other resource records, in seconds. |
| Time interval b/w mDNS probing messages | 25 | The time interval, in ticks, between mDNS probing messages. |
| Time interval b/w mDNS announcement messages | 25 | The time interval, in ticks, between mDNS announcement messages. |
| Time interval b/w goodbye messages | 25 | The time interval, in ticks, between repeated "goodbye" messages |
| Min time interval b/w two queries | 100 | The minimum time interval, in ticks, between two queries. |
| Max time interval b/w two queries | 360000 | The maximum time interval, in ticks, between two queries. |
| Min delay for sending the first query | 2 | The minimum delay for sending first query, in ticks. |
| Delay range for sending the first query | 10 | The delay range for sending first query, in ticks. |
| Query response time interval | 100 | The time interval, in ticks, in responding to a query to ensure an interval of at least 1sec since the last time the record was multicast |
| Probe query response time | 25 | The time interval, in ticks, in responding to a probe queries to ensure an interval of at least 250ms since the last time the record was multicast. |
| Unique query response delay | 1 | The delay, in ticks, in responding to a query to a service that is unique to the local network. |
| Minimum delay in responding to a query to a shared resource | 2 | The minimum delay, in ticks, in responding to a query to a shared resource. |
| Delay range in responding to a query to a shared resource | 10 | The delay range, in ticks, in responding to a query to a shared resource. |
| Minimum delay in responding to a query with TC bit | 40 | The minimum delay, in ticks, in responding to a query with TC bit. |
| Delay range in responding to a query with TC bit | 10 | The delay range, in ticks, in responding to a query with TC bit. |
| Timer count range | 12 | When sending out mDNS responses, the packet contains responses that otherwise would be sent within this timer counter range. The timer count range is expressed in ticks. |
| Number of retransmitted probing messages | 3 | The number of retransmitted probing messages. |
| Number of retransmitted goodbye messages | 1 | The number of retransmitted "goodbye" messages. |
| Minimum number of the count with no multicast response | 2 | The number of queries that no multicast response, then the host may take this as an indication that the record may no longer be valid. |
| Time interval in deleting the record from cache | 1000 | The time interval, in ticks, in deleting the record from the cache after seeing two or more of these queries, and seeing no multicast response containing the expected answer. |
| Delay for deleting a resource record | 100 | The delay for deleting a resource record when the TTL of this record is zero, in ticks. |
| Name | g_mdns0 | Name of the mDNS/DNS-SD instance. |
| mDNS thread priority | 3 | Priority of the mDNS thread. |
| Internal thread stack size | 4096 | Size of the stack area in bytes |
| Local service cache size | 4096 | Storage space for local registered services in bytes. |
| Peer service cache size | 4096 | Storage space for service information received in bytes. |
| Name of Probing notify callback function | probing_notify | Optional callback function invoked at the end of the probing operation. It notifies the application whether the host name (when enabling mDNS on a local interface), or the service name (after registering a service) is unique. |
| Name of generated initialization function | mdns_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
In some cases, settings other than the defaults for lower-level modules can be desirable. The configurable properties for the lower-level stack modules are given in the following sections for completeness and as a reference.
Note: Most of the property settings for lower-level modules are intuitive and usually can be determined by inspection of the associated properties window from the SSP configurator.
Only a few number of settings must be modified from the default for the IP layer and lower-level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and are locked to prevent user modification. The following table identifies all the settings within the properties section for the module:
Configuration Settings for the NetX Duo IP Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ip0 | Module name |
| IPv4 Address (use commas for separation) | 0,0,0,0 | IPv4 Address selection |
| Subnet Mask (use commas for separation) | 255,255,255,0 | Subnet Mask selection |
| IPv6 Global Address (use commas for separation) | 0x2001, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x1 | IPv6 global address selection |
| IPv6 Link Local Address (use commas for separation, All zeros means use MAC address) | 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 | IPv6 link local address selection |
| IP Helper Thread Stack Size (bytes) | 2048 | IP Helper Thread Stack Size (bytes) selection |
| IP Helper Thread Priority | 3 | IP Helper Thread Priority selection |
| ARP | Enable | ARP selection |
| ARP cache storage units | Bytes, Entries Default: Bytes | ARP cache storage units selection |
| ARP Cache cache Size (in Bytes or storage units) | 520 | ARP Cache Size in Bytes/Entries selection. Must be a multiple of 52 Bytes. Note: 1 Entry = 52 Bytes |
| Reverse ARP | Enable, Disable Default: Disable | Reverse ARP selection |
| TCP | Enable, Disable Default: Enable | TCP selection |
| UDP | Enable, Disable Default: Enable | UDP selection |
| ICMP | Enable, Disable Default: Enable | ICMP selection |
| IGMP | Enable, Disable Default: Enable | IGMP selection |
| IP fragmentation | Enable, Disable Default: Disable | IP fragmentation selection |
| Name of generated initialization function | ip_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
Configuration Settings for the NetX Duo Common Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name of generated initialization function | nx_common_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
Configuration Settings for the NetX Duo Packet Pool Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_packet_pool0 | Module name |
| Packet Size in Bytes | 1568 | Packet size selection |
| Number of Packets in Pool | 16 | Number of packets in pool selection |
| Name of generated initialization function | packet_pool_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
The ETHERC peripheral module uses PCLKA as its clock source. The PCLKA frequency is set using the SSP configurator clock tab prior to a build, or by using the CGC interface at run-time.
The ETHERC peripheral module uses pins on the MCU device to communicate to external devices. I/O pins must be selected and configured by the external device as required. The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the ETHERC pins.
Pin Selection for the ETHERC Module
| Resource | ISDE Tab | Pin selection Sequence |
|---|---|---|
| ETHERC | Pins | Select Peripherals > Connectivity:ETHERC > ETHERC1.RMII |
Pin Configuration Settings for the ETHERC1
| Property | Value | Description |
|---|---|---|
| Operation Mode | Disabled, Custom, RMII Default: Disabled | Select RMII as the Operation Mode for ETHERC1 |
| Pin Group Selection | Mixed, _A only Default: _A only | Pin group selection |
| REF50CK | P701 | REF50CK Pin |
| TXD0 | P700 | TXD0 Pin |
| TXD1 | P406 | TXD1 Pin |
| TXD_EN | P405 | TXD_EN Pin |
| RXD0 | P702 | RXD0 Pin |
| RXD1 | P703 | RXD1 Pin |
| RX_ER | P704 | RX_ER Pin |
| CRS_DV | P705 | CRS_DV Pin |
| MDC | P403 | MDC Pin |
| MDIO | P404 | MDIO Pin |
The steps in using the NetX Duo mDNS/DNS-SD module in a typical application are:
nx_ip_status_check (or if your system has multiple network interfaces, call nx_ip_interface_status_check) with the NX_IP_LINK_ENABLED option.nx_mdns_cache_notify_set API.nx_mdns_enable API.nx_mdns_service_add API by providing the service name, type, subtype, priority, weight, and port.probing_notify callback is invoked.nx_mdns_service_delete API.nx_mdns_service_notify_set API.nx_mdns_service_one_shot_query and nx_mdns_service_continuous_query API respectively.nx_mdns_service_lookup API.The following figure illustrates common steps in a typical operational flow diagram:
