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.

Introduction

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.

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.

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.

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.

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

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.

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.

Use Cases

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

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]].

Smart Home

Smart Home Devices

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.

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.

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.

Smart Home Hubs

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.

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.

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.

Smart Home Cloud Services

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.

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.

Smart Home Software Applications

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.

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.

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.

Smart Buildings

Smart Building Devices

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.

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.

Smart Building Hubs

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.

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.

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.

Smart Building Cloud Services

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.

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.

Smart Building Software Applications

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.

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.

Smart Cities

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.

Manufacturing

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.

Energy

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.

Transportation

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.

Agriculture

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.

Deployment Models

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.

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

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]].

Direct

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

A diagram showing a WoT Consumer directly communicating with a collection of connected devices using the Web Thing Protocol.
Direct deployment model

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.

Gateway

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.

A diagram showing a WoT Consumer communicating with a collection of Web Things via a Web of Things gateway using the Web Thing Protocol.
Gateway deployment model

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).

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.

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.
Gateway deployment model with gateway also acting as a Consumer

Cloud

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.

A diagram showing a WoT Consumer communicating with a collection of connected devices via cloud service using the Web Thing Protocol.
Cloud deployment model

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).

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.

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.

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.
Cloud deployment model with cloud service also acting as a Consumer

Requirements

HTTP Sub-Protocol

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

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]].

Sub-Protocol Mechanism

  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

Properties

  1. MUST define a way for a WoT Consumer to read the current value of a property of a Web Thing
  2. MUST define a way for a WoT Consumer to write the value of a property of a Web Thing
  3. MUST define a way for a WoT Consumer to read the values of all properties of a Web Thing at once
  4. MUST define a way for a WoT Consumer to write the values of multiple properties of a Web Thing at once
  5. SHOULD define a way for a WoT Consumer to read the values of multiple properties of a Web Thing at once
  6. SHOULD define a way for a WoT Consumer to write the values of all properties of a Web Thing at once
  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. 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. MUST define a way to observe all properties of a Web Thing at once
  10. MUST define a way to stop observing all properties of a Web Thing at once
  11. SHOULD define a way for a WoT Consumer to resume a dropped connection and catch up on missed property changes

Actions

  1. MUST define a way for a WoT Consumer to invoke an action on a Web Thing
  2. MUST define a way for a WoT Consumer to query the status of an ongoing action on a Web Thing
  3. MUST define a way for a WoT Consumer to cancel an ongoing action on a Web Thing
  4. MUST define a way for a WoT Consumer to query the status of all ongoing actions on a Web Thing

Events

  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. 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. MUST define a way for a WoT Consumer to subscribe to all events on a Web Thing at once
  4. MUST define a way for a WoT Consumer to unsubscribe from all events on a Web Thing at once
  5. SHOULD define a way for a WoT Consumer to resume a dropped connection and catch up on missed events

Errors

  1. MUST define a standardised format for a sending error messages to a WoT Consumer when an operation is not successful
  2. SHOULD define common error responses for all operations on a Web Thing

WebSocket Sub-Protocol

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]].

Sub-Protocol Mechanism

  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. 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. 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. 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. MAY define a way for a Web Thing to act as a WebSocket client rather than a WebSocket server in certain deployment models

Properties

  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. MUST define a way for a WoT Consumer to write the value of a property of a Web Thing
  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. MUST define a way for a WoT Consumer to write the values of multiple properties of a Web Thing at once
  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. SHOULD define a way for a WoT Consumer to write the values of all properties of a Web Thing at once
  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. 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. MUST define a way to observe all properties of a Web Thing at once
  10. MUST define a way to stop observing all properties of a Web Thing at once
  11. MUST define a way for a Web Thing to send a reading of a property value to a WoT Consumer
  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. SHOULD define a way for a WoT Consumer to resume a dropped connection and catch up on missed property changes

Actions

  1. MUST define a way for a WoT Consumer to invoke an action on a Web Thing
  2. MUST define a way for a WoT Consumer to query the status of an ongoing action on a Web Thing
  3. MUST define a way for a WoT Consumer to cancel an ongoing action on a Web Thing
  4. MUST define a way for a WoT Consumer to query the status of all ongoing actions on a Web Thing
  5. MUST define a way for a Web Thing to send the status of an ongoing action to a WoT Consumer
  6. MUST define a way for a Web Thing to send the status of all ongoing actions to a WoT Consumer at once

Events

  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. 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. MUST define a way for a WoT Consumer to subscribe to all events on a Web Thing at once
  4. MUST define a way for a WoT Consumer to unsubscribe from all events on a Web Thing at once
  5. MUST define a way for a Web Thing to send an event to a WoT Consumer
  6. SHOULD define a way for a WoT Consumer to resume a dropped connection and catch up on missed events

Errors

  1. MUST define a standardised format for sending error messages to a WoT Consumer when an operation is not successful
  2. SHOULD define common error responses for all operations on a Web Thing

Other Messages

  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. 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

Discovery

  1. SHOULD define a list of discovery mechanisms [[wot-discovery]] which Web Things may use and WoT Consumers must support

Security

  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. MAY require that conformant Web Things and WoT Consumers support security bootstrapping [[wot-discovery]]
  3. MUST document any security considerations which are identified

Privacy

  1. MUST document any privacy considerations which are identified

Accessibility

  1. MUST document any accessibility considerations which are identified

Out of Scope

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

  1. Defining or constraining an information model for describing the capabilities of connected devices (covered by WoT Thing Description [[wot-thing-description]])
  2. Describing protocol bindings for existing (“brownfield”) IoT devices (covered by WoT Protocol Binding Templates [[wot-binding-templates]])
  3. Defining an API for managing a collection of Web Things (covered by WoT Discovery [[wot-discovery]])