├── .github └── ISSUE_TEMPLATE │ ├── bug-report.md │ ├── question.md │ ├── requirement.md │ └── use-case.md ├── .pr-preview.json ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE.md ├── README.md ├── charter ├── README.md ├── index.html └── w3c.json ├── index.html ├── requirements ├── images │ ├── cloud_deployment_model.png │ ├── cloud_deployment_model2.png │ ├── direct_deployment_model.png │ ├── gateway_deployment_model.png │ └── gateway_deployment_model2.png └── index.html └── w3c.json /.github/ISSUE_TEMPLATE/bug-report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug Report 3 | about: Report a bug with the Web Thing Protocol specification 4 | title: 'Bug: ' 5 | labels: bug 6 | assignees: '' 7 | 8 | --- 9 | 10 | 11 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/question.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Question 3 | about: Ask a question about the Web Thing Protocol 4 | title: 'Question: [One line description]' 5 | labels: question 6 | assignees: '' 7 | 8 | --- 9 | 10 | 11 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/requirement.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Requirement 3 | about: Propose a technical requirement for the Web Thing Protocol specification 4 | title: 'Requirement: ' 5 | labels: requirement 6 | assignees: '' 7 | 8 | --- 9 | 10 | [MUST/SHOULD/MAY] 11 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/use-case.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Use Case 3 | about: Propose new use cases of the Web Thing Protocol 4 | title: 'Use Case: [One line description]' 5 | labels: use case 6 | assignees: '' 7 | 8 | --- 9 | 10 | As a I want to so that 11 | -------------------------------------------------------------------------------- /.pr-preview.json: -------------------------------------------------------------------------------- 1 | { 2 | "src_file": "index.html", 3 | "type": "respec" 4 | } 5 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/). 4 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Web Thing Protocol Community Group 2 | 3 | This repository is being used for work in the W3C Web Thing Protocol Community Group, governed by the [W3C Community License Agreement (CLA)](http://www.w3.org/community/about/agreements/cla/). To make substantive contributions, you must join the CG. 4 | 5 | If you are not the sole contributor to a contribution (pull request), please identify all 6 | contributors in the pull request comment. 7 | 8 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows: 9 | 10 | ``` 11 | +@github_username 12 | ``` 13 | 14 | If you added a contributor by mistake, you can remove them in a comment with: 15 | 16 | ``` 17 | -@github_username 18 | ``` 19 | 20 | If you are making a pull request on behalf of someone else but you had no part in designing the 21 | feature, you can remove yourself with the above syntax. 22 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | All documents in this Repository are licensed by contributors 2 | under the 3 | [W3C Software and Document License](http://www.w3.org/Consortium/Legal/copyright-software). 4 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Web Thing Protocol 2 | This is the source code repository for the W3C Web Thing Protocol Community Group. 3 | 4 | * [Charter](https://w3c.github.io/web-thing-protocol/charter/) 5 | * [Use Cases & Requirements Report](https://www.w3.org/community/reports/web-thing-protocol/CG-FINAL-web-thing-protocol-requirements-20231101/) 6 | * [Web Thing Protocol Draft Report](https://w3c.github.io/web-thing-protocol/) 7 | * [Wiki](https://github.com/w3c/web-thing-protocol/wiki) 8 | -------------------------------------------------------------------------------- /charter/README.md: -------------------------------------------------------------------------------- 1 | [W3C Web Thing Protocol Community Group Charter](https://w3c.github.io/web-thing-protocol/charter/) 2 | -------------------------------------------------------------------------------- /charter/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Web Thing Protocol Community Group Charter 6 | 7 | 8 | 9 | 10 | 29 | 30 | 31 |

32 | Web Thing Protocol Community Group Charter 33 |

34 |

35 | To submit feedback, please use GitHub issues. 36 |

37 | 47 |

48 | Mission 49 |

50 |

51 | The mission of this group is to define a common protocol for communicating with connected devices over the web, to enable ad-hoc interoperability on the Web of Things. 52 |

53 | 54 |

55 | Scope 56 |

57 |

Deliverables of the group may include use cases, requirements and specifications. This includes:

58 |
    59 |
  1. Definition of a WebSocket sub-protocol for the Web of Things, using the W3C “Web of Things (WoT) Thing Description” data model and operations
    2. 60 |
  2. Definition of an HTTP sub-protocol for the Web of Things 61 |
    (or support of the Web of Things Working Group in defining this sub-protocol and ensuring consistency with the WebSocket sub-protocol where appropriate)
    3. 62 |
  3. Evaluation of other potential Web of Things sub-protocols (e.g. for CoAP)
    4. 63 |
64 |

Key use cases include:

65 |
    66 |
  1. Web of Things gateways which expose the Web Thing Protocol to allow clients to monitor and control connected devices over the web (where the devices themselves may communicate with the gateway using other underlying protocols)
    2. 67 |
  2. Web of Things devices which directly expose the Web Thing Protocol
    3. 68 |
  3. Web of Things clients which discover, monitor and control connected devices using the Web Thing Protocol
    4. 69 |
70 | 71 |

72 | Out of Scope 73 |

74 |

Protocol bindings/sub-protocols for non-web or non-internet protocols.

75 |

76 | Deliverables 77 |

78 |

79 | Specifications 80 |

81 |
    82 |
  • Web Thing Protocol Specification, including:
    • 83 |
      84 |
    • A WebSocket sub-protocol for the Web of Things
      • 85 |
    • An HTTP sub-protocol for the Web of Things 86 |
      (or reference to an HTTP sub-protocol in the Web of Things (WoT) Thing Description specification.)
      • 87 |
    88 |
89 |

90 | Non-Normative Reports 91 |

92 |

93 | The group may produce other Community Group Reports within the scope of 94 | this charter but that are not Specifications, for instance use cases, 95 | requirements, or white papers. 96 |

97 |

98 | Test Suites and Other Software 99 |

100 |

101 | The group MAY produce test suites to support the Specifications. Please 102 | see the GitHub LICENSE file for test suite contribution licensing 103 | information. 104 |

105 |

106 | Dependencies or Liaisons 107 |

108 | 114 |

115 | Community and Business Group Process 116 |

117 |

118 | The group operates under the Community and Business 120 | Group Process. Terms in this Charter that conflict with those of the 121 | Community and Business Group Process are void. 122 |

123 |

124 | As with other Community Groups, W3C seeks organizational licensing 125 | commitments under the W3C Community 127 | Contributor License Agreement (CLA). When people request to 128 | participate without representing their organization's legal interests, 129 | W3C will in general approve those requests for this group with the 130 | following understanding: W3C will seek and expect an organizational 131 | commitment under the CLA starting with the individual's first request to 132 | make a contribution to a group Deliverable. 133 | The section on Contribution Mechanics describes 134 | how W3C expects to monitor these contribution requests. 135 |

136 | 137 |

138 | The W3C Code of 139 | Ethics and Professional Conduct applies to participation in 140 | this group. 141 |

142 | 143 |

144 | Work Limited to Charter Scope 145 |

146 |

147 | The group will not publish Specifications on topics other than those 148 | listed under Specifications above. See 149 | below for how to modify the charter. 150 |

151 |

152 | Contribution Mechanics 153 |

154 |

155 | Substantive Contributions to Specifications can only be made by Community 156 | Group Participants who have agreed to the W3C Community 158 | Contributor License Agreement (CLA). 159 |

160 |

161 | Specifications created in the Community Group must use the 163 | W3C Software and Document License. All other documents produced by 164 | the group should use that License where possible. 165 |

166 |

167 | Community Group participants agree to make all contributions in the 168 | GitHub repo the group is using for the particular document. This may be 169 | in the form of a pull request (preferred), by raising an issue, or by 170 | adding a comment to an existing issue. 171 |

172 |

173 | All Github repositories attached to the Community Group must contain a 174 | copy of the CONTRIBUTING 176 | and LICENSE 178 | files. 179 |

180 |

181 | Transparency 182 |

183 |

184 | The group will conduct all of its technical work in public. If the group 185 | uses GitHub, all technical work will occur in its GitHub repositories 186 | (and not in mailing list discussions). This is to ensure contributions 187 | can be tracked through a software tool. 188 |

189 |

190 | Meetings may be restricted to Community Group participants, but a public 191 | summary or minutes must be posted to the group's public mailing list, or 192 | to a GitHub issue if the group uses GitHub. 193 |

194 |

195 | Decision Process 196 |

197 |

198 | This group will seek to make decisions where there is consensus. Groups 199 | are free to decide how to make decisions (e.g. Participants who have 200 | earned Committer status for a history of useful contributions assess 201 | consensus, or the Chair assesses consensus, or where consensus isn't 202 | clear there is a Call for Consensus [CfC] to allow multi-day online 203 | feedback for a proposed course of action). It is expected that 204 | participants can earn Committer status through a history of valuable 205 | contributions as is common in open source projects. After discussion and 206 | due consideration of different opinions, a decision should be publicly 207 | recorded (where GitHub is used as the resolution of an Issue). 208 |

209 |

210 | If substantial disagreement remains (e.g. the group is divided) and the 211 | group needs to decide an Issue in order to continue to make progress, the 212 | Committers will choose an alternative that had substantial support (with 213 | a vote of Committers if necessary). Individuals who disagree with the 214 | choice are strongly encouraged to take ownership of their objection by 215 | taking ownership of an alternative fork. This is explicitly allowed (and 216 | preferred to blocking progress) with a goal of letting implementation 217 | experience inform which spec is ultimately chosen by the group to move 218 | ahead with. 219 |

220 |

221 | Any decisions reached at any meeting are tentative and should be recorded 222 | in a GitHub Issue for groups that use GitHub and otherwise on the group's 223 | public mail list. Any group participant may object to a decision reached 224 | at an online or in-person meeting within 7 days of publication of the 225 | decision provided that they include clear technical reasons for their 226 | objection. The Chairs will facilitate discussion to try to resolve the 227 | objection according to the decision process. 228 |

229 |

230 | It is the Chairs' responsibility to ensure that the decision process is 231 | fair, respects the consensus of the CG, and does not unreasonably favour 232 | or discriminate against any group participant or their employer. 233 |

234 |

235 | Chair Selection 236 |

237 |

238 | Participants in this group choose their Chair(s) and can replace their 239 | Chair(s) at any time using whatever means they prefer. However, if 5 240 | participants, no two from the same organisation, call for an election, 241 | the group must use the following process to replace any current Chair(s) 242 | with a new Chair, consulting the Community Development Lead on election 243 | operations (e.g., voting infrastructure and using RFC 2777). 245 |

246 |
    247 |
  1. Participants announce their candidacies. Participants have 14 days to 248 | announce their candidacies, but this period ends as soon as all 249 | participants have announced their intentions. If there is only one 250 | candidate, that person becomes the Chair. If there are two or more 251 | candidates, there is a vote. Otherwise, nothing changes. 252 |
    2. 253 |
  2. Participants vote. Participants have 21 days to vote for a single 254 | candidate, but this period ends as soon as all participants have voted. 255 | The individual who receives the most votes, no two from the same 256 | organisation, is elected chair. In case of a tie, RFC2777 is used to 257 | break the tie. An elected Chair may appoint co-Chairs. 258 |
    3. 259 |
260 |

261 | Participants dissatisfied with the outcome of an election may ask the 262 | Community Development Lead to intervene. The Community Development Lead, 263 | after evaluating the election, may take any action including no action. 264 |

265 |

266 | Amendments to this Charter 267 |

268 |

269 | The group can decide to work on a proposed amended charter, editing the 270 | text using the Decision Process described above. 271 | The decision on whether to adopt the amended charter is made by 272 | conducting a 30-day vote on the proposed new charter. The new charter, if 273 | approved, takes effect on either the proposed date in the charter itself, 274 | or 7 days after the result of the election is announced, whichever is 275 | later. A new charter must receive 2/3 of the votes cast in the approval 276 | vote to pass. The group may make simple corrections to the charter such 277 | as deliverable dates by the simpler group decision process rather than 278 | this charter amendment process. The group will use the amendment process 279 | for any substantive changes to the goals, scope, deliverables, decision 280 | process or rules for amending the charter. 281 |

282 | 283 | 284 | -------------------------------------------------------------------------------- /charter/w3c.json: -------------------------------------------------------------------------------- 1 | { 2 | "contacts": "ianbjacobs", 3 | "repo-type": "process" 4 | } 5 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Web Thing Protocol 7 | 8 | 28 | 29 | 30 | 31 |

Web Thing Protocol

32 |

WebSocket Sub-protocol

33 | 34 |
35 |

This document defines a WebSocket sub-protocol called the Web Thing 36 | Protocol, for monitoring and controlling connected devices over the 37 | World Wide Web. The Web Thing Protocol is intended as a dedicated 38 | real-time protocol for the Web of 39 | Things, to enable a WoT 40 | Consumer 41 | to communicate with one or more WoT 42 | Things 43 | over a WebSocket connection. 44 |

45 |
46 | 47 |
48 | 55 |
56 | 57 |
58 |

Introduction

59 |

This document defines a WebSocket [[WEBSOCKETS-PROTOCOL]] sub-protocol for 60 | monitoring and controlling connected devices over the Web. 61 |

62 |

The Web of Things (WoT) is a 63 | collection of standardised technology building blocks that help provide 64 | interoperability on the 65 | Internet of 66 | Things (IoT). The WoT Thing Description specification 67 | [[wot-thing-description11]] defines a metadata format for 68 | describing the capabilities of "Things" (connected 69 | devices) on the Web. The WoT Discovery specification [[wot-discovery]] 70 | defines mechanisms for discovering Things on the Web. This 71 | specification complements those building blocks by 72 | defining a dedicated real-time protocol for communicating with Things over the 73 | Web. 74 |

75 |

WebSockets [[WEBSOCKETS-PROTOCOL]] provide a way to upgrade a 76 | standard HTTP [[HTTP11]] request to a full-duplex, persistent, real-time 77 | communication channel over a single TCP connection. This can be used to 78 | create a versatile and efficient two-way channel with which a WoT 79 | Consumer 80 | can communicate with one or more 81 | Things 82 | [[wot-architecture11]] to carry out the full set of WoT 83 | operations. 84 | However, since a WebSocket is essentially just a raw TCP socket with no 85 | semantics of its own, a sub-protocol needs to be defined in order for a 86 | Consumer and Thing to communicate. 87 |

88 |

Whilst many other WebSocket 89 | sub-protocols exist, what makes the Web Thing Protocol unique 90 | is that it is specifically designed around the Web of Things 91 | information 92 | model and 93 | set 94 | of operations [[wot-thing-description11]], as well as being 95 | targeted specifically at Web of Things use cases [[wot-usecases]]. It 96 | can therefore be thought of as being native to the Web of Things. 97 |

98 |

99 | The sub-protocol defines message payload formats for each of the 100 | well-known 101 | 102 | operation types defined in the WoT 103 | 104 | interaction model [[wot-architecture11]], and other messages needed for 105 | WebSocket communication. 106 |

107 |

108 | This specification is intended to complement deliverables of the 109 | WoT Working Group, including WoT 110 | Architecture [[wot-architecture11]], WoT Thing Description 111 | [[wot-thing-description11]], WoT Discovery [[wot-discovery]], 112 | WoT Binding Templates [[wot-binding-templates]] and WoT Profile 113 | [[wot-profile]]. It is intended to implement use cases and requirements 114 | defined in the 115 | Web 117 | Thing Protocol Use Cases & Requirements community report. 118 |

119 |

Whilst this document is not on a standards track, the Web Thing Protocol 120 | is intended to eventually join a standards track at the W3C or another 121 | standards body such as the IETF. 122 |

123 |
124 | 125 |
126 |
127 | 128 |
129 |

Terminology

130 |

Fundamental WoT terminology such as Thing or Web Thing, Consumer or WoT 131 | Consumer, WoT Thing Description or Thing Description, Interaction Model, 132 | Interaction Affordance, Property, Action and Event are defined in 133 | the 134 | Terminology 135 | section of the WoT Architecture specification [[wot-architecture11]]. 136 |

137 |
138 | 139 |
140 |

WebSocket Connection

141 |
142 |

Protocol Handshake

143 |

In order to communicate with a Web Thing, 144 | a WoT Consumer [[wot-architecture11]] MUST 145 | locate one or more WebSocket [[WEBSOCKETS-PROTOCOL]] endpoints provided by the Thing for a given set of 146 | Interaction Affordances 147 | [[wot-thing-description11]]. 148 |

149 |

The URL of a WebSocket endpoint to be used for a given interaction MUST be obtained from a Thing 150 | Description 151 | [[wot-architecture11]] by locating a Form inside 152 | the corresponding Interaction Affordance for which: 153 |

    154 |
  • After being resolved against a base URL 156 | [[wot-thing-description11]] where applicable, the URI scheme [[RFC3986]] of the value of its href member 158 | [[wot-thing-description11]] is "ws" or &"wss"
    • 159 |
  • Its subprotocol 161 | member has a value of "webthingprotocol"
    • 162 |
163 |

164 |

To open a WebSocket on a Thing, an HTTP GET request [[RFC9110]] MUST be upgraded to 166 | a WebSocket connection using a standard WebSocket protocol handshake [[WEBSOCKETS-PROTOCOL]], 168 | specifying the "webthingprotocol" sub-protocol. 169 |

170 | 
171 |         GET wss://mythingserver.com/things/robot
172 |         Host: mythingserver.com
173 |         Origin: https://mythingserver.com
174 |         Upgrade: websocket
175 |         Connection: Upgrade
176 |         Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
177 |         Sec-WebSocket-Protocol: webthingprotocol
178 |         Sec-WebSocket-Version: 13
179 |
180 | 
181 |         HTTP/1.1 101 Switching Protocols
182 |         Upgrade: websocket
183 |         Connection: Upgrade
184 |         Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
185 |         Sec-WebSocket-Protocol: webthingprotocol        
186 |
187 |

188 | Sub-protocol name to be confirmed, see IANA Considerations. 189 |

190 |

A WebSocket can be opened from a web page using the JavaScript WebSocket API [[WEBSOCKETS-API]] 191 | which will take care of the handshake detailed above and allow messages to be sent and received. 192 |

193 | 
194 |         const socket = new WebSocket('wss://mywebthingserver/things/robot', 'webthingprotocol');
195 |
196 |
197 | 198 |
199 |

WebSocket Re-use

200 |

A single WebSocket [[WEBSOCKETS-PROTOCOL]] connection from a WoT Consumer MAY be shared between multiple 201 | Interaction 202 | Affordances of a Thing. A single WebSocket connection from a WoT Consumer MAY also be shared 203 | between multiple Things. 204 |

205 |

Before opening a new WebSocket connection, a WoT Consumer SHOULD check whether it already has an open 206 | connection to the same WebSocket endpoint URL.

207 |

If an existing connection to the same WebSocket endpoint URL exists, then that connection SHOULD be re-used 208 | rather than opening an additional socket.

209 |

If an existing connection to the same WebSocket endpoint URL exists but is using a different set of credentials 210 | for its given SecurityScheme 212 | [[wot-thing-description11]] (e.g. a different Bearer Token), then the WoT Consumer MUST NOT re-use the 213 | connection.

214 |
215 |
216 | 217 |
218 |

WebSocket Messages

219 |

All messages MUST be a JSON object [[JSON]].

220 | 221 | 222 | 223 | 224 | 225 | 226 | 227 | 228 | 229 | 230 | 231 | 232 | 233 | 234 | 235 | 236 | 237 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 251 | 252 | 253 | 254 | 255 | 256 | 267 | 268 | 269 | 270 | 271 | 273 | 274 | 275 |
Common members of all messages
MemberTypeAssignmentDescription
thingIDstringMandatoryThe ID (URI) of the Thing to which the message relates.
messageIDstringMandatoryA unique identifier (UUID) for the current message.
messageTypestringMandatoryA string which denotes the type of message (one of request, response or 249 | notification). 250 |
operationstringMandatoryA string which denotes the type of WoT operation 258 | [[wot-thing-description11]] to which the message relates (one of 259 | readproperty, writeproperty, observeproperty, 260 | unobserveproperty, invokeaction, queryaction, 261 | cancelaction, subscribeevent, unsubscribeevent, 262 | readallproperties, writeallproperties, readmultipleproperties, 263 | writemultipleproperties, observeallproperties, 264 | unobserveallproperties, subscribeallevents, unsubscribeallevents, or 265 | queryallactions). 266 |
correlationIDstringOptionalA unique identifer (UUID) which is shared between messages corresponding to the same operation, e.g. a 272 | request and a response.
276 | 277 |

The top level JSON object MUST contain a thingID member with the value set to a unique identifier of 278 | the Web Thing to which the message relates. 279 | If the Thing Description of the Web Thing contains an id member then the value of that 280 | id member MUST be used as the unique identifier assigned to thingID. 281 | If the Thing Description of the Web Thing does not contain an id member then the URL 282 | [[URL]] from which the Thing Description was retrieved MAY be used as the thingID value 283 | instead. The value of the thingID member MUST be a valid URI [[URI]] serialised as a string. 284 |

285 |

The top level JSON object MUST contain a messageID member with the value set to a unique identifier 286 | for the current message in UUIDv4 format [[rfc9562]].

287 |

The top level JSON object MUST contain a messageType member, with its value set to one of 288 | request, response or notification. 289 |

290 | 291 | 292 | 293 | 294 | 295 | 296 | 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 305 | 307 | 308 | 309 | 310 | 311 | 313 | 314 | 315 | 316 | 317 | 319 | 320 | 321 |
Message types
Message typeDirectionDescription
requestConsumer ➡ ThingA message sent from a Consumer to a Thing (e.g. to request a reading of a property, invoke an 306 | action or subscribe to an event)
responseThing ➡ ConsumerA message sent from a Thing to a Consumer in response to a request (e.g. to respond with a property 312 | reading, provide the final response to an action or confirm a subscription to an event)
notificationThing ➡ ConsumerA message pushed from a Thing to a Consumer (e.g. an event, change in property value, or 318 | change in action state)
322 | 323 |

The top level JSON object MUST contain an operation member, with its value set to one of the 324 | well-known WoT operation names from 325 | the Thing Description specification [[wot-thing-description11]].

326 |

The lifecycle of an operation consists of a series of messages in a sequence (e.g. a request followed by a 327 | response, or a request followed by a response then one or more notifications). Each type of operation follows a 328 | particular sequence of message types, outlined in the table below:

329 | 330 | 331 | 332 | 333 | 334 | 335 | 336 | 337 | 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | 347 | 348 |
Operation lifecycles
OperationLifecycle
readpropertyrequest, response
writepropertyrequest, response
349 | 350 |

The top level JSON object MAY contain a correlationID member which provides a unique identifier in 351 | UUIDv4 format [[rfc9562]] which is shared between messages corresponding to the same WoT operation (e.g. a 352 | property read request and response, or an event subscription request and event notification). If a request message 353 | contains a correlatonID member then any response and notification messages which correspond to the 354 | same operation SHOULD also include a correlationID member with the same value.

355 | 356 |

All date and time values MUST use the date-time format 357 | defined in [[RFC3339]]. 358 |

359 | 
360 |       2025-01-15T12:08:00.42Z
361 |
362 |

363 | In order to reduce ambiguity, RFC 3339 only permits an hour with a value 364 | between 00 and 23 (not 24), and time zones expressed as a numerical 365 | offset relative to UTC. The suffix "Z" when applied to a time denotes a 366 | UTC offset of 00:00. 367 |

368 |
369 |

readproperty

370 |
371 |

Request

372 |

To request a property reading from a Thing, a Consumer MUST send a message to the Thing 374 | which contains the following members:

375 | 376 | 377 | 378 | 379 | 380 | 381 | 382 | 383 | 384 | 385 | 386 | 387 | 388 | 389 | 390 | 391 | 392 | 393 | 394 | 395 | 396 | 397 | 398 | 399 | 400 | 401 | 402 | 405 | 406 | 407 |
Members of a readproperty request message
MemberTypeAssignmentDescription
messageTypestring"request"A string which denotes that this message is a request sent from a Consumer to a Thing.
operationstring"readproperty"A string which denotes that this message relates to a readproperty operation.
namestringMandatoryThe name of the Property to read, as per its key in the properties member of 403 | the Thing Description. 404 |
408 | 
409 |           {
410 |             "thingID": "https://mythingserver.com/things/mylamp1",
411 |             "messageID": "c370da58-69ae-4e83-bb5a-ac6cfb2fed54",
412 |             "messageType": "request",
413 |             "operation": "readproperty",
414 |             "name": "on",
415 |             "correlationID": "5afb752f-8be0-4a3c-8108-1327a6009cbd"
416 |           }
417 |
418 |

When a Thing receives a message from a Consumer with messageType set to 419 | request and operation set to readproperty it MUST 420 | attempt to read the value of the Property with the given name. 421 |

422 |
423 |
424 |

Response

425 |

Upon successfully reading the value of the requested Property, the Thing MUST send a message to the 426 | requesting Consumer containing the following members:

427 | 428 | 429 | 430 | 431 | 432 | 433 | 434 | 435 | 436 | 437 | 438 | 439 | 440 | 441 | 442 | 444 | 445 | 446 | 447 | 448 | 449 | 451 | 452 | 453 | 454 | 455 | 456 | 460 | 461 | 462 | 463 | 464 | 465 | 467 | 468 | 469 | 470 | 471 | 472 | 473 | 474 | 475 |
Members of a readproperty response message
MemberTypeAssignmentDescription
messageTypestring"response"A string which denotes that this message is a response sent from a Thing to a Consumer. 443 |
operationstring"readproperty"A string which denotes that this message relates to a readproperty operation. 450 |
namestringMandatoryThe name of the Property being read, as per its key in the properties member of 457 | the 458 | Thing Description. 459 |
valueanyMandatoryThe current value of the Property being read, with a type and structure conforming to the data 466 | schema of the corresponding PropertyAffordance in the Thing Description.
timestampstringOptionalA timestamp in date-time format [[RFC3339]] set to the time the property reading took place.
476 | 
477 |           {
478 |             "thingID": "https://mythingserver.com/things/mylamp1",
479 |             "messageID": "79057736-3e0e-4dc3-b139-a33051901ee2",
480 |             "messageType": "response",
481 |             "operation": "readproperty",
482 |             "name": "on",
483 |             "value": true,
484 |             "timestamp": "2024-01-13T23:20:50.52Z",
485 |             "correlationID": "5afb752f-8be0-4a3c-8108-1327a6009cbd"
486 |           }
487 |
488 |
489 |
490 | 491 |
492 |

writeproperty

493 |
494 |

Request

495 |

To set the value of a Property of a Thing, a Consumer MUST send a message to the Thing which contains the following members:

497 | 498 | 499 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 509 | 510 | 511 | 512 | 513 | 514 | 515 | 516 | 517 | 518 | 519 | 520 | 521 | 522 | 523 | 524 | 527 | 528 | 529 | 530 | 531 | 532 | 534 | 535 | 536 |
Members of a writeproperty request message
MemberTypeAssignmentDescription
messageTypestring"request"A string which denotes that this message is a request sent from a Consumer to a Thing.
operationstring"writeproperty"A string which denotes that this message relates to a writeproperty operation.
namestringMandatoryThe name of the Property whose value should be set, as per its key in the 525 | properties member of the Thing Description. 526 |
valueanyMandatoryThe desired new value of the Property, with a type and structure conforming to the data schema 533 | of the corresponding PropertyAffordance in the Thing Description.
537 | 
538 |           {
539 |             "thingID": "https://mythingserver.com/things/mylamp1",
540 |             "messageID": "97d22676-6d45-4435-aef5-dd87467a0c44",
541 |             "messageType": "response",
542 |             "operation": "writeproperty",
543 |             "name": "on",
544 |             "value": true,
545 |             "correlationID": "f6cf46a8-9c96-437e-8b53-925b7679a990"
546 |           }
547 |
548 |
549 | 550 |
551 |

Response

552 |

When a Thing receives a message from a Consumer with messageType set to 553 | request and operation set to writeproperty it MUST 554 | attempt to set the Property with the name provided in the name member to 555 | the value provided in the value member. 556 |

557 |

Upon successfully submitting the value of the requested Property, the Thing MUST send a message to the 558 | requesting Consumer containing the following members:

559 | 560 | 561 | 562 | 563 | 564 | 565 | 566 | 567 | 568 | 569 | 570 | 571 | 572 | 573 | 574 | 576 | 577 | 578 | 579 | 580 | 581 | 583 | 584 | 585 | 586 | 587 | 588 | 592 | 593 | 594 | 595 | 596 | 597 | 601 | 602 | 603 | 604 | 605 | 606 | 607 | 608 | 609 |
Members of a writeproperty response message
MemberTypeAssignmentDescription
messageTypestring"response"A string which denotes that this message is a response sent from a Thing to a Consumer. 575 |
operationstring"writeproperty"A string which denotes that this message relates to a writeproperty operation. 582 |
namestringMandatoryThe name of the Property being written, as per its key in the properties member of 589 | the 590 | Thing Description. 591 |
valueanyOptionalThe value which has been successfully assigned to the Property being written, with a type and 598 | structure conforming to the data schema of the corresponding PropertyAffordance in the Thing 599 | Description. 600 |
timestampstringOptionalA timestamp in date-time format [[RFC3339]] set to the time the property write took place.
610 | 
611 |           {
612 |             "thingID": "https://mythingserver.com/things/mylamp1",
613 |             "messageID": "db25fe4f-bee8-43a7-8ff0-3a1ff6e620b0",
614 |             "messageType": "response",
615 |             "operation": "writeproperty",
616 |             "name": "on",
617 |             "value": true,
618 |             "timestamp": "2024-01-13T23:20:50.52Z",
619 |             "correlationID": "f6cf46a8-9c96-437e-8b53-925b7679a990"
620 |           }
621 |
622 |

If the Thing can confirm that the requested value has been set successfully then the response message 623 | to a writeproperty request SHOULD contain a value member with its value set to the 624 | value which has been successfully set. 625 |

626 |

If the Thing can not confirm that the requested value has been set successfully (e.g. in the case of a 627 | write-only property or a device that is temporarily asleep so the write has been queued) then 628 | the response message to a writeproperty request MUST NOT contain a 629 | value member. 630 |

631 |

If a Consumer attempts to set the value of a numerical Property to a value which conforms to the 632 | Property's data schema but to a level of precision the Thing does not support, (e.g. 3.14159), then the 633 | Thing MAY respond with the actual value set (e.g. 3.14). 634 |

635 |

636 |
637 |
638 |
639 | 640 |
641 |

Example Thing Descriptions

642 |
643 | 644 |
645 |

Privacy Considerations

646 |
647 | 648 |
649 |

Security Considerations

650 |
651 | 652 |
653 |

Accessibility Considerations

654 |
655 | 656 |
657 |

IANA Considerations

658 |

This specification proposes the registration of a sub-protocol in the IANA "WebSocket Subprotocol Name Registry". 660 | The name of the sub-protocol and the published URL of its definition are to be confirmed, but currently the name 661 | "webthingprotocol" and this document are used as a placeholder and draft proposal.

662 |
663 |
Subprotocol Identifier
664 |
webthingprotocol
665 | 666 |
Subprotocol Common Name
667 |
Web Thing Protocol
668 | 669 |
Subprotocol Definition
670 |
This document.
671 |
672 |
673 | 674 | 675 | 676 | -------------------------------------------------------------------------------- /requirements/images/cloud_deployment_model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/web-thing-protocol/11d2ab1213f157ab4db5877cd3f473c4de5260d3/requirements/images/cloud_deployment_model.png -------------------------------------------------------------------------------- /requirements/images/cloud_deployment_model2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/web-thing-protocol/11d2ab1213f157ab4db5877cd3f473c4de5260d3/requirements/images/cloud_deployment_model2.png -------------------------------------------------------------------------------- /requirements/images/direct_deployment_model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/web-thing-protocol/11d2ab1213f157ab4db5877cd3f473c4de5260d3/requirements/images/direct_deployment_model.png -------------------------------------------------------------------------------- /requirements/images/gateway_deployment_model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/web-thing-protocol/11d2ab1213f157ab4db5877cd3f473c4de5260d3/requirements/images/gateway_deployment_model.png -------------------------------------------------------------------------------- /requirements/images/gateway_deployment_model2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/web-thing-protocol/11d2ab1213f157ab4db5877cd3f473c4de5260d3/requirements/images/gateway_deployment_model2.png -------------------------------------------------------------------------------- /requirements/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Web Thing Protocol 6 | 9 | 30 | 31 | 32 |
33 |

This document outlines the use cases and requirements for a common sub-protocol for the Web of Things to enable ad-hoc interoperability between Web Things and their Consumers. This includes requirements for an HTTP sub-protocol and a WebSocket sub-protocol which define a standard way to monitor and control a connected device over the World Wide Web.

34 |
35 |
36 |
37 |
38 |

Introduction

39 | 40 |

The goal of the Web of Things (WoT) is to counter the fragmentation of the Internet of Things (IoT) using web technologies. By providing standardised metadata and other re-usable technological building blocks, W3C WoT enables easy integration across IoT platforms and application domains.

41 |

The W3C WoT Thing Description [[wot-thing-description]] specification defines the first building block of the Web of Things, by defining an information model and JSON-based representation format for describing the capabilities of connected devices and the interfaces with which to communicate with them.

42 |

The Thing Description specification is designed to be protocol-agnostic and flexible enough to describe a wide range of existing ("brownfield") IoT devices, rather than specifying a fixed protocol or application programming interface (API) which all devices must implement. The downside of this open ended flexibility is that it makes ad-hoc interoperability on the Web of Things very difficult, because it's nearly impossible to create a single WoT Consumer which is guaranteed to be able to communicate with any Web Thing [[wot-architecture]] out of the box.

43 |

The Web Thing Protocol specification will be designed to complement the WoT Thing Description specification [[wot-thing-description]] by defining a common sub-protocol for the Web of Things such that any WoT Consumer and Web Thing which implement the specification will be guaranteed to be able to communicate with each other other out of the box, without device-specific customisation.

44 |

The Web Thing Protocol specification (or specifications) will define:

45 |
    46 |
  • An HTTP sub-protocol (REST API) which defines a standard way to communicate with a Web Thing using the HTTP protocol [[HTTP11]]
    • 47 |
  • A WebSocket sub-protocol which defines how to communicate with a Web Thing over the WebSockets protocol [[WEBSOCKETS-PROTOCOL]]
    • 48 |
49 |

This document outlines the use cases and requirements for such a specification, based on existing Web of Things implementations and the collective experience of members of the Web Thing Protocol Community Group.

50 |

In addition to the WoT Thing Description, the Web Thing Protocol Community Group should aim for the Web Thing Protocol specification to complement other deliverables in progress by the WoT Working Group where possible, including WoT Discovery [[wot-discovery]], WoT Binding Templates [[wot-binding-templates]] and WoT Profile [[wot-profile]]. It's possible some of the requirements below may be fulfilled by those specifications. The Web Thing Protocol specification itself, or subsections of it, are intended to eventually join a standards track at the W3C or another standards body such as the IETF.

51 |
52 |
53 |
54 |
55 |

Use Cases

56 |

Below are a selection of use cases of the Web Thing Protocol from a range of different application domains.

57 |

A larger set of use cases for the Web of Things in general can also be found in Web of Things (WoT): Use Cases and Requirements [[wot-usecases]].

58 |
59 |

Smart Home

60 |
61 |

Smart Home Devices

62 |

As the manufacturer of a smart home device I want to know that any compliant smart home software application will be able to communicate with my device without device-specific customisation, so that I can maximise the size of the market for my product.

63 |

As a retailer of smart home devices I want to be able to tell my customers that a device will work with their existing smart home app, hub or cloud service so that I can sell more devices.

64 |

As a customer looking to buy a smart home device, I want to be sure that the device is compatible with my existing smart home app, hub or cloud service.

65 |
66 |
67 |

Smart Home Hubs

68 |

As the manufacturer of a smart home hub I want my hub to be compatible with as many devices as possible in order to maximise the size of the market for my product.

69 |

As the manufacturer of a smart home hub, I want to bridge a wide range of different smart home protocols to a single standardised interface so that they can be consumed by a single client software application.

70 |

As the user of a smart home hub, I want my hub to be compatible with as many devices as possible so that I'm not locked in to a single hardware vendor and can easily integrate devices from different vendors together in order to automate my home.

71 |
72 |
73 |

Smart Home Cloud Services

74 |

As the developer of a smart home cloud service I want to be able to monitor and control a wide range of smart home devices from different vendors in order to maximise the size of the market for my service.

75 |

As a smart home user I want to have a choice of third party services to help monitor and automate my home so that I am not locked into a single service provider and can find the best value service for my needs.

76 |
77 |
78 |

Smart Home Software Applications

79 |

As the developer of an IoT software library, I want my library to work with a wide range of different IoT devices without needing per-device customisation so that I can maximise the audience for my software.

80 |

As the developer of a smart home mobile app I want to offer my users out-of-the-box interoperability with a wide range of smart home devices so that I can maximise the audience for my app.

81 |

As a user of a smart home mobile app I want to know that I will be able to monitor and control any conformant smart home device so that I don't need a different app per device or device-specific customisations.

82 |
83 |
84 |
85 |

Smart Buildings

86 |
87 |

Smart Building Devices

88 |

As the manufacturer of a smart building device I want to know that any compliant building management system will be able to communicate with my device without device-specific customisation, so that I can maximise the size of the market for my product.

89 |

As a facilities manager of a commercial building, I want to know that a given IoT device will seamlessly integrate with my existing building management system without device-specific customisation.

90 |
91 |
92 |

Smart Building Hubs

93 |

As the manufacturer of a smart building hub for commercial buildings, I want my hub to be compatible with as many devices as possible in order to maximise the size of the market for my product.

94 |

As the manufacturer of a smart building hub for commercial buildings, I want to bridge a wide range of different building management systems to a single standardised interface that my smart building software can consume.

95 |

As a facilities manager of a commercial building I want to consolidate my multi-vendor building management system into a single standardised interface that I can use for command, control, automation and analytics for my building.

96 |
97 |
98 |

Smart Building Cloud Services

99 |

As the developer of a cloud service which provides digital twins of commercial buildings, I want to be able to consume data from a wide range of devices and building management systems in order to maximise the size of the market for my service.

100 |

As a facilities manager of a commercial building, I want to have a choice of third party services which can provide analytics for the data from my building management system so that I am not locked into a single service provider and can find the best value service for my needs.

101 |
102 |
103 |

Smart Building Software Applications

104 |

As the developer of an IoT software library, I want my library to work with a wide range of different IoT devices without needing per-device customisation so that I can maximise the audience for my software.

105 |

As a facilities manager of a commercial building I want to monitor and control the HVAC, lighting, safety and security systems of my building all through a single desktop or tablet application, so that I don't have to piece together information from multiple separate systems in order to get a full picture of the operations of my building.

106 |
107 |
108 |
109 |

Smart Cities

110 |

As a technician working on a smart city project for a public body, I want to be able to consolidate data from a wide range of different public and private sources into a standardised format in order to create a real time digital twin of a whole city to be used for city planning.

111 |
112 |
113 |

Manufacturing

114 |

As a factory worker I want to be able to consume data from all of the devices on my factory floor in a single standardised format so that I can build a digital twin of the factory in order to model how it's running and identify optimisations.

115 |
116 |
117 |

Energy

118 |

As a technician at a renewable energy company, I want to create digital twins of a range of different assets in order to monitor the performance and efficiency of my energy network in real time and carry out predictive maintenance.

119 |
120 |
121 |

Transportation

122 |

As an operations manager at a bus company, I want to monitor the location and condition of a range of different assets over the internet in order to monitor the efficiency of my bus network and carry out predictive maintenance.

123 |
124 |
125 |

Agriculture

126 |

As a farmer I want to integrate a range of different sensors (e.g. temperature, light, soil moisture) and actuators (e.g. sprinklers and window openers) from different vendors in order to automate a greenhouse on my farm and maximise crop yields.

127 |
128 |
129 |
130 |

Deployment Models

131 |

The Web Thing Protocol will need to operate within three key deployment models depending on whether a Web Thing is hosted by a connected device, by an on-premises Web of Things gateway, or an off-premises Web of Things cloud service.

132 |

These three deployment models are common across a range of different application domains.

133 |

For a broader discussion of deployment models for the Web of Things in general, see Common Deployment Patterns in Web of Things (WoT) Architecture 1.1 [[wot-architecture11]].

134 |
135 |

Direct

136 |

The direct deployment model is when a Consumer communicates directly with an IoT device using the Web Thing Protocol.

137 |
138 | A diagram showing a WoT Consumer directly communicating with a collection of connected devices using the Web Thing Protocol. 139 |
Direct deployment model
140 |
141 |

In this deployment model, the IoT device itself must act as an HTTP server which serves its own Thing Description and can respond to HTTP requests or maintain a WebSocket connection with a Consumer.

142 |
143 |
144 |

Gateway

145 |

The gateway deployment model is when a Consumer communicates with a connected device via a gateway on the same premises as the device, which bridges another protocol to the Web Thing Protocol.

146 |
147 | A diagram showing a WoT Consumer communicating with a collection of Web Things via a Web of Things gateway using the Web Thing Protocol. 148 |
Gateway deployment model
149 |
150 |

In this deployment model, a gateway acts as an HTTP server which exposes a Web Thing for a connected device and translates HTTP and/or WebSocket messages into messages of the device's native protocol (e.g. Zigbee, Z-Wave, HomeKit, Modbus or BACnet) over a local area network (LAN) or personal area network (PAN).

151 |

A gateway can also act as a Consumer which consumes Web Things using the direct deployment model, and can be used to proxy a Web Thing from one network to another.

152 |
153 | A diagram showing a WoT Consumer communicating with a Web of Things gateway using the Web Thing protocol and the gateway also communicating with a collection of connected devices using the Web Thing Protocol. 154 |
Gateway deployment model with gateway also acting as a Consumer
155 |
156 |
157 |
158 |

Cloud

159 |

The cloud deployment model is when a Consumer communicates with an IoT device via cloud service on the internet, which communicates with the device using some other protocol on the back end.

160 |
161 |
162 | A diagram showing a WoT Consumer communicating with a collection of connected devices via cloud service using the Web Thing Protocol. 163 |
Cloud deployment model
164 |
165 |

In this deployment model, a cloud service hosted in a data centre acts as an HTTP server which exposes a Web Thing for an IoT device and translates HTTP and/or WebSocket messages into messages using another IoT protocol (e.g. AMQP or MQTT).

166 |

The cloud deployment model differs from the gateway deployment model in that the Web Thing is hosted on different premises to the IoT device it represents and communicates with the device over the internet.

167 |

A cloud service can also act as a Consumer which consumes Web Things that use the direct or gateway deployment model, and can be used to proxy a Web Thing from one origin to another.

168 |
169 | A diagram showing a WoT Consumer communicating with a Web of Things cloud service using the Web Thing protocol and the cloud service also communicating with a collection of connected devices and a Web of Things Gateway using the Web Thing Protocol. 170 |
Cloud deployment model with cloud service also acting as a Consumer
171 |
172 | 173 |
174 |
175 |

Requirements

176 |
177 |

HTTP Sub-Protocol

178 |

The HTTP Sub-protocol may be defined by the W3C WoT Profile specification [[wot-profile]].

179 |

The HTTP sub-protocol SHOULD define the [[HTTP11]] requests and responses a WoT Consumer and Web Thing would use in order to carry out the set of operations described below, including methods, headers, payloads and expected response codes. Resources SHOULD be retrieved using the HTTP protocol [[HTTP11]] and serialised in JSON [[JSON]].

180 |
181 |

Sub-Protocol Mechanism

182 |
    183 |
  1. MUST define a mechanism by which the Thing Description of a Web Thing can denote that the Web Thing uses the Web Thing Protocol’s HTTP sub-protocol
    2. 184 |
185 |
186 |
187 |

Properties

188 |
    189 |
  1. MUST define a way for a WoT Consumer to read the current value of a property of a Web Thing
    2. 190 |
  2. MUST define a way for a WoT Consumer to write the value of a property of a Web Thing
    3. 191 |
  3. MUST define a way for a WoT Consumer to read the values of all properties of a Web Thing at once
    4. 192 |
  4. MUST define a way for a WoT Consumer to write the values of multiple properties of a Web Thing at once
    5. 193 |
  5. SHOULD define a way for a WoT Consumer to read the values of multiple properties of a Web Thing at once
    6. 194 |
  6. SHOULD define a way for a WoT Consumer to write the values of all properties of a Web Thing at once
    7. 195 |
  7. MUST define a way for a WoT Consumer to observe a property of a Web Thing so that it gets notified when the value of the property changes
    8. 196 |
  8. MUST define a way for a WoT Consumer to stop observing a property of a Web Thing so that it no longer gets notified when the value of the property changes
    9. 197 |
  9. MUST define a way to observe all properties of a Web Thing at once
    10. 198 |
  10. MUST define a way to stop observing all properties of a Web Thing at once
    11. 199 |
  11. SHOULD define a way for a WoT Consumer to resume a dropped connection and catch up on missed property changes
    12. 200 |
201 |
202 |
203 |

Actions

204 |
    205 |
  1. MUST define a way for a WoT Consumer to invoke an action on a Web Thing
    2. 206 |
  2. MUST define a way for a WoT Consumer to query the status of an ongoing action on a Web Thing
    3. 207 |
  3. MUST define a way for a WoT Consumer to cancel an ongoing action on a Web Thing
    4. 208 |
  4. MUST define a way for a WoT Consumer to query the status of all ongoing actions on a Web Thing
    5. 209 |
210 |
211 |
212 |

Events

213 |
    214 |
  1. MUST define a way for a WoT Consumer to subscribe to an event on a Web Thing so that it gets notified whenever an event is emitted
    2. 215 |
  2. MUST define a way for a WoT Consumer to unsubscribe from an event on a Web Thing so that it stops getting notified whenever an event is emitted
    3. 216 |
  3. MUST define a way for a WoT Consumer to subscribe to all events on a Web Thing at once
    4. 217 |
  4. MUST define a way for a WoT Consumer to unsubscribe from all events on a Web Thing at once
    5. 218 |
  5. SHOULD define a way for a WoT Consumer to resume a dropped connection and catch up on missed events
    6. 219 |
220 |
221 |
222 |

Errors

223 |
    224 |
  1. MUST define a standardised format for a sending error messages to a WoT Consumer when an operation is not successful
    2. 225 |
  2. SHOULD define common error responses for all operations on a Web Thing
    3. 226 |
227 |
228 |
229 |
230 |

WebSocket Sub-Protocol

231 |

The WebSocket sub-protocol SHOULD define the WebSocket [[websockets-protocol]] messages that a WoT Consumer and Web Thing would use to carry out the following set of operations, including the messages types, payloads, error conditions and how they should be used. Messages SHOULD be serialised in JSON [[JSON]].

232 |
233 |

Sub-Protocol Mechanism

234 |
    235 |
  1. MUST define a mechanism by which the Thing Description of a Web Thing can denote that the Web Thing uses the Web Thing Protocol's WebSocket sub-protocol
    2. 236 |
  2. SHOULD describe the protocol handshake process for a WoT Consumer to request that a Web Thing use the Web Thing Protocol's WebSocket sub-protocol
    3. 237 |
  3. SHOULD define a way for a single WebSocket endpoint to be shared by all interaction affordances of a Web Thing (e.g. so that a Consumer can subscribe to multiple events from the same Thing without needing to open a separate socket for each)
    4. 238 |
  4. SHOULD define a way for a single WebSocket endpoint to be shared by multiple Web Things (e.g. so that a Consumer can authenticate and communicate with multiple Things from the same origin, without needing to open a separate socket for each)
    5. 239 |
  5. MAY define a way for a Web Thing to act as a WebSocket client rather than a WebSocket server in certain deployment models
    6. 240 |
241 |
242 |
243 |

Properties

244 |
    245 |
  1. MUST define a way for a WoT Consumer to request a reading of the current value of a property of a Web Thing
    2. 246 |
  2. MUST define a way for a WoT Consumer to write the value of a property of a Web Thing
    3. 247 |
  3. MUST define a way for a WoT Consumer to request a reading of the values of all properties of a Web Thing at once
    4. 248 |
  4. MUST define a way for a WoT Consumer to write the values of multiple properties of a Web Thing at once
    5. 249 |
  5. SHOULD define a way for a WoT Consumer to request a reading of the values of multiple properties of a Web Thing at once
    6. 250 |
  6. SHOULD define a way for a WoT Consumer to write the values of all properties of a Web Thing at once
    7. 251 |
  7. MUST define a way for a WoT Consumer to observe a property of a Web Thing so that it gets notified when the value of the property changes
    8. 252 |
  8. MUST define a way for a WoT Consumer to stop observing a property of a Web Thing so that it no longer gets notified when the value of the property changes
    9. 253 |
  9. MUST define a way to observe all properties of a Web Thing at once
    10. 254 |
  10. MUST define a way to stop observing all properties of a Web Thing at once
    11. 255 |
  11. MUST define a way for a Web Thing to send a reading of a property value to a WoT Consumer
    12. 256 |
  12. MUST define a way for a Web Thing to send readings of the values of multiple properties at once to a WoT Consumer
    13. 257 |
  13. SHOULD define a way for a WoT Consumer to resume a dropped connection and catch up on missed property changes
    14. 258 |
259 |
260 |
261 |

Actions

262 |
    263 |
  1. MUST define a way for a WoT Consumer to invoke an action on a Web Thing
    2. 264 |
  2. MUST define a way for a WoT Consumer to query the status of an ongoing action on a Web Thing
    3. 265 |
  3. MUST define a way for a WoT Consumer to cancel an ongoing action on a Web Thing
    4. 266 |
  4. MUST define a way for a WoT Consumer to query the status of all ongoing actions on a Web Thing 267 |
    5. 268 |
  5. MUST define a way for a Web Thing to send the status of an ongoing action to a WoT Consumer
    6. 269 |
  6. MUST define a way for a Web Thing to send the status of all ongoing actions to a WoT Consumer at once
    7. 270 |
271 |
272 |
273 |

Events

274 |
    275 |
  1. MUST define a way for a WoT Consumer to subscribe to an event on a Web Thing so that it gets notified whenever an event is emitted
    2. 276 |
  2. MUST define a way for a WoT Consumer to unsubscribe from an event on a Web Thing so that it stops getting notified whenever an event is emitted
    3. 277 |
  3. MUST define a way for a WoT Consumer to subscribe to all events on a Web Thing at once
    4. 278 |
  4. MUST define a way for a WoT Consumer to unsubscribe from all events on a Web Thing at once
    5. 279 |
  5. MUST define a way for a Web Thing to send an event to a WoT Consumer
    6. 280 |
  6. SHOULD define a way for a WoT Consumer to resume a dropped connection and catch up on missed events
    7. 281 |
282 |
283 |
284 |

Errors

285 |
    286 |
  1. MUST define a standardised format for sending error messages to a WoT Consumer when an operation is not successful
    2. 287 |
  2. SHOULD define common error responses for all operations on a Web Thing
    3. 288 |
289 |
290 |
291 |

Other Messages

292 |
    293 |
  1. SHOULD define a way for a WoT Consumer to send a “ping” message to a Web Thing in order to keep a WebSocket connection open
    2. 294 |
  2. SHOULD define a way for a Web Thing to send a “pong” response message to a WoT Consumer to confirm that a “ping” message was received
    3. 295 |
296 |
297 |
298 |
299 |

Discovery

300 |
    301 |
  1. SHOULD define a list of discovery mechanisms [[wot-discovery]] which Web Things may use and WoT Consumers must support
    2. 302 |
303 |
304 | 310 |
311 |

Security

312 |
    313 |
  1. SHOULD define a list of security schemes [[wot-thing-description]] which conformant Web Things may use and all conformant WoT Consumers must support
    2. 314 |
  2. MAY require that conformant Web Things and WoT Consumers support security bootstrapping [[wot-discovery]]
    3. 315 |
  3. MUST document any security considerations which are identified
    4. 316 |
317 |
318 |
319 |

Privacy

320 |
    321 |
  1. MUST document any privacy considerations which are identified
    2. 322 |
323 |
324 |
325 |

Accessibility

326 |
    327 |
  1. MUST document any accessibility considerations which are identified
    2. 328 |
329 |
330 |
331 |
332 |

Out of Scope

333 |

The following requirements are considered out of scope for the Web Thing Protocol specification:

334 |
    335 |
  1. Defining or constraining an information model for describing the capabilities of connected devices (covered by WoT Thing Description [[wot-thing-description]])
    2. 336 |
  2. Describing protocol bindings for existing (“brownfield”) IoT devices (covered by WoT Protocol Binding Templates [[wot-binding-templates]])
    3. 337 |
  3. Defining an API for managing a collection of Web Things (covered by WoT Discovery [[wot-discovery]])
    4. 338 |
339 |
340 | 341 | 342 | -------------------------------------------------------------------------------- /w3c.json: -------------------------------------------------------------------------------- 1 | { 2 | "group": [ 3 | "117875" 4 | ], 5 | "contacts": [ 6 | "benfrancis", "ashimura" 7 | ], 8 | "shortName": "web-thing-protocol", 9 | "repo-type": "cg-report" 10 | } 11 | --------------------------------------------------------------------------------