//
//  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
//
//      https://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.
//
:imagesdir: ../../images/

== S7 Communication

When communicating with S7 Devices there is a whole family of protocols, that can be used.
In general you can divide them into `Profinet` protocols and `S7 Comm` protocols.
The later are far simpler in structure, but also far less documented.
The `S7 Comm` protocols are generally split up into two flavours: The classic `S7 Comm` and a newer version unofficially called `S7 Comm Plus`.

=== Overview of the Protocols

[ditaa,protocols-s7-osi]
....
                    :                                                       :             : implemented               :
                    :                                                       :             :      |                    :
                    :                       Profinet                        :             :      | S7 Protocol        :
                    :                                                       :             :      V                    :
- - - - - - - - - - +-------------+-------------+-------------+-------------+-------------+-------------+-------------+ - -
                    |c0B0         |c0B0         |c0B0         |c0B0         |c05A         |c0BA         |c0BA         |
 Application        |             |             |             |             |             |             |             |
 Layer              |             |             |             |             |             |             |             |
                    |             |             |             |             |             |             |             |
                    | Profinet IO | Profinet IO | Profinet CBA| Profinet CBA|             |             |             |
- - - - - - - - - - |   RT / IRT  |             |             |      RT     |             |             |             | - -
                    |             |             |             |             |             |             |             |
 Presentation       |             |             |             |             |             |             |             |
 Layer              |             |             |             |             |     S7      |     S7      |     S7      |
                    |             |             |             |             |    Comm     |    Comm     |    Comm     |
                    |             |             |             |             |    Plus     |             |             |
- - - - - - - - - - |             +-------------+-------------+             |             |             |             | - -
                    |             |cAAA         |cAAA         |             |             |             |             |
 Session            |             |             |             |             |             |             |             |
 Layer              |             |     RPC     |    DCOM     |             |             |             |             |
                    |             |             |             |             |             |             |             |
                    |             |             |             |             |             |             |             |
- - - - - - - - - - |             +-------------+-------------+             +-------------+-------------+-------------+ - -
                    |             |cAAA         |cAAA         |             |cF6F                                     |
                    |             |             |             |             |         ISO Transport Protocol          |
                    |             |             |             |             |                 RFC 905                 |
                    |             |             |             |             | (Class 0)                               |
                    |             |             |             |             +---------------------------+             |
                    |             |             |             |             |cFF6                       |             |
 Transport          |             |             |             |             | ISO on TCP                |             |
 Layer              |             |     UDP     |     TCP     |             |  RFC 1006                 |             |
                    |             |             |             |             +---------------------------+             |
                    |             |             |             |             |cAAA                       |             |
                    |             |             |             |             |     TCP                   |             |
                    |             |             |             |             |                           |     ISO     |
- - - - - - - - - - |             +-------------+-------------+             +---------------------------+   Transport | - -
                    |             | cAAA                      |             |cAAA                       |   Protocol  |
 Network            |             |                           |             |                           |   RFC 905   |
 Layer              |             |            IP             |             |     IP                    |   (Class 4) |
                    |             |                           |             |                           |             |
                    |             |                           |             |                           |             |
- - - - - - - - - - +-------------+---------------------------+-------------+---------------------------+-------------+ - -
                    |cAAA                                                                                             |
 Data Link          |                                                                                                 |
 Layer              |                                                                                                 |
                    |                                                                                                 |
                    |                       Industrial                                                                |
- - - - - - - - - - |                        Ethernet                                                                 | - -
                    |                                                                                                 |
 Physical           |                                                                                                 |
 Layer              |                                                                                                 |
                    |                                                                                                 |
                    |                                                                                                 |
- - - - - - - - - - +-------------------------------------------------------------------------------------------------+ - -
....

=== Protocol Descriptions

|===
|Name |ISO |RFC |Link
|Transmission Control Protocol (TCP) |- | RFC 793 |https://tools.ietf.org/html/rfc793
|ISO on TCP |- | RFC 1006| https://tools.ietf.org/html/rfc1006
|ISO Transport Protocol (Class 4) |ISO DP 8073 | RFC 905 |https://tools.ietf.org/html/rfc905
|S7 Comm (0x32) |- |- |http://gmiru.com/article/s7comm/ http://gmiru.com/article/s7comm-part2/ https://www.eng.tau.ac.il/~yash/jdsfl2014.pdf
|S7 Comm Plus (0x72) |- |- |(Information seems to be invalid or incorrect however) https://opensource-security.de/thesis/MA_Maik_Brueggemann.pdf
|RPC |- | RFC 1057 & RFC 5531 |https://tools.ietf.org/html/rfc1057 https://tools.ietf.org/html/rfc5531
|DCOM |- |- | https://msdn.microsoft.com/library/cc201989.aspx
|===

=== Interaction with an S7 PLC

Currently we are concentrating on implementing the TCP-based variants of the `S7 Comm` and `S7 Comm Plus` protocols.
Both are transferred using `ISO TP` which is wrapped by `ISO on TCP`.
Both protocols require establishing a connection on the `ISO TP` level first.
After the `ISO TP` connection is established, the higher level protocols then establish their connections.
These are then handled by the individual protocol sub-pages:

- link:s7comm.html[S7 Comm (0x32)]
- link:s7comm-plus.html[S7 Comm Plus (0x72)]

The hex-value behind each of these correlates to the first byte used in the protocols messages to indicate the type of protocol.

[seqdiag,s7-interaction]
....
{
    === Connect ===

    Client -> "ISO TP" [label = "Connection Request"]
    Client <- "ISO TP" [label = "Connection Response"]

    === Higher Level Connect ===

    === Higher Level Communication ===

    === Disconnect ===

    Client -> "ISO TP" [label = "Disconnect Request"]

}
....

=== ISO TP Message Types

Even if `ISO TP` defines more types of messages, the ones required for `S7 Comm` or `S7 Comm Plus` are only the following.
Each message is called a `TPDU` (Transport Protocol Data Unit):

- Connection Request TPDU
- Connection Response TPDU
- Data TPDU
- Disconnect Request TPDU

Notice: There is no `Disconnect Response` in `ISO TP: Class 0`.

==== Connection Request TPDU

// len (length of bits - use instead of explicit byte count - requires "*" as first element)
// label
// color / background
// linecolor
// rotate (degrees)
// colheight
// height
// numbered
// label_orientation (vertical, horizontal)
// stacked (no value)
// icon
// shape (box, circle, ...)
[packetdiag,s7-connect-request,svg]
....
{
    colwidth = 32

    // ISO on TCP
    * ISO on TCP Magic Number (0x03) [len = 8, color = "#068D9D"]
    * Reserved (0x00) [len = 8, color = "#068D9D"]
    * Packet Length (including ISO on TCP header) [len = 16, color = "#068D9D"]

    // ISO Transport Protocol
    * ISO TP Header Length\n(excluding length byte) [len = 8, color = "#53599A"]
    * TPDU-Code\n(CR = 0xE0) [len = 4, color = "#AEECEF"]
    * Signal CDT\n(0x00) [len = 4, color = "#53599A"]
    // ISO TP Header (Fixed Part)
    * Destination Reference [len = 16, color = "#53599A"]
    * Source Reference [len = 16, color = "#53599A"]
    * Protocol Class\n(Class 0 = 0x00) [len = 8, color = "#53599A"]

    // ISO TP Header (Variable Part / Parameters)
    * Parameter Code\n(TPDU Size = 0xC0) [len = 8, color = "#53599A"]
    * Parameter Length\n(1 = 0x01) [len = 8, color = "#53599A"]
    * Parameter Value\n(TPDU Size 1024 = 0x0A) [len = 8, color = "#53599A"]

    * Parameter Code\n(Calling TSAP = 0xC1) [len = 8, color = "#53599A"]
    * Parameter Length (2 = 0x02) [len = 8, color = "#53599A"]
    * Device Group\n(PG/PC = 0x01) [len = 8, color = "#53599A"]
    * TSAP Id (0x00) [len = 8, color = "#53599A"]

    * Parameter Code\n(Called TSAP = 0xC2) [len = 8, color = "#53599A"]
    * Parameter Length (2 = 0x02) [len = 8, color = "#53599A"]
    * Device Group\n(Others = 0x03) [len = 8, color = "#53599A"]
    * Rack Number[len = 4, color = "#80DED9"]
    * Slot Number[len = 4, color = "#80DED9"]
}
....

Legend:

- [protocolIsoOnTcp]#ISO on TCP Packet Header#
- [protocolIsoTP]#ISO Transport Protocol Packet Header#
- [protocolId]#Part of the packet that identifies the type of request#
- [protocolParameter]#Variable Parts of the ISO Transport Protocol Packet Header#

==== Connection Response TPDU

The `Connection Response` is identical to the `Connection Request` with the only difference that the `TPDU-Code` has a code of `0xD0`.

==== Data TPDU

// len (length of bits - use instead of explicit byte count - requires "*" as first element)
// label
// color / background
// linecolor
// rotate (degrees)
// colheight
// height
// numbered
// label_orientation (vertical, horizontal)
// stacked (no value)
// icon
// shape (box, circle, ...)
[packetdiag,s7-data,svg]
....
{
    colwidth = 32

    // ISO on TCP
    * ISO on TCP Magic Number (0x03) [len = 8, color = "#068D9D"]
    * Reserved (0x00) [len = 8, color = "#068D9D"]
    * Packet Length (including ISO on TCP header) [len = 16, color = "#068D9D"]

    // ISO Transport Protocol
    * ISO TP Header Length\n(excluding length byte) [len = 8, color = "#53599A"]
    * TPDU-Code\n(DATA = 0xF0) [len = 4, color = "#AEECEF"]
    * Signal CDT\n(0x00) [len = 4, color = "#53599A"]
    * TPDU-NR/EOT [len = 8, color = "#53599A"]

}
....

Legend:

- [protocolIsoOnTcp]#ISO on TCP Packet Header#
- [protocolIsoTP]#ISO Transport Protocol Packet Header#
- [protocolId]#Part of the packet that identifies the type of request#

==== Disconnect Request TPDU

// len (length of bits - use instead of explicit byte count - requires "*" as first element)
// label
// color / background
// linecolor
// rotate (degrees)
// colheight
// height
// numbered
// label_orientation (vertical, horizontal)
// stacked (no value)
// icon
// shape (box, circle, ...)
[packetdiag,s7-disconnect-request,svg]
....
{
    colwidth = 32

    // ISO on TCP
    * ISO on TCP Magic Number (0x03) [len = 8, color = "#068D9D"]
    * Reserved (0x00) [len = 8, color = "#068D9D"]
    * Packet Length (including ISO on TCP header) [len = 16, color = "#068D9D"]

    // ISO Transport Protocol
    * ISO TP Header Length\n(excluding length byte) [len = 8, color = "#53599A"]
    * TPDU-Code\n(DR = 0x80) [len = 4, color = "#AEECEF"]
    * Signal CDT\n(0x00) [len = 4, color = "#53599A"]
    * Destination Reference [len = 16, color = "#53599A"]
    * Source Reference [len = 16, color = "#53599A"]
    * Reason [len = 8, color = "#53599A"]

    // ISO TP Header (Variable Part / Parameters) (Optional)
    * Parameter Code\n(Disconnect Additional Information = 0xE0) [len = 8, color = "#53599A"]
    * Parameter Length\n(1 ... 128) [len = 8, color = "#53599A"]
    * Parameter Data\n(Custom user data) [len = 24, color = "#53599A"]

}
....

Legend:

- [protocolIsoOnTcp]#ISO on TCP Packet Header#
- [protocolIsoTP]#ISO Transport Protocol Packet Header#
- [protocolId]#Part of the packet that identifies the type of request#
- [protocolParameter]#Variable Parts of the ISO Transport Protocol Packet Header#
