nxp-monkey fetch

Purpose

Download and unpack NXP MCUXpresso Config Tools data for one or more parts into the local cache and mirror the result into a working directory tree split by media type. Positional inputs may be exact NXP portfolio keys, concrete orderable MPNs, or prefixes. This is the primary data-acquisition entry point for both human users and LLM/agent workflows.

Usage

nxp-monkey fetch PART [PART ...] [--variant VARIANT] [--version VERSION]
                  [--force] [--output DIR]
                  [--no-json-mirror]
                  [--json-mirror-only PATTERN] [--json-mirror-skip PATTERN]
nxp-monkey fetch --family PREFIX [...same flags...]
nxp-monkey fetch --all              [...same flags...]

Selection

Form	Effect
positional PARTs	Resolve each value as an exact part, concrete orderable alias, or prefix, then fetch every matched part.
--family PREFIX	Fetch every part whose name starts with PREFIX.
--all	Fetch every part in the portfolio.

NXP portfolio keys often contain masked characters, for example MIMX9352xxxxM. A concrete BOM/orderable value such as MIMX9352CVVXMAB resolves to that key when it is unique. A shorter value such as MIMX93 expands like a prefix and may fetch many keys; use --variant ksdk2_0 when only the canonical silicon-data binder is needed.

Variant handling

By default, fetch pulls every SDK variant NXP publishes for the part (ksdk2_0 + zephyr3_2 + i_mx_2_0). The theme is "grab everything; the agent sorts it out." Variants the part does not publish are silently skipped. Use --variant VARIANT to restrict to a single SDK variant; doing so makes a missing variant an error rather than a skip. ksdk2_0 remains the canonical silicon-data variant per ADR-0008 — the all-variants default supplements it with Zephyr DT codegen scripts and i.MX Linux binders.

Output layout

The platformdirs cache is always populated. In addition, each fetched part is mirrored into DIR/<PART>/ under --output (cwd when absent), split by media type so an agent can consume either side without an XML parser:

DIR/<PART>/
  xml/                              # raw NXP binders, one subdir per SDK variant
    ksdk2_0/...                     #   canonical silicon data (registers, pins, clocks)
    zephyr3_2/...                   #   Zephyr DT codegen scripts
    i_mx_2_0/...                    #   i.MX Linux binder (when published)
  json/
    <PART>.json                    # PartDetails spine: header, cores, packages, db_links
    <PART>.roadmap.json            # agent guide + inferred schema + folder layout
    ksdk2_0/...                     # full lossless XML->JSON mirror (one .json per .xml)
    zephyr3_2/...
    i_mx_2_0/...

Existing destination trees are replaced. The JSON sidecars (<PART>.json, <PART>.roadmap.json) and the XML -> JSON mirror are always written; they are independent of the global --json flag. The roadmap describes the layout, key file pointers per variant, and the observed XML namespaces.

XML -> JSON mirror

For each fetched variant, fetch walks the XML tree and writes a parallel .json tree under DIR/<PART>/json/<VARIANT>/. The conversion is lossless for data: tags are namespace-stripped, attributes are @attr keys, mixed text uses #text, repeated children become lists, and the source xmlns map is preserved on the root as @_xmlns. See nxp_monkey/xml_json.py.

Flag	Effect
`--no-json-mirror`	Skip the per-file XML->JSON conversion. The spine and roadmap are still written.
`--json-mirror-only PATTERN`	Only convert files whose variant-relative path matches PATTERN (fnmatch glob). Repeatable.
`--json-mirror-skip PATTERN`	Skip files matching PATTERN. Repeatable. Applied after `--json-mirror-only`.

Stdout / stderr

Stdout is one absolute path per line: the mirrored DIR/<PART>/ directory for each part fetched. Stays clean for pipeline use. If a bulk or expanded selection produces no fetched variants, the command exits non-zero with a concise error.

Stderr carries two rich progress views: a transferred-bytes bar with one row per (part, variant) while ZIPs are streamed from NXP, then a per-(part, variant) bar with an M of N column while the XML->JSON mirror is written. Redirect 2>/dev/null if undesired. Programmatic callers should prefer the library API and pass progress_callback= to fetch() / mirror_xml_tree_as_json().

--json invocation summary

With the global --json flag, fetch additionally writes a fetch.json file in DIR summarising the invocation (parts, variants, version, per-part mirror paths, mirror file counts) and prints that path on stdout instead of the per-part directories. JSON sidecars and the mirror are written either way.

Library equivalent

# Library fetch operates on a single (part, variant) at a time and
# returns the unpacked processors tree path.
from nxp_monkey import fetch, DEFAULT_SDK_VARIANTS, NxpFetchError
for variant in DEFAULT_SDK_VARIANTS:
    try:
        fetch("MIMX9352CVVXMAB", variant=variant)
    except NxpFetchError:
        pass  # Part may not publish every variant.

# JSON spine + roadmap + mirror are exposed separately:
from nxp_monkey import details, build_roadmap
from nxp_monkey.xml_json import mirror_xml_tree_as_json

Tests

tests/L0_public_cli/test_fetch_cli.py
tests/L3_public_workflows/test_fetch.py