Siemens S7

Pull

Synopsis

Director reads one Siemens S7 PLC: the data blocks, the process image of the inputs and the outputs, the markers (bit memory), the timers, and the counters of an S7-300, S7-400, S7-1200, or S7-1500, or of a PLC that speaks their protocol, S7comm. A LOGO! 8 or an S7-200 behind its communication processor (CP) is reached by TSAP. Nothing is installed on the PLC or beside it: Director connects as an HMI or a programming device would, over ISO-on-TCP (port 102), sends read requests, and writes what comes back as ECS records. It never writes to the PLC.

One device, one PLC. Monitoring twelve PLCs takes twelve devices. The device holds one connection to its PLC and sends its requests over it one at a time. A PLC has few connections to spare: an S7-300's CPU has a handful.

What to read is declared by datasets. A PLC's memory has no names a client can read: an address means something only to whoever wrote the program. So the device's datasets are your own, each a table of typed fields read on the dataset's own interval. For example, the line's speed, a real at DB10.DBD0; whether it runs, the bit DB10.DBX8.0; or the recipe, a string of 20 characters from DB10.DBB18. Addresses are written as STEP 7 and TIA Portal write them.

The device dials the PLC and binds no port, so any number of S7 devices, on one Director or several, can name port 102, and none of them blocks a listener. One Director owns each device: two would read every field twice, and the PLC would spend two of its connections on it.

note

The Siemens S7 device needs Director 2.3.1 or later. With no Director or cluster at that version selected, the wizard shows Siemens S7 devices are unavailable on directors or clusters below version 2.3.1 and the device cannot be created.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: s7
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    port: <numeric>
    rack: <numeric>
    slot: <numeric>
    connection_type: <string>
    remote_tsap: <string|numeric>
    local_tsap: <string|numeric>
    timeout: <numeric>
    max_items_per_request: <numeric>
  definitions: <definition[]>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y	-	Unique numeric identifier
name	Y	-	Device name
description	N	-	Optional description
type	Y	-	Must be s7
tags	N	-	Optional tags
pipelines	N	-	Optional pre-processor pipelines
status	N	true	Enable/disable the device

Connection

Field	Required	Default	Description
address	Y	-	Host name or IP address of the PLC, or of its CP. An IPv6 address can be written as it is or in brackets. A wildcard address (0.0.0.0, ::) is refused, and so is a port written into the address: the port is its own field.
port	N	102	The PLC's ISO-on-TCP port, from 1 to 65535. Every S7 CPU and CP listens on 102.
rack	N	0	The CPU's rack, from 0 to 7
slot	N	1	The CPU's slot, from 0 to 31: 1 (or 0) for an S7-1200 or S7-1500, 2 for an S7-300, and for an S7-400 the slot the CPU is plugged into
connection_type	N	pg	What the device connects as. The PLC keeps a share of its connections for each type: pg (a programming device), op (an operator panel), or basic (S7 basic communication). PD is also accepted, and read as pg.
remote_tsap	N	-	The PLC's TSAP, for a PLC addressed by TSAP rather than by rack and slot. See TSAPs. Two bytes of hexadecimal (02.00, 0x0200, or 0200) or a number from 0 to 65535. In YAML, quote the hexadecimal forms (remote_tsap: "02.00"): unquoted, 02.00 is read as the number 2, a different TSAP. With it, rack, slot, and connection_type are not used, and a device that names them says so in its log.
local_tsap	N	01.00	The device's TSAP, written as remote_tsap is. Only with remote_tsap.
timeout	N	10	Seconds a connect and each request wait for their answer, from 1 to 300
max_items_per_request	N	20	How many fields one request reads at most, from 1 to 20, for a PLC that takes fewer. The PDU size the PLC agrees to may make it fewer still. See Requests.

A device that fails these checks does not start, and its state is Configuration error; the message names the field. Examples are a missing or wildcard address, a rack or a slot out of range, a TSAP that is not one, a local_tsap without a remote_tsap, or a value that is not a number. A number is read whole: NaN, an infinity, or a fraction is refused, never converted.

Connection

Connecting

The device connects in three steps:

1. It opens a TCP connection to the PLC.
2. It asks for an ISO connection (COTP, ISO 8073 class 0) from its own TSAP to the PLC's.
3. It sets up S7 communication, where the two agree on the size of a PDU. The device asks for 960 bytes. An S7-300 or S7-1200 answers 240, and an S7-400 480. Every request and its answer are cut to the size agreed.

The connection is held from one reading to the next.

Rack and Slot

For an S7-300, S7-400, S7-1200, or S7-1500, the PLC's TSAP is made of the connection type and the CPU's rack and slot: the type in its high byte, and the rack (three bits) and the slot (five bits) in its low byte. A programming device's connection to rack 0, slot 2 is 01.02; an operator panel's to rack 0, slot 1 is 02.01. The device's own TSAP is 01.00.

TSAPs

A PLC whose connections are configured by TSAP, such as a LOGO! 8 or an S7-200 behind a CP 243-1, names them in its own tools. In LOGO!Soft Comfort, the server connection names the LOGO!'s TSAP, which is the device's remote_tsap (for example 02.00), and the TSAP it accepts a connection from, which is the device's local_tsap (for example 01.00).

PUT/GET on an S7-1200 or S7-1500

An S7-1200 or S7-1500 answers a client like this device only when Permit access with PUT/GET communication from remote partner is ticked in the CPU's protection settings. It reads only data blocks whose Optimized block access is turned off: an optimized data block has no addresses.

warning

PUT/GET access is not limited to this device or to reading. Once it is permitted, any client that can reach the PLC may read and write its data, whatever access the device itself uses. Keep the PLC on a network that only trusted hosts can reach, and check the CPU's manual for the protection settings its firmware also requires.

A PLC that refuses for either reason still answers, so the device reaches it. The device names the refusal and what to change, and its state is Configuration error while the PLC refuses every field (see Device State).

Refused and Dropped Connections

• A connection the PLC turns down is a Connection error. A PLC answers a connection request with a disconnect, or closes the TCP connection, when the TSAP names no CPU or no connection of that type is free. The message says what to check: the rack and the slot (or the TSAPs), the connection type, and whether the PLC has a free connection of that type.
• A connection the PLC closed between readings is opened again at once, and the reading is made. A PLC may drop a connection that has been idle; when the first request of a reading fails on a connection that had answered before, the device connects again. A timeout is not treated this way: a PLC that does not answer is not asked again.

Datasets

The device's definitions are its datasets. In the console they are the datasets and profiles assigned to the device in its Data collection; see Datasets and Profiles. In a configuration file each dataset is a definition named s7_field_collector, the device's one dataset type:

Dataset	Definition	Definition ID	Kind	One record per
field	s7_field_collector	19150	metric	reading of the dataset's table

• Any number of datasets. Each dataset is a table of its own, read on its own interval, so a device reads as many as are assigned: for example, the line's values every 10 seconds and its alarm bits every 5.
• Pipelines. A dataset's records enter the pre-processing pipeline the dataset selects, or the device's when it selects none, so two datasets on one device can reach two pipelines.
• Nothing assigned is allowed. The device then only checks, every minute, that its PLC takes a connection, so its connection state stays current, and writes nothing.
• A dataset that cannot be read is left out, with a warning in the device's log that names it and says why: a table that is not a name, a field whose address or type is not valid, or a field named twice. The rest of the device runs. With every dataset assigned to it left out, the device stops with Configuration error, since running on it would report Connected while reading nothing.

Dataset Properties

Field	Required	Default	Description
table	Y	-	The name the dataset's fields sit under in a record (see Records): letters, digits, and underscores, at most 64, not starting with a digit. table is reserved.
interval	N	60	Seconds between readings, 1 or more
labels	N	-	An object of names and values written on every record as ECS labels. At most 32; a name is letters, digits, underscores, and hyphens, and a value at most 256 characters.
pipeline_name	N	the device's	The pre-processing pipeline the dataset's records enter

Fields

A dataset's inputs are its fields, at most 512. Each needs a name, unique in the table: letters, digits, and underscores, at most 64, not starting with a digit.

Field	Required	Description
address	Y	Where the field is, as STEP 7 and TIA Portal write it: in English or German mnemonics, in any case, with or without TIA Portal's %. See Addresses.
type	N	What the field's bytes are read as, which has to fit the address. Left out, the address's width gives it: bool, byte, word, dword, timer, or counter. See Types.
length	N*	A string's: the most characters it holds, the n of its STRING[n], from 1 to 254. Refused for any other type.

* Required for a string.

Addresses

Address	What it names
DB1.DBX0.1, DB1.DBB0, DB1.DBW0, DB1.DBD0	A data block's bit, byte, word, and double word
I0.1, IB0, IW0, ID0 (E in German)	The process image of the inputs
Q0.1, QB0, QW0, QD0 (A in German)	The process image of the outputs
M0.1, MB0, MW0, MD0	The markers
T1	A timer
C1 (Z in German)	A counter

A bit can also be written with an X, as IEC 61131-3 writes one: IX0.1. Data blocks are numbered from 1 to 65535, timers and counters from 0 to 65535, and a byte is 2097151 at most, the last a request can address.

Types

A field's type has to fit its address, as a TIA Portal tag's data type has to fit its absolute address. A misfit is refused, and the error names the address that would hold the type: MW10 is a word, and type real is a double word: write it as MD10.

Type	Address	Written as
bool	A bit	true or false
byte, usint, sint	A byte	A number
char	A byte	Text of one character
word, uint, int	A word	A number
s5time	A word	Milliseconds
date	A word	Text, YYYY-MM-DD
dword, udint, dint	A double word	A number
real	A double word	A number, the shortest decimal that reads back as the REAL
time	A double word	Milliseconds, signed
time_of_day (tod)	A double word	Text, HH:MM:SS.mmm
lword, ulint, lint, lreal	A byte, the first of eight	A number
date_and_time (dt)	A byte, the first of eight	Text, YYYY-MM-DDTHH:MM:SS.mmm, with no zone
dtl	A byte, the first of twelve	Text, YYYY-MM-DDTHH:MM:SS.nnnnnnnnn, with no zone
string	A byte, the first of 2 + length	Text, its characters read as ISO 8859-1
timer	A timer, T1	Its time, in milliseconds
counter	A counter, C1	Its count, 0 to 999

Any type longer than a double word is read from its first byte, so its address is a B address. Dates and times are written as text with no zone, because the PLC's clock names none.

Requests

A field is one item of a read request, so a field the PLC refuses is the only one left out. The items are packed into requests in the order the fields are declared, each request holding as many as fit:

• at most max_items_per_request, and never more than 20;
• within the PDU size agreed, for the request, whose items take 12 bytes each, and for its answer, whose items take their data and 4 bytes each, padded to an even length.

With 240-byte PDUs that is 19 fields of up to four bytes a request; with 960-byte PDUs, 20. A value longer than an answer holds, such as a long string on a PLC with 240-byte PDUs, is read in parts and joined.

The requests are planned for the PDU size of the current connection, and planned again when a new connection agrees to another size; the device logs the size agreed when it changes. Adjacent fields are not merged into one item: merging would make a field the PLC refuses take its neighbors with it.

Readings

• At start the device reads every dataset once.
• Each dataset on its own interval after that, from the start of one reading to the start of the next.
• Datasets due at the same time are read one after the other over the one connection. A reading that takes longer than its interval delays the next, which starts a moment after it ends.

Records

Every record is one ECS 8.11 document with the following fields:

Field	Value
@timestamp	The reading's time
ecs.version	8.11.0
event.module	s7
event.dataset	s7.field
event.kind	metric
event.category, event.type	host, info
observer.name	The device's name in the console
observer.hostname	The Director's host name
observer.vendor, observer.product	VirtualMetric, Siemens S7
server.address, server.port	The address the device is configured with, and its port
server.ip	The address, when it is an IP address
network.protocol, network.transport	s7comm, tcp
labels.<name>	The dataset's labels, when it has any
s7.field.table	The dataset's table
s7.field.<table>.<field>	The value of each field that was read, as Types writes it

The values sit under the table's name, so two tables can name a field alike with different types without one mapping conflicting with the other.

A field the PLC refused, or whose bytes hold no value of its type (a real that is not a number, a date_and_time that is no date), is absent from that record. The device's log says so once, with the reason, for as long as it lasts. A record with no field is not written.

Device State

The connection state follows the PLC:

• Connected while the PLC answers any field of the device's datasets. A device with no dataset assigned is Connected while its PLC takes a connection: the TCP, ISO, and S7 setup steps of Connecting, after which the connection is closed at once.
• Configuration error while the PLC answers but refuses every field of every dataset. A PLC whose PUT/GET access is off, or whose data blocks are optimized, does this; the message names the refusal and what to change. A configuration that cannot run is a Configuration error too (see Configuration).
• Connection error while the PLC cannot be connected to, turns the connection down, or none of the datasets could be read at its latest reading.

The state follows every dataset's latest reading, not only the datasets of the reading in progress. A record that could not be written, or a failure inside one dataset, affects that dataset alone and does not change the device's state.

note

The Siemens S7 device is not simulated. A dataset's records are the values of your own fields, a shape a generated sample cannot stand in for.

Console

In the console, go to Fleet Management > Devices > Siemens S7, listed under Protocols beside Modbus and Prometheus, and click Add new device. The wizard's steps are:

1. General settings, as on every device.
2. Connection settings: Address, Port, and PLC addressing.
   • Rack and slot shows Rack, Slot, and Connection type (PG (programming device), OP (operator panel), or S7 basic communication).
   • TSAP shows PLC TSAP and Device TSAP (Optional).
3. Advanced settings: Timeout and Maximum fields per request.
4. Data collection: the S7 datasets the device reads.
5. Review and create.

The device's page has the same tabs, and Data collection.

An S7 dataset is created in Fleet Management > Datasets as the type S7 Fields; see Management. Its settings are Table name, Interval (Optional) in seconds, the Fields list (Field, Address, Type, and Length for a String), the labels, and the pre-processing pipeline. Types are shown in TIA Portal's spelling, such as Real, DInt, and Date_And_Time, and From the address leaves the type to the address's width.

Examples

S7-1500 by Rack and Slot

Reading the packaging line's values every 10 seconds and its alarm bits every 5, from an S7-1500 at rack 0, slot 1, connected as an operator panel...

- id: 519100191 name: packaging-line-plc description: S7-1500 of the packaging line type: s7 status: true properties: address: "192.0.2.50" rack: 0 slot: 1 connection_type: op timeout: 10 definitions: - name: s7_field_collector status: true properties: table: line interval: 10 labels: machine: packer-1 location: hall-b inputs: - name: speed properties: { address: DB10.DBD0, type: real } - name: packs properties: { address: DB10.DBD4, type: dint } - name: running properties: { address: DB10.DBX8.0, type: bool } - name: total_energy properties: { address: DB10.DBB10, type: lreal } - name: recipe properties: { address: DB10.DBB18, type: string, length: 20 } - name: last_stop properties: { address: DB10.DBB40, type: date_and_time } - name: s7_field_collector status: true properties: table: alarms interval: 5 inputs: - name: door_open properties: { address: M100.0 } - name: overtemperature properties: { address: M100.1 } - name: alarm_word properties: { address: MW102, type: word }

S7-300 Process Image, Timer, and Counter

Reading an S7-300's inputs and outputs, a timer, and a counter every 30 seconds. Its CPU is in slot 2...

- id: 519100192 name: boiler-house-plc description: S7-300 of the boiler house type: s7 status: true properties: address: "plc-boiler.plant.example.com" rack: 0 slot: 2 connection_type: pg timeout: 5 definitions: - name: s7_field_collector status: true properties: table: boiler interval: 30 inputs: - name: inputs_0 properties: { address: IB0 } - name: burner_on properties: { address: Q4.0 } - name: flow_raw properties: { address: IW256, type: int } - name: purge_timer properties: { address: T5 } - name: starts properties: { address: C3 }

LOGO! 8 by TSAP

Reading a LOGO! 8 addressed by the TSAPs its server connection names in LOGO!Soft Comfort. A LOGO!'s V memory is data block 1...

- id: 519100193 name: pump-station-logo description: LOGO! 8 of the pump station type: s7 status: true properties: address: "192.0.2.60" remote_tsap: "02.00" local_tsap: "01.00" definitions: - name: s7_field_collector status: true properties: table: pumps interval: 15 inputs: - name: pump_1_on properties: { address: DB1.DBX0.0 } - name: level properties: { address: DB1.DBW2, type: int }