Skip to content

Commit 2d96f98

Browse files
authored
Merge pull request #45 from nokkies/feat/catalog-number-fallback
Feat/catalog number fallback
2 parents 50e0c11 + e8477af commit 2d96f98

13 files changed

Lines changed: 1078 additions & 40 deletions

‎acd/api.py‎

Lines changed: 64 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,13 @@
66
from dataclasses import dataclass
77
from os import PathLike
88
from pathlib import Path
9+
from typing import Dict, Tuple, Union
910

11+
from acd.l5x.catalog_numbers import (
12+
CATALOG_NUMBERS,
13+
load_external_catalog,
14+
merge_catalog,
15+
)
1016
from acd.integrity import (
1117
FILEINFO_LENGTH,
1218
compute_fileinfo,
@@ -24,15 +30,39 @@
2430
from acd.l5x.elements import DumpCompsRecords, RSLogix5000Content
2531

2632

33+
def _resolve_catalog_table(catalog_file: Union[PathLike, Dict[Tuple[int, int, int], str], None]):
34+
"""Resolve a catalog argument into a merged CIP-identity -> catalog table.
35+
36+
- None -> None (ExportL5x uses the built-in CATALOG_NUMBERS; unchanged).
37+
- a dict -> used as the override (merged over the built-in table).
38+
- a path -> load_external_catalog(path), then merge over the built-in table.
39+
40+
The merged table is what the builders pass to catalog_number_for_identity,
41+
so an out-of-table identity that IS in the external catalog resolves to a
42+
real part number (clean Studio import); one that is NOT still falls back to
43+
the CIP-... placeholder. This is the A3 fix made data-driven.
44+
"""
45+
if catalog_file is None:
46+
return None
47+
if isinstance(catalog_file, dict):
48+
external = catalog_file
49+
else:
50+
external = load_external_catalog(str(catalog_file))
51+
return merge_catalog(CATALOG_NUMBERS, external)
52+
53+
2754
# Clean top-level API
2855

29-
def load_acd(path, temp_dir: str = None) -> RSLogix5000Content:
56+
def load_acd(path, temp_dir: str = None, catalog_file=None) -> RSLogix5000Content:
3057
"""Load an ACD file into a Python object model.
3158
3259
Args:
3360
path: Path to the .ACD file.
3461
temp_dir: Directory for SQLite and extracted files. A temporary
3562
directory is created and cleaned up automatically if omitted.
63+
catalog_file: Optional external catalog (JSON path or dict) merged over
64+
the built-in table so out-of-table CPUs/modules resolve to real part
65+
numbers. None -> built-in only (default, unchanged).
3666
3767
Returns:
3868
RSLogix5000Content with a fully populated controller object tree.
@@ -43,7 +73,7 @@ def load_acd(path, temp_dir: str = None) -> RSLogix5000Content:
4373
if cleanup:
4474
temp_dir = tempfile.mkdtemp(prefix="acd_load_")
4575
try:
46-
exporter = ExportL5x(str(path), temp_dir)
76+
exporter = ExportL5x(str(path), temp_dir, _catalog_table=_resolve_catalog_table(catalog_file))
4777
return exporter.project
4878
finally:
4979
if cleanup:
@@ -161,10 +191,16 @@ class ImportProjectFromFile(ImportProject):
161191
"""Import a Controller from an ACD stored on file"""
162192

163193
filename: PathLike
194+
# Optional external catalog (a CIP-identity -> catalog-number JSON file, OR an
195+
# already-loaded dict). When given, it is merged over the built-in table so an
196+
# out-of-table CPU/module resolves to a real part number (clean Studio import).
197+
# None -> built-in table only (default, unchanged behaviour).
198+
catalog_file: Union[PathLike, dict, None] = None
164199

165200
def import_project(self) -> RSLogix5000Content:
166201
# Import Project Interface
167-
export = ExportL5x(self.filename)
202+
table = _resolve_catalog_table(self.catalog_file)
203+
export = ExportL5x(self.filename, _catalog_table=table)
168204
return export.project
169205

170206

@@ -251,11 +287,21 @@ class DumpCompsRecordsToFile(ExportProject):
251287

252288
def extract(self):
253289
export = ExportL5x(self.filename)
290+
# The README documents dumping to a fresh directory
291+
# (DumpCompsRecordsToFile("My.ACD", "output/")). Ensure that directory
292+
# exists before writing output.log into it; previously a non-existent
293+
# output_directory raised FileNotFoundError.
294+
os.makedirs(self.output_directory, exist_ok=True)
254295
with open(
255296
os.path.join(self.output_directory, "output.log"),
256297
"w",
257298
) as log_file:
258-
DumpCompsRecords(export._cur, 0).dump(log_file=log_file)
299+
# Write the record tree into the same output_directory (previously
300+
# it defaulted to "./dump", so output.log and the tree ended up in
301+
# different places).
302+
DumpCompsRecords(
303+
export._cur, 0, base_directory=self.output_directory
304+
).dump(log_file=log_file)
259305

260306

261307
@dataclass
@@ -271,15 +317,26 @@ class ConvertAcdToL5x(Extract):
271317
272318
:param PathLike acd_filename: Path to the source .ACD file.
273319
:param PathLike l5x_filename: Path for the output .L5X file.
274-
:param bool pretty_print: Pretty-print the XML output (default True).
320+
:param bool pretty_print: Pretty-print the XML output (default False).
321+
Default is False because the raw to_xml() format is what Studio 5000
322+
expects: minidom.toprettyxml inserts blank lines between <Port> elements
323+
inside <Ports>, which Studio's strict L5X parser rejects with "Required
324+
property 'Port' was missing". The known-good reference files (resources/)
325+
are not pretty-printed. Set pretty_print=True only for human reading.
275326
"""
276327

277328
acd_filename: PathLike
278329
l5x_filename: PathLike
279-
pretty_print: bool = True
330+
pretty_print: bool = False
331+
# Optional external catalog (JSON path or dict); merged over the built-in
332+
# table so out-of-table CPUs/modules resolve to real part numbers. None ->
333+
# built-in only (default, unchanged). See _resolve_catalog_table.
334+
catalog_file: Union[PathLike, Dict[Tuple[int, int, int], str], None] = None
280335

281336
def extract(self):
282-
project = ImportProjectFromFile(self.acd_filename).import_project()
337+
project = ImportProjectFromFile(
338+
self.acd_filename, catalog_file=self.catalog_file
339+
).import_project()
283340
raw_xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' + project.to_xml()
284341
if self.pretty_print:
285342
try:

‎acd/l5x/catalog_numbers.py‎

Lines changed: 188 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
11
# Maps (vendor, product_type, product_code) → CatalogNumber string.
22
# Built from Logix-exported L5X files; not stored in the ACD binary.
3-
from typing import Dict, Tuple
3+
import json
4+
from typing import Dict, Optional, Tuple
5+
6+
7+
class CatalogError(ValueError):
8+
"""Raised when an external catalog file is malformed.
9+
10+
A catalog that fails to validate is a data error the caller can fix, so it
11+
is surfaced loudly (not swallowed) rather than silently producing wrong
12+
catalog numbers.
13+
"""
414

515
CATALOG_NUMBERS: Dict[Tuple[int, int, int], str] = {
616
(1, 0, 18): "ETHERNET-MODULE",
@@ -27,6 +37,8 @@
2737
(1, 14, 72): "1769-L33ERM",
2838
(1, 14, 93): "1756-L72",
2939
(1, 14, 94): "1756-L73",
40+
(1, 14, 164): "1756-L81E",
41+
(1, 14, 165): "1756-L82E",
3042
(1, 14, 166): "1756-L83E",
3143
(1, 14, 167): "1756-L84E",
3244
(1, 14, 168): "1756-L85E",
@@ -40,6 +52,180 @@
4052
(1182, 0, 4177): "Promass_83/A",
4153
(1182, 43, 4154): "Promag_100",
4254
(1182, 43, 4155): "Promass_300_500",
43-
(1182, 43, 4156): "Promag_300_500",
55+
(1182, 43, 4156): "Promass_300_500",
4456
(1182, 43, 4170): "Promass_100",
4557
}
58+
59+
60+
def _identity_key_from_any(raw: object) -> Optional[Tuple[int, int, int]]:
61+
"""Coerce a catalog key into an (int, int, int) identity, or None.
62+
63+
Accepts the two natural JSON shapes: a 3-element array/tuple
64+
``[vendor, product_type, product_code]`` or an object
65+
``{"vendor": v, "product_type": t, "product_code": c}``. Returns None
66+
when the shape is unrecognised so the caller can raise a clear error.
67+
"""
68+
if isinstance(raw, (list, tuple)) and len(raw) == 3:
69+
try:
70+
return (int(raw[0]), int(raw[1]), int(raw[2]))
71+
except (TypeError, ValueError):
72+
return None
73+
if isinstance(raw, dict):
74+
try:
75+
return (
76+
int(raw["vendor"]),
77+
int(raw["product_type"]),
78+
int(raw["product_code"]),
79+
)
80+
except (KeyError, TypeError, ValueError):
81+
return None
82+
return None
83+
84+
85+
def load_external_catalog(path: str) -> Dict[Tuple[int, int, int], str]:
86+
"""Load and validate a JSON catalog of CIP identity → catalog number.
87+
88+
The file is a mapping from an identity triple to a catalog-number string.
89+
Two key shapes are accepted (per entry, or as a single wrapper):
90+
* array: ``{"1:12:166": "1756-EN2T"}`` or ``{"entries": {"1:12:166": ...}}``
91+
* object: ``{"1:12:166": "1756-EN2T"}`` where the key is
92+
``"vendor:product_type:product_code"`` (e.g. ``"1:12:166"``)
93+
94+
The colon-joined string form is chosen deliberately: identity triples are
95+
stable, sortable, and unambiguous when written as ``v:t:c``. Every value
96+
must be a non-empty string; every key must parse as three non-negative
97+
integers. The result is a plain dict keyed by the (v, t, c) tuple, ready
98+
to be passed to ``catalog_number_for_identity(table=...)`` or merged over
99+
``CATALOG_NUMBERS``.
100+
101+
This is the extension point for a shared, richer catalog (Rockwell's own
102+
data, or the module templates aei-logix5000 extracts) so that adding a
103+
part number is a data change, not a code change.
104+
"""
105+
with open(path, "r", encoding="utf-8") as fh:
106+
data = json.load(fh)
107+
108+
if not isinstance(data, dict):
109+
raise CatalogError(f"external catalog root must be a JSON object: {path}")
110+
if "entries" in data and isinstance(data.get("entries"), dict):
111+
data = data["entries"]
112+
113+
out: Dict[Tuple[int, int, int], str] = {}
114+
for key, value in data.items():
115+
# Allow "_"-prefixed metadata keys (e.g. "_comment") for documentation
116+
# inside the JSON; they are skipped, not validated, so a file can carry
117+
# a human-readable note and still load.
118+
if isinstance(key, str) and key.startswith("_"):
119+
continue
120+
identity = _identity_key_from_any(key)
121+
if identity is None:
122+
# Try the "v:t:c" string form.
123+
identity = _parse_colon_key(key)
124+
if identity is None:
125+
raise CatalogError(
126+
f"unrecognised catalog identity key {key!r} in {path}"
127+
)
128+
if not isinstance(value, str) or not value.strip():
129+
raise CatalogError(
130+
f"catalog value for identity {identity} must be a non-empty "
131+
f"string in {path}"
132+
)
133+
v, t, c = identity
134+
if v < 0 or t < 0 or c < 0:
135+
raise CatalogError(f"identity {identity} has a negative component in {path}")
136+
out[identity] = value.strip()
137+
return out
138+
139+
140+
def _parse_colon_key(key: object) -> Optional[Tuple[int, int, int]]:
141+
"""Parse a ``"vendor:product_type:product_code"`` string key."""
142+
if not isinstance(key, str):
143+
return None
144+
parts = key.split(":")
145+
if len(parts) != 3:
146+
return None
147+
try:
148+
return (int(parts[0]), int(parts[1]), int(parts[2]))
149+
except ValueError:
150+
return None
151+
152+
153+
def merge_catalog(
154+
base: Optional[Dict[Tuple[int, int, int], str]] = None,
155+
overrides: Optional[Dict[Tuple[int, int, int], str]] = None,
156+
) -> Dict[Tuple[int, int, int], str]:
157+
"""Return a new table = ``base`` with ``overrides`` applied on top.
158+
159+
``base`` defaults to the built-in ``CATALOG_NUMBERS``. ``overrides``
160+
(typically from ``load_external_catalog``) win on any conflicting
161+
identity. Neither input is mutated.
162+
"""
163+
base = CATALOG_NUMBERS if base is None else base
164+
if not overrides:
165+
return dict(base)
166+
merged = dict(base)
167+
merged.update(overrides)
168+
return merged
169+
170+
171+
def _fallback_catalog_number(identity: Tuple[int, int, int]) -> str:
172+
"""Derive a structured CatalogNumber for a CIP identity not in the table.
173+
174+
The ACD binary stores hardware identity only as (vendor, product_type,
175+
product_code) -- the human-readable catalog number is NOT present in the
176+
file (that is the whole reason this table exists). When the identity is
177+
unknown we must not emit an empty CatalogNumber: Studio 5000 will reject
178+
or mis-resolve a module whose CatalogNumber attribute is blank, while the
179+
raw identity is always known and unambiguous.
180+
181+
The fallback is a deterministic, self-describing placeholder in the form
182+
``CIP-<vendor>-<product_type>-<product_code>``. It is a stable key that
183+
(a) always round-trips the module's true hardware identity into the L5X,
184+
(b) is trivially greppable so a missing table entry is obvious, and (c)
185+
can be matched against the CIP registry (vendor/product type/product code
186+
are the canonical CIP identity fields) to recover the real catalog number
187+
offline. Callers that have a richer catalog (e.g. Rockwell's own) should
188+
override ``CATALOG_NUMBERS`` or call this helper with their own table.
189+
"""
190+
vendor, product_type, product_code = identity
191+
return f"CIP-{vendor}-{product_type}-{product_code}"
192+
193+
194+
def catalog_number_for_identity(
195+
identity: Tuple[int, int, int],
196+
table: Optional[Dict[Tuple[int, int, int], str]] = None,
197+
) -> str:
198+
"""Resolve the CatalogNumber string for a CIP identity triple.
199+
200+
Resolution order:
201+
1. the ``table`` (default: the built-in ``CATALOG_NUMBERS``), or
202+
2. a structured ``CIP-<vendor>-<type>-<code>`` placeholder.
203+
204+
To use a richer/shared catalog (Rockwell's own data, or the module
205+
templates aei-logix5000 extracts), load it with
206+
:func:`load_external_catalog`, combine it with :func:`merge_catalog`
207+
(external entries win), and pass the result as ``table=``::
208+
209+
from acd.l5x.catalog_numbers import (
210+
load_external_catalog, merge_catalog,
211+
)
212+
table = merge_catalog(None, load_external_catalog("shared_catalog.json"))
213+
number = catalog_number_for_identity((1, 14, 216), table=table)
214+
215+
A zero identity ``(0, 0, 0)`` means the module record did not carry a
216+
CIP identity at all (e.g. an unparseable record); for that case an empty
217+
string is returned rather than a fabricated identity, so the caller can
218+
distinguish "no identity present" from "identity present but unknown".
219+
220+
This is the single choke point for catalog resolution: ``ModuleBuilder``
221+
calls it instead of indexing ``CATALOG_NUMBERS`` directly, so adding a
222+
better catalog (or a CIP-registry lookup) is a one-line change here and
223+
every module benefits.
224+
"""
225+
if table is None:
226+
table = CATALOG_NUMBERS
227+
if identity == (0, 0, 0):
228+
return ""
229+
if identity in table:
230+
return table[identity]
231+
return _fallback_catalog_number(identity)

0 commit comments

Comments
 (0)