Commits

Jens Reimann committed 68ccadd

provide some basic information about the message channel

  • Participants
  • Parent commits cc1ca1f
  • Branches 1.2

Comments (0)

Files changed (5)

File org.openscada.documentation/protocol/book/index.html

 <div class="tocbox">
 <div class="heading toc">Table of contents</div>
 <div class="tocentry level_1"><a href="#section_1"><span class="number">1</span><span class="title">Introduction</span></a></div>
-<div class="tocentry level_1"><a href="#section_license"><span class="number">2</span><span class="title">GNU Free Documentation License</span></a></div>
+<div class="tocentry level_1"><a href="#section_2"><span class="number">2</span><span class="title">NGP – NextGenerationProtocol</span></a></div>
+<div class="tocentry level_2"><a href="#section_2.1"><span class="number">2.1</span><span class="title">Overview</span></a></div>
+<div class="tocentry level_2"><a href="#section_2.2"><span class="number">2.2</span><span class="title">Message channel</span></a></div>
+<div class="tocentry level_3"><a href="#section_2.2.1"><span class="number">2.2.1</span><span class="title">Message types</span></a></div>
+<div class="tocentry level_3"><a href="#section_2.2.2"><span class="number">2.2.2</span><span class="title">Message sequence</span></a></div>
+<div class="tocentry level_3"><a href="#section_2.2.3"><span class="number">2.2.3</span><span class="title">Exception Handling</span></a></div>
+<div class="tocentry level_3"><a href="#section_2.2.4"><span class="number">2.2.4</span><span class="title">Message Codec</span></a></div>
+<div class="tocentry level_1"><a href="#section_3"><span class="number">3</span><span class="title">Appendices</span></a></div>
+<div class="tocentry level_2"><a href="#section_license"><span class="number">3.I</span><span class="title">GNU Free Documentation License</span></a></div>
 </div>
 <div class="bodybox">
 <div class="book_title">openSCADA Protocol Description</div><div class="book_authors">Authors</div><ul class="book_author_list"><li>Jens Reimann (ctron@dentrassi.de)</li></ul><div class="book_copyright">Copyright &copy; 2013</div><p class="book_copyrightText">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 &quot;GNU Free Documentation License&quot;.</p><div id="section_1" class="heading level_1"><span class="number">1</span><span class="title">Introduction</span></div>
-<div id="section_license" class="heading level_1"><span class="number">2</span><span class="title">GNU Free Documentation License</span></div>
+<p>
+This document describes the internal openSCADA protocols.
+</p>
+<p>
+The reader of this document should be familiar with TCP/IP based network 
+communication.
+</p>
+<div id="section_2" class="heading level_1"><span class="number">2</span><span class="title">NGP – NextGenerationProtocol</span></div>
+<p>
+The <q>NPG</q> protocol (<q>next generation protocol</q>) is the
+successor of the <q>GMPP/NET</q> protocol of openSCADA. it was created in order
+to fix some performance issues and make it easier to extend the protocol. 
+</p>
+<div id="section_2.1" class="heading level_2"><span class="number">2.1</span><span class="title">Overview</span></div>
+<p>
+NGP is a plain Client/Server TCP/IP protocol. The server side is also the TCP server. So an
+DA server (aka <q>Hive</q>, <q>Driver Module</q>) is the
+TCP server.
+</p>
+<p>
+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.
+</p>
+<p>
+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 <q>data</q>
+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.
+</p>
+<p>
+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.
+</p>
+<p>
+The result of the second layer is a <q>stream</q> of interpreted
+messages which make up the real data of the openSCADA protocol that is transmitted.
+</p>
+<div id="section_2.2" class="heading level_2"><span class="number">2.2</span><span class="title">Message channel</span></div>
+<div id="section_2.2.1" class="heading level_3"><span class="number">2.2.1</span><span class="title">Message types</span></div>
+<p>
+The message channel sends frames. Frames have a distinct type and encoding. The following frame
+types are defined:
+</p>
+<table class="dcm_simple"><colgroup>
+<col class="dcm_left" />
+<col class="dcm_left" />
+<col class="dcm_left" />
+<col class="dcm_left" />
+</colgroup>
+<thead><tr>
+<th>Name</th>
+<th>Numeric</th>
+<th>Sender</th>
+<th>Description</th>
+</tr></thead>
+<tbody>
+<tr>
+<td class="dcm_left">HELLO</td>
+<td class="dcm_left">0</td>
+<td class="dcm_left">Client</td>
+<td class="dcm_left">Sent by the client to initiate the communication. Must only be sent once, as
+first message</td>
+</tr>
+<tr>
+<td class="dcm_left">MESSAGE</td>
+<td class="dcm_left">1</td>
+<td class="dcm_left">Any</td>
+<td class="dcm_left">A message containing data. Must only be sent after the handshake
+was completed successfully.</td>
+</tr>
+<tr>
+<td class="dcm_left">ACCEPT</td>
+<td class="dcm_left">2</td>
+<td class="dcm_left">Server</td>
+<td class="dcm_left">Sent by the server after a HELLO message was received and confirming the
+successful handshake. Must only be sent once.</td>
+</tr>
+<tr>
+<td class="dcm_left">CLOSE</td>
+<td class="dcm_left">3</td>
+<td class="dcm_left">Any</td>
+<td class="dcm_left">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.</td>
+</tr>
+<tr>
+<td class="dcm_left">START</td>
+<td class="dcm_left">4</td>
+<td class="dcm_left">Client</td>
+<td class="dcm_left">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, &hellip;) have been applied by the client.</td>
+</tr>
+<tr>
+<td class="dcm_left">PING</td>
+<td class="dcm_left">5</td>
+<td class="dcm_left">Any</td>
+<td class="dcm_left">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.</td>
+</tr>
+<tr>
+<td class="dcm_left">PONG</td>
+<td class="dcm_left">5</td>
+<td class="dcm_left">Any</td>
+<td class="dcm_left">Sent exactly once by any party after a PING message was received.</td>
+</tr>
+</tbody>
+</table>
+<div id="section_2.2.2" class="heading level_3"><span class="number">2.2.2</span><span class="title">Message sequence</span></div>
+<p>
+The connection is initiated by the client. The client openes 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.  
+</p>
+<p>
+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.
+</p>
+<div id="section_2.2.3" class="heading level_3"><span class="number">2.2.3</span><span class="title">Exception Handling</span></div>
+<p>
+In case anything goes wrong each side may close the TCP connection at any time.
+</p>
+<div id="section_2.2.4" class="heading level_3"><span class="number">2.2.4</span><span class="title">Message Codec</span></div>
+<table class="dcm_simple"><colgroup>
+<col class="dcm_left" />
+<col class="dcm_left" />
+<col class="dcm_left" />
+<col class="dcm_left" />
+</colgroup>
+<thead><tr>
+<th>Index</th>
+<th>Field</th>
+<th>Type</th>
+<th>Description</th>
+</tr></thead>
+<tbody>
+<tr>
+<td class="dcm_left">0</td>
+<td class="dcm_left">Version</td>
+<td class="dcm_left">byte</td>
+<td class="dcm_left">Version identifier, contains 0x01 at the moment.</td>
+</tr>
+<tr>
+<td class="dcm_left">1</td>
+<td class="dcm_left">Message type/numeric</td>
+<td class="dcm_left">byte</td>
+<td class="dcm_left">The numeric value of the message.</td>
+</tr>
+<tr>
+<td class="dcm_left">2</td>
+<td class="dcm_left">Data Size</td>
+<td class="dcm_left">32bit signed integer</td>
+<td class="dcm_left">The amout of data following. Although this is a signed integer, it must never be negative.</td>
+</tr>
+<tr>
+<td class="dcm_left">6</td>
+<td class="dcm_left">Data</td>
+<td class="dcm_left">bytes</td>
+<td class="dcm_left">Message payload, must be encoded/decoded depending on the mesage type.</td>
+</tr>
+</tbody>
+</table>
+<div id="section_3" class="heading level_1"><span class="number">3</span><span class="title">Appendices</span></div>
+<div id="section_license" class="heading level_2"><span class="number">3.I</span><span class="title">GNU Free Documentation License</span></div>
 <pre>
 
                 GNU Free Documentation License

File org.openscada.documentation/protocol/content/introduction.content

 <?xml version="1.0" encoding="UTF-8"?>
 <content:fragment xmlns:content="urn:openscada:doc:content">
+
+<content:p>
+This document describes the internal openSCADA protocols.
+</content:p>
+
+<content:p>
+The reader of this document should be familiar with TCP/IP based network 
+communication.
+</content:p>
+
 </content:fragment>

File org.openscada.documentation/protocol/content/ngp/01_overview.content

+<?xml version="1.0" encoding="UTF-8"?>
+<content:fragment xmlns:content="urn:openscada:doc:content">
+
+<content:p>
+The <content:q>NPG</content:q> protocol (<content:q>next generation protocol</content:q>) is the
+successor of the <content:q>GMPP/NET</content:q> protocol of openSCADA. it was created in order
+to fix some performance issues and make it easier to extend the protocol. 
+</content:p>
+
+<content:section content:title="Overview">
+
+<content:p>
+NGP is a plain Client/Server TCP/IP protocol. The server side is also the TCP server. So an
+DA server (aka <content:q>Hive</content:q>, <content:q>Driver Module</content:q>) is the
+TCP server.
+</content:p>
+
+<content:p>
+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.
+</content:p>
+
+<content:p>
+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 <content:q>data</content:q>
+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.
+</content:p>
+
+<content:p>
+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.
+</content:p>
+
+<content:p>
+The result of the second layer is a <content:q>stream</content:q> of interpreted
+messages which make up the real data of the openSCADA protocol that is transmitted.
+</content:p>
+
+</content:section>
+
+
+<content:section content:title="Message channel">
+
+<content:section content:title="Message types">
+
+<content:p>
+The message channel sends frames. Frames have a distinct type and encoding. The following frame
+types are defined:
+</content:p>
+
+<content:simpleTable>
+<content:column content:horizontalAlign="LEFT" content:title="Name"/>
+<content:column content:horizontalAlign="LEFT" content:title="Numeric"/>
+<content:column content:horizontalAlign="LEFT" content:title="Sender"/>
+<content:column content:horizontalAlign="LEFT" content:title="Description"/>
+
+<content:row>
+<content:cell>HELLO</content:cell><content:cell>0</content:cell><content:cell>Client</content:cell>
+<content:cell>Sent by the client to initiate the communication. Must only be sent once, as
+first message</content:cell>
+</content:row>
+
+<content:row>
+<content:cell>MESSAGE</content:cell><content:cell>1</content:cell><content:cell>Any</content:cell>
+<content:cell>A message containing data. Must only be sent after the handshake
+was completed successfully.</content:cell>
+</content:row>
+
+<content:row>
+<content:cell>ACCEPT</content:cell><content:cell>2</content:cell><content:cell>Server</content:cell>
+<content:cell>Sent by the server after a HELLO message was received and confirming the
+successful handshake. Must only be sent once.</content:cell>
+</content:row>
+
+<content:row>
+<content:cell>CLOSE</content:cell><content:cell>3</content:cell><content:cell>Any</content:cell>
+<content:cell>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.</content:cell>
+</content:row>
+
+<content:row>
+<content:cell>START</content:cell><content:cell>4</content:cell><content:cell>Client</content:cell>
+<content:cell>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.</content:cell>
+</content:row>
+
+<content:row>
+<content:cell>PING</content:cell><content:cell>5</content:cell><content:cell>Any</content:cell>
+<content:cell>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.</content:cell>
+</content:row>
+
+<content:row>
+<content:cell>PONG</content:cell><content:cell>5</content:cell><content:cell>Any</content:cell>
+<content:cell>Sent exactly once by any party after a PING message was received.</content:cell>
+</content:row>
+
+</content:simpleTable>
+
+</content:section>
+
+<content:section content:title="Message sequence">
+
+<content:p>
+The connection is initiated by the client. The client openes 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.  
+</content:p>
+
+<content:p>
+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.
+</content:p>
+
+</content:section>
+
+<content:section content:title="Exception Handling">
+<content:p>
+In case anything goes wrong each side may close the TCP connection at any time.
+</content:p>
+</content:section>
+
+<content:section content:title="Message Codec">
+
+<content:simpleTable>
+
+<content:column content:horizontalAlign="LEFT" content:title="Index"/>
+<content:column content:horizontalAlign="LEFT" content:title="Field"/>
+<content:column content:horizontalAlign="LEFT" content:title="Type"/>
+<content:column content:horizontalAlign="LEFT" content:title="Description"/>
+
+<content:row>
+<content:cell>0</content:cell><content:cell>Version</content:cell><content:cell>byte</content:cell>
+<content:cell>Version identifier, contains 0x01 at the moment.</content:cell>
+</content:row>
+
+<content:row>
+<content:cell>1</content:cell><content:cell>Message type/numeric</content:cell><content:cell>byte</content:cell>
+<content:cell>The numeric value of the message.</content:cell>
+</content:row>
+
+<content:row>
+<content:cell>2</content:cell><content:cell>Data Size</content:cell><content:cell>32bit signed integer</content:cell>
+<content:cell>The amout of data following. Although this is a signed integer, it must never be negative.</content:cell>
+</content:row>
+
+<content:row>
+<content:cell>6</content:cell><content:cell>Data</content:cell><content:cell>bytes</content:cell>
+<content:cell>Message payload, must be encoded/decoded depending on the mesage type.</content:cell>
+</content:row>
+
+</content:simpleTable>
+
+</content:section>
+
+</content:section>
+
+</content:fragment>

File org.openscada.documentation/protocol/merged.book

Binary file modified.

File org.openscada.documentation/protocol/protocol.bookBuilder

   <elements xsi:type="map:MapSection" title="Introduction">
     <elements xsi:type="map:File" path="content/introduction.content"/>
   </elements>
+  <elements xsi:type="map:MapSection" title="NGP – NextGenerationProtocol">
+    <elements xsi:type="map:File" path="content/ngp/01_overview.content"/>
+  </elements>
+  <elements xsi:type="map:MapSection" numberingStyle="ROMAN" title="Appendices">
+    <elements xsi:type="map:MapSection" id="license"/>
+  </elements>
   <authors name="Jens Reimann" ref="ctron@dentrassi.de" id="jens.reimann"/>
   <copyright year="2013" author="jens.reimann"/>
 </builder:BookBuilder>