.. _user/protocols/s7:

******************
Siemens SIMATIC S7
******************

Overview
========

The Simatic S7 is a product line of PLCs (S7-200, S7-300, S7-400, S7-1200, S7-1500)
by Siemens that are widely used in industrial automation.
The S7 is capable of connecting several sensors and actuators through digital or
analog IOs which can be modular extended.

The S7 PLC can be projected and programmed with STEP7 (TIA Portal) software from Siemens.

The read and write access to data on the PLC can be realized through the S7 Communication Services
based on ISO-on-TCP (RFC1006). In this case the PLC acts as a server allowing communication partners
to access PLC data without the need of projecting the incoming connections during PLC programming.

.. important::
  To activate the S7 Communication Services you need to enable PUT/GET access in PLC Settings!
  You should keep in mind that this opens up the controller access by other applications as well.

  .. figure:: ../../resources/s7_put_get_access.PNG

.. _user/protocols/s7_device_configuration:

Configuring the connection
==========================

.. important::
  The S7 protocol driver behaves differently from other protocol drivers when
  polling, because it only allows a single polling interval to be set for all
  mappings. The reason for this is that the driver optimizes the request as it
  groups multiple readings into as few block reads as possible. For this reason
  the interval is set in the connection details, and not in the mappings for this
  protocol. If multiple different polling rates are required, you should consider
  using multiple commissioning files. Support for different polling rates in a
  single commissioning file may be added in the future.

.. _user/protocols/s7_connection:

.. include:: ../protocolSchemas/S7Connection.rst

Hardware specific values
------------------------

.. table:: Hardware specific values for rack and slot

    +---------+-------+---------------------+
    | CPU     |  Rack | Slot                |
    +=========+=======+=====================+
    | S7-300  |  0    | 2                   |
    +---------+-------+---------------------+
    | S7-400  |  see hardware configuration.|
    +---------+-------+---------------------+
    | WinAC   |  see hardware configuration.|
    +---------+-------+---------------------+
    | S7-1200 |  0    | 1                   |
    +---------+-------+---------------------+
    | S7-1500 |  0    | 1                   |
    +---------+-------+---------------------+

.. _user/protocols/s7_endpoint:

.. include:: ../protocolSchemas/S7Endpoint.rst

The address of a PLC variable is a string built like this:

``<data block number>,<memory area><data type><byte offset>.<bit position>.<array length>``

<data block number>
  Name of the data block the value is stored in e.g. DB10. Only use this parameter if your value is part of a data block.
<memory area>
  Memory area where the value is stored. Must not be defined if target is a data block!

.. table:: Memory areas

    +--------------------+-----------------+
    | Memory area        | Address symbol  |
    +====================+=================+
    | input              |  I              |
    +--------------------+-----------------+
    | peripheral input   |  PI             |
    +--------------------+-----------------+
    | output             |  Q              |
    +--------------------+-----------------+
    | peripheral output  |  PQ             |
    +--------------------+-----------------+
    | marker             |  M              |
    +--------------------+-----------------+
    | counter            |  C              |
    +--------------------+-----------------+
    | timer              |  T              |
    +--------------------+-----------------+

<data type>
  Data type of the addressed value. Data type "string" can only be used in data blocks.

.. table:: Data types

    +--------------------------------+--------------------------+
    | Data type                      |  Address symbol          |
    +================================+==========================+
    | bit                            |  X (or empty)            |
    +--------------------------------+--------------------------+
    | byte                           |  B                       |
    +--------------------------------+--------------------------+
    | char                           |  C                       |
    +--------------------------------+--------------------------+
    | word                           |  W                       |
    +--------------------------------+--------------------------+
    | int16                          |  I                       |
    +--------------------------------+--------------------------+
    | dword                          |  DW                      |
    +--------------------------------+--------------------------+
    | int32                          |  DI                      |
    +--------------------------------+--------------------------+
    | real                           |  R                       |
    +--------------------------------+--------------------------+
    | int64                          |  LI (S7-1200/1500 only)  |
    +--------------------------------+--------------------------+
    | lreal                          |  LR (S7-1200/1500 only)  |
    +--------------------------------+--------------------------+
    | string                         |  S (only in data blocks) |
    +--------------------------------+--------------------------+
    | date_and_time                  |  DT                      |
    +--------------------------------+--------------------------+
    | date_and_time in UTC           |  DTZ                     |
    +--------------------------------+--------------------------+
    | date_and_time (12 byte)        |  DTL (S7-1200/1500 only) |
    +--------------------------------+--------------------------+
    | date_and_time in UTC (12 byte) |  DTLZ (S7-1200/1500 only)|
    +--------------------------------+--------------------------+

<byte offset>
  The offset of the byte to address.
<bit position>
  To address a bit position place it here. In case you are addressing a string data type this parameter is the string length.
<array length>
  To address multiple values in a row define the length of the array here.

The minimum information any address must contain is <data block number> or <memory area>, <data type> and <byte offset>.
<bit position> is only necessary for addressing bits. <array length> is always optional.

Address Examples:
  - MR4             // REAL starting at marker byte 4 (MD4 in STEP 7)
  - M32.2           // Bit at marker byte 32 bit 2
  - PIW30           // WORD starting at peripheral input byte 30
  - PII30           // INT starting at peripheral input byte 30
  - DB1,R0.20       // Array of 20 REAL values in DB1 starting at byte 0
  - DB1,R4          // Single REAL value
  - DB1,REAL8       // Another single REAL value
  - DB1,I12.2       // Two INT value array
  - DB10,INT6       // DB10.DBW6 as INT
  - DB10,I6         // same as above
  - DB10,I6.2       // DB10.DBW6 and DB10.DBW8 in an array with length 2
  - DB10,S20.30     // String at offset 20 with length of 30 (actual array length 32 due to format of String type, length byte will be read/written)
  - DB10,S20.30.3   // Array of 3 strings at offset 20, each with length of 30 (actual array length 32 due to format of String type, length byte will be read/written)
  - DB10,C22.30     // Character array at offset 22 with length of 30 (best to not use this with strings as length byte is ignored)
  - DB10,X6.0.1     // Bit at DB10.DBX6.0 as array with length 1
  - DB10,DT0        // Date and time
  - DB10,DTZ0       // Date and time in UTC

.. important::
  To access data from data blocks you need to disable "Optimized Block Access" in data block attributes!

 .. figure:: ../../resources/s7_data_block_attributes.PNG


Example Commissioning File:
===========================

Download: :download:`s7-example.yml`

.. literalinclude:: s7-example.yml
  :language: yaml
  :linenos:

Output Format on Write
----------------------
When data is written to a S7 endpoint, you will get the result of the operation over the **/res** topic like this:

.. code:: json

  {
    "id": 29194,
    "timestamp":1629351968526,
    "result": 0
  }

Output Format on Read
---------------------

If data is read from Siemens SIMATIC S7 the output will be provided as JSON
object, with the actual S7 data in the property ``value``, and the reception
timestamp in the property ``timestamp``.

.. code:: json

  {
    "value": "<value>",
    "timestamp": "<msSinceEpoch>"
  }

Input Format on Write
---------------------

If data is written to Siemens SIMATIC S7 it must be provided as JSON object,
with the actual S7 data in the property ``value``:

.. code:: json

  { "value": "<value>" }

Additionally an ``id`` property can be provided in the published message
to use as a correlation value for the response of the write operation.

.. code:: json

  { "value": "<value>", "id": "<your correlation id>" }

The result of a write operation is published on the ``/res`` topic for the Endpoint
see :ref:`user/services/structure/resources/endpoint/results`
for more details on writing operations