|
1 | 1 | # Maps (vendor, product_type, product_code) → CatalogNumber string. |
2 | 2 | # 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 | + """ |
4 | 14 |
|
5 | 15 | CATALOG_NUMBERS: Dict[Tuple[int, int, int], str] = { |
6 | 16 | (1, 0, 18): "ETHERNET-MODULE", |
|
27 | 37 | (1, 14, 72): "1769-L33ERM", |
28 | 38 | (1, 14, 93): "1756-L72", |
29 | 39 | (1, 14, 94): "1756-L73", |
| 40 | + (1, 14, 164): "1756-L81E", |
| 41 | + (1, 14, 165): "1756-L82E", |
30 | 42 | (1, 14, 166): "1756-L83E", |
31 | 43 | (1, 14, 167): "1756-L84E", |
32 | 44 | (1, 14, 168): "1756-L85E", |
|
40 | 52 | (1182, 0, 4177): "Promass_83/A", |
41 | 53 | (1182, 43, 4154): "Promag_100", |
42 | 54 | (1182, 43, 4155): "Promass_300_500", |
43 | | - (1182, 43, 4156): "Promag_300_500", |
| 55 | + (1182, 43, 4156): "Promass_300_500", |
44 | 56 | (1182, 43, 4170): "Promass_100", |
45 | 57 | } |
| 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