Re: IOTDB: bands

Hey David,

First, thanks for all the input/comments/feedback. Lots of goodness in there!!

Sorry for my rather long mail (you can skip to "showtime" below and control a REAL device in our office via a REST API!!).

After spending a decade on building Web-conntected devices (and getting my phd on the Web of Things ;) ), I fully agree we need both "current" & "planned" states. We face this exact problem for commercial connected products at EVRYTHNG, so the model we propose supports both (have look here if you didn't see it already, it's pretty detailed: https://github.com/w3c/wot/blob/master/TF-AP/WoT-Label%20v0.1.pdf <https://github.com/w3c/wot/blob/master/TF-AP/WoT-Label%20v0.1.pdf>).

** PROPERTIES **
A property "SHOULD" always reflect the most recent (known) state of a thing. So for simple scenarios, it's OK to be able to change them on the spot. For example, the location of a thing: the device doesn't know where it is (no GPS, etc. on board), so I could use an app on my phone and set the "location property" from outside the device. Another exception is when you don't care about the status and assume that sooner or later the device will update it successfully (does this even exist?) or maybe when you know that the current status will be updated right away (Web API runs on device and has the confirmation asap). 

The model you suggest, where you have two copies of the same property (current_X and planned_X) is very useful when the device can only poll data from a server (it knows which one to listen to: planned_X, and updates the current_X when its done). This is how NEST API does it. But I don't think we should force every property to be doubled, unless for those you really need this. 

This is what we've been doing with EVRYTHNG and works well in the real world (see here: https://dev.evrythng.com/developers/apidoc/properties <https://dev.evrythng.com/developers/apidoc/properties>)

** ACTIONS **
But when you need to model any operation that is more complex than "just change the value" (which is common in the real world), then you will use *ACTIONS*. An action is a higher level abstraction for what a device does which has a special meaning, a context, some validation, and more (who can access it, when, how, how many updates per day, etc.). The simplest action would be "setStatus()" which takes a boolean as param. If the Web thing is on a proxy, it can use a callback that send this command in "whatever-the-device-understandsese" to the actual device and update the "status" property once it gets a confirmation. So a simple action, is nothing more than a getter/setter around properties, but with room to add as much complexity as required.

But many operations will involve and change various properties (some instantaneously, other later), and the logic of this ("code" of the action handler) is left to the developer (either on the device itself, so would be C/C++/etc., or in the proxy). Think of a printer - you will obviously need to expose high-level actions (print X, reboot, etc.), as I don't think I'd like to write a script that coordinates and sets a bunch "raw" of properties that control the various motors, inks, etc. each time I'd like to print something.

(To see how we've used actions at EVRYTHNG, here's our API: https://dev.evrythng.com/developers/apidoc/actions <https://dev.evrythng.com/developers/apidoc/actions> )


** WHAT'S NEXT? **

I suggest you look at the JSON payloads I've uploaded in our github (https://github.com/w3c/wot/tree/master/TF-AP/JSON%20Payloads <https://github.com/w3c/wot/tree/master/TF-AP/JSON%20Payloads>), this will give you an excellent idea of how you would implement the various operations you suggest over REST, from getting the metadata and also interacting with the device (from discovering actions, how they work, how you create them, etc.). I would truly love your feedback on those.

We'll also present this model tomorrow during the TF-TD call, so please join!


** SHOW TIME!!! **
Finally, you can see how this model works with actual devices (http://devices.webofthings.io/ <http://devices.webofthings.io/> --> hint: ask for "application/json" using curl/postman on those URLs, it's more fun!!). It's obviously a work in progress, but we'll be releasing the source code of the server side (in node.js as well) in the next few weeks. 


Would love to discuss this more in detail in the upcoming calls. 

Vlad







--
vlad trifa, phd //// 
co-founder, head of r&d + innovation 
m +44 750 888 2051 // w evrythng.com <http://evrythng.net/>
t @vladounet /////// w vladtrifa.com <http://vladtrifa.com/>
> On 02 Jun 2015, at 19:32, David Janes <davidjanes@davidjanes.com> wrote:
> 
> I think I understand, pretty well, what your model does. I just don't see how putting all these disparate concepts into one pile makes things simpler or easier for implementers or for people trying to understand how things work.
> Things have an actual state. Things have a control state. I can sit and watch things in front of me demonstrate that these are different: I'll take a video if you want!
> Things have metadata, which includes its name, its reachability, its facets (definable by the user), perhaps an ACL, perhaps manufacturer data and so forth.
> Things have a model, which is a description of how it works, and what the values in it's state mean. The model is basically static after definition.
> Your model - from the slideshow - looks like this
> HTTP GET to retrieve a thing's description 
> HTTP GET to retrieve all properties of a thing 
> HTTP PUT to update all properties of a thing 
> HTTP PATCH to apply changes to some properties 
> HTTP POST to invoke actions on a thing 
> HTTP POST is also used to notify events 
> So specifically
> A Things Description - lets say this is the JSON-LD - isn't the same as its Metadata, it's actual state (istate), or control state (ostate)
> Is this the same URL as #1? If so, you're already basically doing bands as I describe it. Otherwise you're returning tons of redundant data - the JSON-LD Model, the Metadata, and so forth, &c &c. And if it's just the URL, you _still_ need to differentiate between all these different types of data
> why do you need to update the Model of a Thing, assuming that's what you mean by properties.
> same
> so doing POST to a Thing changes one set of data (making an operation), and doing PUT changes a different set of data
> same
> D.
> 
> On Tue, Jun 2, 2015 at 1:10 PM, Dave Raggett <dsr@w3.org <mailto:dsr@w3.org>> wrote:
> 
>> On 2 Jun 2015, at 16:26, David Janes <davidjanes@davidjanes.com <mailto:davidjanes@davidjanes.com>> wrote:
>> 
>> This is really one my favorite insights into how Things and APIs work together. I gave two presentations on Global IoT Day in Vienna about this
>> 
>> http://www.slideshare.net/dpjanes/2015-04-global-io-t-day-wien-interoperability-with-stanardless-iot <http://www.slideshare.net/dpjanes/2015-04-global-io-t-day-wien-interoperability-with-stanardless-iot>
>> http://www.slideshare.net/dpjanes/what-a-thing-api-should-look-like-global-iot-day <http://www.slideshare.net/dpjanes/what-a-thing-api-should-look-like-global-iot-day>
>> 
>> So building on the previous message, we have the same definitions for controlling a thing as reading values of a Thing. How do we differentiate between these various aspects? Add into the picture that we also have to deal with _metadata_ and we have to deal with the _model_ (in JSON-LD), how does this fit?
>> 
>> So here's the key insight: a "Thing" is _not_ JSON dictionary that we manipulate. Instead a Thing, identified by some Thing ID, is a jumping off point to a cloud of related but independent JSON dictionaries. These are (at least):
>> istate - the Input State: the actual state of thing
>> ostate - the Output State: the state we want the thing to become
>> meta - the Thing's metadata
>> model - the Thing's JSON-LD Model
>> The entire IoT / Web of Things can - and _should_ -  be seen as just reading an manipulating these four JSON dictionaries! The back end is just shuffling the data around to the proper point to be actioned!
> 
> This sounds over complicated. What is wrong with a single model of the thing and relying on the server platform to do its best to propagate property changes in both directions?
> 
> In my NodeJS server, the server creates a proxy object from its model. The object is set up with setters and getters for its properties. For the WebSocket protocol binding, a PUT message updates all of the properties whilst a PATCH message updates a subset. The model consists of {metadata, events, properties, actions}.  The script writer doesn’t have to deal with the protocol as this is handled by the server.
> 
> In principle, the metadata can change e.g. when a sensor is moved from one location to another.  This shows the need for propagating changes to metadata using same framework as for thing properties.  I think it would be appropriate to also associate events with metadata changes.
> 
> You could describe actions in terms of pre and post conditions and then use a reasoning engine to figure out what sequence of actions on what things are needed to address some goal.
> 
> Or perhaps I am missing your point?
> 
> —
>    Dave Raggett <dsr@w3.org <mailto:dsr@w3.org>>
> 
> 
> 
>