Channels

A channel is a way to receive continuous updates about a stream or stream set relevant to updates of PI AF attribute data reference and PI point values.

Channels use the WebSocket protocol (defined in the Request for Comments document RFC 6455 The WebSocket Protocol) to enable the PI Web API server to send messages containing new stream time-series data value changes. After a channel is opened, the client receives continuous updates from the server without having to poll. This increases efficiency by reducing unnecessary requests, as well as reducing the overhead that comes with HTTP headers.

Explanation of channels

Normally, when clients apply PI Web API, they send an http request to the server and the server sends back a response. Although this is satisfactory if clients need information only once or twice, it becomes rather inefficient if they require information constantly. In such situations, the preferred solution is to open a channel in which clients make web socket requests to the server, and the server accepts those web socket connections in return. Thereafter, the server can send messages to clients whenever a value is changed or added. Clients no longer have to constantly poll the server for information. The server simply messages clients whenever new information is available. When clients no longer want messages, they can close the connection. If a client crashes, the server reacts and closes the connection itself.

Normal vs. Channel communication

For more information on channels and how to implement them, refer to the PI Web API online help.

WebSocket protocol

Channels are accessed using the WebSocket protocol. Numerous WebSocket client libraries are available in several languages for use with channels.

Note: Because the WebSocket protocol is a relatively new technology, be advised that there are still authentication issues in some browsers, especially with Basic and Kerberos authentication. Clients may need to authenticate using https before they can open any channels. This can be done by issuing any PI Web API request.

Stream value changes

During operation, the channel periodically polls the PI System's data update queue at intervals specified by the ChannelPollingInterval configuration value, which is measured in milliseconds and defaults to 1000. If any data updates are detected while polling, PI Web API sends them to the client in a message.

If the optional URL parameter includeInitialValues is set to true (default is false), the server sends an initial message with current values for all streams. Thereafter, the server sends messages containing all stream value changes since the last message. The payload of these messages is the same as the GetEnd method for streams and stream sets. Any streams whose values have not changed since the last message will not be included in the message. Value changes are sent in the order they were received by the PI System. There is no guarantee that value changes are sent in chronological order.

By default, no empty messages are sent to the client. However, if the URL parameter heartbeatRate is set to an integer multiple of the polling interval, the channel periodically sends an empty message to confirm that the connection is still alive. In the following example, after five polling intervals without a data update, an empty message is sent:

wss://myserver/piwebapi/streams/{webID}/channel?heartbeatRate=5