Internet Engineering Task Force P. Gansterer
Internet-Draft August 28, 2015
Intended status: Informational
Expires: February 29, 2016
Web Process Control Protocol (WPCP)
draft-gansterer-wpcp-00
Abstract
The WebSocket protocol enables two-way real-time communication
between clients and servers in web-based applications. This document
specifies a WebSocket subprotocol as a transport mechanism for
exchanging data in the area of process control. This includes
process data, historical data, alarms and events.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on February 29, 2016.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Gansterer Expires February 29, 2016 [Page 1]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Transport . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Call . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1.1. Read Data . . . . . . . . . . . . . . . . . . . . . . 4
3.1.2. Write Data . . . . . . . . . . . . . . . . . . . . . 5
3.1.3. Read History Data . . . . . . . . . . . . . . . . . . 5
3.1.4. Read History Alarm . . . . . . . . . . . . . . . . . 6
3.1.5. Browse . . . . . . . . . . . . . . . . . . . . . . . 7
3.1.6. Handle Alarm . . . . . . . . . . . . . . . . . . . . 7
3.2. SubscribeEvent . . . . . . . . . . . . . . . . . . . . . 8
3.2.1. Subscribe Audit . . . . . . . . . . . . . . . . . . . 8
3.3. SubscribeSingleValue . . . . . . . . . . . . . . . . . . 8
3.3.1. Subscribe Data . . . . . . . . . . . . . . . . . . . 8
3.4. SubscribeMultipleValues . . . . . . . . . . . . . . . . . 9
3.4.1. Subscribe Alarm . . . . . . . . . . . . . . . . . . . 9
4. Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5. Aggregations . . . . . . . . . . . . . . . . . . . . . . . . 10
6. ID Format . . . . . . . . . . . . . . . . . . . . . . . . . . 11
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
7.1. Message Value Keys Registry . . . . . . . . . . . . . . . 11
7.2. Registration of the WebSocket WPCP Subprotocol . . . . . 11
7.3. Registration of the WebSocket RWPCP Subprotocol . . . . . 11
8. Security Considerations . . . . . . . . . . . . . . . . . . . 12
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
9.1. Normative References . . . . . . . . . . . . . . . . . . 12
9.2. Informative References . . . . . . . . . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction
Many embedded devices and programmable logic controller (PLC) provide
data via Web service to display them in the browser. This Web
services usually must be polled to get the latest values, which
introduces a big overhead in communication. OPC UA [OPCUA] solves
this problem, but requires also too much resources as shown in JasUA
[JASUA]. In comparison to that webMI [WEBMI] meets the browser
needs, but uses plain HTTP communication.
This protocol fills the gap between them by defining a protocol over
WebSockets, which can be used directly in the browser and does not
provide a big overheader, to be easily integrated into small devices
used in the Internet of Things.
Gansterer Expires February 29, 2016 [Page 2]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
It is base on JSON-CAPS [JSON-CAPS] and defines domain specific
messages for process control.
1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
2. Transport
WPCP uses JSON-CAPS as the foundation and only defines additional
messages. WPCP uses the only the compact encoding and CBOR via
Websocket as defined in JSON-CAPS. It uses "wpcp" as the WebSocket
subprotocl.
To support servers behind firewall using Network Address Translators
(NAT) [RFC3022] the additional suprotocol "rwpcp" can be used. In
that case a proxy is required, which accept connection from the
client and the server.
In the default mode every client connects directly to the server.
+----------+ +-----+ +--------+
| Client 1 |---| NAT |--->| |
+----------+ +-----+ | |
| Server |
+----------+ +-----+ | |
| Client 2 |---| NAT |--->| |
+----------+ +-----+ +--------+
Figure 1
Gansterer Expires February 29, 2016 [Page 3]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
If the server can not be reached directly by the clients an Proxy can
be used where the server connect to. The Proxy is then able to
redirect messages from the client to the server. The Proxy can be
used to reduce the load too. The server uses the rwpcp WebSocket
subprotocl, while all clients use the wpcp WebSocket subprotocol.
+----------+ +-----+ +-------+
| Client 1 |---| NAT |--->| |
+----------+ +-----+ | | +-----+ +--------+
| Proxy |<---| NAT |---| Server |
+----------+ +-----+ | | +-----+ +--------+
| Client 2 |---| NAT |--->| |
+----------+ +-----+ +-------+
\___________ ____________/ \___________ __________/
\/ \/
uses wpcp uses rwpcp
Figure 2
3. Messages
3.1. Call
3.1.1. Read Data
This service is used to retrieve the current data of an item from the
server.
Message Type: readdata
Payload Item: object with following keys:
id (REQUIRED): The unique id of the data item.
Result Item Value: object with following keys:
status (OPTIONAL): Information about the quality of the of the
value. (0=Good)
timestamp (OPTIONAL): Timestamp of the last change in
milliseconds since 1970-01-01.
value (REQUIRED): The value of the data item.
Gansterer Expires February 29, 2016 [Page 4]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
3.1.2. Write Data
This service is used to set the data of an item at the server.
Message Type: writedata
Payload Item: object with following keys:
id (REQUIRED): The unique id of the data item.
value (REQUIRED): New value for the data item.
Result Item Value: The boolean value true if successful, false
otherwise.
3.1.3. Read History Data
This service is used to retrieve the previous values of a data item
from the server.
Message Type: readhistorydata
Payload Item: object with following keys:
id (REQUIRED): The unique id of the data item.
starttime (OPTIONAL): Beginning of period to read.
endtime (OPTIONAL): End of period to read.
maxresults (OPTIONAL): The maximum numer of results which should
be returned.
aggregation (OPTIONAL): An identifier used to dertime how the
values schould be aggregated. The valid values are listed in
Table 2.
interval (OPTIONAL): Interval between aggregated values.
Result Item Value: list of objects with following keys:
value (REQUIRED): The value of the data item.
timestamp (REQUIRED): Timestamp when changed happend or the
timestamp for the requested interval in milliseconds since
1970-01-01.
Gansterer Expires February 29, 2016 [Page 5]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
status (OPTIONAL): Information about the quality of the of the
value. (0=Good)
3.1.4. Read History Alarm
This service is used to retrieve the previous states of alarms from
the server.
Message Type: readhistoryalarm
Payload Item: object with following keys:
id (REQUIRED): The unique id of the event notifier.
starttime (OPTIONAL): Beginning of period to read.
endtime (OPTIONAL): End of period to read.
maxresults (OPTIONAL): The maximum numer of results which should
be returned.
filter (OPTIONAL): A filter used to determin which event schould
be returned.
Result Item Value: list of objects with following keys:
key (OPTIONAL): As described in JSON-CAPS.
retain (OPTIONAL): As described in JSON-CAPS.
token (OPTIONAL): An unique and opaque identifier for use with
handlealarm calls.
id (OPTIONAL): A dataitem responsible for the alarm.
timestamp (REQUIRED): Timestamp of the last change in
milliseconds since 1970-01-01.
priority (OPTIONAL): Priotiy of the alarm.
message (OPTIONAL): A textual description of the alarm for
display in UI.
acknowledged (OPTIONAL): Boolean value indicating if the alarm
has been acknowledged already.
Gansterer Expires February 29, 2016 [Page 6]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
active (OPTIONAL): Boolean value indicating if the current state
of the alarm indicates that the situation the alarm is
representing exists.
3.1.5. Browse
This server is used to get a list of child items of the provided item
in the address room of the server.
Message Type: browse
Payload Item: object with following keys:
id (REQUIRED): The unique id of the item to get the children for.
Result Item Value: list of objects with following keys:
id (OPTIONAL): The unique id of the child item.
name (REQUIRED): Name of the child item.
title (OPTIONAL): Title of the child item.
description (OPTIONAL): Description of the child item.
type (OPTIONAL): Type of the child item.
3.1.6. Handle Alarm
This service is used to accept an alarm at the server.
Message Type: handlealarm
Payload Item: object with following keys:
token (REQUIRED): The unique token of an alarm item.
acknowledged (OPTIONAL): If set to true the alarm should be
acknowledged.
Further specifications can define additonal propeties, which
define how the server schould deal with an alarm. The server MUST
return false if an unknow property has been received.
Result Item Value: The boolean value true if successful, false
otherwise.
Gansterer Expires February 29, 2016 [Page 7]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
3.2. SubscribeEvent
3.2.1. Subscribe Audit
This service is used to subscribe to server audit events.
Message Type: subscribeaudit
Payload Item: object with following keys:
id (REQUIRED): The unique id of the event notifier. An empty
value indicates the root of the server and includes all audit
events.
Subscription Item: object with following keys:
timestamp (REQUIRED): Timestamp when the event happend in
milliseconds since 1970-01-01.
message (OPTIONAL): A textual description of the event for
display in UI.
3.3. SubscribeSingleValue
3.3.1. Subscribe Data
This service is used to subscribe a data item at the server.
Message Type: subscribedata
Payload Item: object with following keys:
id (REQUIRED): The unique id of the data item.
Subscription Item: object with same keys as the readdata result
item:
status (OPTIONAL): Information about the quality of the of the
value. (0=Good)
timestamp (OPTIONAL): Timestamp of the last change in
milliseconds since 1970-01-01.
value (REQUIRED): The value of the data item.
Gansterer Expires February 29, 2016 [Page 8]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
3.4. SubscribeMultipleValues
3.4.1. Subscribe Alarm
This service is used to subscribe alarms via an filter at the server.
Message Type: subscribealarm
Payload Item: object with following keys:
id (REQUIRED): The unique id of the event notifier. An empty
value indicates the root of the server and includes all alarms.
filter (OPTIONAL): An object describing an filter which the items
needs to match to be sent via an publish message.
Subscription Item: object with following keys:
key (REQUIRED): As described in JSON-CAPS.
retain (OPTIONAL): As described in JSON-CAPS.
token (OPTIONAL): An unique and opaque identifier for use with
handlealarm calls.
id (OPTIONAL): A dataitem responsible for the alarm.
timestamp (OPTIONAL): Timestamp of the last change in
milliseconds since 1970-01-01.
priority (OPTIONAL): Priotiy of the alarm.
message (OPTIONAL): A textual description of the alarm for
display in UI.
acknowledged (OPTIONAL): Boolean value indicating if the alarm
has been acknowledged already.
active (OPTIONAL): Boolean value indicating if the current state
of the alarm indicates that the situation the alarm is
representing exists.
4. Objects
The two peers do most of the communication via objects. The
attributes of those objects are defined in this section.
Gansterer Expires February 29, 2016 [Page 9]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
+--------------+----------------------------------------------------+
| Name | Description |
+--------------+----------------------------------------------------+
| acknowledged | Boolean value indicating if the alarm has been |
| | acknowledged already. |
| active | Boolean value indicating if the current state of |
| | the alarm indicates that the situation the alarm |
| | is representing exists. |
| filter | Priotiy of the alarm. |
| id | Unique identifer of a datapoint. It is recommended |
| | to use strings. |
| key | As described in JSON-CAPS. |
| message | A textual description of the alarm for display in |
| | UI. |
| priority | Priotiy of the alarm. |
| retain | As described in JSON-CAPS. |
| timestamp | Timestamp of the last change in milliseconds since |
| | 1970-01-01 |
| token | An unique and opaque identifier for use with |
| | handlealarm calls. |
| status | Information about the quality of the of the value. |
| | (0=Good) |
| value | Value of the datapoint. If possible objects should |
| | be avoided as type of the value. |
+--------------+----------------------------------------------------+
Table 1: Value Keys
5. Aggregations
Historical reads support an optional aggregation option. The
following table lists the valid values:
+------------+------------------------------------------------------+
| Name | Description |
+------------+------------------------------------------------------+
| average | It adds up all values in divides them by the count. |
| minimum | It returns the minimum value. |
| maximum | It returns the maximum value. |
| start | It returns the earlies value in the interval. |
| end | It returns the latest value in the interval. |
| startbound | It returns the value at the beginning of the |
| | interval. |
| endbound | It returns the value at the end of the interval. |
+------------+------------------------------------------------------+
Table 2: Aggregations
Gansterer Expires February 29, 2016 [Page 10]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
6. ID Format
Some request need an id parameter which is used to refer to a
specific item in the address space of the server. This can be done
in two different forms:
Absolute: The value must be of the type string containing an
absoulte address. An empty string refers to the root node in the
address space. E.g. {"id": "GlobalTemparature7"}
Relative: The value must be an array. The first item must be an
absoulte address specifing the start node for the relative path.
All following items in the array are used to refer to subnodes.
E.g. {"id": ["Motor5", "Temparatures", "Case"]}
7. IANA Considerations
IANA should create two registries for new WPCP values. The
registries are separate, that is, not under an umbrella registry, and
follow the rules in [RFC5226]. IANA has also assigned a new
WebSocket Subprotocol entry.
7.1. Message Value Keys Registry
IANA should create the "Web Process Control Protocol (WPCP) Value
Keys" registry. The initial values are shown in Table 1.
New entries are assigned by Specification Required.
7.2. Registration of the WebSocket WPCP Subprotocol
IANA has registered the WebSocket WPCP subprotocol under the
"WebSocket Subprotocol Name" registry with the following data:
Subprotocol Identifier: wpcp
Subprotocol Common Name: Web Process Control Protocol (WPCP)
Subprotocol Definition: draft-gansterer-wpcp
7.3. Registration of the WebSocket RWPCP Subprotocol
IANA has registered the WebSocket RWPCP subprotocol under the
"WebSocket Subprotocol Name" registry with the following data:
Subprotocol Identifier: rwpcp
Gansterer Expires February 29, 2016 [Page 11]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
Subprotocol Common Name: Reverse Web Process Control Protocol
(RWPCP)
Subprotocol Definition: draft-gansterer-wpcp
8. Security Considerations
It is RECOMMENDED that the traffic transported over a WebSocket
communication be protected by using a secure WebSocket connection
(using TLS [RFC5246] over TCP).
9. References
9.1. Normative References
[JSON-CAPS]
Gansterer, P., "JavaScript Object Notation (JSON) Call And
Publish/Subscribe (CAPS)", August 2015,
<http://wpcp.net/spec/latest-json-caps-draft.html>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/
RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>.
9.2. Informative References
[JASUA] Hennig, S., Braune, A., and M. Damm, "JasUA: A JavaScript
Stack enabling web browsers to support OPC Unified
Architecture's Binary mapping natively", September 2010.
[OPCUA] ISO/IEC, "IEC 62541: OPC Unified Architecture", 2008,
<http://www.opcfoundation.org/UA/>.
[RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network
Address Translator (Traditional NAT)", RFC 3022, DOI
10.17487/RFC3022, January 2001,
<http://www.rfc-editor.org/info/rfc3022>.
Gansterer Expires February 29, 2016 [Page 12]
Internet-Draft Web Process Control Protocol (WPCP) August 2015
[WEBMI] Gansterer, P., "webMI Implementation Guideline", August
2008.
Author's Address
Patrick Gansterer
Vienna
Austria
Phone: +43 676 686 01 04
Email: paroga@paroga.com
Gansterer Expires February 29, 2016 [Page 13]
Html markup produced by rfcmarkup 1.96, available from
http://tools.ietf.org/tools/rfcmarkup/