Which is better to actuate devices, invoking ACTION or writing PROPERTY?

[mryuichi]

In the last plugfest, TUM gave us a very precise description of the devices with TDs, but I feel them a few complicated descriptions. For example, in HueColorLight, the description of property "on" appears in three places: "properties" and "input" and "output" in the "actions". If stopping to use ACTION to change the value (e.g. ON/OFF) the property "on" and writing the value to the property "on" instead, all operation to the device can be performed by reading or writing the value from/to the properties. It's very simple. The description can be shortened to a third of the original TD.
In fact, in some standards such as BACnet, KNX, and ECHONET, the lamp is turned on by writing the value to PROPERTY, not invoking ACTION. It should be more natural to describe in PROPERTY instead of ACTION according to the existing standards of the device interfaces.
I think that ACTION should be limited to use when it's necessary to interrupt the process in the middle, etc.

[sebastiankb]

I think, the major issue here is that the Hue device has designed this interface and the TD from TUM simple follows this. You are right, this may not be perfect and can be designed differently.

Would you like more clarification on when to use PROPERTIES and when to use ACTIONS? Maybe the WoT profile can be a good place to have that clear definition. What do you think?

[benfrancis]

In case it's helpful, Mozilla's draft specification provided this rule of thumb:

Actions are used when the setting of a property alone is not sufficient to affect a required change in state. This may be used to describe a function which takes a period of time to complete, manipulates multiple properties, or has a different outcome based on provided arguments or current state. An example might include a "fade" action which has a specified "duration", a "sequence" action which triggers a sequence of flashing lights or a "toggle" action on a switch.

[danielpeintner]

I agree, some kind of non-normative guidelines may be useful.

Having said that, in the end it depends a lot on various aspects and it seems impossible to me to prescribe when to pick what

• greenfield (I can decide what I want to do)
• brownfield
• personal preference (yes, I think so ;-))
• ...

[mryuichi]

@sebastiankb Thank you for your comment apologize for my late reply.

In my opinion, the description of ACTION in the TD document should be modified, because it can be interpreted as having to use ACTION to invoke devices. Mozzila's draft is useful for this point.

When I talked to the chair of ECHONET Web API WG several weeks ago, he said "ECHONET Web API respects the idea of WoT, but writing properties of the devices are natural to control them. ECHONET Web API cannot be aligned with WoT to this point." If the WoT specification allows writing properties for the invocation of the devices, some modifications of TD doc are needed. If you agree with this, I'll create a text to clarify it.
Hue's interface is also designed with the properties for the functions. So I believe it intends to invoke devices by using write the properties, and we can get a simpler/shorter Thing Description of Hue than TUM using only PROPERTies, without ACTIONs.

It's important to make the specification acceptable from existing standards like ECHONET, OPC UA, and so on. If you know experts of them, could you have their opinions?

[egekorkan]

For the case of Philips Hue, it is possible to model everything as properties, however, the responses of the API for making a change is completely different than when reading something. We had chosen actions in order to use the clear input/output mechanism and not do super messy granular readOnly/writeOnly clauses. We could of course omit this since the response of the API is anyway not so easy to parse.

[sebastiankb]

@mryuichi Many thanks for the clarification.

You are right we should be more clear in the TD specification about this point.

If the WoT specification allows writing properties for the invocation of the devices, some modifications of TD doc are needed. If you agree with this, I'll create a text to clarify it.

That would be great if you can provide a proposal.

It's important to make the specification acceptable from existing standards like ECHONET, OPC UA, and so on.

100% agree with this and we should doing so. One question: Is it possible to have a device available for the next PlugFest that follows ECHONET Web API?

It's important to make the specification acceptable from existing standards like ECHONET, OPC UA, and so on. If you know experts of them, could you have their opinions?

As you know, there is a plan for OPC UA to start a common activity to design TDs that fit well with OPC UA interfaces. Maybe we should also think about doing this with ECHONET consortia. What do you think?

[mryuichi]

@sebastiankb Thanks for your comment.,

That would be great if you can provide a proposal.

OK. I will make a proposal to clarify that.

100% agree with this and we should doing so. One question: Is it possible to have a device available for the next PlugFest that follows ECHONET Web API?

I'll ask a member of ECHONET consortium if they can join our next plugfest.

As you know, there is a plan for OPC UA to start a common activity to design TDs that fit well with OPC UA interfaces. Maybe we should also think about doing this with ECHONET consortia. What do you think?

That's a great idea. First, why not take the opportunity to hear from them about the differences between ECHONET Web API and WoT?

[sebastiankb]

@mryuichi

OK. I will make a proposal to clarify that.

Many thanks.

I'll ask a member of ECHONET consortium if they can join our next plugfest.

That would be great.

That's a great idea. First, why not take the opportunity to hear from them about the differences between ECHONET Web API and WoT?

Yes, that makes sense.

[mryuichi]

@egekorkan, thank you for your comment. I think your comment is appropriate. Sorry for the late reply.

It's great to be able to represent product-specifc specifications with TD. But at same time, I'm worried it might build silos over the WoT.
WoT's goal was to ensure interoperability between various standards and to eliminate the silos. In order to achive this, we need some guidelines on createing a TD. This should be discussed in the Profile TF.
On the other hand, I think we should define TDs so that it can be represented simply without converting the existing stadandards as much as possible. After a quick look at some of the standards, the propery, the event, and the action defined on TD correspond to them as follows:

standards	property	event	action
WoT	property	event	action
OPC UA	attribute	event	method
Azure DTDL	property	event	command
OCF	property	event
KNX	property	event
ECHONET Lite	property
BACnet	property	event
NGSI	property	event
Mozilla WebThing	property	event	action

(If you are an expert for these standards, please check if these are correct. The blank shows no correspoinding item.)

In these standards, the devices can be operated by changing the value of the property (using WriteProperty) instead of invoking the action. Therefore, I think the description of the WoT documents should be modified so that the device can be operated by writing the property in TD as well.

[k-toumura]

I think the advantage of Thing Description is that it can handle protocol binding and interaction affordance separately.
Even if the concrete operation is to write to a property (e.g., write {"value":1} using PUT https://example.com/property/123, or writing 0xAB to register D08, etc.) for invoking an action, it is easier for Thing user to understand if it is abstracted as an Action Affordance.

[mryuichi]

@sebastiankb

I talked to steering members of the ECHONET consortium about their participation in the WoT plugfest and found they have an ECHONET device simulator running on the cloud. to check the connection to their Web API.
This simulator is for ECHONET members, so I ask the consortium to make it available for us. I'll share how to connect to it after the approval.

Unfortunately, the introduction to the ECHONET Web API and the gaps to the WoT is difficult for a while due to the busy schedule.

[egekorkan]

@mryuichi the table above is actually really helpful, thank you for the contribution! :)

[relu91]

I think the advantage of Thing Description is that it can handle protocol binding and interaction affordance separately.
Even if the concrete operation is to write to a property (e.g., write {"value":1} using PUT https://example.com/property/123, or writing 0xAB to register D08, etc.) for invoking an action, it is easier for Thing user to understand if it is abstracted as an Action Affordance.

Totally agree here.

Here's my comment on our rule of thumb when designing TDs:

it seems that I am also allowed to think of actions as processes or logical operations that a Thing can do. In our experiments, we usually follow the OOP rule of thumb, so if I property getter needs inputs then it's actually an action. Furthermore, if something is logically a long-running process then starts when invoked and can be named as a verb then it's an action. For example, a performSelfCheck that computes the sanity of the configuration of a web thing is an Action.

[sebastiankb]

From today's TD call:

• we should check with ECHONET how Actions are used (see slide 16 here). @mryuichi will check with the ECHONET representatives
• @mryuichi will provide a proposal for describing the usage of properties and actions
• we should also decide if we clarify this in the Architecture document

[mryuichi]

we should check with ECHONET how Actions are used (see slide 16). @mryuichi will check with the ECHONET representatives

In the presentation (see slide 25 here) of ECHONET lite on the Open day of vf2f, we found that ECHONET Lite device is basically controlled by setting its property in Web API, but there are exceptions.
(1) Set only property in ECONET Lite is mapped to action in Web API.
(2) Logical objects such as “bulk” and *group” can be controlled by invoking the action.

Case (1) is defined as only 4 cases in Web API (see document) at the moment. Reset the cumulative power generation value of Fuel cell, etc.
Case (2) is that multiple operations are defined as one object and it can be executed in one operation with invoking the action. This is a feature that helps application developers.

@mryuichi will provide a proposal for describing the usage of properties and actions

I found an amazing slide in OCF presentation. (See slide 5 in here)

This slide shows two approaches to device interface representation. One is to define by device resources and their properties. This definition is equivalent to Property in WoT. The other is to define by device functions and operations. This is equivalent to Action in WoT.
The slide also provides an example of a presentation. In this example, the light bulb is represented in two ways, and the same content can be represented by ether Property or Action.

When describing a device as a property, for example, turning on the switch of the bulb, only the property of the switch is changed after this operation. On the other hand, when describing a device operation with Action, different properties can be assigned to the input and the output of the Action. Therefore, only when the input and the output are the same property, it can be described by both Property and Action.

A quick look at the specifications shows that OCF, KNX, BACnet, and ECHONET are defined based on the property so that these devices are easy to map to both Properties and Actions of WoT.

I would like to write a formal description of the usage of property and action.

we should also decide if we clarify this in the Architecture document

The definitions of Action and Property in the architecture document are as follows:

Action
An Interaction Affordance that allows to invoke a function of the Thing, which manipulates state (e.g., toggling a lamp on or off) or triggers a process on the Thing (e.g., dim a lamp over time).
Property
An Interaction Affordance that exposes state of the Thing. This state can then be retrieved (read) and optionally updated (write). Things can also choose to make Properties observable by pushing the new state after a change.

These two definitions say that when you control a device, you’d rather use Action. If we can use both Action and Property, the word “optionally” in the property definition above should be deleted.

[mlagally]

@mryuichi
I'm trying to understand the divergence between Echonet and the WoT TD to ensure we can easily provide interoperability.

As part of the WoT Profile I'm working on payload definitions, that should be clearly defined there.
Unfortunately the Echonet specifications are only available in Japanese language, so I'm not able to review.

Can you please help with a proposal of the required payload structure for Echonet?

[mryuichi]

@mlagally
Sorry, I can't, because Fujitsu is a member of ECHONET consortium but is a B-member that dosen't have the right to make the ECHONET specifications. It should be better to ask A-members such as Mitsubishi, Panasonic, and Toshiba, under the W3C-ECOHNET liaison.