webthingsio / api Goto Github PK

Define how to specify units for properties

The default binding of the REST API is to HTTP which is used in examples, but we could provide guidance for protocol bindings to other similar protocols like CoAP and HTTP/2

Currently the binarySensor has a property called 'on' with values of true or false.

on implies semantics which the adapters can't enforce, and consequently it will sometimes wind up inverting the sense because an input signal happens to be 0 when the device is on and 1 when its off.

I'd like to propose 3 changes:
1 - Change 'on' to 'value'. value doesn't have any extra semantics.
2 - Change true/false to be 1/0. This would then make a binary sensor more like a special case of a multiLevelSensor
3 - Add a property which inverts the sense of the signal reported. On the raspberry pi, the GPIO pins have an 'activeLow' attribute, so that the pin reports 0 when the voltage is high and reports 1 when the voltage is low.

Is there a possibility to include the "decoding" part of a binary data which usually is part of the sensor. For instance, a LoRaWan device getting temperature and pressure will return this data in binary format and this needs to be translated in properties of the device.
The description of this process could be included in the specific part of the device definition, either using a kind of declarative part (i.e: temparture is at byte 2 and is encoded in 3 bytes) or through a kind of small javascript program that do the decoding and convert binary to properties.

Any though on this?

In the current version of the spec I've provided a simple example of how to subscribe to a property:

REQUEST

GET ws://mythingserver.com/things/pi/temperature
Origin: mythingserver.com
Connection: Upgrade
Host: mythingserver.com
Upgrade: websocket

RESPONSE

HTTP 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

ONMESSAGE

{
"temperature": 21.0
}

The basic idea is that you send an HTTP GET request to the property URL and ask for it to be upgraded to a WebSocket which is kept open. Then every time the property changes a new value gets pushed down the WebSocket using JSON.

This works in this simple example, but opening a separate WebSocket for each property URL you want to subscribe to doesn't really scale very well. What if you want to subscribe to all property changes on a Thing, or a subset of properties of a Thing? How can we reduce the number of open sockets per thing or per client?

I had been hoping to keep this as RESTful as possible and avoid having to invent a custom PubSub protocol on top of WebSockets. There are many existing pubsub protocols we could use for that, but most of them would be an overkill and aren't really very webby.

The CoAP protocol has an extension which defines an OBSERVE method to allow subscribing to changes. How can we implement something similar as an extension of HTTP, using WebSockets?

A simpler option might be to use Server Sent Events, but they aren't as widely supported by browsers.

When is it appropriate to use properties and when is it appropriate to use actions?

See w3c/wot#247

The "type" field currently refers to the type of the value that the property has, boolean, integer, float, etc.

I've wondering if there should also be a kind, something like wall switch versus a switched outlet. Maybe this distinction should just be at the UI and something persisted in the database rather than as a property attribute?

Consider defining minimum and maximum properties for properties and arguments

I'd like to propose that we add support for a multiLevelSwitch. This would have the following properties:

• on (as per onOffSwitch)
• level of type "percentage" would be a number in the range 0 to 100.

This would allow us to support dimmable modules under both ZigBee and ZWave.

Hi, what is the difference between this project and the one that the Open Connectivity Foundation (OCF) is doing with Iotivity? It seems that data models have been documented here . With these two projects, how should a developer decide which project to pursue for development?

Thank You,

It may be that an action cannot be canceled since it might be already "in flight" or the Thing is otherwise unable to cancel the action (e.g. because it currently does not have enough resources).

In that case the Thing should be allowed to return the appropriate error code, which would be either 403 Forbidden or 503 Service Unavailable.

Some existing IoT systems separate out "desired" state and "reported" state for Things, particularly for APIs which manage a virtual "shadow" or "twin" of a real life Thing.

This separation is used for "optimistic concurrency" or to ensure "eventual consistency". When setting a property the idea is that you set the "desired" state and eventually that becomes the "reported" state. By also using datestamps for change requests this enables the system to resolve race conditions or collisions.

E.g. JSON Schema or Semantic Extensions using JSON-LD.

Some properties, like a temperature, humidity or light level, are read-only.

Some properties, like a wall switch, can be controlled, and you can both turn them on/off or detect if some external force (a human) has manually changed the state.

Some properties, like an X-10 wall switch, can be controlled, but you can't detect if they're on or off. An IR transmitter would be another example of a write-only device.

I think that the thing description should include an accessibility attribute to determine whether properties can be modified or not.

This is not to be confused with authorization (i.e. user A may be allowed to change the state of a switch, while user B might not be allowed).

Consider explicitly mentioning support for the HTTP OPTIONS verb so that clients can find out which verbs are supported by any given resource.

In our implementation each thing has a unique id. Should this be added to document?

Create "Web of Things Integration Patterns" note using this document as a starting point

E.g. vendor-prefixing like W3C Web App Manifest https://w3c.github.io/manifest/#proprietary-extensions

"name" is used elsewhere to be a human friendly name whereas the name of actions and events is a computer friendly string like the property, action and event keys in the Thing Description.

Maybe name should be something else, like "type".

As described in WebThingsIO/philips-hue-adapter#5 there are other ways of specifying color for bulbs that may allow more consistency of color across manufacturers.

Consider explicitly mentioning the use of pagination for very long responses (e.g. a list of Things or a history of Property values), making use of “next”, “previous”, “first” and “last” link relations.

Hi *,

I wonder if it is possible to see or check, if a property is writeable or not before sending the actual PUT request?

Some property resources may be read only and some may be writable. (src)

Have responses to PUT, POST or PATCH requests return a representation of the updated resource. Use an HTTP 201 response and Location header for a POST which creates a new resource.

Arguably related to #14 and #15. Something like "The Gateway may use an authentication mechanism to limit access to the API. While non-normative, one mechanism used by Mozilla's Gateway is providing an Authorization header including a Bearer token."

When a websocket endpoint is acting as a gateway/adapter to many Web Things, it'd be ideal to have a single websocket connection to the gateway. This could be handled by including a URL in the message indicating what it went to, etc.

Create "Web Thing API Protocol Bindings" note, using this document as a starting point.

The default encoding is JSON, but alternatives could include CBOR and others.

In the Thing resource it shows temperature as an integer.
In the Property resource response for retrieving the temperature it shows the temperature as a string (i.e. 21 in quotes) rather than an integer (21 with no quotes).

Need to define a mechanism for defining arguments and argument types for actions, and possibly a mechanism for returning values as well.

This'll make diffs for PR reviews, and contributing a little easier.

https://github.com/tabatkins/bikeshed

The Thing Description needs to include links to property, action and event URLs - either a single URL for each or individual URLs for individual properties/actions/events.

Consider supporting PATCH requests to only update part of a resource, using JSON patch notation from RFC 6902 (media type application/json-patch+json)

Add formal references to other specifications (HTTP, JSON, REST etc.).

Here is an example API from lockitron: https://api.lockitron.com/

We need a web thing type definition for a smart lock. Or maybe even a couple different types of smart locks. For example, those that click to temporarily unlock and then fall back to a locked state, or those that toggle between locked and unlocked states. It seems somewhat analogous to a pushbutton that you have to continue to press for it to remain active versus a switch that is set to either on or off.

For existing smart locks, we'll need an adapter running on the Things Gateway to accommodate them. For new locks, we'd like the smart lock industry to move toward WoT standardization.

I might be wrong but I have the feeling that the current solution of Wot is limited to private network unless we configure the router to make the things accessible from outside. This is the case, since it seem that's all your "things" seem to be server. So if you want to access the "things" from internet, it is not possible unless we setup some routing system. Of course, there could be the gateway taking care of this, but we would still have to configure the router. Lambda user, will never do such manipulation. This is why the "things" should most of the time be client to an external server accessible from internet. But I can't hardly see any specification for this use case in Wot. Even the WebSocket solution assume that the "things" is server and don't provide any solution to get the thing description like you do in REST.

Again I might be wrong :p

Note: Try to keep security metadata in HTTP headers rather than the Thing Description itself.

I think that providing a list of pre-defined Thing types is beyond the scope of this standard and it opens up the document to be extended for every imaginable device configuration (e.g. #53).

The section on how to define a Thing type should be the first one, with some examples.

Provide useful error codes, making full use of HTTP status codes

Decide whether to specify Web Thing discovery mechanisms in this specification, in an accompanying note or not at all. Examples of discovery mechanisms might include looking up in a directory (e.g. on a gateway or in the cloud), crawling/indexing/searching using a search engine, proximity based broadcasts (e.g. using physical web beacons) and local network based broadcasts (e.g. using CoAP, UPnP or mDNS).

Maybe combine with Integration Patterns note and call it Web of Things Design Patterns.

Need to define best practices for doing this.

The documentation gives the impression that a Thing is expected to persist the state of actions and also the events that happened while processing the action request.

Especially for resource constrained devices this is unfavorable and they will most likely apply the action and internally discard the data associated with the request.

Especially in that case of the reboot example the documentation gives the impression that a rebooted device should have a history of a previous reboot request.

It should be allowed for a thing to return a 404 for an action request that it has processed.
In that case the Thing should publish the action status to the websocket, if the Thing supports it.

After having looked at lots of prior art, I think we should consider changing the properties member into an object rather than an array, with the property name as a key.

For example this...

  "properties": [
    {
      "name": "temperature",
      "type": "number",
      "unit": "celsius",
      "description": "An ambient temperature sensor",
      "href": "/things/pi/properties/temperature"
    },
    {
      "name": "humidity",
      "type": "number",
      "unit": "percent",
      "href": "/things/pi/properties/humidity"
    },
    {
      "name": "led",
      "type": "boolean",
      "description": "A red LED",
      "href": "/things/pi/properties/led"
    }
  ]

would become this...

  "properties": {
    "temperature" {
      "type": "number",
      "unit": "celsius",
      "description": "An ambient temperature sensor",
      "href": "/things/pi/properties/temperature"
    },
   "humidity": {
      "type": "number",
      "unit": "percent",
      "href": "/things/pi/properties/humidity"
    },
    "led": {
      "type": "boolean",
      "description": "A red LED",
      "href": "/things/pi/properties/led"
    }
  }

Reasons:

• A particular property can be more directly referenced in code (e.g. using a JSON pointer) without having to iterate through the array
• The "name" member of a property object could still be used as a human friendly name (This is what "name" is used for elsewhere in the spec), while the key is used as a computer friendly string to reference the property by
• Lots of existing systems like JSON Schema and cloud services like AWS IoT & Azure IoT do it this way

We should also consider making the same change to actions and properties in the Thing Description.

Subscriptions may be created to properties and actions by a GET request on a property or action resource which is upgraded to a WebSocket connection such that data can be pushed from the server to the client when necessary.

There may be use cases where a client wants to subscribe to events other than changes in property resources or the creation of or changes to action resources.

For example, a Thing may have a "temperature" property which could be subscribed to whenever the temperature changes, but the Thing may also want to emit an event only when the temperature passes a certain threshold.

Should we add an "events" member to the Web Thing Description in addition to "properties" and "actions" for this type of use case? Is there a way for events be represented by resources in a RESTful way?