Skip to content

Merge fix/l5x-export-issues: Task/AOI/Program/Controller serialization + ACD write path - #28

Merged
hutcheb merged 11 commits into
hutcheb:mainfrom
cmwarre:merge-upstream-into-fixes
Apr 17, 2026
Merged

hutcheb merged 11 commits into
hutcheb:mainfrom
cmwarre:merge-upstream-into-fixes

Conversation

@cmwarre

@cmwarre cmwarre commented Apr 17, 2026

Copy link
Copy Markdown
Collaborator

Summary

This PR merges cmwarre/acd:fix/l5x-export-issues into hutcheb/acd:main, reconciled with the recently-merged PR #27 (jpect). The two efforts worked in parallel on overlapping L5X export fixes; I did a three-way merge locally, kept the best of both, and verified tests pass.

New features and fixes in this branch

L5X serialization (extending PR #27):

  • Explicit attribute-name override map on Controller for correctly-cased L5X attributes (SFCExecutionControl, SFCRestartPosition, SFCLastScan, ProjectSN, CanUseRPIFromProducer)
  • Lowercase bool emission (True → "true") so Studio 5000 accepts boolean attrs
  • None-valued attributes are skipped entirely (lets individual builders opt fields out of XML cleanly)
  • Structural stub injection on <Controller> (RedundancyInfo, Security, SafetyInfo) — Studio 5000 rejects the L5X without these. <Tasks/> stub is not injected because this branch serialises real tasks.
  • Extended _LIST_SECTION_NAMES dict with tasks and scheduled_programs entries
  • Safer UTF-16 decode helper with missing-key guards in ControllerBuilder

New serialized elements (extracted from the binary databases):

  • Task — type, rate, priority, watchdog decoded from binary; EventInfo for event tasks; ScheduledProgram list resolved via program comment_id lookup
  • AOI metadata — revision, revision extension, vendor, created/edited dates and authors, software revision
  • Program attributes — MainRoutineName, FaultRoutineName, TestEdits, Disabled, UseAsFolder
  • Controller attributes — Name, MajorRev, MinorRev, MajorFaultProgram, SFC* fields, ProjectSN, + a handful of config flags
  • Improved DataType User/ProductDefined classification; I/O module and internal tags filtered from controller tag export

New write path (acd/zip/write_acd.py, acd/zip/write_dat.py):

  • save_acd(project, path) — byte-identical round-trip for unmodified projects
  • patch_rungs(project, changes) — patches ladder rung text in SbRegion.Dat in-memory and writes a valid ACD back out
  • Exposes _raw_files, _file_order, _footer_unknown, _id_to_name on the project for modification flows

Cleaner top-level API (acd/api.py):

  • load_acd(path) → RSLogix5000Content
  • save_acd(project, path)
  • patch_rungs(project, changes)
  • Retains jpect's ConvertAcdToL5x class with pretty-print option

Performance:

  • 130× load speedup on the CuteLogix.ACD fixture (reduces re-query fan-out in TagBuilder/DataTypeBuilder and avoids redundant comps scans in the Controller loop)

Conflict resolution notes (for review)

Test plan

  • All non-environmental tests pass (test_api.py, test_database.py, test_extract_database.py) — 12 tests, 0 failures related to this change
  • test_unzip.py has 5 pre-existing failures on both branches due to an async def sample_acd fixture + non-async tests (unrelated to this merge; needs a separate fix to either drop async on the fixture or install pytest-asyncio and mark tests appropriately)
  • Verify a round-trip L5X import into Studio 5000 Logix Designer
  • Verify save_acd / patch_rungs byte-identical round-trip on a real project file

🤖 Generated with Claude Code

cmwarre and others added 11 commits March 25, 2026 21:02
- 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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
Fixes hutcheb#19, hutcheb#20, hutcheb#22, hutcheb#23, hutcheb#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 <noreply@anthropic.com>
…og from binary

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 <noreply@anthropic.com>
Decode AOI metadata from two sources:
- Comps record: Vendor (u16 length at 0xA6, ASCII string at 0xA8)
- Comps ext[0x01]: Revision major (u16 at 0x1A), Revision minor (u16 at 0x1C)
- Large nameless record: CreatedBy, CreatedDate, EditedBy, EditedDate,
  SoftwareRevision, RevisionExtension via sequential fffeff/FILETIME parsing

Adds helper functions _parse_fffeff() and _parse_aoi_nameless() for the
nameless record parsing.

ExecutePrescan/ExecutePostscan/ExecuteEnableInFalse default to "false"
(all observed AOIs use these defaults; no binary flag found for "true").

Validated: all 28 AOIs in CIPDemo_RevEng.ACD match the Studio 5000 L5X
reference exactly for all metadata fields.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…e, 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 <noreply@anthropic.com>
…ython'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 <noreply@anthropic.com>
…orFaultProgram, SFCExecution*, ProjectSN, config flags

- 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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
Reconciles two parallel L5X export fix efforts. Kept our superset
collection dict, per-attribute XML casing overrides, lowercase bool
emission, and None-skip; folded in jpect's _l5x_exclude exclusion
mechanism, ConvertAcdToL5x pretty-print API, safer UTF-16 decoding
with missing-key guards, UTF-8 decode errors=replace, and structural
stub injection (RedundancyInfo/Security/SafetyInfo — Tasks omitted
since we serialise real tasks).

Dropped jpect's _name auto-emit (would add spurious Name attr to
RSLogix5000Content) and ClassVar _xml_element_name (redundant with
our _export_name __post_init__ pattern).

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
@hutcheb
hutcheb merged commit 3b91e57 into hutcheb:main Apr 17, 2026
5 checks passed
cmwarre pushed a commit to cmwarre/acd that referenced this pull request Apr 18, 2026
Merge fix/l5x-export-issues: Task/AOI/Program/Controller serialization + ACD write path
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants