feat: tag_browser — parse I/Q/M tags and DB/FB/OB interfaces from decompressed EXPLORE XML

[tommasofaedo]

Summary

Follow-up to #776. That PR added the preset-dictionary decompressor; this one adds the small, non-invasive layer on top that turns a decompressed EXPLORE response into structured records — for I/Q/M symbols and DB / FB / OB / UDT block interfaces. This is the wiring flagged as TODO in #776 / #757.

All of it lives in s7commplus/tag_browser.py and tests/test_tag_browser.py and touches no existing files, so you can merge it as-is, call the helpers from browse() yourself, or fold it into #776 — whatever is least noisy.

I/Q/M symbolic tags

• parse_ident_container() / tags_from_explore() — decompress the <IdentContainer> blob (IntfDescTag dict, 0xce9b821b) and map Range+Width+ByteNumber+BitNumber to TIA syntax (%I0.0, %Q0.1, %MB100, %MW102, %MD104) as Tag records.

DB / FB / OB / UDT interfaces

• parse_block_interface() / block_interface_from_explore() — decompress the <BlockInterface> blob (DebugInfo_IntfDesc dict, 0x66052b13) into Member records (name, type, LID, offset, section). A block EXPLORE bundles several preset-dict streams, so it targets the interface dict explicitly rather than taking the first zlib stream.
• Types. A <Member>'s type is a RID reference 0x0200_00XX where XX is a Siemens SoftDataType id (SOFTDATATYPE map transcribed from thomas-v2/S7CommPlusDriver Core/Softdatatype.cs, the same source as the shipped dictionaries). Complex members (arrays, UDTs, strings) already carry a ready-made, human-readable Type attribute (Array[0..5] of IEC_TIMER, "myUdt"), which is used directly; the raw RID stays on Member.rid.
• Sections. FB/OB members are tagged with their section (Input/Output/InOut/Static/Temp/Constant); section-header and list-wrapper <Member> elements (no RID) are skipped. DB/UDT members are flat (empty section).
• Nested UDT fields. When a member is of a UDT/struct, its definition is embedded under the primary part's <SubParts> (selected by the member's SubPartIndex); it is expanded recursively into Member.fields. Library types (e.g. IEC_TIMER) are referenced but not inlined, so they expand to no fields. Embedded type definitions are never surfaced as top-level members.

DB listing

• datablocks_from_explore() — parse the DB list from a 0x8A11FFFF wildcard EXPLORE. PlcContentInfo is a standard zlib stream (78 da) embedded in a larger BLOB, so it is raw-inflated to tolerate the trailing bytes.

Honest scope / testing

• Based on the feat/zlib-preset-dictionaries branch, not master — it imports the decompressor, so it should merge after (or into) feat: zlib preset dictionary decompressor for S7CommPlus blobs #776.
• Validated on a live S7-1200 G2 (FW V4.1) only. I no longer have the G1 FW V4.5 unit from S7-1200 FW V4.5: I/Q/M symbolic tag browse via oracle-reconstructed preset dictionary (33/40 tags complete) #757, but the G2 declares the same dictionaries.

I/Q/M symbols (verified against TIA Portal): input_1 %I0.0, output_1 %Q0.1, merker_1 %M0.2, mtag_byte %MB100, mtag_word %MW102, mtag_dword %MD104, mtag_bool %M108.0.

Optimized DB Data_block_1 (11 elementary members: Bool/Int/Real, cross-checked against the physical <Offsets>), plus a live FB (FB_Macchina) with sections + Array[0..5] of IEC_TIMER / Array[0..2] of Bool, and a DB member of a user UDT elettrovalvola that expands into its 6 inner fields (fc_apertura, stato_ev, …). Tests use real EXPLORE blob fixtures from the G2; 10/10 pass, ruff clean.

This makes the oracle pipeline from #757 (_build_fdict / regex _extract_tags / symbolic-READ width workaround) obsolete: <SimpleType> carries the real M widths directly, and block interfaces resolve straight to clean member names, types, sections and nested UDT fields.

🤖 Generated with Claude Code

[gijzelaerr]

Nice work — clean module, real hardware fixtures, well-scoped. Three things I noticed:

1. Off-by-one in _find_preset_stream (tag_browser.py:262)

end = len(data) - 6 should be len(data) - 5. The zlib header is 6 bytes (CMF + FLG + 4-byte DICTID), so valid start positions go up to len(data) - 6 inclusive, but the while i < end loop excludes that last position. Unlikely to bite in practice (a stream starting 6 bytes from the end would have no compressed data), but still a real off-by-one.

2. No cycle guard in recursive UDT expansion (tag_browser.py:231)

_build_member follows SubPartIndex → _parse_source_part → _build_member without tracking visited parts. A malformed BlockInterface with circular SubPartIndex references would hit RecursionError. A seen: set[int] threaded through the recursion would prevent it. Not a concern with real PLCs, but cheap to add.

3. DB listing only matches 78 da (tag_browser.py:281)

datablocks_from_explore hardcodes b"\x78\xda" (zlib best-compression), but standard zlib streams can use other FLG bytes (78 9c, 78 5e, 78 01). If a firmware version emits PlcContentInfo with default compression the function silently returns []. Scanning for any 0x78 byte and validating the header checksum (CMF*256 + FLG must be divisible by 31) would be more robust.

None of these block merging — just worth fixing while the code is fresh.

[tommasofaedo]

Thanks for the careful review — all three fixed in 48c8659:

1. Off-by-one in _find_preset_stream — end = len(data) - 5, so the last valid 6-byte header start position is now scanned.
2. Cycle guard in recursive UDT expansion — a seen set of <Part> identities is threaded through _parse_source_part/_build_member; a circular SubPartIndex now stops instead of hitting RecursionError.
3. DB listing zlib header — datablocks_from_explore now uses a new _find_zlib_stream helper that matches any CMF 0x78 with a valid header checksum (CMF*256 + FLG divisible by 31) and no preset-dict flag, rather than hardcoding 78 da, so 78 01/5e/9c from other firmwares are tolerated.

10/10 tests still pass, ruff clean.