Live streams

Collector: Siemens S7

Poll S7-300, S7-400, S7-1200 and S7-1500 controllers (PUT/GET, non-optimised DBs) with an address map.

Siemens S7 (S7-300, 400, 1200, 1500)

Siemens S7-300, S7-400, S7-1200 and S7-1500 controllers (and the S7-1500 software controller) answer the classic S7 protocol on TCP port 102. The collector is the client: it connects to the CPU, polls the addresses you list in a map and publishes every poll as a sample. It only reads. S7-1200 and S7-1500 CPUs refuse this protocol until you allow it in TIA Portal (see the next section); if you would rather not change the PLC, use the CPU's own OPC UA server with the opcua source instead.

Prepare the PLC (S7-1200 and S7-1500)

In TIA Portal open the CPU properties, Protection & Security, Connection mechanisms, and tick Permit access with PUT/GET communication from remote partner. Without it every read is refused.
For every data block you want to read, open its properties, Attributes, and clear Optimized block access; then compile and download. Optimised blocks have no fixed byte offsets, so the PLC answers "object does not exist". After clearing the box the offsets are shown in the DB's Offset column: those are the numbers for the byte column. Merkers (M), inputs (I), outputs (Q), timers and counters need nothing special.
Apply a CPU access level that still lets this read through (full access or read access without a password prompt on the PUT/GET connection).

Configuration

collector.yaml

sources:
  - name: Packaging line PLC
    type: s7
    host: 10.20.0.30
    cpu: s7-1500             # sets rack 0 / slot 1; s7-300 is 0/2, s7-400 is 0/3
    poll_ms: 500
    map: s7.csv

Name	Type	Description
`host`required	`string`	The CPU’s address (its PROFINET/Ethernet port, or a CP).
`port`	`number` Default: `102`	ISO-on-TCP port.
`cpu`	`s7-300 \| s7-400 \| s7-1200 \| s7-1500` Default: `s7-1500`	Picks the default rack and slot: 0/2 for S7-300, 0/3 for S7-400, 0/1 for S7-1200 and S7-1500.
`rack, slot`	`number` Default: `from cpu`	Override when the CPU sits elsewhere (an S7-400 in a multi-rack setup, a CPU behind a CP). Wrong values give a connection error.
`map`required	`path`	The address map CSV, relative to collector.yaml.
`poll_ms`	`number` Default: `1000`	Default poll interval; a row can set its own.
`timeout_s`	`number` Default: `3.0`	Per request (the connection attempt is also capped by the snap7 library at 5 s). A request that fails or does not answer in time turns its tags into gaps and the collector reconnects; each source uses its own thread, so an offline PLC never delays other sources or shutdown.
`max_gap`	`number` Default: `8`	Bytes that may be read and thrown away to merge two nearby tags of the same DB into one request. 0 merges only touching tags.

The address map

One row per tag. Column order does not matter; name, area, byte and type are required.

s7.csv

name,area,db,byte,bit,type,scale,offset,unit,poll_ms,description
Line speed,DB,10,0,,REAL,,,m/min,,
Tank level,DB,10,4,,INT,0.1,,%,1000,Raw is tenths of a percent
Batch count,DB,10,6,,DINT,,,,,
Motor running,DB,10,10,0,BOOL,,,,,Bit 0 of byte 10
Door open,M,,20,3,BOOL,,,,,
Start button,I,,0,1,BOOL,,,,,
Valve 1 command,Q,,4,0,BOOL,,,,,
Cycle timer,DB,10,12,,S5TIME,,,s,,
Timer T5,T,,5,,S5TIME,,,s,,Timer number in the byte column
Parts counter C2,C,,2,,UINT,,,,,Counter number in the byte column
Last cycle,DB,10,16,,TIME,0.001,,s,,TIME is milliseconds
Batch start,DB,10,20,,DATE_AND_TIME,,,,,Unix seconds (UTC)

Name	Type	Description
`name`required	`string`	The channel name in Kymoscope. Unique within the source.
`area`required	`DB \| M \| I \| Q \| T \| C`	Data block, merkers, inputs, outputs, timers, counters.
`db`	`number`	The DB number (area DB only).
`byte`required	`number`	Byte offset in the DB or area (0x hex accepted). For T and C it is the timer or counter number.
`bit`	`number 0-7`	The bit inside the byte, required for BOOL (DBX10.3 is byte 10, bit 3).
`type`required	`BOOL BYTE WORD DWORD INT DINT UINT UDINT LINT REAL LREAL S5TIME TIME DATE DATE_AND_TIME`	S7 types are big-endian. INT is 16-bit signed, DINT 32-bit signed, REAL a 32-bit float, LREAL 64-bit. S5TIME is read as seconds. TIME is milliseconds (scale 0.001 for seconds). DATE and DATE_AND_TIME are Unix seconds (DATE_AND_TIME is taken as UTC). Timers are S5TIME and counters UINT.
`scale, offset`	`number` Default: `1, 0`	value = raw x scale + offset.
`unit`	`string`	Engineering unit shown on the channel.
`poll_ms`	`number`	This tag’s interval; tags of the same area, DB and interval are read together.
`description`	`string`	Free text.

Tags of the same DB and interval are merged into as few requests as the CPU's negotiated PDU size allows (240 bytes on older CPUs, 480 or 960 on newer ones), so a map of hundreds of tags costs a handful of requests per poll. Strings, arrays and structures are not read as such: list the elements you need one by one.

Gaps, errors and health

Every sample is stamped with the time the response arrived.
When the connection drops or a request times out, the tags of that poll are stored as gaps (Bad status), never as the last value. The collector reconnects on its own with a growing delay up to one minute.
When the PLC refuses an address, only that tag becomes a gap; neighbours merged into the same request are re-read one by one. The log names the tag once with the likely cause: access refused (PUT/GET not permitted or a CPU password), object does not exist (the DB is missing or still optimised) or invalid address(offset past the end of the DB).

Health stream channels for an S7 source

connected, reconnects, polls, poll_errors, overruns, last_poll_s, values_per_s,
refused_03 (access refused), refused_05 (invalid address), refused_0a (object does not exist) ...

discover and backfill

discover writes the tags of the map as a tags file; the classic protocol cannot list a PLC's variables. backfill does not apply: an S7 CPU keeps no history, so a gap while the collector is down stays a gap (the collector's own disk buffer covers outages of the link to Kymoscope).

Permissions to ask the site for

TCP port 102 from the collector host to the CPU, and the PUT/GET setting above for S7-1200 and S7-1500. The collector only reads; it never writes to or controls the PLC.
The classic S7 protocol has no encryption. Keep it on the customer network; the data leaves your site encrypted. Many CPUs allow only a few simultaneous PUT/GET connections (S7-1200: 3 to 8 depending on firmware): the collector uses one.
Install with pip install "kymoscope-collector[s7]" (pure Python, no Siemens software needed).