From c7d3f6cce68e562cb9cd827875fbf09e09721eab Mon Sep 17 00:00:00 2001 From: Cody Warren Date: Wed, 25 Mar 2026 21:02:11 -0600 Subject: [PATCH 01/10] feat: add save_acd() write path with byte-identical round-trip - write_acd.py: new ACD container packer (footer-based format, all 25 embedded files, preserves per-file compression and footer unknown value) - export_l5x.py: preserve all embedded files verbatim from the original ACD (read pre-decompression from archive offsets, not extracted copies) and attach _raw_files/_file_order/_footer_unknown to the project object - api.py: add load_acd() and save_acd() clean top-level functions; SQLite and temp dir are internal implementation details No-op round-trip is byte-identical across all 25 embedded files. Co-Authored-By: Claude Sonnet 4.6 --- acd/api.py | 48 ++++++++++++++++++++++++++++++++++ acd/l5x/export_l5x.py | 16 +++++++++++- acd/zip/write_acd.py | 61 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 124 insertions(+), 1 deletion(-) create mode 100644 acd/zip/write_acd.py diff --git a/acd/api.py b/acd/api.py index 6239fffd3..f0d137bba 100644 --- a/acd/api.py +++ b/acd/api.py @@ -1,15 +1,63 @@ import os +import tempfile +import shutil from abc import abstractmethod from dataclasses import dataclass from os import PathLike +from pathlib import Path from acd.l5x.export_l5x import ExportL5x from acd.zip.unzip import Unzip +from acd.zip.write_acd import write_acd from acd.database.acd_database import AcdDatabase from acd.l5x.elements import DumpCompsRecords, RSLogix5000Content +# Clean top-level API + +def load_acd(path, temp_dir: str = None) -> RSLogix5000Content: + """Load an ACD file into a Python object model. + + Args: + path: Path to the .ACD file. + temp_dir: Directory for SQLite and extracted files. A temporary + directory is created and cleaned up automatically if omitted. + + Returns: + RSLogix5000Content with a fully populated controller object tree. + The project also carries _raw_files / _file_order / _footer_unknown + for use by save_acd(). + """ + cleanup = temp_dir is None + if cleanup: + temp_dir = tempfile.mkdtemp(prefix="acd_load_") + try: + exporter = ExportL5x(str(path), temp_dir) + return exporter.project + finally: + if cleanup: + shutil.rmtree(temp_dir, ignore_errors=True) + + +def save_acd(project: RSLogix5000Content, output_path) -> None: + """Write a project object model back to an ACD file. + + The project must have been loaded via load_acd() or ExportL5x so that + it carries _raw_files, _file_order, and _footer_unknown. + + Args: + project: Project loaded by load_acd(). + output_path: Destination .ACD file path. + """ + write_acd( + files=project._raw_files, + output_path=output_path, + file_order=project._file_order, + footer_unknown=project._footer_unknown, + ) + + # Returned Project Structures diff --git a/acd/l5x/export_l5x.py b/acd/l5x/export_l5x.py index cedc1db6f..eff826f8d 100644 --- a/acd/l5x/export_l5x.py +++ b/acd/l5x/export_l5x.py @@ -5,7 +5,7 @@ from dataclasses import dataclass from pathlib import Path from sqlite3 import Cursor -from typing import Union +from typing import Dict, List, Union from acd.database.dbextract import DbExtract from acd.zip.unzip import Unzip @@ -78,6 +78,17 @@ def __post_init__(self): unzip = Unzip(self.input_filename) unzip.write_files(self._temp_dir) + # Preserve all embedded files in original order for round-trip writing. + # Read directly from the ACD archive (pre-decompression) so that + # compressed files are carried as-is and write-back is byte-identical. + self._file_order: List[str] = [r.filename for r in unzip.records] + self._footer_unknown: int = unzip.header._unknown_two + self._raw_files: Dict[str, bytes] = {} + with open(self.input_filename, "rb") as acd_fh: + for record in unzip.records: + acd_fh.seek(record.file_offset) + self._raw_files[record.filename] = acd_fh.read(record.file_length) + log.info("Getting records from ACD Comps file and storing in sqllite database") comps_db = DbExtract(os.path.join(self._temp_dir, "Comps.Dat")).read() # Deduplicate by object_id (last occurrence wins, matching original behavior) @@ -143,6 +154,9 @@ def project(self): Path(os.path.join(self._temp_dir, "QuickInfo.XML")) ).build() self._project.controller = self.controller + self._project._raw_files = self._raw_files + self._project._file_order = self._file_order + self._project._footer_unknown = self._footer_unknown return self._project def populate_region_map(self): diff --git a/acd/zip/write_acd.py b/acd/zip/write_acd.py new file mode 100644 index 000000000..7eb1c9f27 --- /dev/null +++ b/acd/zip/write_acd.py @@ -0,0 +1,61 @@ +"""Write a Rockwell ACD container file from a dict of raw file bytes. + +The ACD container format is footer-based: + + [file data blocks, packed sequentially starting at offset 0] + [file record table: 528 bytes × num_files] + [filename: UTF-16LE null-terminated, zero-padded to 520 bytes] + [file_length: u32_le] + [file_offset: u32_le -- absolute offset from start of ACD] + [footer: num_files u32_le + unknown u32_le] + +The first bytes of the ACD are the first bytes of the first embedded file +(typically Version.Log, which starts with 0x0D 0x0A — this is what the +reader checks as its "magic number"). +""" + +import struct +from pathlib import Path +from typing import Dict, List + + +def write_acd( + files: Dict[str, bytes], + output_path, + file_order: List[str] = None, + footer_unknown: int = 2, +) -> None: + """Pack files into a Rockwell ACD container. + + Args: + files: Mapping of filename → raw bytes. + output_path: Destination .ACD path. + file_order: Filenames in desired write order. Defaults to files.keys(). + footer_unknown: The second u32 in the ACD footer. Preserve the value + from the original file (accessible via Unzip.header._unknown_two). + """ + if file_order is None: + file_order = list(files.keys()) + + output = bytearray() + file_records = [] + + # Write file data blocks sequentially, recording each file's offset + for filename in file_order: + offset = len(output) + data = files[filename] + output.extend(data) + file_records.append((filename, offset, len(data))) + + # File record table — 528 bytes per entry + for filename, offset, length in file_records: + # Filename section: UTF-16LE + null terminator, zero-padded to 520 bytes + encoded = filename.encode("utf-16-le") + b"\x00\x00" + name_section = encoded.ljust(520, b"\x00") + output.extend(name_section) + output.extend(struct.pack(" Date: Wed, 25 Mar 2026 21:17:07 -0600 Subject: [PATCH 02/10] Add rung write-back: SbRegion.Dat patching via patch_rungs() API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - write_dat.py: patch_sbregion_dat() rebuilds SbRegion.Dat with modified rung text. Uses rung-scoped @HEX@ resolution (only substitutes tags that appear in the specific rung being patched) to avoid false matches on short names inside instruction opcodes. - elements.py: Routine now carries _rung_ids: List[int] alongside rungs, giving callers the object_id needed to target a specific rung. - export_l5x.py: stores _id_to_name (object_id→comp_name) on project for write-back reference resolution. - api.py: patch_rungs(project, {rung_object_id: new_text}) convenience wrapper that patches _raw_files["SbRegion.Dat"] in-place before save_acd(). Validated on DemoPLC.ACD: rung text round-trips correctly and only SbRegion.Dat differs (28 bytes larger for a 14-char appended comment). Co-Authored-By: Claude Sonnet 4.6 --- acd/api.py | 31 +++++++ acd/l5x/elements.py | 7 +- acd/l5x/export_l5x.py | 5 +- acd/zip/write_dat.py | 189 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 229 insertions(+), 3 deletions(-) create mode 100644 acd/zip/write_dat.py diff --git a/acd/api.py b/acd/api.py index f0d137bba..c74b3c1fe 100644 --- a/acd/api.py +++ b/acd/api.py @@ -9,6 +9,7 @@ from acd.l5x.export_l5x import ExportL5x from acd.zip.unzip import Unzip from acd.zip.write_acd import write_acd +from acd.zip.write_dat import patch_sbregion_dat from acd.database.acd_database import AcdDatabase from acd.l5x.elements import DumpCompsRecords, RSLogix5000Content @@ -58,6 +59,36 @@ def save_acd(project: RSLogix5000Content, output_path) -> None: ) +def patch_rungs(project: RSLogix5000Content, changes: dict) -> None: + """Patch rung text in a loaded project's SbRegion.Dat in-place. + + Call this before save_acd() to modify ladder rung logic. + + Args: + project: Project loaded by load_acd(). + changes: Mapping of {rung_object_id: new_rung_text}. + + rung_object_id — the integer object_id for the rung. Available + as routine._rung_ids[i] for the i-th rung in a Routine. + + new_rung_text — the new rung text with plain tag names (not + @HEX@ placeholders). Tag names are resolved back to object_id + placeholders automatically using project._id_to_name. + + Example: + project = load_acd("project.ACD") + routine = project.controller.programs[0].routines[0] + changes = {routine._rung_ids[0]: "XIC(MyTag)OTE(OutputTag);"} + patch_rungs(project, changes) + save_acd(project, "modified.ACD") + """ + project._raw_files["SbRegion.Dat"] = patch_sbregion_dat( + project._raw_files["SbRegion.Dat"], + changes, + project._id_to_name, + ) + + # Returned Project Structures diff --git a/acd/l5x/elements.py b/acd/l5x/elements.py index 400bda046..6ff62e5c5 100644 --- a/acd/l5x/elements.py +++ b/acd/l5x/elements.py @@ -107,6 +107,7 @@ class Routine(L5xElement): name: str type: str rungs: List[str] + _rung_ids: List[int] = field(default_factory=list) @dataclass @@ -463,8 +464,10 @@ def build(self) -> Routine: "LEFT JOIN rungs r ON r.object_id = rm.object_id " "WHERE rm.parent_id=" + str(self._object_id) + " ORDER BY rm.seq_no" ) - rungs = [row[1] for row in self._cur.fetchall() if row[1] is not None] - return Routine(name, name, routine_type, rungs) + rows = [(row[0], row[1]) for row in self._cur.fetchall() if row[1] is not None] + rung_ids = [row[0] for row in rows] + rungs = [row[1] for row in rows] + return Routine(name, name, routine_type, rungs, rung_ids) @dataclass diff --git a/acd/l5x/export_l5x.py b/acd/l5x/export_l5x.py index eff826f8d..e163593d2 100644 --- a/acd/l5x/export_l5x.py +++ b/acd/l5x/export_l5x.py @@ -100,8 +100,10 @@ def __post_init__(self): self._cur.executemany("INSERT INTO comps VALUES (?,?,?,?,?,?)", comps_by_id.values()) self._db.commit() - # Build name lookup for SbRegion tag reference resolution (object_id → comp_name) + # Build name lookup for SbRegion tag reference resolution (object_id → comp_name). + # Store on self for use during write-back (patch_sbregion_dat needs id_to_name). name_lookup = {oid: t[2] for oid, t in comps_by_id.items()} + self._id_to_name: Dict[int, str] = name_lookup log.info( "Getting records from ACD Region Map file and storing in sqllite database" @@ -157,6 +159,7 @@ def project(self): self._project._raw_files = self._raw_files self._project._file_order = self._file_order self._project._footer_unknown = self._footer_unknown + self._project._id_to_name = self._id_to_name return self._project def populate_region_map(self): diff --git a/acd/zip/write_dat.py b/acd/zip/write_dat.py new file mode 100644 index 000000000..cbf807362 --- /dev/null +++ b/acd/zip/write_dat.py @@ -0,0 +1,189 @@ +"""Patch embedded .Dat files inside a loaded ACD project. + +Currently supports SbRegion.Dat (rung text write-back). + +SbRegion.Dat layout (after decompression): + Header (24 bytes + variable header_buffer): + [0:4] format_type u32_le + [4:8] blank_2 u32_le (0) + [8:12] file_length u32_le (bounds records region; see note below) + [12:16] first_record_position u32_le (offset to first record = 24 + len(header_buffer)) + [16:20] blank_3 u32_le + [20:24] number_records_fafa u32_le (count of 0xFAFA records — updated on rebuild) + [24:] header_buffer bytes (variable padding, copy verbatim) + + Records (from first_record_position to file_length+1): + [0:2] identifier u16_le (0xFAFA=64250, 0xFDFD=65021, etc.) + [2:6] len_record u32_le (total record bytes including this 6-byte header) + [6:] payload bytes (len_record - 6 bytes) + + Trailer (from file_length+1 to EOF): + FEFE pointer/index regions — copy verbatim, not parsed by record iterator. + + The Kaitai Dat parser reads exactly (file_length - first_record_position + 1) bytes + for the records sub-stream (i.e., records region = dat_bytes[first_record_pos:file_length+1]). + file_length is therefore NOT the total file size. + +FAFA rung payload layout (when language_type is "Rung NT" or "REGION NT"): + [0:4] record_length u32_le (= payload_len - 4 = 51 + len_record_buffer) + [4:6] sb_regions u16_le + [6:10] object_id u32_le ← rung identifier, matched for patching + [10:51] language_type bytes[41] (null-terminated, zero-padded) + [51:55] len_record_buffer u32_le + [55:] record_buffer bytes (UTF-16LE encoded rung text, null-terminated) +""" + +import gzip +import re +import struct +from typing import Dict + +_FAFA = 0xFAFA # 64250 + +# Byte offsets within a FAFA rung payload +_OFF_OBJ_ID = 6 # u32_le: rung object_id +_OFF_LANG_TYPE_END = 51 # exclusive end of fixed fields before len_record_buffer +_OFF_LEN_BUF = 51 # u32_le: byte length of record_buffer +_OFF_BUF = 55 # start of UTF-16LE rung text + +# language_type values that indicate rung text records +_RUNG_LANG_TYPES = {b"Rung NT", b"REGION NT"} + + +def _is_rung_record(payload: bytes) -> bool: + """Return True if this FAFA payload contains rung text.""" + if len(payload) < _OFF_BUF: + return False + lang_null = payload[10:51].split(b"\x00")[0] + return lang_null in _RUNG_LANG_TYPES + + +def _get_rung_object_id(payload: bytes) -> int: + return struct.unpack_from(" str: + """Decode the original rung text (with @HEX@ placeholders) from a payload.""" + len_buf = struct.unpack_from(" bytes: + """Encode rung text to UTF-16LE with null terminator.""" + return text.encode("utf-16-le") + b"\x00\x00" + + +def _restore_tag_refs(new_text: str, orig_text_with_refs: str, id_to_name: Dict[int, str]) -> str: + """Replace tag names in new_text with @HEX_OBJECT_ID@ placeholders. + + Only substitutes tags that appear as @HEX@ references in orig_text_with_refs + (the original raw rung text before name resolution). This prevents false-positive + substitution of short names into instruction opcodes (e.g. 'X' inside 'XIC'). + + Substitutions within the scoped set are done longest-name-first to handle + cases where one tag name is a prefix of another. + """ + # Identify which object IDs were referenced in the original rung + rung_ids = {int(m, 16) for m in re.findall(r"@([A-Za-z0-9]+)@", orig_text_with_refs)} + + # Build rung-scoped name → id map + scoped = {} + for oid in rung_ids: + name = id_to_name.get(oid) + if name: + scoped[name] = oid + + # Apply longest-first replacement + for name in sorted(scoped, key=len, reverse=True): + if name in new_text: + new_text = new_text.replace(name, f"@{scoped[name]:X}@") + + return new_text + + +def _build_fafa_record(orig_payload: bytes, new_text_bytes: bytes) -> bytes: + """Reconstruct a FAFA rung record with replaced text, preserving all other fields.""" + new_len = len(new_text_bytes) + new_payload = ( + struct.pack(" bytes: + """Return new SbRegion.Dat bytes with modified rung text. + + Args: + dat_bytes: Raw bytes of SbRegion.Dat from _raw_files (may be gzip-compressed). + changes: Mapping of {rung_object_id: new_rung_text}. Tag names in new_rung_text + are plain strings (as they appear in the Python object model / L5X); this + function re-inserts the @HEX_OBJECT_ID@ placeholders before encoding. + id_to_name: Mapping of {object_id: comp_name} used to resolve which @HEX@ tokens + to substitute when writing back. Available as project._id_to_name after load_acd(). + + Returns: + New SbRegion.Dat bytes (uncompressed). Swap into project._raw_files["SbRegion.Dat"] + before calling save_acd(). + """ + if not changes: + return dat_bytes + + # Decompress if needed + if dat_bytes[:2] == b"\x1f\x8b": + dat_bytes = gzip.decompress(dat_bytes) + + # Parse fixed 24-byte header fields we need + (format_type, blank_2, _file_length, first_record_pos, + blank_3, num_fafa) = struct.unpack_from(" Date: Thu, 26 Mar 2026 09:33:33 -0600 Subject: [PATCH 03/10] fix: correct L5X export for programs, AOIs, DataTypes, and tag filtering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes hutcheb/acd#19, #20, #22, #23, #24. - RSLogix5000Content root element now emits correct casing (was Rslogix5000Content) - DataType elements now emit correct casing (was Datatype) - Program elements now include Name attribute (was always None) - AOI elements now serialized as AddOnInstructionDefinition under AddOnInstructionDefinitions (were silently dropped — aois not in the handled-list check in to_xml()) - DataTypes filtered to User class only (was emitting 329 ProductDefined built-in types alongside 19 user-defined) - Controller tags filtered to exclude empty-DataType and $hex$ placeholder names (reduces tag count from 1214 to ~1159 vs Logix's 1096) Introduces _LIST_SECTION_NAMES dict to map Python attribute names to L5X XML section wrapper tags, replacing the fragile attribute.title() approach. Uses getattr(_export_name) in to_xml() so subclasses can override the XML element tag name without mangling by .title(). Co-Authored-By: Claude Sonnet 4.6 --- acd/l5x/elements.py | 54 ++++++++++++++++++++++++++++++++------------- 1 file changed, 39 insertions(+), 15 deletions(-) diff --git a/acd/l5x/elements.py b/acd/l5x/elements.py index 6ff62e5c5..8fef89f64 100644 --- a/acd/l5x/elements.py +++ b/acd/l5x/elements.py @@ -18,6 +18,18 @@ class L5xElementBuilder: _object_id: int = -1 +# Maps Python attribute names to L5X XML section wrapper tag names. +# Entries here also control which list attributes are serialized as child sections. +_LIST_SECTION_NAMES = { + "tags": "Tags", + "data_types": "DataTypes", + "members": "Members", + "programs": "Programs", + "routines": "Routines", + "aois": "AddOnInstructionDefinitions", +} + + @dataclass class L5xElement: _name: str @@ -34,13 +46,8 @@ def to_xml(self): if isinstance(attribute_value, L5xElement): child_list.append(attribute_value.to_xml()) elif isinstance(attribute_value, list): - if ( - attribute == "tags" - or attribute == "data_types" - or attribute == "members" - or attribute == "programs" - or attribute == "routines" - ): + if attribute in _LIST_SECTION_NAMES: + section_name = _LIST_SECTION_NAMES[attribute] new_child_list: List[str] = [] for element in attribute_value: if isinstance(element, L5xElement): @@ -48,7 +55,7 @@ def to_xml(self): else: new_child_list.append(f"<{element}/>") child_list.append( - f'<{attribute.title().replace("_", "")}>{"".join(new_child_list)}' + f'<{section_name}>{"".join(new_child_list)}' ) else: @@ -58,7 +65,9 @@ def to_xml(self): f'{attribute.title().replace("_", "")}="{attribute_value}"' ) - _export_name = self.__class__.__name__.title().replace("_", "") + _export_name = ( + getattr(self, "_export_name", "") or self.__class__.__name__.title().replace("_", "") + ) return f'<{_export_name} {" ".join(attribute_list)}>{"".join(child_list)}' @@ -79,6 +88,10 @@ class DataType(L5xElement): cls: str members: List[Member] + def __post_init__(self): + super().__post_init__() + self._export_name = "DataType" + @dataclass class Tag(L5xElement): @@ -112,12 +125,18 @@ class Routine(L5xElement): @dataclass class AOI(L5xElement): + name: str routines: List[Routine] tags: List[Tag] + def __post_init__(self): + super().__post_init__() + self._export_name = "AddOnInstructionDefinition" + @dataclass class Program(L5xElement): + name: str routines: List[Routine] tags: List[Tag] @@ -152,7 +171,8 @@ class RSLogix5000Content(L5xElement): export_options: str def __post_init__(self): - self._name = "RSLogix5000Content" + super().__post_init__() + self._export_name = "RSLogix5000Content" def radix_enum(i: int) -> str: @@ -493,7 +513,7 @@ def build(self) -> AOI: if len(collection_results) != 0: collection_id = collection_results[0][1] else: - return AOI(name, routines, tags) + return AOI(name, name, routines, tags) self._cur.execute( "SELECT comp_name, object_id, parent_id, record FROM comps WHERE parent_id=" @@ -523,7 +543,7 @@ def build(self) -> AOI: for result in results: tags.append(TagBuilder(self._cur, result[1]).build()) - return AOI(name, routines, tags) + return AOI(name, name, routines, tags) @dataclass @@ -582,7 +602,7 @@ def build(self) -> Program: ) comment_results = self._cur.fetchall() - return Program(name, routines, tags) + return Program(name, name, routines, tags) @dataclass @@ -653,7 +673,9 @@ def build(self) -> Controller: data_types: List[DataType] = [] for result in results: _data_type_object_id = result[1] - data_types.append(DataTypeBuilder(self._cur, _data_type_object_id).build()) + dt = DataTypeBuilder(self._cur, _data_type_object_id).build() + if dt.cls == "User": + data_types.append(dt) # Get the Controller Scoped Tags self._cur.execute( @@ -673,7 +695,9 @@ def build(self) -> Controller: tags: List[Tag] = [] for result in results: _tag_object_id = result[1] - tags.append(TagBuilder(self._cur, _tag_object_id).build()) + tag = TagBuilder(self._cur, _tag_object_id).build() + if tag.data_type and not tag.name.startswith("$"): + tags.append(tag) # Get the Program Collection and get the programs self._cur.execute( From 85f10564b3157e12a605786b6af0ff8bacb6894b Mon Sep 17 00:00:00 2001 From: Cody Warren Date: Thu, 26 Mar 2026 10:27:46 -0600 Subject: [PATCH 04/10] Add Task serialization: TaskBuilder decodes Type/Rate/Priority/Watchdog from binary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reverse-engineered task record BLOB offsets from CIPDemo_RevEng.ACD: - 0x106C (u32 μs): Rate - 0x10F6 (u16): Type (1=EVENT, 2=PERIODIC, 4=CONTINUOUS) - 0x10F8 (u16): Priority - 0x110A (u32 μs): Watchdog - 0x112E (u8): DisableUpdateOutputs - 0x5A (u16 + N×u32): scheduled program comment_ids Also adds: - ScheduledProgram, EventInfo, Task dataclasses - None-skipping in to_xml() for optional fields (Rate on CONTINUOUS tasks) - "tasks"/"scheduled_programs" entries in _LIST_SECTION_NAMES Co-Authored-By: Claude Sonnet 4.6 --- acd/l5x/elements.py | 117 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) diff --git a/acd/l5x/elements.py b/acd/l5x/elements.py index 8fef89f64..a86e90e79 100644 --- a/acd/l5x/elements.py +++ b/acd/l5x/elements.py @@ -27,6 +27,8 @@ class L5xElementBuilder: "programs": "Programs", "routines": "Routines", "aois": "AddOnInstructionDefinitions", + "tasks": "Tasks", + "scheduled_programs": "ScheduledPrograms", } @@ -43,6 +45,8 @@ def to_xml(self): for attribute in self.__dict__: if attribute[0] != "_": attribute_value = self.__getattribute__(attribute) + if attribute_value is None: + continue if isinstance(attribute_value, L5xElement): child_list.append(attribute_value.to_xml()) elif isinstance(attribute_value, list): @@ -141,6 +145,38 @@ class Program(L5xElement): tags: List[Tag] +@dataclass +class ScheduledProgram(L5xElement): + name: str + + def __post_init__(self): + super().__post_init__() + self._export_name = "ScheduledProgram" + + +@dataclass +class EventInfo(L5xElement): + event_trigger: str + enable_timeout: str + + def __post_init__(self): + super().__post_init__() + self._export_name = "EventInfo" + + +@dataclass +class Task(L5xElement): + name: str + type: str + rate: Union[str, None] # None for CONTINUOUS tasks (omitted from XML) + priority: str + watchdog: str + disable_update_outputs: str + inhibit_task: str + event_info: Union[EventInfo, None] # None for non-EVENT tasks + scheduled_programs: List[ScheduledProgram] + + @dataclass class Controller(L5xElement): serial_number: str @@ -153,6 +189,7 @@ class Controller(L5xElement): data_types: List[DataType] tags: List[Tag] programs: List[Program] + tasks: List[Task] aois: List[AOI] map_devices: List[MapDevice] @@ -605,6 +642,57 @@ def build(self) -> Program: return Program(name, name, routines, tags) +_TASK_TYPE_MAP = {1: "EVENT", 2: "PERIODIC", 4: "CONTINUOUS"} + + +@dataclass +class TaskBuilder(L5xElementBuilder): + def build(self, comment_id_to_program: Dict[int, str]) -> Task: + self._cur.execute( + "SELECT comp_name, record FROM comps WHERE object_id=" + str(self._object_id) + ) + row = self._cur.fetchone() + name, record = row[0], row[1] + + # All task config fields live within ext[0x01], accessed via absolute BLOB offsets. + # These offsets were reverse-engineered from CIPDemo_RevEng.ACD. + rate_us = struct.unpack_from(" Controller: @@ -720,6 +808,34 @@ def build(self) -> Controller: _program_object_id = result[1] programs.append(ProgramBuilder(self._cur, _program_object_id).build()) + # Build comment_id → program name map for task scheduled-program resolution. + # comment_id is a u16 at BLOB offset 0x0C in each program's RxGeneric record. + self._cur.execute( + "SELECT comp_name, record FROM comps WHERE parent_id=" + str(_program_collection_object_id) + ) + comment_id_to_program: Dict[int, str] = { + struct.unpack_from(" --- acd/l5x/elements.py | 140 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 129 insertions(+), 11 deletions(-) diff --git a/acd/l5x/elements.py b/acd/l5x/elements.py index a86e90e79..38d7b4f01 100644 --- a/acd/l5x/elements.py +++ b/acd/l5x/elements.py @@ -130,6 +130,17 @@ class Routine(L5xElement): @dataclass class AOI(L5xElement): name: str + revision: str + revision_extension: Union[str, None] # None if absent (omitted from XML) + vendor: Union[str, None] # None if absent (omitted from XML) + execute_prescan: str + execute_postscan: str + execute_enable_in_false: str + created_date: str + created_by: str + edited_date: str + edited_by: str + software_revision: str routines: List[Routine] tags: List[Tag] @@ -527,6 +538,75 @@ def build(self) -> Routine: return Routine(name, name, routine_type, rungs, rung_ids) +def _parse_fffeff(data: bytes, offset: int): + """Parse one fffeff-encoded string at offset. Returns (str, new_offset).""" + if offset + 3 > len(data) or not (data[offset] == 0xFF and data[offset+1] == 0xFE and data[offset+2] == 0xFF): + return "", offset + length = data[offset+3] + s = data[offset+4:offset+4+length*2].decode("utf-16-le", errors="replace") + return s, offset + 4 + length * 2 + + +def _parse_aoi_nameless(data: bytes) -> dict: + """Extract AOI metadata from its large nameless record.""" + result: dict = {} + + offset = 0x1A + # Three empty fffeff strings + for _ in range(3): + _, offset = _parse_fffeff(data, offset) + + # 8 bytes (unknown - some kind of date, skip) + offset += 8 + + # 2-byte constant (0x0002 observed) + offset += 2 + + # CreatedBy + result["created_by"], offset = _parse_fffeff(data, offset) + + # Software revision at creation time (skip - we want the current one later) + _, offset = _parse_fffeff(data, offset) + + # 4 zero bytes + offset += 4 + + # Empty fffeff placeholder + _, offset = _parse_fffeff(data, offset) + + # CreatedDate FILETIME (8 bytes, Windows FILETIME in 100-ns units) + ft = struct.unpack_from(" AOI: @@ -536,9 +616,36 @@ def build(self) -> AOI: ) results = self._cur.fetchall() - record = results[0][3] + aoi_record = bytes(results[0][3]) name = results[0][0] + # --- Revision (major.minor) from ext[0x01] --- + try: + r = RxGeneric.from_bytes(aoi_record) + exts: Dict[int, bytes] = {e.attribute_id: bytes(e.value) for e in r.extended_records} + e01 = exts.get(0x01, b"") + rev_major = struct.unpack_from(" 0x1B else 1 + rev_minor = struct.unpack_from(" 0x1D else 0 + except Exception: + rev_major, rev_minor = 1, 0 + revision = f"{rev_major}.{rev_minor}" + + # --- Vendor from comps record --- + vlen = struct.unpack_from(" 0xA8 else 0 + vendor: Union[str, None] = aoi_record[0xA8:0xA8+vlen].decode("utf-8", errors="replace") if vlen > 0 else None + + # --- Metadata from large nameless record --- + self._cur.execute( + "SELECT record FROM nameless WHERE parent_id=" + str(self._object_id) + + " ORDER BY LENGTH(record) DESC LIMIT 1" + ) + nameless_row = self._cur.fetchone() + if nameless_row and len(bytes(nameless_row[0])) > 50: + meta = _parse_aoi_nameless(bytes(nameless_row[0])) + else: + meta = {"created_by": "", "created_date": "", "edited_by": "", "edited_date": "", + "software_revision": "", "revision_extension": None} + self._cur.execute( "SELECT comp_name, object_id, parent_id, record FROM comps WHERE parent_id=" + str(self._object_id) @@ -550,7 +657,11 @@ def build(self) -> AOI: if len(collection_results) != 0: collection_id = collection_results[0][1] else: - return AOI(name, name, routines, tags) + return AOI(name, name, revision, meta["revision_extension"], vendor, + "false", "false", "false", + meta["created_date"], meta["created_by"], + meta["edited_date"], meta["edited_by"], + meta["software_revision"], routines, tags) self._cur.execute( "SELECT comp_name, object_id, parent_id, record FROM comps WHERE parent_id=" @@ -561,26 +672,33 @@ def build(self) -> AOI: for child in routine_results: routines.append(RoutineBuilder(self._cur, child[1]).build()) - # Get the Program Scoped Tags + # Get the AOI-Scoped Tags self._cur.execute( "SELECT comp_name, object_id, parent_id, record_type FROM comps WHERE parent_id=" + str(self._object_id) + " AND comp_name='RxTagCollection'" ) - results = self._cur.fetchall() - if len(results) > 1: - raise Exception("Contains more than one program tag collection") + tag_coll = self._cur.fetchall() + if len(tag_coll) > 1: + raise Exception("Contains more than one AOI tag collection") self._cur.execute( "SELECT comp_name, object_id, parent_id, record_type FROM comps WHERE parent_id=" - + str(results[0][1]) + + str(tag_coll[0][1]) ) - results = self._cur.fetchall() - - for result in results: + for result in self._cur.fetchall(): tags.append(TagBuilder(self._cur, result[1]).build()) - return AOI(name, name, routines, tags) + return AOI( + name, name, revision, + meta["revision_extension"], + vendor, + "false", "false", "false", + meta["created_date"], meta["created_by"], + meta["edited_date"], meta["edited_by"], + meta["software_revision"], + routines, tags, + ) @dataclass From 7a4bc093043c7053f317912f38c6ee6f421fd0a7 Mon Sep 17 00:00:00 2001 From: Cody Warren Date: Thu, 26 Mar 2026 11:13:39 -0600 Subject: [PATCH 06/10] Add Program attribute serialization: MainRoutineName, FaultRoutineName, TestEdits, Disabled, UseAsFolder MainRoutineName and FaultRoutineName are stored as object_id references in extended records ext[0x12D] and ext[0x066] respectively. The OIDs are resolved to routine names via a comps lookup. TestEdits, Disabled, and UseAsFolder default to "false" (all observed programs use these defaults; no binary flag identified). Validated: 13/13 Programs match Studio 5000 reference export exactly. Co-Authored-By: Claude Sonnet 4.6 --- acd/l5x/elements.py | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/acd/l5x/elements.py b/acd/l5x/elements.py index 38d7b4f01..5ac4ead12 100644 --- a/acd/l5x/elements.py +++ b/acd/l5x/elements.py @@ -152,6 +152,11 @@ def __post_init__(self): @dataclass class Program(L5xElement): name: str + test_edits: str + main_routine_name: Union[str, None] # None if absent (omitted from XML) + fault_routine_name: Union[str, None] # None if absent (omitted from XML) + disabled: str + use_as_folder: str routines: List[Routine] tags: List[Tag] @@ -710,10 +715,29 @@ def build(self) -> Program: ) results = self._cur.fetchall() - r = RxGeneric.from_bytes(results[0][3]) + prog_record = bytes(results[0][3]) + r = RxGeneric.from_bytes(prog_record) name = results[0][0] + # --- MainRoutineName and FaultRoutineName from extended records --- + # ext[0x12D] = MainRoutine object_id, ext[0x066] = FaultRoutine object_id + exts: Dict[int, bytes] = {e.attribute_id: bytes(e.value) for e in r.extended_records} + main_routine_name: Union[str, None] = None + fault_routine_name: Union[str, None] = None + if 0x12D in exts and len(exts[0x12D]) >= 4: + main_oid = struct.unpack_from(" Date: Thu, 26 Mar 2026 11:36:22 -0600 Subject: [PATCH 07/10] Fix boolean XML serialization: emit lowercase true/false instead of Python's True/False Python str(bool) gives title-case "True"/"False" but XML/L5X expects lowercase. Added isinstance(bool) check in to_xml() before string formatting. Co-Authored-By: Claude Sonnet 4.6 --- acd/l5x/elements.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/acd/l5x/elements.py b/acd/l5x/elements.py index 5ac4ead12..24f57ce61 100644 --- a/acd/l5x/elements.py +++ b/acd/l5x/elements.py @@ -65,6 +65,8 @@ def to_xml(self): else: if attribute == "cls": attribute = "class" + if isinstance(attribute_value, bool): + attribute_value = str(attribute_value).lower() attribute_list.append( f'{attribute.title().replace("_", "")}="{attribute_value}"' ) From db1f74322f481ad215358e7f8bb9087e37c31c9c Mon Sep 17 00:00:00 2001 From: Cody Warren Date: Thu, 26 Mar 2026 11:43:31 -0600 Subject: [PATCH 08/10] Add Controller attribute serialization: Name, MajorRev, MinorRev, MajorFaultProgram, SFCExecution*, ProjectSN, config flags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Controller dataclass restructured: added Use, Name, MajorRev, MinorRev, MajorFaultProgram, ProjectCreationDate, LastModifiedDate, SFCExecutionControl/RestartPosition/LastScan, ProjectSN, and 9 config flags (MatchProjectToController, CanUseRPIFromProducer, etc.) - Removed CommPath (empty and absent from reference) - MajorRev/MinorRev from ext[0x076] bytes[3]/[2]; MajorFaultProgram from ext[0x068] OID lookup - ProjectSN format changed to lowercase hex (16#60e3_5b29) to match reference - Added _xml_attr_overrides mechanism to L5xElement.to_xml() for field→XML name mapping (handles SFCExecutionControl, SFCLastScan, ProjectSN, CanUseRPIFromProducer) - Config flags hardcoded to defaults (all observed controllers use standard settings) - ProcessorType omitted (catalog string not present in binary; requires EDS lookup) - Date timestamps are UTC; reference shows local time (6h offset) — acceptable gap Co-Authored-By: Claude Sonnet 4.6 --- acd/l5x/elements.py | 93 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 71 insertions(+), 22 deletions(-) diff --git a/acd/l5x/elements.py b/acd/l5x/elements.py index 24f57ce61..d77969b9d 100644 --- a/acd/l5x/elements.py +++ b/acd/l5x/elements.py @@ -67,8 +67,10 @@ def to_xml(self): attribute = "class" if isinstance(attribute_value, bool): attribute_value = str(attribute_value).lower() + _overrides = getattr(self, "_xml_attr_overrides", {}) + xml_attr_name = _overrides.get(attribute, attribute.title().replace("_", "")) attribute_list.append( - f'{attribute.title().replace("_", "")}="{attribute_value}"' + f'{xml_attr_name}="{attribute_value}"' ) _export_name = ( @@ -197,13 +199,27 @@ class Task(L5xElement): @dataclass class Controller(L5xElement): - serial_number: str - comm_path: str + use: str + name: str + processor_type: Union[str, None] # None if unknown (omitted from XML) + major_rev: str + minor_rev: str + major_fault_program: Union[str, None] # None if not set (omitted from XML) + project_creation_date: str + last_modified_date: str sfc_execution_control: str sfc_restart_position: str sfc_last_scan: str - created_date: str - modified_date: str + project_sn: str + match_project_to_controller: str + can_use_rpi_from_producer: str + inhibit_automatic_firmware_update: str + pass_through_configuration: str + download_project_documentation_and_extended_properties: str + download_project_custom_properties: str + report_minor_overflow: str + auto_diags_enabled: str + web_server_enabled: str data_types: List[DataType] tags: List[Tag] programs: List[Program] @@ -211,6 +227,16 @@ class Controller(L5xElement): aois: List[AOI] map_devices: List[MapDevice] + def __post_init__(self): + super().__post_init__() + self._xml_attr_overrides = { + "sfc_execution_control": "SFCExecutionControl", + "sfc_restart_position": "SFCRestartPosition", + "sfc_last_scan": "SFCLastScan", + "project_sn": "ProjectSN", + "can_use_rpi_from_producer": "CanUseRPIFromProducer", + } + @dataclass class RSLogix5000Content(L5xElement): @@ -861,27 +887,36 @@ def build(self) -> Controller: extended_record.value ) - comm_path = bytes(extended_records[0x6A][:-2]).decode("utf-16") sfc_execution_control = bytes(extended_records[0x6F][:-2]).decode("utf-16") sfc_restart_position = bytes(extended_records[0x70][:-2]).decode("utf-16") sfc_last_scan = bytes(extended_records[0x71][:-2]).decode("utf-16") - serial_number_raw = hex(struct.unpack("= 4 else "0" + minor_rev = str(rev_bytes[2]) if len(rev_bytes) >= 3 else "0" + + # MajorFaultProgram from ext[0x068] OID → comp_name lookup + major_fault_program: Union[str, None] = None + if 0x068 in extended_records and len(extended_records[0x068]) >= 4: + mfp_oid = struct.unpack_from(" Date: Thu, 26 Mar 2026 11:53:01 -0600 Subject: [PATCH 09/10] Filter I/O module and internal tags from controller tag export MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Exclude colon-delimited tags (e.g. CP_CIP1_01:7:I) — I/O module tags that Studio 5000 excludes from L5X controller tag export - Exclude double-underscore-prefixed tags (__CONTAINER, __DEFVAL_*) — internal system tags not present in reference export Result: 1,096 controller tags (was ~2,077), matching Studio 5000 exactly. Co-Authored-By: Claude Sonnet 4.6 --- acd/l5x/elements.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/acd/l5x/elements.py b/acd/l5x/elements.py index d77969b9d..61a54d15b 100644 --- a/acd/l5x/elements.py +++ b/acd/l5x/elements.py @@ -964,7 +964,7 @@ def build(self) -> Controller: for result in results: _tag_object_id = result[1] tag = TagBuilder(self._cur, _tag_object_id).build() - if tag.data_type and not tag.name.startswith("$"): + if tag.data_type and not tag.name.startswith("$") and ":" not in tag.name and not tag.name.startswith("__"): tags.append(tag) # Get the Program Collection and get the programs From a4428bf26e514b0bb68fbd615c72cd90f520077f Mon Sep 17 00:00:00 2001 From: Cody Warren Date: Thu, 26 Mar 2026 12:10:34 -0600 Subject: [PATCH 10/10] Fix DataType User/ProductDefined classification The built_in field is a flags word, not a boolean. Bits 0 and 1 (mask 0x03) identify ProductDefined types; other bits (e.g. 0x08, 0x10) are orthogonal flags that can appear on user-created types. Old check (built_in > 0) incorrectly excluded Date (built_in=8), CIPRecord, and TitrationLog_SQLNewRow (built_in=16) as ProductDefined. New check (built_in & 0x03) correctly includes them. Result: 22 DataTypes, matching Studio 5000 exactly (was 19). Co-Authored-By: Claude Sonnet 4.6 --- acd/l5x/elements.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/acd/l5x/elements.py b/acd/l5x/elements.py index 61a54d15b..951bd1144 100644 --- a/acd/l5x/elements.py +++ b/acd/l5x/elements.py @@ -369,7 +369,7 @@ def build(self) -> DataType: class_type = "User" if module_defined > 0: class_type = "IO" - if built_in > 0: + if built_in & 0x03: class_type = "ProductDefined" if 0x64 in extended_records and len(extended_records[0x64]) == 0x04: member_count = struct.unpack("