Introduction

TS7CommPlusDriver speaks S7CommPlus, the native protocol of the S7-1200 and S7-1500 — the same one TIA Portal uses to program them. Unlike S7 over ISOTCP, it addresses variables by their symbolic path (the name the variable has in the PLC program) instead of a DB number plus a byte offset, so an optimized DB — the default in TIA Portal — can stay optimized.

S7CommPlus ISOTCP
PLCs S7-1200, S7-1500 S7-300/400, S7-1200/1500, S7-200 behind a CP 243-1, LOGO! 7/8
Addressing symbolic: DB4.Var26.v1, MArea.Clock_10Hz absolute: DB1.DBD0, M10.3
Optimized block access may stay on must be turned off
Permit access with PUT/GET not needed needed
Encryption TLS, on by default none
Password login not usable yet — see TLS and certificates –

It does not talk to the S7-300, S7-400, S7-200 or LOGO!, which have no S7CommPlus. Use TISOTCPDriver for those, and also for an S7-1200/1500 when you control the TIA project and would rather address by byte.

One driver talks to one PLC. The driver owns the session; to talk to two PLCs use two communication ports and two drivers, one each.

Required components
  1. A TTCP_UDPPort with Host = PLC IP address, Port = 102 (default) and PortType = ptTCP. See Communication ports.
  2. A TS7CommPlusDriver (unit S7PlusFamily) with CommunicationPort pointing to the port.
  3. The tags (TPLCTagNumber, TPLCBlock, TPLCString, TPLCStruct) with ProtocolDriver pointing to the driver and LongAddress holding the symbolic path (see Addressing).

The fastest way to get to step 3 is the Tag Builder wizard (see below), which reads the variable list from the PLC and creates the tags with the path, the type and the byte swapping already set.

Preparing the PLC

Nothing has to be changed in the program structure: optimized DBs are fine, and PUT/GET stays off. Only two things matter:

  1. IP address configured on the CPU (and reachable from the machine running the application).
  2. Protection level, in the CPU properties → Protection & Security → Access level:
Protection level What the driver can do
Full access (no password) read and write
Read access read only; every write fails
HMI access / No access the connection is refused

Leave the password out: a CPU set to Full access with password needs a login, and the password legitimation of S7CommPlus is not finished in this driver yet (see TLS and certificates).

Driver properties
Property Default Description
CommunicationPort – The TTCP_UDPPort used by the driver.
UseTLS True Encrypts the session. Required by most S7-1200/1500 firmware from TIA Portal V15 on; set it to False only for known legacy V1 firmware.
ReadOnly False When True no write reaches the PLC: every write is answered with ioReadOnlyProtocol. For a screen that must only watch.
ReadSomethingAlways True A scan round that has to read something also refreshes the polled tags that are not due, as long as they fit in the request already going out. Fresh values for no extra round trip.
MaxItemsPerRequest 100 Most items in one read/write request. A bigger batch is split into several requests, so this bounds the request, not the number of tags. Do not raise it blindly: a PLCSim refused 101 items.
MaxTagsPerScan 500 Most tags served in one scan round. Tags beyond it stay due and are served by the next round — nothing is dropped. A whole-DB tag counts as one.
MaxItemsPerSubscription 500 Most items in one subscription (a limit of size, not of count: it depends on how long the LID paths of the tags are).
SubscriptionCycleMs 100 How often the PLC looks for a change on the tags with RefreshTime = 0. Nothing below 100 is accepted (a shorter one is raised to 100).
SubscriptionCreditLimit 10 Notification credit of those subscriptions; renewed automatically while positive.
SubscriptionTimeoutMs 5000 Watchdog: a subscription that stays silent for this long while the session is up was lost and is created again. Never less than 10 cycles; 0 turns it off.
ProgramCheckIntervalMs 10000 How often the driver looks for a download to the PLC (DB list + type modification time) and re-resolves the addresses if it changed. 0 turns it off; below 1000 is raised to 1000.
Password empty PLC password for legitimation. Not usable yet — see TLS and certificates.
Username empty Optional user name for the “new” style legitimation. Leave empty.
ServerCertificate empty Empty accepts whatever certificate the PLC presents. With a value, only that certificate (or one signed by it) is accepted. In the Object Inspector the “…” button loads it from a .pem/.crt/.cer/.der file.
ClientCertificate empty Certificate presented to the PLC when it asks for one (mutual TLS): PEM text, a PEM/PKCS#12 file name, or the base64 of a PKCS#12. Empty: none, the usual case.
ClientCertificatePassword empty Password of the private key or of the PKCS#12 of ClientCertificate.

There is also a read-only PeerCertificate property: the certificate the PLC presented in the last handshake, as base64 of its DER. Copy it into ServerCertificate to trust only that PLC.

Addressing

LongAddress of the tag is the path of the variable, as written in TIA Portal. Two forms reach a DB:

DB4.Var26.v1               // by DB number
BlocoSimbolico_4.Var26.v1  // by the symbolic name of the DB, as in the program

The dots are part of the path: Var26.v1 is a member v1 inside the structure Var26, exactly as in the PLC program. The process areas are named IArea, QArea, MArea, S7Timers and S7Counters, and a tag name may itself contain dots:

MArea.Clock_10Hz
QArea.Motor1_Run
S7Timers.T1

Which tag class to use:

Variable in the PLC Tag class LongAddress
A scalar (Bool, Int, Real, …) TPLCTagNumber DB4.Var26
A STRING TPLCString DB4.Message
An array of a simple type TPLCBlock DB4.Arr
One element of an array TPLCBlock sized to one element, or TPLCTagNumber DB4.Arr[2]
A structure TPLCStruct with one TPLCStructItem per member DB4.MyStruct
A whole DB TPLCStruct DB4
An array of structures TPLCStruct covering the array, members mapped to every index DB4.Arr
One element of an array of structures TPLCStruct of its own DB4.Arr[1]

The TagType of a TPLCTagNumber must match the type the variable has in the PLC, and so must SwapBytes/SwapWords/SwapDWords: the PLC is big-endian, so a 2-byte value needs SwapBytes, a 4-byte one SwapBytes + SwapWords, an 8-byte one all three. The Tag Builder fills these in from the PLC’s own type information; only a tag typed by hand can get them wrong.

A whole DB is not its bytes. Reading the root of a DB returns a small metadata object, not the memory of the DB: a whole-DB TPLCStruct is read member by member, and written the same way.

Tag Builder

Right-click the TS7CommPlusDriver → Tag Builder opens S7CommPlus – tag import (basket). The tree on the left only browses; what will be created lives in the basket on the right, where each entry has its own name, scan time and options.

  1. Press Read the variables from the PLC. The port must be Active = True beforehand, otherwise the wizard warns and reads nothing. Only the DB list (plus the I, Q and M areas, if Include the I, Q and M areas is ticked) is read at this point; the variables of a DB are read when it is expanded or added, and the IDE freezes for the time of one DB.
  2. Select what you want on the tree (Shift/Ctrl for several) and press Add to the basket, double-click a leaf or drag it into the basket. What an entry becomes depends only on what was added:
What you add What it becomes
A simple variable a TPLCTagNumber (a TPLCString for a STRING), read by its symbolic path
An array of a simple type a TPLCBlock, with the option of also creating the TPLCBlockElement of its elements
A structure a TPLCStruct, with the option of also creating the TPLCStructItem of its members
An array of structures a TPLCStruct covering the whole array, with the option of mapping the members of the first element (TPLCStructItem) to every index
One element of an array of structures (DB.Arr[1]) a TPLCStruct of its own, read by the path of the element
A whole DB (the DB node) a TPLCStruct read by the name of the DB, with an item per variable if the children are mapped
An element of an array, or a member inside such an element a loose TPLCTagNumber, read by its path

The elements of arrays and their members are on the tree too (turn Show the array elements off for a DB with thousands of them). Add the variables below adds every simple variable and array under the selected node, one entry each; the Only the types list (Real, DInt) and the tree filter narrow it. The filter takes a piece of the path, or a mask with * and ?.
3. For what is added: the name prefix, the scan time (ms; 0 = on change) and whether the child items are mapped. They are only the starting values of the new entries: each entry can be changed afterwards.
4. Edit the entries on the basket. With several selected, the scan time, the prefix and Map the child items apply to all of them; the name is edited one at a time, or generated for all by the name template: {name} is the last level of the path, {path} the whole path, {db} the DB and {n} the number in the selection (p{name}_{n}).
5. Create the components. The names are checked first: an invalid name, a repeated one (also among the items, elements and bits that will be created) or one that already exists stops the creation and says which. Adding the same node twice is allowed, as long as the names differ. The components appear on the form or data module with ProtocolDriver already linked, and the creation shows a progress bar.

Child items and BOOL. A BOOL is read from the PLC as the whole byte that holds it, so a TPLCStructItem of a Bool would show the neighbouring bits too. With the child items mapped, each BOOL of a structure or of an array of Bool becomes a TTagBit over a byte item (TPLCStructItem, or TPLCBlockElement in a block) that is always created, named <name>_Byte<offset>: the Bools that share a byte share that item. An array of Bool is assumed to take one byte per element.

A variable that cannot become a tag is listed with the reason (type not supported, could not read the STRING length) when Show the variables that do not become tags is on. The Classic wizard button opens the previous wizard, with ticks per mode.

Polling or on change

RefreshTime of the tag decides:

  • > 0 — polling: the driver reads the tag every RefreshTime ms, batching the tags that are due into as few requests as MaxItemsPerRequest allows.
  • = 0 — on change: the driver creates a subscription on the PLC, which then reports the changes every SubscriptionCycleMs (100 ms minimum). A value that flips faster than half of that cycle can go unnoticed — a 10 Hz clock flips every 50 ms and is always seen in the same state — so give such a tag a RefreshTime above 0 and poll it.

Subscriptions are recreated by themselves after a lost session or a dropped subscription (SubscriptionTimeoutMs), and the addresses are resolved again after a download to the PLC (ProgramCheckIntervalMs). RefreshCaches forces that immediately — call it after a download of a new program if the tags must be right at once.

Active alarms

ReadActiveAlarms(Languages, Alarms) of the driver returns the alarms that are active in the PLC now (S7-1200/1500): one TS7PlusAlarm per alarm, with the CPU alarm ID, the domain, the sequence counter, whether it is coming or going, the time of the event and of the acknowledgement (UTC), the associated values and the texts of each language. Languages is a list of language IDs (S7PlusLang_Portuguese_BR = 1046, S7PlusLang_English_US = 1033…); empty keeps every language the PLC sends. The texts already have the associated values in place of the @1%d@ marks. It is a single request, so it can be called whenever a snapshot is wanted; no subscription is created and the alarms are not acknowledged.

To be told when an alarm comes or goes, subscribe: AlarmSubscribe(Languages, SendTexts, CreditLimit) and then call AlarmPoll(WaitMs, Alarms), which waits up to WaitMs ms (the driver is held meanwhile, so keep it short) and returns the alarms that arrived since the last call; empty with ioOk means none did. SendTexts = True (default) makes the PLC send the texts with each notification; an S7-1200 without TLS refuses that, so use False there and read the texts with ReadActiveAlarms. The credit is renewed on its own and the subscription is created again after a reconnect. AlarmUnsubscribe removes it without touching the data subscriptions. An alarm that was already active when subscribing is not sent: take that snapshot with ReadActiveAlarms first.

var Alarms: TS7PlusAlarmArray; i: Integer;
begin
  Drv.ReadActiveAlarms([S7PlusLang_English_US], Alarms);  // what is active now
  Drv.AlarmSubscribe([S7PlusLang_English_US]);              // and what changes from now on
  while not Terminated do
    if Drv.AlarmPoll(500, Alarms) = ioOk then
      for i := 0 to High(Alarms) do
        WriteLn(S7PlusAlarmToString(Alarms[i], S7PlusLang_English_US));
end;

The alarm subscription follows the format of the S7CommPlusDriver and s7commplus reference libraries; it is not yet validated against every PLC model.

Logging the PLC alarms: THMIS7PlusAlarmLogger

THMIS7PlusAlarmLogger (an THMIAlarmLogger descendant, PascalSCADA HMI palette) takes these alarms into the same flow as the tag based alarm log: set Driver to the TS7CommPlusDriver, AsyncDBConnection to the database connection, LanguageId (e.g. 1046; 0 = every language) and Active = True. The driver subscribes as soon as the connection is up, and again after every reconnect, and hands the alarms to the logger; there is no polling in your code. Each alarm that comes gets a new ID (OnGenerateNewAlarmID, or the internal counter) and raises OnS7PlusAlarmIncoming; when it goes, OnS7PlusAlarmOutgoing with the same ID. Both receive the TS7PlusAlarm (CPU time converted to local time, texts, associated values) and return the SQL to run, exactly like OnIncomingAlarm/OnOutgoingAlarm; OnRefreshActiveAlarms fires afterwards. Events are raised in the main thread. The tag based AlarmMessages keep working in the same component.

Each time the subscription is created the logger receives first the alarms that were already active and reconciles them with what it has open: an alarm that came while the connection was down is opened, one that went meanwhile is closed (with the time it was noticed). Alarms are identified by the CPU alarm ID; one alarm coming twice without going in between is logged once. SendTexts = False is for an S7-1200 without TLS (the alarms then arrive without texts).

For your own code, TS7CommPlusDriver.AddAlarmHandler(Handler) delivers the same alarms (from the scan thread; IsSnapshot = True for the list of the ones already active) and AlarmRequest(...) asks for the subscription without needing the connection to be open yet.

Step-by-step example

Read the temperature "Data".Temperature (Real) of an S7-1200 at 192.168.0.10 and write the setpoint "Data".Setpoint (Int):

  1. In TIA Portal: nothing to change; just note the name of the DB (Data) and compile.
  2. Drop a TTCP_UDPPort: Host = 192.168.0.10, Port = 102, PortType = ptTCP.
  3. Drop a TS7CommPlusDriver: CommunicationPort = TCP_UDPPort1, leave UseTLS = True.
  4. Right-click the driver → Tag Builder: Read the variables from the PLC, open the DB Data, select Temperature and Setpoint, set the scan time to 500, Add to the basket and then Create the components.
  5. Link a THMILabel to Temperature and a THMIEdit to Setpoint. Set Port.Active := True and run.

The same from code:

uses tcp_udpport, S7PlusFamily, PLCTagNumber;

var
  Port: TTCP_UDPPort;
  Drv: TS7CommPlusDriver;
  Temp, Setpoint: TPLCTagNumber;
begin
  Port := TTCP_UDPPort.Create(Self);
  Port.Host := '192.168.0.10';
  Port.Port := 102;

  Drv := TS7CommPlusDriver.Create(Self);
  Drv.CommunicationPort := Port;
  Drv.UseTLS := True;

  Temp := TPLCTagNumber.Create(Self);
  Temp.LongAddress := 'Data.Temperature';  // the symbolic path
  Temp.TagType := pttFloat;
  Temp.SwapBytes := True;                  // big-endian PLC
  Temp.SwapWords := True;
  Temp.RefreshTime := 500;                 // 0 = on change

  Setpoint := TPLCTagNumber.Create(Self);
  Setpoint.LongAddress := 'Data.Setpoint';
  Setpoint.TagType := pttSmallInt;
  Setpoint.SwapBytes := True;

  Temp.ProtocolDriver := Drv;              // last
  Setpoint.ProtocolDriver := Drv;

  Port.Active := True;
end;
TLS and certificates

UseTLS is on by default and most S7-1200/1500 firmware from V15 on requires it. The TLS tunnel is built by the driver itself, over OpenSSL loaded at run time: libssl-3-x64.dll / libcrypto-3-x64.dll, or the 1.1 versions, or the legacy ssleay32.dll/libeay32.dll. Ship those DLLs next to the executable (or anywhere on the PATH) when the application uses TLS.

  • ServerCertificate empty accepts the certificate the PLC presents. Fill it to pin one PLC: the handshake then fails for any other certificate (another PLC, a device in between), and the reason shows on OnDebug. The name in the certificate is not compared — PLC certificates rarely carry their IP address.
  • ClientCertificate adds mutual TLS: the certificate this side presents, with its private key, as PEM text, as the name of a PEM/PKCS#12 file (read at each connection, so the key stays out of the form) or as the base64 of a PKCS#12. Needs OpenSSL 1.1.1 or newer; a PKCS#12 made with old algorithms (RC2) also needs the legacy provider of OpenSSL 3.

Password legitimation is not finished. Password (and Username) makes the driver log in right after each new connection, but only the challenge-retrieval step is confirmed against real hardware: the PLC still rejects the encrypted response. A CPU at Full access with password therefore answers reads and refuses writes. Use a protection level without password, or accept read-only access.

Common problems
Symptom Likely cause
Port opens but no tag updates, ioConnectPLCFailed Wrong IP, port 102 blocked, or the CPU protection level is HMI access/No access.
Every tag fails with ioAuthError The CPU protects what the session needs and the login did not happen — see Password legitimation above.
A tag fails with ioObjectNotExists right after a download The address of the program that was replaced is still cached: call RefreshCaches (it happens by itself within ProgramCheckIntervalMs).
Writes fail while reads work Protection level Read access, ReadOnly = True, or Full access with password (no login).
Absurd 16/32-bit values (1 becomes 256) Missing SwapBytes/SwapWords on a tag typed by hand.
A tag on an array of structures reads garbage Read it as a TPLCStruct covering the array: reading the whole array returns a value the driver does not decode and it already reads it member by member.
A fast signal is always seen in the same state The tag is on change with a cycle longer than the signal: give it a RefreshTime above 0.
The Tag Builder warns and reads nothing The port was not Active = True when the wizard was opened.
Values stop arriving after a while, without an error The subscription went silent: check SubscriptionTimeoutMs (the driver recreates it) and OnDebug.
Related examples

The tag plan rules (what becomes a tag, and with which type) live in S7PlusTagPlan and are tested without a PLC in tests/.