udsdoc 0.71.0

Generate UDS (ISO 14229 / 15765) specification documents and ISO 22901-1 ODX/PDX from AUTOSAR DCM/CanTp/DEM ARXML (formerly udsxml2tex)

udsdoc

AUTOSAR DCM/CanTp/DEM ARXML → ISO 14229 (UDS) / ISO 15765 / ISO 22901-1 (ODX/PDX) specification documents.

Renamed from udsxml2tex (v0.66.0). The old PyPI package now installs this one; the udsxml2tex CLI command, UDSXML2TEX_* environment variables, ~/.udsxml2tex/ config directory and udsxml2tex-* pre-commit hook ids keep working as deprecated aliases until v1.0. Migration: pip install udsdoc, command udsdoc, import udsdoc.

udsdoc parses AUTOSAR diagnostic ARXML (DCM, CanTp, DEM, DoIP, COM, AP) and renders a complete UDS specification in LaTeX / PDF / HTML / Markdown / RST, plus ASAM ODX 2.2.0 / PDX (ISO 22901-1) for industry diagnostic tooling.

It also ships a local browser UI (--serve) that one-clicks an entire BSW software repository through the pipeline, auto-detecting single-ECU vs multi-ECU layouts.

---

Install

pip install udsdoc                  # core (LaTeX / Markdown / RST)
pip install udsdoc[web]             # browser UI (--serve) + inline TikZ-UML SVG figures
pip install udsdoc[llm]             # LLM analysis (Anthropic + OpenAI / Ollama)
pip install udsdoc[ecu-test]        # CAN/ISO-TP hardware testing
pip install udsdoc[all]             # everything

Other extras: yaml, svg, watch, lsp, progress, rich, viz.

A LaTeX distribution (TeX Live / MiKTeX with xelatex for CJK) is required to compile generated .tex to PDF. The HTML output renders standalone. TikZ-UML diagrams in the HTML output (SID 0x10 session FSM, SID 0x27 SecurityAccess FSM and sequence) are compiled to inline SVG when xelatex plus a PDF→SVG tool are present — the [web] / [svg] extras pull in pymupdf, which provides an in-process PDF→SVG converter so no system binary (pdftocairo / dvisvgm / pdf2svg / inkscape) is required. Without the toolchain the HTML output silently falls back to Mermaid.

---

Quick start

# Single ARXML → LaTeX
udsdoc dcm.arxml -o spec.tex

# Merge DCM + CanTp + DEM
udsdoc dcm.arxml cantp.arxml --dem dem.arxml -o spec.tex

# Auto-discover everything under a BSW repo (CLI mirror of the browser UI)
udsdoc --repo /path/to/bsw-project -o spec.tex
udsdoc --repo /path/to/bsw-project --repo-dry-run     # show classification

# Application + Bootloader ARXMLs owned by separate teams — placed in
# parallel subtrees (app/, boot/) under the repo root. The scanner
# detects boot-domain files by path tokens (boot/, bootloader/, bl/,
# fbl/, pbl/, sbl/, *_boot*, *_bl*) and merges them into ONE spec with
# the Drive vs Boot domain tagged per session / service / DID / RID.
udsdoc --repo /path/to/bsw-project -o spec.tex
#   → "INFO: …merged bootloader spec (1 sessions, 1 dids, 1 routines)"

# Hand-off helper: OEM team has only a requirement-analysis CSV (Compliance Matrix
# format from `udsdoc --compliance-matrix-csv …`) and needs a Dcm ARXML skeleton
# to give the external bootloader supplier as the contract. Generate one
# without parsing any ARXML at all:
udsdoc --gen-arxml-from-csv oem_boot_requirements.csv \
           --gen-arxml-output   boot_skeleton.arxml \
           --gen-arxml-ecu-name BootMcuA \
           --gen-arxml-domain   boot          # boot|drive|both|all

# Output formats
udsdoc dcm.arxml --format html  -o spec.html
udsdoc dcm.arxml --format md    -o spec.md
udsdoc dcm.arxml --format pdx   -o ecu.pdx            # ISO 22901-1 PDX
udsdoc dcm.arxml --pdf                                 # compile to PDF

# Multi-language output:
#   --lang en+ja+de   → ONE document with stacked translations (browser UI default)
#   --langs en,ja,de  → one document per language (legacy multi-file mode)
udsdoc dcm.arxml --lang en+ja+de  -o spec.tex
udsdoc dcm.arxml --langs en,ja,de -o spec.md --format md

# Validation, diff, multi-ECU systems
udsdoc dcm.arxml --validate
udsdoc new.arxml --diff old.arxml
udsdoc --system system.yaml --system-output-dir out/   # 1+1 / gateway

# Browser UI
udsdoc --serve                                         # http://127.0.0.1:8765

Python API

from udsdoc import ArxmlParser, TexGenerator, validate, diff_specs

spec = ArxmlParser().parse_multi(["dcm.arxml", "cantp.arxml"])
TexGenerator().generate(spec, "spec.tex")
TexGenerator().compile_pdf("spec.tex")

print(validate(spec).summary())                # ISO 14229-1 consistency
print(diff_specs(spec_a, spec_b).to_markdown())

---

Features

Coverage

• DCM (ISO 14229-1) — sessions, security, all 26 standard services, DIDs, routines, DTCs, memory ranges, IO control / periodic / dynamic DIDs, Authentication, ResponseOnEvent, LinkControl, multi-client.
• CanTp (ISO 15765-2) — channels, BS/STmin, N_As/Bs/Cs/Ar/Br/Cr, addressing.
• DEM (ISO 14229-1 §11) — DTC config, OBD/WWH-OBD, freeze frames, extended data, operation cycles, indicators, combined DTCs.
• DoIP (ISO 13400), Communication ARXML, Adaptive Platform service interfaces.
• C/C++ source scanning — DID/RID global variables (transitive depth ≤3).
• Bootloader overlay — single document covering Drive + Boot domains via YAML.

Output

• tex (Jinja2 + structured ZIP), pdf (xelatex/latexmk), html (multi-page ZIP with offline Mermaid + NRC ladders), md, rst, odx, pdx.
• Visualizations: heatmaps, timing diagrams, UML sequences, byte-level DID maps, session/security FSMs.

Requirements Compliance (ASPICE SYS.2.BP4 / ISO 26262-8 §6.4.5)

• --compliance-matrix CSV [CSV ...] + --compliance-matrix-sources YAML — append a Requirements Compliance Matrix chapter to the LaTeX/PDF output that joins each upstream requirement against the parsed ARXML (SID / DID / RID / DTC / session / security level). Resolved coverage % is computed and shown; unresolved rows are flagged with an asterisk.

Quality

• --validate — 17 ISO 14229-1 consistency checks.
• --diff — semantic spec diff between two ARXML baselines.
• --iso-version {2006,2013,2020} — drop features outside the chosen revision.
• --autosar-compat-report — flag features postdating the detected AUTOSAR release.
• Schema export: JSON Schema (draft-07), Pydantic v2 model source.

LLM analysis ([llm] extra)

• --llm-summarize, --llm-query, --llm-nrc-descriptions, --llm-translate.
• Backends: Anthropic Claude API or any OpenAI-compatible server (Ollama, llama.cpp, vLLM, OpenRouter, Azure). One-shot setup: udsdoc --bootstrap-ollama (Linux/macOS), or use the browser UI's Chat tab — pick any supported OSS model from the catalogue dropdown and press Install (progress bar included).

ECU hardware testing ([ecu-test] extra)

• Auto-generates UDS test cases from the parsed spec, executes over CAN / ISO-TP via python-can. Heuristic generator or formal --ecu-formal state-machine explorer (all-transitions coverage). HTML / JUnit XML / CSV / coverage reports.

Multi-ECU systems

• Declarative YAML config (--system) for redundant / gateway-with-forwarder topologies, per-ECU spec + integration document, ARXML coverage-gap routing inference, cross-ECU validator.

Browser UI (--serve, [web] extra)

• Local FastAPI server with four sidebar tabs:
  • Generate — pick a BSW repository folder; the server uploads UDS-relevant files (.arxml, .c, .h, .yaml, .json), classifies each ARXML by AUTOSAR module, auto-detects single vs multi-ECU, and generates the chosen format. format=tex ZIPs include a compiled spec.pdf when xelatex is on PATH; otherwise the UI flags the failure (and the ZIP carries a PDF_NOT_COMPILED.txt with the underlying reason). Optional Compliance Matrix (Compliance Matrix) CSV upload (ASPICE SYS.2.BP4 / ISO 26262-8 §6.4.5 — DOORS-style) appends a per-row compliance chapter with LaTeX \cite{} references; a Load sample bundle button materialises a complete demo repo + two Compliance Matrix CSVs server-side for a one-click pipeline preview. An Export ODX / PDX card turns the loaded repo session into an ODX 2.2 PDX bundle for CANalyzer & CANoe in one click.
  • Spec — parsed SID / NRC / DID / RID / DTC tables shown after a successful Parse & Preview.
  • Chat — multi-turn LLM Q&A with streaming responses (Anthropic Claude API / Ollama / OpenAI-compatible). Installed Ollama / OpenAI models are auto-detected, and host RAM is read server-side to recommend a model size class.
  • About — version, links, feature list.

Tooling

• Interactive wizard (-I), config files (--config), file watching (--watch), parallel parse, incremental cache, XSD validation, pytest plugin (uds_spec fixture), LSP server, shell completion, plugin system (ParserPlugin / GeneratorPlugin), i18n (en / de / ja with bilingual --lang ja+en mode + multi-language --langs en,ja,de).

Distribution

• Docker image (TeX Live + udsdoc[all]).
• GitHub Action (Marketplace-ready).
• pre-commit hooks (validate / regen PDF / regen TeX ZIP).
• VS Code extension (right-click .arxml → generate / validate / diff / LLM).

---

Documentation

• Full feature reference & Python API: docs/README_full.md
• Standards coverage matrices (ISO ↔ AUTOSAR ECUC ↔ udsdoc, with file:line source citations): docs/standards/ — ISO 15765-2 (CanTp), ISO 14229-2 (session/timing), ISO 14229-1 (services, DTC/Dem), required-ARXMLs note.
• App + Boot ARXML split & CSV → ARXML hand-off: docs/app-boot-arxml.md
• Changelog: CHANGELOG.md
• Contributing: CONTRIBUTING.md

---

Requirements

• Python ≥ 3.9
• lxml ≥ 4.9, Jinja2 ≥ 3.1
• LaTeX with xelatex (TeX Live / MiKTeX) for PDF output

---

License

MIT