writeProperty message

[benfrancis]

This PR defines a writeProperty message format.

It is intended to fulfil requirement 5.2.2.2 from the Use Cases & Requirements document.

I think the only potentially controversial point with this PR might be the note regarding writeOnly properties which establishes that a writeProperty message may not always receive a response.

Let me know what you think.

---

Preview | Diff

[benfrancis]

Note that an error message can be sent in response if the Thing definitely knows the write was unsuccessful (I'm going to add error conditions to the readProperty and writeProperty in a follow-up PR.

[hspaay]

Looks good. The only comment is about always confirming a writeProperty. I prefer to see a confirmation regardless whether it is readonly or not.

[hspaay]

To me these are two different things. Write-only means that the value of the property cannot be read. The ability to confirm that a write was completed is a separate concern.
If the underlying hardware offers no such confirmation then a 'completed' response would mean that the write was applied. I would still like to see a confirmation.

[benfrancis]

I agree that a property that can't be read and a write that can't be confirmed could be argued to be subtly different things. However, unconfirmable writes do exist.

For example, in the X10 communication protocol some devices do not acknowledge the receipt of commands. You can send a command to switch a device on, but there's no way to tell whether that command was received.

My concern would be that if a Web Thing sends a confirmation message when a write may not actually have been completed or received, it may be misleading.

As far as I know a Thing Description has no way to distinguish a confirmable writeproperty operation from a non-confirmable one (other than by using the writeOnly member of a PropertyAffordance).

Therefore my suggestion would be that a Web Thing that can not confirm whether a write operation has succeeded (for whatever reason) should use the writeOnly member as a hint, and a Consumer should not treat a lack of a response as an error condition in that case. An error message could be sent in response if the write is definitely known to have failed.

[RobWin]

That's why I would really like to differentiate between propertyReading and an acknowledgment that the write request or invokeAction request was processed using the best available method. Even if a write operation cannot be confirmed, the Thing provider should still be able to acknowledge that the request was received and acted upon to the best of its ability.

[benfrancis]

If there's a need for a message type to acknowledge a propertyWrite message without providing a property reading, then yes it does seem like that would need to be separate message type from propertyReading. Adding a special "propertyWriteAcknowledgement" message type feels wrong though, so if this really is important then maybe this is further evidence for the need to split out operation name and message type.

I've filed #42 to explore this further.

[relu91]

I read through the proposal and I also find this point very sensitive. My main concern his how a Consumer should behave when writing a property. If the response "acknowledge" (either we decide to use propertyReading or dedicated ack) MIGHT arrive, then the best behaviour is to never wait for something, but rather request again a property read (if not write-only). If we don't have the ability to specify if a property write is acknowledgable by the TD, I think the default should be "there is no acknowledge".

I would explore the possibility to introduce the term acknowledge: true as a custom protocol binding keyword.

[hspaay]

My vote goes to Ben's proposal in #42:

Response
{
  "thingID": "https://mythingserver.com/things/mylamp1",
  "messageID": "79057736-3e0e-4dc3-b139-a33051901ee2",
  "messageType": "response",
  "operation": "writeproperty",
  "name": "on",
  "value": true,
  "correlationID": "5afb752f-8be0-4a3c-8108-1327a6009cbd"
}
Note: To address the issue raised in https://github.com/w3c/web-thing-protocol/pull/38 about non-confirmable writes, a value could only be provided in a response if it is confirmed to have been written.

This addresses the concern I raised as there is always a response. The response can carry a value if the output is available, no value if the property is writeonly, or an error if it fails. This is deterministic and simple. The Affordance already states whether the property is writeonly so there is no guesswork involved.

[relu91]

Sorry I didn't catch up with the discussion. Then I definitely support the direction above!

[benfrancis]

OK, I will create a PR to split operation from messageType and then re-write this one rebased on top of that.