diff --git a/acd/api.py b/acd/api.py index 5a2ccc204..64204f184 100644 --- a/acd/api.py +++ b/acd/api.py @@ -1,16 +1,95 @@ import os +import tempfile +import shutil import xml.dom.minidom 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.zip.write_dat import patch_sbregion_dat 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, + ) + + +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 5a9d466e7..ff99544c0 100644 --- a/acd/l5x/elements.py +++ b/acd/l5x/elements.py @@ -7,29 +7,31 @@ from os import PathLike from pathlib import Path from sqlite3 import Cursor -from typing import ClassVar, List, Tuple, Dict, Union +from typing import List, Tuple, Dict, Union from acd.generated.comps.rx_generic import RxGeneric -# Maps Python attribute names to their L5X XML collection element names. -# Explicit mapping avoids title()-based casing bugs (e.g. "Datatypes" vs "DataTypes") -# and handles non-obvious names like aois -> AddOnInstructionDefinitions. -_XML_COLLECTION_NAMES: Dict[str, str] = { + +@dataclass +class L5xElementBuilder: + _cur: Cursor + _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", + "tasks": "Tasks", + "scheduled_programs": "ScheduledPrograms", } -@dataclass -class L5xElementBuilder: - _cur: Cursor - _object_id: int = -1 - - @dataclass class L5xElement: _name: str @@ -40,55 +42,42 @@ def __post_init__(self): def to_xml(self) -> str: attribute_list: List[str] = [] child_list: List[str] = [] - - # Emit _name as Name="..." for elements that don't already have a public 'name' - # field (Tag, DataType, Member, Routine all declare name as a public dataclass - # field and will emit it via the normal attribute loop — emitting it here too - # would produce a duplicate attribute and invalid XML). - # RSLogix5000Content sets _name equal to the class name as a sentinel; skip that too. - class_name = type(self).__name__ - if ( - hasattr(self, "_name") - and self._name - and self._name != class_name - and "name" not in self.__dict__ - ): - attribute_list.append(f'Name="{self._name}"') - 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): - if attribute in _XML_COLLECTION_NAMES: + 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): - # Skip elements marked for L5X exclusion (e.g. ProductDefined - # data types, tags with corrupt/hex-placeholder names). - # This keeps the in-memory model intact while cleaning up - # the XML output — avoids breaking existing API consumers. if getattr(element, "_l5x_exclude", False): continue new_child_list.append(element.to_xml()) else: new_child_list.append(f"<{element}/>") - coll_name = _XML_COLLECTION_NAMES[attribute] child_list.append( - f'<{coll_name}>{"".join(new_child_list)}' + f'<{section_name}>{"".join(new_child_list)}' ) else: if attribute == "cls": 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}"' ) - # Use _xml_element_name class variable if defined (e.g. AOI -> AddOnInstructionDefinition) - # otherwise fall back to the Python class name directly (no .title() — preserves casing) - export_name = getattr(type(self), "_xml_element_name", class_name) - return f'<{export_name} {" ".join(attribute_list)}>{"".join(child_list)}' + _export_name = ( + getattr(self, "_export_name", "") or self.__class__.__name__.title().replace("_", "") + ) + return f'<{_export_name} {" ".join(attribute_list)}>{"".join(child_list)}' @dataclass @@ -108,9 +97,12 @@ class DataType(L5xElement): cls: str members: List[Member] + def __post_init__(self): + super().__post_init__() + self._export_name = "DataType" + @property def _l5x_exclude(self) -> bool: - """Exclude ProductDefined (firmware built-in) types from L5X export.""" return self.cls == "ProductDefined" @@ -146,46 +138,124 @@ class Routine(L5xElement): name: str type: str rungs: List[str] + _rung_ids: List[int] = field(default_factory=list) @dataclass class AOI(L5xElement): - _xml_element_name: ClassVar[str] = "AddOnInstructionDefinition" + 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] + def __post_init__(self): + super().__post_init__() + self._export_name = "AddOnInstructionDefinition" + @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] +@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 - 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] + tasks: List[Task] 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", + } + def to_xml(self) -> str: base = super().to_xml() - # Inject L5X-required stub sections that the generic model doesn't carry. - # Without these, Studio 5000 may reject the file as structurally incomplete. + # Studio 5000 rejects the L5X without these structural sections. Tasks is + # omitted because we serialise real tasks via the collection loop. stubs = ( '' '' '' - '' ) closing = "" return base[: -len(closing)] + stubs + closing @@ -205,7 +275,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: @@ -321,7 +392,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(" 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) + + +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: ) 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) @@ -556,7 +725,11 @@ 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, 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=" @@ -567,26 +740,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, 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 @@ -598,10 +778,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(" 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("= 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(" 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(" 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("