Unified Tag API replacing SymbolTable

[gijzelaerr]

Summary

Unified Tag API for reading and writing typed PLC values, using PLC4X / Siemens STEP7 address syntax familiar to every TIA Portal user. Includes symbolic (LID-based) access for S7-1200/1500 optimized DBs.

Tag API

A Tag describes a typed value at a specific S7 address. Tags can be created ad-hoc, loaded from files, or discovered from the PLC.

from s7 import Client, Tag, load_csv, load_json, load_tia_xml, from_browse

client = Client()
client.connect("192.168.1.10", 0, 1)

# Ad-hoc access with PLC4X-style strings
speed = client.read_tag("DB1.DBD0:REAL")
running = client.read_tag("DB1.DBX4.0:BOOL")
client.write_tag("DB1.DBW6:INT", 1500)

# Batch read (uses optimizer when enabled)
values = client.read_tags(["DB1.DBD0:REAL", "DB1.DBW6:INT"])

# Load named tags from a file
tags = load_tia_xml("db1.xml")  # dict[str, Tag]
temperature = client.read_tag(tags["Motor.Temperature"])

Address syntax

DB1.DBX0.0:BOOL          bit in data block
DB1.DBB10:BYTE           byte
DB1.DBW10:INT            word (2 bytes)
DB1.DBD10:REAL           double word (4 bytes)
DB1:10:INT               short form
DB1:10:STRING[20]        variable-length string
DB1:10:REAL[5]           array of 5 REALs
M10.5:BOOL               Merker bit
MW20:WORD                Merker word
I0.0:BOOL                input bit
Q0.0:BOOL                output bit

Leading % is optional. All fixed-size types support [count] arrays.

Symbolic access for optimized DBs (experimental)

S7-1200/1500 DBs with "Optimized block access" enabled (the TIA Portal V13+ default) do not use fixed byte offsets. The PLC relocates variables internally between downloads, so byte addresses like DB1.DBX0.0 are unreliable. Symbolic access navigates the PLC's symbol tree using LIDs (Local IDs).

# Discover LIDs from the PLC
variables = client.browse()
tags = from_browse(variables)  # Tags configured for symbolic access

# Read/write routes through S7CommPlus LID-based access
speed = client.read_tag(tags["Motor.Speed"])
client.write_tag(tags["Motor.Speed"], 1500.0)

# Or construct symbolic Tags manually
tag = Tag.from_access_string(
    "8A0E0001.A",           # AccessArea.LID (hex, dot-separated)
    datatype="REAL",
    name="Motor.Speed",
    symbol_crc=0x12345678,  # optional layout version check
)

The wire encoding follows the S7CommPlusDriver reference but has not yet been validated against a real optimized-DB PLC.

API additions

• snap7.tags.Tag — canonical dataclass (area, db_number, byte_offset, datatype, bit, count, name, access_sequence, symbol_crc, is_symbolic)
• Tag.from_string(address) — PLC4X address parser
• Tag.from_access_string(hex_path, datatype, ...) — symbolic access parser
• load_csv, load_json, load_tia_xml — return dict[str, Tag]
• from_browse(variables) — convert client.browse() results to Tag dict
• Client.read_tag(tag_or_str) — read typed value
• Client.write_tag(tag_or_str, value) — write typed value
• Client.read_tags([tags]) — batch read via optimizer
• S7CommPlusClient.read_symbolic, write_symbolic — LID-based PDU builders