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)}{coll_name}>'
+ f'<{section_name}>{"".join(new_child_list)}{section_name}>'
)
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}>'
+ _export_name = (
+ getattr(self, "_export_name", "") or self.__class__.__name__.title().replace("_", "")
+ )
+ return f'<{_export_name} {" ".join(attribute_list)}>{"".join(child_list)}{_export_name}>'
@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("