search

WebThingsIO / api

Web Thing API Specification
http://iot.mozilla.org/wot/
Other
164 stars 24 forks source link

Add a Things Discovery section #75

Closed benfrancis closed 4 years ago

benfrancis commented 6 years ago

Add a section to explain how Thing Descriptions can be discovered. This could include:

Another possibility is adding HTML link relations to web pages which point to a Thing Description, similar to <link rel="manifest">

benfrancis commented 6 years ago

@mrstegeman @hobinjk Would you mind providing a quick overview of how the webthing mDNS broadcasts and Eddystone beacons work to start to put together some wording for this? Currently this isn't documented anywhere.

mrstegeman commented 6 years ago

Discovery via mDNS can be done in either of the following ways:

Discovery via Bluetooth:

phoddie commented 6 years ago

Thanks for the details on the use of mDNS in Web of Things. That's helpful for our current exploration. I understand that this may change later as the specification evolves. A few observations based on a recent review of the mDNS specification and related documents.

The _http._tcp service is intended for providing web pages to a browser. From dns-sd.org:

The meaning of this service type, though called just "http", actually denotes something more precise than just "any data transported using HTTP" The DNS-SD service type "http" should only be used to advertise content that:

  • is served over HTTP,
  • can be displayed by "typical" web browser client software, and
  • is intented primarily to be viewed by a human user.

This suggests that a more specific service type would be preferred, such as _webthing._tcp. Doing so eliminates the need for the webthing=txt entry in the TXT record and removes a filtering step for clients looking only for Web of Things compatible devices.

The url entry in the TXT record specifies an absolute URL (e.g. http://mything.local/description). At zeroconf.org, this practice is not recommended:

The TCP (or UDP) port number of the service, and target host name, are given in the SRV record. This information — target host name and port number — MUST NOT be duplicated using name/value attributes in the TXT record.

The approach described on dns-sd.org for the path entry in the TXT record for _http._tcp services seems applicable here:

generate a URL of the form shown below, where {host} and {port} are obtained from the information in the service's SRV record, and {path} is obtained from the "path" key in the TXT record:

Applying the rule reduces http://mything.local/description to /description. Both this change and the elimination of the webthing TXT entry reduces the size of the mDNS TXT answers, leaving room for future options or merging more mDNS answers into a single packet.

mrstegeman commented 6 years ago

@phoddie Thank you for pointing this out, we're in the process of changing over.

Do you know if there is a way to specify that the host is using TLS/HTTPS? The dns-sd spec you pointed out says to build the URL as such: http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]]

phoddie commented 6 years ago

When using the _http._tcp service, the current recommendation seems to be to have the HTTP server force an upgrade to HTTPS:

Work is currently being done on adding mechanisms to HTTP and TLS to allow the server to tell the client that it needs to activate TLS on the current connection before proceeding. If this becomes widely adopted, it further justifies the decision to not create a separate DNS-SD service type "_https._tcp", because security becomes just another one of the things that is negotiated on a per-connection basis (like content-type negotiation today) rather than being an entirely separate thing.

If you switch from _http._tcp to your own Web of Thing service type, you can define any rules you like. Still, the host name and port should come from the SRV record as noted above.

I'm no expect on TLS, but I recall there is some challenge in providing certificates for a .local host.

benfrancis commented 6 years ago

I'm wondering how in future a Web of Things client might differentiate between things using different protocol bindings (other than HTTP).

I guess a CoAP binding might be advertised as _webthing._udp, but that doesn't leave much room for other protocol bindings which might also use TCP or UDP.

Does mDNS have a way to differentiate, or even to advertise multiple services on different ports?

mrstegeman commented 6 years ago

@benfrancis Yes, you'd just set up multiple advertisements.

phoddie commented 6 years ago

Does mDNS have a way to differentiate, or even to advertise multiple services on different ports?

Yes. You can have as many services as you like on a single device. Many devices do including just about every Mac.

mrstegeman commented 6 years ago

As an update to my earlier comment, here is what is currently implemented.

Discovery via mDNS can be done by broadcasting a service as follows:

Discovery via Bluetooth:

phoddie commented 6 years ago

Great to see the type change. Is there a reason to continue using an absolute URL in the TXT record?

mrstegeman commented 6 years ago

@phoddie We actually did switch to path. My comment was invalid. I will edit it.

phoddie commented 6 years ago

Oh, great. Is that in the current shipping Gateway?

mrstegeman commented 6 years ago

Yes.

phoddie commented 6 years ago

Excellent. We'll give that a try. Thank you!

phoddie commented 5 years ago

Spiffy. We just tried the latest Gateway and it works with _webthing._tcp. We also confirmed that it is using the port number from the SRV record. Very cool. Thank you. We'll push an update to our WebThings module for the Moddable SDK to sync with these changes.

mrstegeman commented 5 years ago

We've now stopped supporting Eddystone beacons, as they're no longer supported by any major OS.