You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by cd...@apache.org on 2018/08/13 07:40:36 UTC
[incubator-plc4x] branch master updated: - Did some cleaning up in
the sites protocols section - Added some initial documentation on the
DeltaV protocol
This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-plc4x.git
The following commit(s) were added to refs/heads/master by this push:
new e986509 - Did some cleaning up in the sites protocols section - Added some initial documentation on the DeltaV protocol
e986509 is described below
commit e986509701ff98ee5b6f4a9165764f7542a11f94
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Mon Aug 13 09:40:33 2018 +0200
- Did some cleaning up in the sites protocols section
- Added some initial documentation on the DeltaV protocol
---
src/site/asciidoc/protocols/{ => ads}/index.adoc | 16 +-
src/site/asciidoc/protocols/delta-v/index.adoc | 186 +++++++++++++++++++++
.../protocols/{ => ethernet-ip}/index.adoc | 15 +-
src/site/asciidoc/protocols/features.adoc | 36 +++-
src/site/asciidoc/protocols/index.adoc | 11 +-
src/site/site.xml | 5 +-
6 files changed, 226 insertions(+), 43 deletions(-)
diff --git a/src/site/asciidoc/protocols/index.adoc b/src/site/asciidoc/protocols/ads/index.adoc
similarity index 52%
copy from src/site/asciidoc/protocols/index.adoc
copy to src/site/asciidoc/protocols/ads/index.adoc
index 8bdf917..dd1736b 100644
--- a/src/site/asciidoc/protocols/index.adoc
+++ b/src/site/asciidoc/protocols/ads/index.adoc
@@ -15,23 +15,11 @@
// limitations under the License.
//
-== Protocols
+== Beckhoff ADS
-- link:modbus/index.html[Modbus]
-- link:opc-ua/index.html[OPC-UA]
-- link:s7/index.html[S7]
+Introduction
=== Links
-Apache 2.0 licensed JNI library for accessing raw IPv4 and IPv6 sockets. Might be the ideal starting point for implementing protocols below TCP & UDP.
-https://www.savarese.org/software/rocksaw/
-Links to different Wireshark captures: https://github.com/automayt/ICS-pcap
-==== Ethernet/IP
-
-As of November 2008, The EtherNet/IP Specification consists of three parts: The Common Industrial
-Protocol (Volume 1 of the CIP Networks Library), the EtherNet/IP Adaptation of CIP (Volume 2), and the
-Integration of Modbus® Devices into a CIP Architecture (Volume 7).
-
-Order Form for the SPEC ($1000) https://secure.odva.org/forms/spec-vendor-id-order-form.htm
diff --git a/src/site/asciidoc/protocols/delta-v/index.adoc b/src/site/asciidoc/protocols/delta-v/index.adoc
new file mode 100644
index 0000000..da1514f
--- /dev/null
+++ b/src/site/asciidoc/protocols/delta-v/index.adoc
@@ -0,0 +1,186 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+== DeltaV Industrial Ethernet Communication
+
+The DeltaV protocol is used in the Emerson DeltaV system.
+In contrast to most other systems, this is a combination of PLC and Control System.
+As Emerson seems to insist on the devices not being PLCs, but controllers, well call them this way in this document.
+Same with the Control System, these seem to be called OS (Operator System).
+
+=== Disclaimer
+
+As we had absolutely no information on the details of the protocol, we started by taking an existing DeltaV training system and replaced the network switch with a hub and used this to take network captures of the entire network traffic of the DeltaV network.
+
+These network captures and some knowledge of the normal system operation were all we had.
+
+All information we got, we got by inspecting these captures, building hypothesis and implementing tooling to verify these assumptions.
+
+Definitely we will not have interpreted everything correct and we'll probably do a lot of updating of this page.
+
+Due to this uncertainty we are only implementing a `promiscuous mode` driver, which is able to read ongoing traffic without the ability to actively interact with the system.
+
+=== The Wrapper Protocol
+
+All communication seems to be done using the `UDP` protocol on port `18507`.
+
+When working with the dumps it seems that this version of the DeltaV protocol was implemented by wrapping another protocol within a thin wrapper protocol.
+We have seen this for almost all other industrial controller types.
+We are hereby assuming that the inner protocol is the version of the DeltaV protocol, which is used for serial communication.
+
+The general structure of such a wrapper packet seems to look like this:
+
+[packetdiag,deltav-wrapper-packet,svg]
+....
+{
+ colwidth = 32
+
+ * Header\n(Constant = 0xFACE) [len = 16]
+ * Payload Length [len = 16]
+ * Type [len = 16]
+ * Message Id [len = 16]
+ * Sender Id [len = 16]
+ * Timestamp [len = 24]
+ * 0x80/0x00 [len = 8]
+ * 0x04 [len = 8]
+ * 0x00 [len = 8]
+ * Payload [len = ?]
+ * Checksum [len = 16]
+}
+....
+
+After the fixed header of `0xFACE` comes a short value providing the `Payload Length`.
+
+After the payload probably comes the message type.
+Here we have observed the internal structure of packets with the same type to be very similar, so we're quite sure this is a type.
+
+The `Message Id` seems to be a counter existing for every communication between two partners, which is incremented for every packet sent to the other partner.
+
+We have observed every unit to have a unique `Sender Id`, however a controller has been seen to have a differing id when communicating with a different operator system.
+What we did notice however, was that controllers usually had numerical ids while the OSes had hexadecimal letters.
+So an id of `0x0002` would probably imply a controller and an id of `0x000d` would imply an operator system.
+But we could be wrong with this assumption and this just being a result of convention.
+
+The 3 bytes after the id seem to relate to a timestamp.
+Inspecting the packets and correlating this to the timestamps in our packet captures, lead us to the assumption that this timestamp uses the first 14 bits for encoding seconds and the last 10 bits for encoding the sub-second fraction.
+While a 3 byte timestamp is only able to measure a 10 minute time-slot and is probably not usable for absolute time measuring, it might be useful to measure transfer times.
+For this a 4 byte value would have been a waste of network capacity and a 2 byte value wouldn't be able to measure up to 16 seconds, which might be too short when taking into account packet resending and network timeouts.
+So for now we are assuming this format is used.
+
+The following 3 bytes seem to have a constant value of `0x800400` for most packets, except the ones with a type of `0x03` and `0x04`.
+For these two types the value seems to be `0x004400`. Here we currently can't make an assumption on the meaning of these fields.
+However as the `0x003` and `0x004` seem to be the first packets used for establishing the connection between the OS and the controller, these could somehow relate to the connection state.
+
+After these mysterious 3 bytes comes the actual payload of the packet.
+The details of these will be discussed later in this document.
+
+At the end comes a short value that seems to be a completely different value for every packet.
+As the message id is incremented every time, we are assuming this is a simple checksum.
+However we currently have no idea on how this is calculated.
+
+UDP being connectionless the DeltaV network protocol seems to require acknowledging.
+This is done by sending a packet back to the originator, but with a length of `0x0000` and the same `type` and mesasge-id`
+
+=== High Level View of the Protocol
+
+In this section we'll describe the general structure of how the communication looks like - which message types are sent when and in which sequence.
+
+==== Connecting an OS to a Controller
+
+[seqdiag,deltav-connect]
+....
+{
+ edge_length = 400;
+ span_height = 18;
+ default_fontsize = 12;
+ activation = none;
+
+ OS -> Controller [label = "Type 0x0003 (Connection Request)"];
+ OS <- Controller [label = "Type 0x0004 (Connection Response)"];
+
+ OS -> Controller [label = "Type 0x0002 Subtype 0x0501 (Version Information)"];
+ OS <-- Controller [label = "Ack"];
+
+ OS <- Controller [label = "Type 0x0002 Subtype 0x0502 (Version Information)"];
+ OS --> Controller [label = "Ack"];
+}
+....
+
+==== Regular sync
+
+It seems that every 15 seconds two packets are exchanged.
+
+The type of these is always `0x0006`.
+
+One thing that is quite obvious, is that these are the only messages, for which the message id doesn't seem to be incremented.
+So these messages have the exact same id as the following request being sent out.
+
+We are assuming that these are sort of heartbeat messages and additionally sync the message ids so the remote could see if it lost messages in the last 15 seconds.
+
+But that is just an assumption.
+
+[seqdiag,deltav-sync]
+....
+{
+ edge_length = 400;
+ span_height = 18;
+ default_fontsize = 12;
+ activation = none;
+
+ OS <- Controller [label = "Type 0x0006 (Sync)"];
+ OS --> Controller [label = "Type 0x0006 (Sync)"];
+}
+....
+
+==== Data changes in the Controller
+
+In general it seems as if all sub-types regarding normal data changes start with `0x04`.
+
+If the value of a subscribed value changes in the controller, a message type `0x0002` with sub-type `0x0403` is sent.
+
+[seqdiag,deltav-data]
+....
+{
+ edge_length = 400;
+ span_height = 18;
+ default_fontsize = 12;
+ activation = none;
+
+ OS <- Controller [label = "Type 0x0002 Subtype 0x0403 (...)"];
+ OS --> Controller [label = "Ack"];
+}
+....
+
+==== Alarms in the Controller
+
+In general it seems as if all sub-types regarding events and alarms start with `0x03`.
+
+[seqdiag,deltav-alarm]
+....
+{
+ edge_length = 400;
+ span_height = 18;
+ default_fontsize = 12;
+ activation = none;
+
+ OS <- Controller [label = "Type 0x0002 Subtype 0x030? (...)"];
+ OS --> Controller [label = "Ack"];
+}
+....
+
+
+
diff --git a/src/site/asciidoc/protocols/index.adoc b/src/site/asciidoc/protocols/ethernet-ip/index.adoc
similarity index 75%
copy from src/site/asciidoc/protocols/index.adoc
copy to src/site/asciidoc/protocols/ethernet-ip/index.adoc
index 8bdf917..f23ac6f 100644
--- a/src/site/asciidoc/protocols/index.adoc
+++ b/src/site/asciidoc/protocols/ethernet-ip/index.adoc
@@ -15,23 +15,16 @@
// limitations under the License.
//
-== Protocols
+== EtherNet/IP
-- link:modbus/index.html[Modbus]
-- link:opc-ua/index.html[OPC-UA]
-- link:s7/index.html[S7]
+Introduction
=== Links
-Apache 2.0 licensed JNI library for accessing raw IPv4 and IPv6 sockets. Might be the ideal starting point for implementing protocols below TCP & UDP.
-https://www.savarese.org/software/rocksaw/
-
-Links to different Wireshark captures: https://github.com/automayt/ICS-pcap
-
-==== Ethernet/IP
-
As of November 2008, The EtherNet/IP Specification consists of three parts: The Common Industrial
Protocol (Volume 1 of the CIP Networks Library), the EtherNet/IP Adaptation of CIP (Volume 2), and the
Integration of Modbus® Devices into a CIP Architecture (Volume 7).
Order Form for the SPEC ($1000) https://secure.odva.org/forms/spec-vendor-id-order-form.htm
+
+
diff --git a/src/site/asciidoc/protocols/features.adoc b/src/site/asciidoc/protocols/features.adoc
index e2c114e..7c60b78 100644
--- a/src/site/asciidoc/protocols/features.adoc
+++ b/src/site/asciidoc/protocols/features.adoc
@@ -21,35 +21,53 @@
The following table contains a list of operations and the protocols that support them:
|===
-|Protocol |Read Single Address Value |Read Multiple Address Values |Write Single Address Value |Write Multiple Address Value
+|Protocol |Read Single Address Value |Read Multiple Address Values |Write Single Address Value |Write Multiple Address Value|Subscribe to Value changes |Subscribe to PLC Events/Alarms
-|S7
-|icon:check[role="green"]
+|ADS
|icon:check[role="green"]
|icon:check[role="green"]
-|icon:exclamation[role="yellow"]
-
-|Beckhoff ADS
-|icon:check[role="green"]
|icon:check[role="green"]
|icon:check[role="green"]
|icon:check[role="green"]
+|icon:question[role="red"]
+
+|DeltaV
+|icon:question[role="red"]
+|icon:question[role="red"]
+|icon:question[role="red"]
+|icon:question[role="red"]
+|icon:question[role="red"]
+|icon:question[role="red"]
+
+|EtherNet/IP
+|icon:question[role="red"]
+|icon:question[role="red"]
+|icon:question[role="red"]
+|icon:question[role="red"]
+|icon:question[role="red"]
+|icon:question[role="red"]
|Modbus
|icon:question[role="red"]
|icon:question[role="red"]
|icon:question[role="red"]
|icon:question[role="red"]
+|icon:question[role="red"]
+|icon:question[role="red"]
|OPC-UA
|icon:question[role="red"]
|icon:question[role="red"]
|icon:question[role="red"]
|icon:question[role="red"]
-
-|IEC 60870-5-104
|icon:question[role="red"]
|icon:question[role="red"]
+
+|S7
+|icon:check[role="green"]
+|icon:check[role="green"]
+|icon:check[role="green"]
+|icon:exclamation[role="yellow"]
|icon:question[role="red"]
|icon:question[role="red"]
|===
diff --git a/src/site/asciidoc/protocols/index.adoc b/src/site/asciidoc/protocols/index.adoc
index 8bdf917..07ba578 100644
--- a/src/site/asciidoc/protocols/index.adoc
+++ b/src/site/asciidoc/protocols/index.adoc
@@ -17,6 +17,9 @@
== Protocols
+- link:ads/index.html[DeltaV]
+- link:delta-v/index.html[DeltaV]
+- link:ethernet-ip/index.html[EtherNet/IP]
- link:modbus/index.html[Modbus]
- link:opc-ua/index.html[OPC-UA]
- link:s7/index.html[S7]
@@ -27,11 +30,3 @@ Apache 2.0 licensed JNI library for accessing raw IPv4 and IPv6 sockets. Might b
https://www.savarese.org/software/rocksaw/
Links to different Wireshark captures: https://github.com/automayt/ICS-pcap
-
-==== Ethernet/IP
-
-As of November 2008, The EtherNet/IP Specification consists of three parts: The Common Industrial
-Protocol (Volume 1 of the CIP Networks Library), the EtherNet/IP Adaptation of CIP (Volume 2), and the
-Integration of Modbus® Devices into a CIP Architecture (Volume 7).
-
-Order Form for the SPEC ($1000) https://secure.odva.org/forms/spec-vendor-id-order-form.htm
diff --git a/src/site/site.xml b/src/site/site.xml
index 1b071c0..472490e 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -111,9 +111,12 @@
</menu>
<menu name="Protocols">
<item name="Features" href="protocols/features.html"/>
+ <item name="ADS" href="protocols/ads/index.html"/>
+ <item name="DelataV" href="protocols/delta-v/index.html"/>
+ <item name="EtherNet/IP" href="protocols/ethernet-ip/index.html"/>
<item name="Modbus" href="protocols/modbus/index.html"/>
<item name="OPC-UA" href="protocols/opc-ua/index.html"/>
- <item name="S7/Profinet" href="protocols/s7/index.html"/>
+ <item name="S7" href="protocols/s7/index.html"/>
</menu>
<menu name="Reports" ref="reports" inherit="bottom"/>
<menu name="Apache" inherit="bottom">