Table of contents
1About this document
2Introduction
3Message channel
3.1Message types
3.2Message sequence
3.3Exception Handling
3.4Message Codec
3.5Message Payload
3.6Message – HELLO
3.7Message – ACCEPT
3.8Message – START
3.9Message – CLOSE
3.10Message – PING
3.11Message – PONG
4Handshake phases
4.1Handshake properties
4.1.1Protocol handshake
5Serialization with OSBP
5.1Value types
5.1.1String
5.1.2Boolean
5.1.3Variant
5.2Message structure
5.3Encoding of fields
5.3.1Null Values
5.3.2Integer
5.3.3Long
5.3.4Double
5.3.5Boolean
5.3.6String
5.3.7Enum
5.3.8Properties map
5.3.9Variant
5.3.10Variant Map
5.4Values
6Communication Concepts
6.1Interfaces
6.2Transient & deleted attributes
6.3Equality
6.4Request & response
6.5Callbacks
6.6Sessions
6.7Session privileges
6.8Error information
7Messages
7.1ae
7.1.1Enums
7.1.1.1MonitorStatus
7.1.1.2QueryState
7.1.1.3Severity
7.1.1.4BrowserType
7.1.2Interfaces
7.1.3Structures
7.1.3.1MonitorStatusInformation
7.1.3.1.1lastFailValue
7.1.3.2BrowserEntry
7.1.3.3EventInformation
7.1.4Messages
7.1.4.1SubscribeMonitorPool
7.1.4.2UnsubscribeMonitorPool
7.1.4.3MonitorPoolStatusUpdate
7.1.4.4MonitorPoolDataUpdate
7.1.4.5SubscribeEventPool
7.1.4.6UnsubscribeEventPool
7.1.4.7EventPoolStatusUpdate
7.1.4.8EventPoolDataUpdate
7.1.4.9CreateQuery
7.1.4.10LoadMore
7.1.4.11CloseQuery
7.1.4.12UpdateQueryState
7.1.4.13UpdateQueryData
7.1.4.14StartBrowse
7.1.4.15StopBrowse
7.1.4.16BrowseData
7.1.4.17AcknowledgeRequest
7.1.4.18AcknowledgeResponse
7.2ca
7.2.1Enums
7.2.1.1Operation
7.2.1.2FactoryState
7.2.1.3ConfigurationState
7.2.2Interfaces
7.2.3Structures
7.2.3.1FactoryInformation
7.2.3.2ConfigurationInformation
7.2.3.3DiffEntry
7.2.4Messages
7.2.4.1GetFactoriesRequest
7.2.4.2GetFactoriesResponse
7.2.4.3GetFactoryWithDataRequest
7.2.4.4GetFactoryWithDataResponse
7.2.4.5GetConfigurationRequest
7.2.4.6GetConfigurationResponse
7.2.4.7ApplyDiffRequest
7.2.4.8ApplyDiffResponse
7.2.4.9ErrorResponse
7.3core
7.3.1Enums
7.3.1.1SubscriptionState
7.3.2Interfaces
7.3.2.1RequestMessage
7.3.2.2ResponseMessage
7.3.3Structures
7.3.3.1ErrorInformation
7.3.3.2Request
7.3.3.3Response
7.3.3.4UserInformation
7.3.3.5OperationParameters
7.3.3.6CallbackRequest
7.3.3.7CallbackResponse
7.3.4Messages
7.3.4.1CreateSession
7.3.4.1.1properties
7.3.4.2SessionAccepted
7.3.4.2.1properties
7.3.4.3SessionRejected
7.3.4.4SessionPrivilegesChanged
7.3.4.4.1granted
7.3.4.5RequestCallbacks
7.3.4.6RespondCallbacks
7.3.4.6.1errorInformation
7.4da
7.4.1Enums
7.4.1.1FolderEntryType
7.4.1.2IODirection
7.4.2Interfaces
7.4.3Structures
7.4.3.1AttributeWriteResultEntry
7.4.3.2BrowserEntry
7.4.4Messages
7.4.4.1SubscribeItem
7.4.4.2UnsubscibeItem
7.4.4.3ItemDataUpdate
7.4.4.3.1addedOrUpdated
7.4.4.4ItemStateUpdate
7.4.4.4.1subscriptionState
7.4.4.5StartWriteValue
7.4.4.6WriteValueResult
7.4.4.7StartWriteAttributes
7.4.4.8WriteAttributesResult
7.4.4.9SubscribeFolder
7.4.4.10UnsubscribeFolder
7.4.4.11FolderDataUpdate
7.4.4.12BrowseFolder
7.4.4.13BrowseResult
7.5hd
7.5.1Enums
7.5.2Interfaces
7.5.3Structures
7.5.3.1QueryParameters
7.5.3.2HistoricalItemInformation
7.5.3.3ValueInformation
7.5.3.3.1quality
7.5.3.3.2manualPercentage
7.5.3.3.3sourceValues
7.5.3.4ValueEntry
7.5.3.4.1valueType
7.5.4Messages
7.5.4.1CreateQuery
7.5.4.2CreateQueryFailure
7.5.4.3CloseQuery
7.5.4.4ChangeQueryParameters
7.5.4.5UpdateQueryState
7.5.4.6UpdateQueryParameters
7.5.4.7UpdateQueryData
7.5.4.8StartBrowse
7.5.4.9StopBrowse
7.5.4.10ListUpdate
8Appendices
8.IGNU Free Documentation License
openSCADA Protocol Description
Authors

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

1About this document

This document describes the internal openSCADA protocols.

The reader of this document should be familiar with TCP/IP based network communication.

2Introduction

The NPG protocol (next generation protocol) is the successor of the GMPP/NET protocol of openSCADA. it was created in order to fix some performance issues and make it easier to extend the protocol.

NGP is a plain Client/Server TCP/IP protocol. The server side is also the TCP server. So an DA server (aka Hive, Driver Module) is the TCP server.

The basic idea of the protocol is that after a common ground for passing messages was established between the client and the server each side may send messages (structures) to the other side at will. The messages are transmitted complete and in order. The encoding of the messages it not relevant. Messages consist of a limited number of primive datatypes and can build structures without references. A message does not have a direct reply. A reply is just another message which might of course contain some id it refers to. But this is not part of the protocol but part of the message.

The protocol is split into two different layers. The first layer is the framing layer which act as a message channel. The second layer uses the message channel to pass messages betwen server and client. So after the TCP connection is established the message channel will perform a handshake and configure the connection parameters (like encryption and compression). After the handshake was performed data messages can be exchanged between the two communication parties. The content of these messages is irrelevant for the message channel and will be interpreted by the second layer.

The second layer gets configured during the message channel handshake and supports different types of codec filters/serializers. Which type is used is decided during the handshake phase. After the codec has been chosen it cannot be changed anymore.

The result of the second layer is a stream of interpreted messages which make up the real data of the openSCADA protocol that is transmitted.

3Message channel

The message channel is the first layer over the TCP protocol. It provides a handshake mechanism and a way to send data messages over the TCP, stream based, link. It allows to add features like encryption and compression and defines communication parameters for the data inside the messages. It does not decode the data messages itself.

3.1Message types

The message channel sends frames. Frames have a distinct type and encoding. The following frame types are defined:

Name Numeric Sender Description
HELLO 0 Client Sent by the client to initiate the communication. Must only be sent once, as first message
MESSAGE 1 Any A message containing data. Must only be sent after the handshake was completed successfully.
ACCEPT 2 Server Sent by the server after a HELLO message was received and confirming the successful handshake. Must only be sent once.
CLOSE 3 Any Sent by either side to provide a reason for the imminent close of the connection. This message may be sent only once and must be last message sent. It may also be sent directly after the HELLO message was received.
START 4 Client Sent by the client to tell the server that the communication parameters of the ACCEPT message have been applied and the handshake is complete. This message must be sent once after the ACCEPT message has been received and the communication parameters (compression, ssl, …) have been applied by the client.
PING 5 Any Sent by any party after the handshake has been completed to see is the other side is still connected. The receiver of the message must respond with a PONG message.
PONG 6 Any Sent exactly once by any party after a PING message was received.
3.2Message sequence

The connection is initiated by the client. The client opens the TCP connection and once this connection is established a HELLO message is sent. The server will then process the message and reply with an ACCEPT message if the connection can be opened. Otherwise a CLOSE message should be sent and the connection will be terminated by the server.

When the client receives the ACCEPT message it changes is communication parameters and responds with a START message, which tells the server that it can start with the data communication. Both sides may not sent PING/PONG messages. And most of all messages of the type MESSAGE for transmitting data.

3.3Exception Handling

In case anything goes wrong each side may close the TCP connection at any time.

3.4Message Codec

Each message consists of a common header and a payload section. The following table shows the structure of the common header.

Index Length Name Type Description
0 1 version byte Version identifier, contains 0x01 at the moment.
1 1 messageType byte The numeric value of the message type (HELLO, ACCEPT, …).
2 4 payloadSize int32 The number of bytes following. Although this is a signed integer, it must never be negative.
6 payloadSize payloadData byte[] Message payload, must be encoded/decoded depending on the mesage type.
3.5Message Payload

All messages except the MESSAGE message are handled by the message channel itself. Therefore the encoding of these messages are part of the message channel. The MESSAGE message contains only payload data which is handeled by the second layer and not the message channel itself. Therefore the handshake phase must come up witch a serialzation method that describes what is inside the MESSAGE messages. And this requires the handshake to complete before any MESSAGE messages can be sent.

3.6Message – HELLO

The payload data is a property (string to string) map. The number of entries, as 32 bit signed integer. Repeating for each entry:

3.7Message – ACCEPT

The payload data is a property (string to string) map. The number of entries, as 32 bit signed integer. Repeating for each entry:

3.8Message – START

This message has no message payload.

3.9Message – CLOSE
Index Length Name Type Description
0 reason string A null byte terminated string without lenght prefix.
0 + reason reasonCode int32 A reason code.
3.10Message – PING

This message has no message payload.

3.11Message – PONG

This message has no message payload.

4Handshake phases

There are four phases in the handshake.

Phase 1: Initially the client starts the communication by opening with a HELLO message. The message may contain a set of properties of capabilities and strictions of the client.

Phase 2: Next the server will validate these properties and evaluate the resulting properties which are the result of the handshake. A common ground for further communication.

Phase 3: This result will be sent to the client in an ACCEPT message and after that applied to its own communication channel. It is not possible to already send the first message with the new communication parameters since the client still does not know them.

Phase 4: The client receives the communication parameters in the ACCEPT message and applies the communication parameters as well. It sends out a START message, with the new communication parameters, and both sides are ready for data transmission.

If the server cannot accept the connections, maybe due to the fact that the handshake did not work out, it can close the connection by optionally sending a CLOSE message first and then closing the TCP connection. Also can the client close the TCP connection after receiving the ACCEPT message it the communication parameters are not as excepted.

4.1Handshake properties

In general any handshake parameters can be sent in the HELLO and ACCEPT messages. Each side must handle unkown properties by simply ignoring them. Each side has to evaluate if the other side is good enough for communication. So for example if the client requests SSL encryption but the server does not not about SSL, it would simply ignore the clients request and not report anything about SSL back. Now the client can decide if it wants to further communicate with this server or close the connection instead. Since no user information has been transmitted up to now this is ok.

The following list therefore only documents the handshake properties which are defined up to now and are in use. The recommendation column specifies if support of this property is highly recommended or an optional feature.

A list of handshake properties
Name Recommendation Sent by Description
timeout Recommended Client, Server The communication timeout in milliseconds. The client can request a value and the server may correct that value. The result is sent back to the client.
startSession.enable Required Client, Server This is a feature flag, indicating that the START message is used. In older versions this START message was unknown and communication could start directly after sending the ACCEPT message. This behaviour is still available when not sending the startSession.enable property. But this behaviour is deprecated and should not be used anymore.
protocol.* Required Client All properties starting with protocol. will be considered candiates for the protocol selection that is used for encoding the MESSAGE messages. So if the protocol osbp.v1 is available the property protocol.osbp.v1 needs to be set to the value true.
preferredClientProtocols Recommended Client A request from the client to use a specific protocol if multiple are possible. The server can override or ignore this setting. It is a list of protocols delimited by comma.
protocol Required Server The protocol selected by the server for MESSAGE messages.
requestSsl Optional Client The client requests SSL encryption.
useSsl Optional Server The server uses SSL encryption. This flag should not be set if the client did not request for SSL encryption since the client will most likely not support it then. If this is howerever a problem for the server, the server can close the connection instead.
4.1.1Protocol handshake

As already mentioned the content of the MESSAGE messages is undefined for the message channel itself. It just consideres them as BLOBs which are transmitted. During the handshake phase openSCADA will use the previously described protocol.* properties to select a protocol codec for these binary BLOBs.

The recommended protocol would be the OSBP (openSCADA binary protocol) as described in protocol.osbp. There there are other protocols and a second one is the Java serialization protocol. Yet this protocol would only work well in a Java based environment.

The following protocols are the ones currently implemented by openSCADA. There can be other implementations as well, but when both side cannot agree on a protocol the connection cannot be established. Therefore it is recommended that a new implemenation at least supports OSBP as a protocol codec.

Protocol ID Description
osbp.v2/ae.1/core.1 openSCADA NGP based AE
osbp.v2/ca.1/core.1 openSCADA NGP based CA
osbp.v2/da.1/core.1 openSCADA NGP based DA
osbp.v2/hd.1/core.1 openSCADA NGP based HD
java/ae.1/core.1 Java serialization based AE
java/ca.1/core.1 Java serialization based CA
java/da.1/core.1 Java serialization based DA
java/hd.1/core.1 Java serialization based HD

Since the binary protocol consists of the types of messages define and the serialization form the protocol ID itself is a combination of all. Including the parent protocol definitions. The protocol ID itself should be considered as a string which either matches or not. The actual composition is only to ease reading and generating a new, different ID if any part changes.

A protocol version gets increased when some part if the definition changes in a way it is not compatible with the previous version. For example do the current protocol implementations handle adding or removing an optional field without the need to increate the protocol version.

5Serialization with OSBP

The openSCADA Binary Protocol codec is the default codec used for the NGP protocol. It describes the format which is used to encode structure into a binary form so that these structures can be sent over the message channel.

The OSBP knows some primary value types and can construct complex structures based on these. While other serialization methods may provide enhanced data structures with different types the NGP protocol stack requires the implementor to only send messages which can be represented by the OSBP codec. Still other protocol stacks using the message channel can use different ways of encoding the payload messages.

All values are encoded in network byte order.

5.1Value types

The following table shows the primary value types:

Type Description
Integer signed 32bit integer
Long signed 64bit integer
Float 64bit floating point according to IEEE 754
Boolean boolean value
String unicode string
Enum An enum, enum values have assigned an ordinal numeric value starting with zero.
Variant The openSCADA Variant Type
Properties Map A map of String to String properties
Variant Map A map of String to Variant
Structure A sub structure
5.1.1String

Strings are encoded as UTF-8 byte arrays with a 4 byte size prefix and no null terminating character.

5.1.2Boolean

Booleans are encoded as byte. true is encoded as 0xFF and false as 0x00. When reading a boolean value everything else then 0x00 is considered as true.

5.1.3Variant

The openSCADA variant type is encoded as follows:

The first byte is the variant type ordinal. Followed by the actual value data.

Variant Type Ordinal Description
BOOLEAN 0 A single boolean value, as byte
INT32 1 An 32bit signed integer
INT64 2 An 64bit signed integer
DOUBLE 3 An 64bit floating point according to IEEE 754
STRING 4 A string, encoded as a length prefixed UTF-8 string
NULL 5 A null value, contains no additional data
5.2Message structure

Each message has a common header followed by the message structure. The message structure itself consist of fields. Each fields must be of one of the primary data types, but still can also be a structure. A structure is encoded right at the point where it is specified.

Common message header
Index Length Name Type Description
0 4 messageCode int32 Message code as 32bit signed integer
4 1 numberOfFields byte The number of fields following this field
5 structure Structure Actual message payload, with a maximum of fields specified in "numberOfFields".

Each field has a type modifier which can be:

Modifier Description
SCALAR Cardinality of 1
OPTIONAL Cardinality of 0…1
ORDERED Cardinality of 0…*, with a specific order, without uniqueness of items
UNIQUE Cardinality of 0…*, without a specific order, with unique items

In Java SCALAR fields are non-null and primitive type of possible. OPTIONAL fields will become non-primitve types. ORDERED fields become types based on List. And UNIQUE will be created as Set.

5.3Encoding of fields

Fields can be encoded in any order as long as the structure grouping is maintained. This is possible due to the numbering of the fields. Also fields which are unknown must be ignored by the decoder, a warning may be print out. This is used for future enhancements where fields are present but unknown by the receiver. Yet if a field is present but has the wrong type it is considered a protocol error and the connection must be closed.

Each field too has a common header:

Common header of fields
Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte The encoded type id of the field
5.3.1Null Values

If the field is optional and the value is not set the type id is TYPE_NULL independent of the type.

5.3.2Integer

If the field is specified as OPTIONAL or SCALAR:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_INT
2 4 value int32 The value

If the field is specified as ORDERED or UNIQUE:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_INT_LIST
2 4 numerOfEntries int32 The number of values following
6 value int32[] The values
5.3.3Long

If the field is specified as OPTIONAL or SCALAR:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_LONG
2 8 value int64 The value

If the field is specified as ORDERED or UNIQUE:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_LONG_LIST
2 4 numerOfEntries int32 The number of values following
6 value int64[] The values
5.3.4Double

If the field is specified as OPTIONAL or SCALAR:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_DOUBLE
2 8 value double The value encoded according to IEEE 754

If the field is specified as ORDERED or UNIQUE:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_DOUBLE_LIST
2 4 numerOfEntries int32 The number of values following
6 value double[] The values encoded according to IEEE 754
5.3.5Boolean

If the field is specified as OPTIONAL or SCALAR:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_BOOLEAN
2 1 value byte The value, 0x00 = false, 0xFF = true

If the field is specified as ORDERED or UNIQUE:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_BOOLEAN_LIST
2 4 numerOfEntries int32 The number of values following
6 value byte[] The values

Although multiple booleans (ORDERED) could be encoded as a bit array, they are in fact not. Each boolean value is encoded in a seperate byte. The fact is that there a not lists of booleans defined up to now, a set of boolean would be possible but only contain 2 bits maximum. Still it is possible to handle your bits directly as integer or log value instead.

5.3.6String

If the field is specified as OPTIONAL or SCALAR:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_STRING
2 4 stringDataSize int32 The number of string bytes following
6 stringDataSize value byte The string encoded as a UTF-8 string without null byte terminate

If the field is specified as ORDERED or UNIQUE:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_STRING_LIST
2 4 numerOfEntries int32 The number of values following

After the numberOfEntries field the actual strings are encoded. So the following structure is repeated:

Index Length Name Type Description
0 4 stringDataSize int32 The number of string bytes following
4 stringDataSize value byte The string encoded as a UTF-8 string without null byte termination
5.3.7Enum

Enums are supposed to have a maximum number of 16 choices and do have a numeric ordinal value.

If the field is specified as OPTIONAL or SCALAR:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_ENUM
2 1 value byte The ordinal number of the enum

If the field is specified as ORDERED:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_ENUM_LIST
2 4 numerOfEntries int32 The number of values following
6 value byte[] The ordinal values of the enum

If the field is specified as UNIQUE:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_ENUM_SET
2 4 numerOfEntries int32 The number of values following
6 value uint16 A bit encoded of the enum values contained. If the enum with the ordinal 3 and 5 are contained in the set the value would be 0x14 since bits 3 and 5 are high.
5.3.8Properties map

If the field is specified as OPTIONAL or SCALAR:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_PROPERTIES
2 value PropertyEntry The value

If the field is specified as ORDERED or UNIQUE:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_PROPERTIES_LIST
2 4 numerOfEntries int32 The number of values following
6 value PropertyEntry[] The values

Each PropertyEntry is encoded as:

Index Length Name Type Description
0 4 keyStringSize int32 The number of string byte for following string
4 keyStringSize keyStringData byte[] The key value. The string encoded as a UTF-8 string without null byte termination
4 + keyStringSize 4 valueStringSize int32 The number of string byte for following string
8 + keyStringSize valueStringSize valueStringData byte[] The value assigned to the key. The string encoded as a UTF-8 string without null byte termination
5.3.9Variant

If the field is specified as OPTIONAL or SCALAR:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_VARIANT
2 value VariantEntry The value

If the field is specified as ORDERED or UNIQUE:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_VARIANT_LIST
2 4 numerOfEntries int32 The number of values following
6 value VariantEntry[] The values

Each VariantEntry is encoded as described in Variant.

5.3.10Variant Map

If the field is specified as OPTIONAL or SCALAR:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_VARIANT_MAP
2 value VariantMapEntry The value

If the field is specified as ORDERED or UNIQUE:

Index Length Name Type Description
0 1 fieldNumber byte The field number
1 1 typeId byte TYPE_VARIANT_MAP_LIST
2 4 numerOfEntries int32 The number of values following
6 value VariantMapEntry[] The values

Each VariantMapEntry is encoded as:

Index Length Name Type Description
0 4 keyStringSize int32 The number of string byte for following string
4 keyStringSize keyStringData byte[] The key value. The string encoded as a UTF-8 string without null byte termination
4 + keyStringSize value VariantEntry The variant value

Each VariantEntry is encoded as described in Variant.

5.4Values
Type ID Numeric hex value
TYPE_NULL 0x00
TYPE_STRING 0x01
TYPE_STRING_LIST 0x11
TYPE_LONG 0x02
TYPE_LONG_LIST 0x12
TYPE_INT 0x03
TYPE_INT_LIST 0x13
TYPE_BOOLEAN 0x04
TYPE_BOOLEAN_LIST 0x14
TYPE_DOUBLE 0x05
TYPE_DOUBLE_LIST 0x15
TYPE_VARIANT 0x06
TYPE_VARIANT_LIST 0x16
TYPE_VARIANT_MAP 0x07
TYPE_VARIANT_MAP_LIST 0x17
TYPE_PROPERTIES 0x08
TYPE_PROPERTIES_LIST 0x18
TYPE_STRUCTURE 0x09
TYPE_STRUCTURE_LIST 0x19
TYPE_ENUM 0x0A
TYPE_ENUM_LIST 0x1A
TYPE_ENUM_SET 0x2A
6Communication Concepts

The following sections describe some communication concepts used by the NGP based protocols. Some may be more specific to to NGP than others. Each section should explain the scope where this concept applies to.

6.1Interfaces

In the section messages all protocol and their data structures are documented. Each protocol has a list of messages, which are the primary data structures that can be sent between the communication partners. Messages are made of attributes, which me be grouped into structures. So far this is not too compilicated.

Then each protocol also defines some interfaces. Although these interfaces are part of the protocol they don't have any influence on the encoded messages which are sent over the wire. The idea of NGP is that these defined messages can be used to generate Java code (and possible other languages as well) which provide the data structures as Java objects. This aids in extending the protocols or creating new ones, since the parsers and data objects can easily be generated.

Although these messages are generated and code duplications don't hurt that much (they always hurt) sometimes it is required in the code handle a group of messages the same way, best without specifing them all. The is were message interfaces come in. Each message can be assigned one or more interfaces which define common attributes to these messages. When interfaces are defined and assigned the developer still has to take core of the attributes to be defined also in the message. This is not automatically done by the Java code generator. For a good example where this is used see concepts.requestAndResponse

For other languages it depends on the implementor of the code generator on how to realize the concept of message interfaces.

6.2Transient & deleted attributes

Attributes can be marked as transient and deleted. These two markers also only apply to the non-wire part of the protocol. It allows to define attributes to be removed from the wire protocol (transient) or from both the wire protocol and the data structures (deleted).

Transient is interesting for the case where you want to add more fields to the generated data structures but never want to send them over the wire.

Deleted is interesting for the case where the attribute should be present in the protocol definition but never in any implementation. For example attributes which where present in the past but are removed now, but are still kept for documenting the fact that they were there in the past.

6.3Equality

Data structures and messages may define some way of equality. If no fields are defined for equality the message instance defines the equality.

Otherwise two objects are equal if all their equality attributes are equal.

This must be implemented according to the programming language these data structures are create for. In Java this is mostly creating an appropriate hashCode and equals method.

6.4Request & response

Since the NGP basic message channel layer does not provide any request/response mechanism (and for good reason) this concept is handled in the message layer itself.

In order to to create a reference between a request and a response two message interfaces and defined which declare a request id that is a 64bit integer. This integer is filled by the sender and used int the reply by the receiver. Yet this concept is completely done by the application and not part of a NGP itself.

However openSCADA itself usese the messages interfaces Request and Response defined in the protocol protocol.core. This allows an easier implementation of the protocol.

Sometimes there are multiple different message types possible as a response. A request could have a success repsonse and an error response which could be two different messages but reference the same request id. In this is case the implemenation still must ensure that only one reply to the request is sent.

6.5Callbacks

The idea of callbacks is that the server can request additional information while he processes a client request. For example during the session creation phase the server might require some authorization from the client to check if the client is allowed to log on to the server. The server can then request a username and password from the client using the callbacks.

Like request/response mechanism this is part of the application layer and not a direct feature of NGP.

openSCADA defines this callback system in the protocol by defining a field named callbackHandlerId in the request message. If the server requires additional information it will send a RequestCallbacks message to the client, using the provided callbackHandlerId from the request. The callback handler id is only valid during the time of the request and must not be used beyond that. Though it is possible to send additional request after the first callback request has been completed.

The client will respond with a RespondCallbacks message when the information was gathered. This can be immediately if no user interface was required or present or after the user entered the data and confirmed. The client will use the request id from the RequestCallbacks message in the response as reference.

The server provides a timeout information after which the callback requests become canceled. This means, were not provided by the client and therefore the server decides what happens, but responses from he client to this callback reqest will not longer be processed. For example a logon request will then be aborted. This is done to ensure that if the client does not response to the callbacks due to any reason, the open requests don't build up in the server and client.

If the client does not support callbacks he can simply send a NULL value instead of a valid callback hander id. In this case the server won't send any requests and simply will assume all callbacks to be canceled immediately.

In fact the callback handler id is generated by the client and the client should generate a unique number. But it could also send a constant number, which would be ok for the server, since the server only references to this number. Still the client would then not be able to distinguish between different requests coming from the server.

6.6Sessions

Sessions are again a concept of higher level openSCADA application modules. While the NGP protocol first uses the TCP connection as session and the handshake phase including the message channel layer on top of it, the application layer also requires some session to work.

In openSCADA all services (Data Access, Configuration, …) require a session to work. During the session creation also the user credentials are validated if required. So the first thing to do after the message channel handshake is completed is for the client to request a session from the server using the CreateSession message from the core protocol.

The server then must respond using either a SessionAccepted message if the session was created successfully or a SessionReject message if not. Please not that the server still can send a RequestCallbacks message before sending the SessionAccepted message since additional user information might be required for the logon process.

6.7Session privileges

Session privileges are some sort of permissions granted and are a concept in higher level openSCADA.

While permissions are checked each time a request is made, session privileges are requested during the connection phase and granted dynamically is the client has permission. Their intended use is for user interface elements to become invisible if the user loooses these permissions.

Session privileges are checked automatically be server and granted as soon as the client gains the permission. This means that if the configuration changes on the server the client will get an update on the changed privileges. Both the initial set and the changes are transmitted using the SessionPrivilegesChanged message.

Please note that is not a security feature but a feature which aids in not confusing the end user with option he does not have in the first place.

Of course the use of all this highly depends on the server and client configuration of the specific system setup.

6.8Error information

Whenever something fails the openSCADA will use the ErrorInformation structure in the error response. It contains a numeric error value, an explenatory message string and some diagnostic information.

At least the message string should be filled, possible in a language the end user will understand. The diagnostic information can be used to provide some information like a stack trace in order to understand what went wrong.

But the diagnostic information should not be overloaded with stuff that normaly nobody cares about since all this information must be transmitted over the wire. If huge amounts of data should be transmitted there should be a switch implemeted to turn it on and the default should be off.

7Messages
7.1ae

This protocol inherits from the following protocols:

The protocol version is: 1

7.1.1Enums

The following enums are defined:

7.1.1.1MonitorStatus

Ordinal Literal
0 INACTIVE
1 OK
2 NOT_OK
3 NOT_OK_AKN
4 NOT_AKN
5 NOT_OK_NOT_AKN
6 UNSAFE
7 INIT
7.1.1.2QueryState

Ordinal Literal
0 DISCONNECTED
1 CONNECTED
2 CONNECTING
3 LOADING
7.1.1.3Severity

Ordinal Literal
0 INFORMATION
1 WARNING
2 ALARM
3 ERROR
7.1.1.4BrowserType

Ordinal Literal
0 MONITORS
1 EVENTS
7.1.2Interfaces

No interfaces defined.

7.1.3Structures

The following structures are defined:

7.1.3.1MonitorStatusInformation

The structure consists of the following attributes:

# Name Type Modifier Description
1 id String SCALAR
2 status MonitorStatus SCALAR
3 statusTimestamp Long SCALAR
4 severity Severity SCALAR
5 value Variant SCALAR
6 lastAknTimestamp Long OPTIONAL
7 lastAknUser String SCALAR
8 lastFailTimestamp Long OPTIONAL
10 lastFailValue Variant SCALAR
9 attributes VariantMap SCALAR
7.1.3.1.1lastFailValue

Hold the value that triggered the last failure

7.1.3.2BrowserEntry

The structure consists of the following attributes:

# Name Type Modifier Description
1 id String SCALAR
2 types BrowserType UNIQUE
3 attributes VariantMap SCALAR
7.1.3.3EventInformation

The structure consists of the following attributes:

# Name Type Modifier Description
1 id String SCALAR
2 sourceTimestamp Long SCALAR
3 entryTimestamp Long SCALAR
4 attributes VariantMap SCALAR
7.1.4Messages

The following messages are defined:

Name Code Description
SubscribeMonitorPool 0x2001
UnsubscribeMonitorPool 0x2002
MonitorPoolStatusUpdate 0x2003
MonitorPoolDataUpdate 0x2004
SubscribeEventPool 0x2101
UnsubscribeEventPool 0x2102
EventPoolStatusUpdate 0x2103
EventPoolDataUpdate 0x2104
CreateQuery 0x2201
LoadMore 0x2202
CloseQuery 0x2203
UpdateQueryState 0x2204
UpdateQueryData 0x2205
StartBrowse 0x2301
StopBrowse 0x2302
BrowseData 0x2303
AcknowledgeRequest 0x2401
AcknowledgeResponse 0x2402
7.1.4.1SubscribeMonitorPool

The message code is: 0x2001

The structure consists of the following attributes:

# Name Type Modifier Description
1 monitorPoolId String SCALAR
7.1.4.2UnsubscribeMonitorPool

The message code is: 0x2002

The structure consists of the following attributes:

# Name Type Modifier Description
1 monitorPoolId String SCALAR
7.1.4.3MonitorPoolStatusUpdate

The message code is: 0x2003

The structure consists of the following attributes:

# Name Type Modifier Description
1 monitorPoolId String SCALAR
2 state SubscriptionState SCALAR
7.1.4.4MonitorPoolDataUpdate

The message code is: 0x2004

The structure consists of the following attributes:

# Name Type Modifier Description
1 monitorPoolId String SCALAR
2 addedOrUpdated MonitorStatusInformation ORDERED
3 removed String UNIQUE
4 full Boolean SCALAR
7.1.4.5SubscribeEventPool

The message code is: 0x2101

The structure consists of the following attributes:

# Name Type Modifier Description
1 eventPoolId String SCALAR
7.1.4.6UnsubscribeEventPool

The message code is: 0x2102

The structure consists of the following attributes:

# Name Type Modifier Description
1 eventPoolId String SCALAR
7.1.4.7EventPoolStatusUpdate

The message code is: 0x2103

The structure consists of the following attributes:

# Name Type Modifier Description
1 eventPoolId String SCALAR
2 state SubscriptionState SCALAR
7.1.4.8EventPoolDataUpdate

The message code is: 0x2104

The structure consists of the following attributes:

# Name Type Modifier Description
1 eventPoolId String SCALAR
2 addedEvents EventInformation ORDERED
7.1.4.9CreateQuery

The message code is: 0x2201

The structure consists of the following attributes:

# Name Type Modifier Description
1 queryId Long SCALAR
2 queryType String SCALAR
3 queryData String SCALAR
7.1.4.10LoadMore

The message code is: 0x2202

The structure consists of the following attributes:

# Name Type Modifier Description
1 queryId Long SCALAR
2 count Integer SCALAR
7.1.4.11CloseQuery

The message code is: 0x2203

The structure consists of the following attributes:

# Name Type Modifier Description
1 queryId Long SCALAR
7.1.4.12UpdateQueryState

The message code is: 0x2204

The structure consists of the following attributes:

# Name Type Modifier Description
1 queryId Long SCALAR
2 state QueryState SCALAR
3 error ErrorInformation SCALAR
7.1.4.13UpdateQueryData

The message code is: 0x2205

The structure consists of the following attributes:

# Name Type Modifier Description
1 queryId Long SCALAR
2 events EventInformation ORDERED
7.1.4.14StartBrowse

The message code is: 0x2301

7.1.4.15StopBrowse

The message code is: 0x2302

7.1.4.16BrowseData

The message code is: 0x2303

The structure consists of the following attributes:

# Name Type Modifier Description
1 addedOrUpdated BrowserEntry ORDERED
2 removed String UNIQUE
3 full Boolean SCALAR
7.1.4.17AcknowledgeRequest

The message code is: 0x2401

The structure consists of the following attributes:

# Name Type Modifier Description
1 request Request SCALAR
2 monitorId String SCALAR
3 aknTimestamp Long OPTIONAL
4 operationParameters OperationParameters OPTIONAL
5 callbackHandlerId Long OPTIONAL

The message implements the following interfaces:

7.1.4.18AcknowledgeResponse

The message code is: 0x2402

The structure consists of the following attributes:

# Name Type Modifier Description
1 response Response SCALAR
2 errorInformation ErrorInformation OPTIONAL

The message implements the following interfaces:

7.2ca

This protocol inherits from the following protocols:

The protocol version is: 1

7.2.1Enums

The following enums are defined:

7.2.1.1Operation

Operation for DiffEntry

Ordinal Literal
0 ADD
1 DELETE
2 UPDATE_SET
3 UPDATE_DIFF
7.2.1.2FactoryState

Ordinal Literal
0 LOADED
1 BOUND
2 BINDING
7.2.1.3ConfigurationState

Ordinal Literal
0 AVAILABLE
1 APPLIED
2 ERROR
3 APPLYING
7.2.2Interfaces

No interfaces defined.

7.2.3Structures

The following structures are defined:

7.2.3.1FactoryInformation

Equality is defined by all of the following attributes:

The structure consists of the following attributes:

# Name Type Modifier Description
1 id String SCALAR
2 description String SCALAR
3 state FactoryState SCALAR
4 configurations ConfigurationInformation ORDERED
7.2.3.2ConfigurationInformation

Equality is defined by all of the following attributes:

The structure consists of the following attributes:

# Name Type Modifier Description
1 factoryId String SCALAR
2 id String SCALAR
3 state ConfigurationState SCALAR
4 data Properties SCALAR
5 errorInformation String SCALAR
7.2.3.3DiffEntry

The structure consists of the following attributes:

# Name Type Modifier Description
1 factoryId String SCALAR
2 configurationId String SCALAR
3 operation Operation SCALAR
5 addedOrUpdatedData Properties SCALAR
6 removedData String UNIQUE

The following attributes are transient and not encoded when transmitted:

# Name Type Modifier Description
4 oldData Properties SCALAR
7.2.4Messages

The following messages are defined:

Name Code Description
GetFactoriesRequest 0x4001
GetFactoriesResponse 0x4002
GetFactoryWithDataRequest 0x4003
GetFactoryWithDataResponse 0x4004
GetConfigurationRequest 0x4005
GetConfigurationResponse 0x4006
ApplyDiffRequest 0x4101
ApplyDiffResponse 0x4102
ErrorResponse 0x4201
7.2.4.1GetFactoriesRequest

The message code is: 0x4001

The structure consists of the following attributes:

# Name Type Modifier Description
1 request Request SCALAR

The message implements the following interfaces:

7.2.4.2GetFactoriesResponse

The message code is: 0x4002

The structure consists of the following attributes:

# Name Type Modifier Description
1 response Response SCALAR
2 factories FactoryInformation ORDERED

The message implements the following interfaces:

7.2.4.3GetFactoryWithDataRequest

The message code is: 0x4003

The structure consists of the following attributes:

# Name Type Modifier Description
1 request Request SCALAR
2 factoryId String SCALAR

The message implements the following interfaces:

7.2.4.4GetFactoryWithDataResponse

The message code is: 0x4004

The structure consists of the following attributes:

# Name Type Modifier Description
1 response Response SCALAR
2 factory FactoryInformation SCALAR

The message implements the following interfaces:

7.2.4.5GetConfigurationRequest

The message code is: 0x4005

The structure consists of the following attributes:

# Name Type Modifier Description
1 request Request SCALAR
2 factoryId String SCALAR
3 configurationId String SCALAR

The message implements the following interfaces:

7.2.4.6GetConfigurationResponse

The message code is: 0x4006

The structure consists of the following attributes:

# Name Type Modifier Description
1 response Response SCALAR
2 configuration ConfigurationInformation SCALAR

The message implements the following interfaces:

7.2.4.7ApplyDiffRequest

The message code is: 0x4101

The structure consists of the following attributes:

# Name Type Modifier Description
1 request Request SCALAR
2 diffs DiffEntry ORDERED
3 operationParameters OperationParameters OPTIONAL
4 callbackHandlerId Long OPTIONAL

The message implements the following interfaces:

7.2.4.8ApplyDiffResponse

The message code is: 0x4102

The structure consists of the following attributes:

# Name Type Modifier Description
1 response Response SCALAR

The message implements the following interfaces:

7.2.4.9ErrorResponse

The message code is: 0x4201

The structure consists of the following attributes:

# Name Type Modifier Description
1 response Response SCALAR
2 errorInformation ErrorInformation SCALAR

The message implements the following interfaces:

7.3core

The core protocol which acts as base for all others

The core protocol acts as a base for all other protocols. It contains the session handling and callbacks.

The protocol version is: 1

7.3.1Enums

The following enums are defined:

7.3.1.1SubscriptionState

Ordinal Literal
0 DISCONNECTED
1 GRANTED
2 CONNECTED
7.3.2Interfaces

The following interfaces are defined:

7.3.2.1RequestMessage

The structure consists of the following attributes:

# Name Type Modifier Description
0 request Request SCALAR
7.3.2.2ResponseMessage

The structure consists of the following attributes:

# Name Type Modifier Description
0 response Response SCALAR
7.3.3Structures

The following structures are defined:

7.3.3.1ErrorInformation

The structure consists of the following attributes:

# Name Type Modifier Description
1 code Long OPTIONAL An error code.
2 message String SCALAR A human readable error message.
3 diagnosticInformation String SCALAR Some technical diagnostic information.
7.3.3.2Request

Equality is defined by all of the following attributes:

The structure consists of the following attributes:

# Name Type Modifier Description
1 requestId Long SCALAR
7.3.3.3Response

The structure consists of the following attributes:

# Name Type Modifier Description
1 request Request SCALAR
7.3.3.4UserInformation

A user information

The structure consists of the following attributes:

# Name Type Modifier Description
1 name String SCALAR The name of the user
7.3.3.5OperationParameters

The structure consists of the following attributes:

# Name Type Modifier Description
1 userInformation UserInformation OPTIONAL
2 properties Properties SCALAR
7.3.3.6CallbackRequest

The structure consists of the following attributes:

# Name Type Modifier Description
1 type String SCALAR
2 attributes Properties SCALAR
7.3.3.7CallbackResponse

The structure consists of the following attributes:

# Name Type Modifier Description
1 canceled Boolean SCALAR
2 attributes Properties SCALAR
7.3.4Messages

The following messages are defined:

Name Code Description
CreateSession 0x0001 Request a new session from the server
SessionAccepted 0x0002 The session was created by the server
SessionRejected 0x0003 The session creation was rejected by the server
SessionPrivilegesChanged 0x0011 A change in privileges for the session
RequestCallbacks 0x0101 Request callbacks from the client
RespondCallbacks 0x0102 Provide response to callbacks request
7.3.4.1CreateSession

Request a new session from the server

Used by the client to request a new session from the server.

This message must only be sent once after the connection was established. The server has to respond either using the SessionAccepted or SessionRejected message.

The message code is: 0x0001

The structure consists of the following attributes:

# Name Type Modifier Description
1 properties Properties SCALAR The properties the client wants this session to have.
2 callbackHandlerId Long OPTIONAL An optional callback handler id which will receive callback requests if required.
7.3.4.1.1properties

This is purely application specific.

7.3.4.2SessionAccepted

The session was created by the server

Sent from the server to the client after receiving the CreateSession message when the server accepted the session creation request.

This message must only be sent once after the CreateSession message was received from the client and only if the SessionRejected message was not sent.

The message code is: 0x0002

The structure consists of the following attributes:

# Name Type Modifier Description
1 properties Properties SCALAR The properties the server granted the session.
7.3.4.2.1properties

This is purely application specific.

7.3.4.3SessionRejected

The session creation was rejected by the server

Sent from the server to the client when the session was requested using the CreateSession message but could not be granted.

This message must only be sent once after the CreateSession message was received from the client and only if the SessionAccepted message was not sent.

The message code is: 0x0003

The structure consists of the following attributes:

# Name Type Modifier Description
1 errorReason String SCALAR The error message why the session was rejected.
7.3.4.4SessionPrivilegesChanged

A change in privileges for the session

This message is sent from the server to the client when the session privilges have changed.

The message code is: 0x0011

The structure consists of the following attributes:

# Name Type Modifier Description
1 granted String UNIQUE The granted privileges of the session
7.3.4.4.1granted

Contains all granted session privileges. The full set is transmitted.

7.3.4.5RequestCallbacks

Request callbacks from the client

The server sends this message in order to request additional information from the client.

The message code is: 0x0101

The structure consists of the following attributes:

# Name Type Modifier Description
1 request Request SCALAR
2 callbackHandlerId Long SCALAR The callback handler id this request is directed to.
3 callbacks CallbackRequest ORDERED
4 timeoutMillis Long OPTIONAL The callback timeout in milliseconds.

The message implements the following interfaces:

7.3.4.6RespondCallbacks

Provide response to callbacks request

The clients answers a previous RequestCallbacks message, providing the results.

The message code is: 0x0102

The structure consists of the following attributes:

# Name Type Modifier Description
1 response Response SCALAR
2 callbacks CallbackResponse ORDERED A result entry for each request entry.
3 errorInformation ErrorInformation OPTIONAL Some error information

The message implements the following interfaces:

7.3.4.6.1errorInformation

This error information is optional. If everything was fine it must be null.

7.4da

openSCADA DA Protocol

The openSCADA DA (Data Access) protocol allows a client to access current value data from the server, subscribe to data items

and start write requests. In addition browse the item namespace.

This protocol inherits from the following protocols:

The protocol version is: 1

7.4.1Enums

The following enums are defined:

7.4.1.1FolderEntryType

Ordinal Literal
0 ITEM
1 FOLDER
7.4.1.2IODirection

Ordinal Literal
0 INPUT
1 OUTPUT
7.4.2Interfaces

No interfaces defined.

7.4.3Structures

The following structures are defined:

7.4.3.1AttributeWriteResultEntry

The structure consists of the following attributes:

# Name Type Modifier Description
1 attribute String SCALAR
2 errorInformation ErrorInformation OPTIONAL
7.4.3.2BrowserEntry

An entry in a folder.

A folder entry is like a directory entry in a file system. A folder has serveral named entries which point to actual files. Yet the name of the folder entry and the item id (file) must not be the same.

The structure consists of the following attributes:

# Name Type Modifier Description
1 name String SCALAR The name of the folder entry.
2 entryType FolderEntryType SCALAR
3 itemId String OPTIONAL The item id the folder entry is pointing to.
4 attributes VariantMap OPTIONAL
5 ioDirection IODirection UNIQUE
7.4.4Messages

The following messages are defined:

Name Code Description
SubscribeItem 0x1001 Subscribe to an item on the server.
UnsubscibeItem 0x1002 Ask the server to stop sending updates for a data item.
ItemDataUpdate 0x1003 The server sends a data update for an item to the client.
ItemStateUpdate 0x1004 Update from the server about a subscribed item's state.
StartWriteValue 0x1101 Request the server to write a value to an item.
WriteValueResult 0x1102 The result from the server to a write value request.
StartWriteAttributes 0x1111 Request the server to write attributes to an item.
WriteAttributesResult 0x1112 The result from the server to a write attributes request.
SubscribeFolder 0x1201 Subscribe to a folder.
UnsubscribeFolder 0x1202 Stop receiving updates for a folder.
FolderDataUpdate 0x1203 A message from the server to inform the client about a folder data change.
BrowseFolder 0x1211 Request a single read on a folder.
BrowseResult 0x1212 The result of the folder browse/read request.
7.4.4.1SubscribeItem

Subscribe to an item on the server.

Request an item subscription at the server. If granted the server will start sending ItemDataUpdate and ItemStateUpdate messages until the Unsubscribe message is sent from the client.

If the server does not allow subscribing to the item an ItemStateUpdate message with the state DISCONNECTED is sent once.

The message code is: 0x1001

The structure consists of the following attributes:

# Name Type Modifier Description
1 itemId String SCALAR
7.4.4.2UnsubscibeItem

Ask the server to stop sending updates for a data item.

The message code is: 0x1002

The structure consists of the following attributes:

# Name Type Modifier Description
1 itemId String SCALAR
7.4.4.3ItemDataUpdate

The server sends a data update for an item to the client.

It a subscribed item changes this message is sent from the server to the client to inform it of the value change.

Note that the server sends only differential updates unless the "cacheValue" flag is set.

The message code is: 0x1003

The structure consists of the following attributes:

# Name Type Modifier Description
1 itemId String SCALAR The id of the item that changed.
2 value Variant OPTIONAL The new value of the item or NULL if the value did not change.
3 addedOrUpdated VariantMap OPTIONAL Attributes that were added or removed.
4 removed String UNIQUE Attributes that were removed.
5 cacheValue Boolean SCALAR Indicates a real differential change or a full transmission from the cache.
7.4.4.3.1addedOrUpdated
7.4.4.4ItemStateUpdate

Update from the server about a subscribed item's state.

The message code is: 0x1004

The structure consists of the following attributes:

# Name Type Modifier Description
1 itemId String SCALAR The id of the item that changed.
2 subscriptionState SubscriptionState SCALAR The new subscription state.
3 errorInformation ErrorInformation OPTIONAL The error information if the item gets disconnected.
7.4.4.4.1subscriptionState

If the subscription state changed to DISCONNECTED the item is considered unsubscribed.

7.4.4.5StartWriteValue

Request the server to write a value to an item.

The message code is: 0x1101

The structure consists of the following attributes:

# Name Type Modifier Description
1 request Request SCALAR
2 itemId String SCALAR The id ot the item to write to.
3 value Variant SCALAR
4 operationParameters OperationParameters OPTIONAL
5 callbackHandlerId Long OPTIONAL The callback handler id.

The message implements the following interfaces:

7.4.4.6WriteValueResult

The result from the server to a write value request.

The message code is: 0x1102

The structure consists of the following attributes:

# Name Type Modifier Description
1 response Response SCALAR
2 errorInformation ErrorInformation OPTIONAL

The message implements the following interfaces:

7.4.4.7StartWriteAttributes

Request the server to write attributes to an item.

The message code is: 0x1111

The structure consists of the following attributes:

# Name Type Modifier Description
1 request Request SCALAR
2 itemId String SCALAR The id ot the item to write to.
3 attributes VariantMap SCALAR
4 operationParameters OperationParameters OPTIONAL
5 callbackHandlerId Long OPTIONAL The callback handler id.

The message implements the following interfaces:

7.4.4.8WriteAttributesResult

The result from the server to a write attributes request.

The message code is: 0x1112

The structure consists of the following attributes:

# Name Type Modifier Description
1 response Response SCALAR
2 attributeResults AttributeWriteResultEntry ORDERED
3 errorInformation ErrorInformation OPTIONAL

The message implements the following interfaces:

7.4.4.9SubscribeFolder

Subscribe to a folder.

This is a request from the client to the server to receive updates for a folder. It is used for browing the data item namespace of the server.

Only the referenced folder is subscribed not the upper hierarchy.

Since there is not state update for the folder, the only way to know if the subscribed folder is still active is to also subscribe to the parent folder and check if the sub-folder was removed.

The message code is: 0x1201

The structure consists of the following attributes:

# Name Type Modifier Description
1 location String ORDERED
7.4.4.10UnsubscribeFolder

Stop receiving updates for a folder.

The message code is: 0x1202

The structure consists of the following attributes:

# Name Type Modifier Description
1 location String ORDERED
7.4.4.11FolderDataUpdate

A message from the server to inform the client about a folder data change.

The message code is: 0x1203

The structure consists of the following attributes:

# Name Type Modifier Description
1 location String ORDERED
2 addedOrModified BrowserEntry ORDERED
3 removed String UNIQUE
4 full Boolean SCALAR
7.4.4.12BrowseFolder

Request a single read on a folder.

This lists a folder contents only once and no subscription is established.

It is not recommended to use this method since many server do update their folder structures during runtime and therefore the client would miss some updates and would need to do a full refresh manually.

The message code is: 0x1211

The structure consists of the following attributes:

# Name Type Modifier Description
1 request Request SCALAR
2 location String ORDERED

The message implements the following interfaces:

7.4.4.13BrowseResult

The result of the folder browse/read request.

The message code is: 0x1212

The structure consists of the following attributes:

# Name Type Modifier Description
1 response Response SCALAR
2 browserData BrowserEntry ORDERED
3 errorInformation ErrorInformation OPTIONAL

The message implements the following interfaces:

7.5hd

This protocol inherits from the following protocols:

The protocol version is: 1

7.5.1Enums

No enums defined.

7.5.2Interfaces

No interfaces defined.

7.5.3Structures

The following structures are defined:

7.5.3.1QueryParameters

The structure consists of the following attributes:

# Name Type Modifier Description
1 startTimestamp Long SCALAR
2 endTimestamp Long SCALAR
3 numberOfEntries Integer SCALAR
7.5.3.2HistoricalItemInformation

Equality is defined by all of the following attributes:

The structure consists of the following attributes:

# Name Type Modifier Description
1 itemId String SCALAR
2 attributes VariantMap SCALAR
7.5.3.3ValueInformation

Equality is defined by all of the following attributes:

The structure consists of the following attributes:

# Name Type Modifier Description
1 quality Float SCALAR
2 manualPercentage Float SCALAR
3 startTimestamp Long SCALAR
4 endTimestamp Long SCALAR
5 sourceValues Long SCALAR
7.5.3.3.1quality

The percent count (from 0.0 to 1.0) of valid values

7.5.3.3.2manualPercentage

The percent count (from 0.0 to 1.0) of manual values

7.5.3.3.3sourceValues

The number of level 0 entries that where used to generate this value

7.5.3.4ValueEntry

The structure consists of the following attributes:

# Name Type Modifier Description
1 valueType String SCALAR
2 values Float ORDERED
7.5.3.4.1valueType

The type of value series (e.g. AVG)

7.5.4Messages

The following messages are defined:

Name Code Description
CreateQuery 0x3001
CreateQueryFailure 0x3002
CloseQuery 0x3003
ChangeQueryParameters 0x3004
UpdateQueryState 0x3005
UpdateQueryParameters 0x3006
UpdateQueryData 0x3007
StartBrowse 0x3101
StopBrowse 0x3102
ListUpdate 0x3103
7.5.4.1CreateQuery

Create a new query. In case the query id already existed in the server a CreateMessageFailure will be replied.

The message code is: 0x3001

The structure consists of the following attributes:

# Name Type Modifier Description
1 request Request SCALAR
2 queryId Long SCALAR
3 itemId String SCALAR
4 updateData Boolean SCALAR
5 queryParameters QueryParameters SCALAR
7.5.4.2CreateQueryFailure

The message code is: 0x3002

The structure consists of the following attributes:

# Name Type Modifier Description
1 response Response SCALAR
2 errorInformation ErrorInformation SCALAR
7.5.4.3CloseQuery

The message code is: 0x3003

The structure consists of the following attributes:

# Name Type Modifier Description
1 queryId Long SCALAR
7.5.4.4ChangeQueryParameters

The message code is: 0x3004

The structure consists of the following attributes:

# Name Type Modifier Description
1 queryId Long SCALAR
2 queryParameters QueryParameters SCALAR
7.5.4.5UpdateQueryState

The message code is: 0x3005

The structure consists of the following attributes:

# Name Type Modifier Description
1 queryId Long SCALAR
2 state String SCALAR
7.5.4.6UpdateQueryParameters

The message code is: 0x3006

The structure consists of the following attributes:

# Name Type Modifier Description
1 queryId Long SCALAR
2 queryParameters QueryParameters SCALAR
3 valueTypes String UNIQUE
7.5.4.7UpdateQueryData

The message code is: 0x3007

The structure consists of the following attributes:

# Name Type Modifier Description
1 queryId Long SCALAR
2 index Integer SCALAR
3 valueInformation ValueInformation ORDERED
4 values ValueEntry ORDERED
7.5.4.8StartBrowse

The message code is: 0x3101

7.5.4.9StopBrowse

The message code is: 0x3102

7.5.4.10ListUpdate

The message code is: 0x3103

The structure consists of the following attributes:

# Name Type Modifier Description
1 addedOrModified HistoricalItemInformation UNIQUE
2 removed String UNIQUE
3 fullUpdate Boolean SCALAR
8Appendices
8.IGNU Free Documentation License

                GNU Free Documentation License
                 Version 1.3, 3 November 2008


 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
     <http://fsf.org/>
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.

This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft
license designed for free software.

We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.


1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License.  Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein.  The "Document", below,
refers to any such manual or work.  Any member of the public is a
licensee, and is addressed as "you".  You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.

A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject.  (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.

The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.  If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant.  The Document may contain zero
Invariant Sections.  If the Document does not identify any Invariant
Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.  A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters.  A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text.  A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification.  Examples of
transparent image formats include PNG, XCF and JPG.  Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.

The "publisher" means any person or entity that distributes copies of
the Document to the public.

A section "Entitled XYZ" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language.  (Here XYZ stands for a
specific section name mentioned below, such as "Acknowledgements",
"Dedications", "Endorsements", or "History".)  To "Preserve the Title"
of such a section when you modify the Document means that it remains a
section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document.  These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no
other conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and
you may publicly display copies.


3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present
the full title with all words of the title equally prominent and
visible.  You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.

It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to
give them a chance to provide you with an updated version of the
Document.


4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it.  In addition, you must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct
   from that of the Document, and from those of previous versions
   (which should, if there were any, be listed in the History section
   of the Document).  You may use the same title as a previous version
   if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities
   responsible for authorship of the modifications in the Modified
   Version, together with at least five of the principal authors of the
   Document (all of its principal authors, if it has fewer than five),
   unless they release you from this requirement.
C. State on the Title page the name of the publisher of the
   Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
   adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice
   giving the public permission to use the Modified Version under the
   terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections
   and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title, and add
   to it an item stating at least the title, year, new authors, and
   publisher of the Modified Version as given on the Title Page.  If
   there is no section Entitled "History" in the Document, create one
   stating the title, year, authors, and publisher of the Document as
   given on its Title Page, then add an item describing the Modified
   Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for
   public access to a Transparent copy of the Document, and likewise
   the network locations given in the Document for previous versions
   it was based on.  These may be placed in the "History" section.
   You may omit a network location for a work that was published at
   least four years before the Document itself, or if the original
   publisher of the version it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
   Preserve the Title of the section, and preserve in the section all
   the substance and tone of each of the contributor acknowledgements
   and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
   unaltered in their text and in their titles.  Section numbers
   or the equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements".  Such a section
   may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements"
   or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.

You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity.  If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.


5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled
"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications".  You must delete all sections
Entitled "Endorsements".


6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the rules
of this License for verbatim copying of each of the documents in all
other respects.

You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert a
copy of this License into the extracted document, and follow this
License in all other respects regarding verbatim copying of that
document.


7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.


8. TRANSLATION

Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers.  In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.


9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense, or distribute it is void, and
will automatically terminate your rights under this License.

However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.

Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.

Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License.  If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.


10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the
GNU Free Documentation License from time to time.  Such new versions
will be similar in spirit to the present version, but may differ in
detail to address new problems or concerns.  See
http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.  If the Document
specifies that a proxy can decide which future versions of this
License can be used, that proxy's public statement of acceptance of a
version permanently authorizes you to choose that version for the
Document.

11. RELICENSING

"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works.  A
public wiki that anybody can edit is an example of such a server.  A
"Massive Multiauthor Collaboration" (or "MMC") contained in the site
means any set of copyrightable works thus published on the MMC site.

"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 
license published by Creative Commons Corporation, a not-for-profit 
corporation with a principal place of business in San Francisco, 
California, as well as future copyleft versions of that license 
published by that same organization.

"Incorporate" means to publish or republish a Document, in whole or in 
part, as part of another Document.

An MMC is "eligible for relicensing" if it is licensed under this 
License, and if all works that were first published under this License 
somewhere other than this MMC, and subsequently incorporated in whole or 
in part into the MMC, (1) had no cover texts or invariant sections, and 
(2) were thus incorporated prior to November 1, 2008.

The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.