udsxml2tex 0.34.7

Convert AUTOSAR DCM/CanTp/DEM arxml to LaTeX UDS (ISO 14229 / 15765) specification documents

udsxml2tex

Convert AUTOSAR DCM/CanTp/DEM ARXML to UDS specification documents

A Python library and CLI that parses AUTOSAR DCM (Diagnostic Communication Manager), CanTp (CAN Transport Protocol), DEM (Diagnostic Event Manager), DoIP, Communication, and Adaptive Platform ARXML files and automatically generates ISO 14229 (UDS) / ISO 15765 specification documents in LaTeX, HTML, PDF, Markdown, RST, CSV, YAML, JSON, or DOCX format.

---

Features

DCM — Application Layer (ISO 14229-1)

• Diagnostic sessions (P2/P2* timing, CommCtrl option mask)
• Security access levels (seed/key sizes, attempt counters, algorithm refs, boot delay)
• UDS service table (SID, sub-functions, NRCs, addressing modes) — full message-format tables for all 24 standard UDS services
• Data Identifiers (DIDs) — data-element layout, read/write access, session/security refs
• Routine Control — start/stop/result support, in/out parameters
• DTC definitions (DcmDspDtc) — extended data records, snapshot records
• Named DTC groups (DcmDspGroupOfDTC) for ClearDTC / ReadDTC
• Memory ranges (ReadMemoryByAddress / WriteMemoryByAddress)
• IO Control DIDs (InputOutputControlByIdentifier 0x2F)
• Periodic DIDs (ReadDataByPeriodicIdentifier 0x2A)
• DID ranges (DcmDspDidRange) and Dynamic DIDs (DynamicallyDefineDataIdentifier 0x2C)
• Authentication configuration (ISO 14229-1:2020 §9.6)
• ResponseOnEvent configuration (ISO 14229-1 §9.9)
• LinkControl supported baud rates (fixed + specific, ISO 14229-1 §9.10)
• Max block length for Upload/Download services (ISO 14229-1 §13)
• Multi-client / multi-protocol configuration (ISO 14229-1 Annex D)
• Access Timing Parameters (ISO 14229-2)
• ClearDiagnosticInformation notifications and DSL buffer sizes

CanTp — Transport Layer (ISO 15765-2)

• Channel parameters (Block Size, STmin, channel mode, CAN-FD detection)
• ISO 15765-2 timing parameters (N_As, N_Bs, N_Cs, N_Ar, N_Br, N_Cr)
• Addressing format and padding configuration

DEM — Diagnostic Event Manager (ISO 14229-1 §11)

• General configuration (DTC status bit storage, availability support)
• DTC Status Availability Mask — explicit or derived from DemGeneral flags (ISO 14229-1 §11.3.5)
• DTC Severity Availability Mask (ISO 14229-1 Annex C.3.1)
• DTC Format Identifier derived from DemTypeOfDTCSupported (ISO 14229-1 §11.3.6)
• DemDTC entries — DTC value, severity, kind, significance, priority, aging
• OBD DTC values (ISO 15031-6) and WWH-OBD DTC class (ISO 27145)
• Combined DTC definitions (DemCombinedDTC)
• Freeze frame classes and DID references (ISO 14229-1 §11.3.3)
• Extended data record classes (ISO 14229-1 §11.3.4)
• Operation cycles, event parameters, enable/storage conditions, indicators (MIL)

DoIP — Diagnostics over IP (ISO 13400)

• DoIP configuration container parsing (doip_parser.py)
• Logical addresses, routing activations, EID/GID, timing parameters

OBD / WWH-OBD

• OBD PID extraction from DCM DID entries in 0xF400–0xF4FF range
• WWH-OBD detection from DEM ObdInfoGroup containers
• Standard PID name mapping (ISO 15031-5)

Communication ARXML

• I-SIGNAL, FRAME, PDU parsing including PDU-to-frame signal mappings
• ECU-INSTANCE inventory (connectors, controllers)
• Network cluster topology (CAN, LIN, FlexRay, Ethernet) with baudrate

Adaptive Platform (AUTOSAR AP)

• SERVICE-INTERFACE parsing (methods, events, fields)
• DIAGNOSTIC-SERVICE-INSTANCE to UDS service mapping
• AP version auto-detection

C source code integration

• Scan application-layer C/C++ source for global variables referenced by DID read/write functions
• Header file scanning, macro alias expansion, transitive call analysis (up to depth 3)
• Populates DataElement.global_variables and shows them in the output tables

Output formats

Format	Flag	Description
LaTeX	--format tex (default)	Full spec document via Jinja2 template
HTML	--format html	Multi-page hierarchical HTML ZIP (sections/ directory layout)
Markdown	--format md	GitHub-flavored Markdown tables
RST	--format rst	reStructuredText for Sphinx pipelines
CSV	--format csv	One CSV per category into <stem>_csv/
YAML	--format yaml	Full spec serialized to YAML
JSON	--format json	Full spec serialized to JSON
DOCX	--format docx	Word document with formatted tables

Validation & diff

• 17 ISO 14229-1 consistency checks (--validate) — duplicate IDs, byte overlap, session/security refs, NRC completeness, DCM↔DEM consistency, memory range overlap, P2 sanity, security level parity, DID total-length mismatch, etc. Colored severity table when [rich] is installed.
• Spec diff (--diff FILE) — compare two ARXML/JSON specs with ADDED/REMOVED/CHANGED entries; rendered as Markdown via rich.

Standards & compatibility

• ISO 14229-1 version filter (--iso-version {2006,2013,2020}) — drop services / NRCs / sub-functions not defined in the chosen revision (--iso-version-mode {warn,strict}).
• AUTOSAR compatibility report (--autosar-compat-report [FILE]) — flags features that postdate the detected AUTOSAR release (R3.0 → R22-11).
• AUTOSAR R3.x / R4.x dual support — namespace auto-detection in ArxmlParser.

Visualizations

• Heatmaps & timing diagrams (--visualizations DIR) — Session×Service support matrix, Security×DID access matrix, P2/P2*/S3/N_Bs/N_Cr timing chart. TikZ output by default; PNG with [viz] extra.
• UML sequence diagrams (--sequence-diagrams DIR) — SecurityAccess, RoutineControl, Upload/Download flows.
• Byte-level DID diagrams (--byte-diagrams DIR) — bytefield LaTeX package visualizations.
• Session state-machine diagram (TexGenerator.generate_session_diagram()) — TikZ for PDF, Mermaid stateDiagram-v2 for HTML (auto-included on the Session-layer page).
• Security-access state machine — ISO 14229-1 Annex I 4-state FSM, Mermaid in HTML (auto-included on the SecurityAccess service page and on the standalone Security page).
• NRC check flowcharts — per-service negative-response decision flow, TikZ for PDF and Mermaid flowchart TD in HTML (auto-included on every service page that defines nrc_list).
• Bundled offline Mermaid runtime — the HTML ZIP ships assets/mermaid.min.js so every diagram renders without network access when the ZIP is opened locally.

LLM-powered analysis

Optional LLM module (udsxml2tex[llm]) for natural-language interaction with the parsed spec. Two backends supported:

• Anthropic Claude API (cloud, requires ANTHROPIC_API_KEY) — best quality.

• OpenAI-compatible HTTP API (--llm-provider openai) — works with Ollama, llama.cpp, vLLM, LM Studio, OpenRouter, Azure OpenAI, real OpenAI. Use a local LLM (e.g. Ollama with llama3.1:8b) when your ARXML can't leave the local machine — no API key, no cloud, no per-token cost.

• Executive summary (--llm-summarize {short,1page,2page,long}) — Markdown-formatted summary.

• Natural-language Q&A (--llm-query QUESTION) — "Which DIDs require security level 2?".

• NRC enrichment (--llm-nrc-descriptions) — ECU-specific paragraph per NRC.

• Translation (--llm-translate {en,ja,de}) — translate any LLM output, preserving Markdown / hex codes / UDS keywords.

• Multi-turn chatbot (udsxml2tex --serve → Chat tab) — conversational Q&A in the browser UI with token-by-token streaming responses; conversation history is kept on the client, spec JSON is cached on the server. Provider selector (Anthropic / OpenAI-compatible) lets you point the chat at a local Ollama instead of the cloud.

• Local LLM bootstrap (udsxml2tex --bootstrap-ollama) — one-shot setup for the Chat tab on a fresh machine: downloads the Ollama binary into ~/.local if missing (no sudo, no systemd), starts ollama serve with OLLAMA_CONTEXT_LENGTH=24576 so 15k-token spec prompts aren't silently truncated, pulls the default qwen2.5:7b model, and prints a ready-to-paste ~/.udsxml2tex/llm.json. Linux + macOS only. Tunable via --bootstrap-model / --bootstrap-ctx.

• Model alias (--llm-model {sonnet,opus,haiku}) — default sonnet (claude-sonnet-4-6).

• Spec JSON is placed in the prompt with a 1-hour cache breakpoint (Anthropic), so repeated queries against the same ECU pay the cache-write cost once. The system prompt is also prefixed with a compact authoritative index of spec.dids / spec.io_control_dids / spec.periodic_dids / spec.dynamic_dids / spec.did_ranges, which raises enumeration recall on smaller local models (7-8B) from ~67% to 100% without hurting cloud-model quality.

Tooling

• Interactive mode (-I) — step-by-step guided generation wizard
• Config file mode (--config) — save/load generation settings as JSON
• Browser mode (--serve) — local FastAPI web server with drag-and-drop UI (academic theme, built-in samples). Tabs: Generate (with a Mode toggle: Single ECU drives the per-ECU spec / /generate, Multi-ECU System drives the redundant / gateway integration ZIP from system.yaml + ARXMLs + optional .c/.h sources / /system; per-mode formats), Chat (LLM Q&A), About.
• Watch mode (--watch) — auto-regenerate on file changes
• Dry-run mode (--dry-run) — preview parsed summary (rich tables when [rich] is installed)
• Progress bars (--progress) — tqdm progress for parse_multi() / parse_streaming()
• JSON Schema export (--json-schema) — draft-07 schema for UdsSpecification
• Pydantic v2 model export (generate_pydantic_models()) — ready-to-use Pydantic model source
• pytest plugin — uds_spec fixture, UdsSpecAssertions mixin, auto-registered
• LSP server (udsxml2tex.lsp_server) — ARXML editor completions via pygls
• Shell completion (--generate-completion bash|zsh|fish)
• Plugin system — ParserPlugin / GeneratorPlugin ABCs for extensions
• i18n (--lang en|ja) — Japanese label support (35 keys)
• Incremental parse cache (--cache-dir DIR) — SHA-256-keyed pickle cache
• Parallel multi-file parse (--parallel) — ProcessPoolExecutor
• Streaming iterparse (parse_streaming()) — low-memory large-file mode
• XSD schema validation (--validate-xsd XSD)
• Full AUTOSAR path matching — _resolve_autosar_path() with path index cache

Multi-ECU systems (1+1 redundant / gateway-with-forwarder)

For diagnostic systems composed of multiple AUTOSAR ECUs (each with its own ARXML), udsxml2tex.multi_ecu models the ECUs and the routing relationships that describe how diagnostic requests flow between them.

• --system CONFIG.yaml — declarative system config (ECU roster, roles, per-ECU ARXML paths, explicit routing rules, physical topology).
• --system-output-dir DIR — produces <DIR>/<ecu>/spec.<ext> for each ECU plus <DIR>/system.<ext> (integration document) and <DIR>/system_topology.tex (standalone topology figure).
• ARXML coverage-gap inference — DIDs/RIDs/SIDs on the endpoint but not the gateway are flagged as forwarded (override with --no-routing-inference).
• Cross-ECU validator — verifies forwarded DIDs/RIDs/SIDs exist on the target, security level / session compatibility, no routing cycles.
• See Multi-ECU systems below for the full YAML schema.

Distribution & integrations

• Docker image (Dockerfile) — TeX Live + udsxml2tex[all] preinstalled
• GitHub Action (action.yml) — Marketplace-ready, Docker-backed
• pre-commit hooks (.pre-commit-hooks.yaml) — validate / regen-pdf / regen-tex
• VS Code extension (vscode-extension/) — right-click .arxml → generate / validate / diff / LLM Q&A

---

Installation

pip install udsxml2tex

Optional dependency groups

pip install udsxml2tex[web]     # --serve browser mode (FastAPI + uvicorn)
pip install udsxml2tex[yaml]    # --format yaml AND multi-ECU --system YAML configs (PyYAML)
pip install udsxml2tex[watch]   # --watch mode (watchdog)
pip install udsxml2tex[docx]    # --format docx (python-docx)
pip install udsxml2tex[lsp]     # LSP server (pygls)
pip install udsxml2tex[progress] # tqdm progress bars (--progress)
pip install udsxml2tex[rich]    # Colored CLI output (rich)
pip install udsxml2tex[viz]     # PNG heatmaps & timing diagrams (matplotlib)
pip install udsxml2tex[llm]     # LLM analysis (anthropic + openai SDKs; cloud or local Ollama)
pip install udsxml2tex[all]     # All optional dependencies

From source (development):

git clone https://github.com/YutaroNakagama/udsxml2tex.git
cd udsxml2tex
pip install -e ".[dev]"

---

Usage

CLI

# Basic conversion (LaTeX)
udsxml2tex input.arxml

# Specify output file
udsxml2tex input.arxml -o output.tex

# Merge multiple ARXML files (DCM + CanTp)
udsxml2tex dcm.arxml cantp.arxml -o spec.tex

# Merge a separate DEM ARXML file
udsxml2tex dcm.arxml --dem dem.arxml -o spec.tex

# Attach DoIP ARXML
udsxml2tex dcm.arxml --doip doip.arxml -o spec.tex

# Attach Communication ARXML (signals, frames, topology)
udsxml2tex dcm.arxml --comm comm.arxml -o spec.tex

# Output format selection
udsxml2tex input.arxml --format html -o spec.html
udsxml2tex input.arxml --format md -o spec.md
udsxml2tex input.arxml --format rst -o spec.rst
udsxml2tex input.arxml --format csv       # writes <stem>_csv/
udsxml2tex input.arxml --format yaml -o spec.yaml
udsxml2tex input.arxml --format json -o spec.json
udsxml2tex input.arxml --format docx -o spec.docx  # requires [docx]

# Compile directly to PDF (requires latexmk/pdflatex)
udsxml2tex input.arxml --pdf

# Run ISO 14229-1 consistency validation
udsxml2tex input.arxml --validate

# Compare two specs (ARXML or JSON)
udsxml2tex new.arxml --diff old.arxml
udsxml2tex new.arxml --diff baseline.json

# Generate JSON Schema for UdsSpecification
udsxml2tex --json-schema

# Scan C source for DID global variables
udsxml2tex input.arxml --c-source src/app/ --c-scan-depth 2

# Generate sequence diagrams and byte-level DID diagrams
udsxml2tex input.arxml --sequence-diagrams diagrams/
udsxml2tex input.arxml --byte-diagrams diagrams/

# Generate heatmaps + timing diagrams (TikZ + PNG with [viz] extra)
udsxml2tex input.arxml --visualizations viz/                 # both TikZ and PNG
udsxml2tex input.arxml --visualizations viz/ --viz-format tikz

# ISO 14229-1 version-aware filtering
udsxml2tex input.arxml --iso-version 2013                     # warn-only (default)
udsxml2tex input.arxml --iso-version 2006 --iso-version-mode strict

# AUTOSAR version compatibility report (Markdown)
udsxml2tex input.arxml --autosar-compat-report                # to stdout
udsxml2tex input.arxml --autosar-compat-report compat.md      # to file

# LLM features — Anthropic (cloud, requires ANTHROPIC_API_KEY)
udsxml2tex input.arxml --llm-summarize 1page --llm-output summary.md
udsxml2tex input.arxml --llm-query "Which DIDs require security level 2?"
udsxml2tex input.arxml --llm-nrc-descriptions --llm-output nrc.json
udsxml2tex input.arxml --llm-summarize --llm-translate ja --llm-output summary_ja.md
udsxml2tex input.arxml --llm-query "Summarize SecurityAccess" --llm-model opus

# LLM features — Ollama / local LLMs (no API key, ARXML stays on-machine)
# One-shot setup: download Ollama, start it, pull a model, write llm.json snippet.
udsxml2tex --bootstrap-ollama                      # Linux / macOS, default qwen2.5:7b @ 24K ctx
udsxml2tex --bootstrap-ollama --bootstrap-model llama3.1:8b
# …or do it manually:
ollama serve &  ollama pull llama3.1:8b
udsxml2tex input.arxml --llm-provider openai --llm-base-url ollama \
                       --llm-model llama3.1:8b --llm-summarize 1page

# LLM features — any OpenAI-compatible server
udsxml2tex input.arxml --llm-provider openai \
                       --llm-base-url https://openrouter.ai/api/v1 \
                       --llm-model meta-llama/llama-3.1-70b-instruct \
                       --llm-api-key sk-or-... \
                       --llm-query "Which DIDs are read-only?"

# Or persist defaults via ~/.udsxml2tex/llm.json (see samples/llm_config_*.json)
cp $(python -c 'import udsxml2tex,os;print(os.path.dirname(udsxml2tex.__file__))')/samples/llm_config_ollama.json ~/.udsxml2tex/llm.json
udsxml2tex input.arxml --llm-summarize     # now uses Ollama by default

# Show progress bar during multi-file parse (requires [progress] extra)
udsxml2tex *.arxml --parallel --progress

# Multi-ECU system mode (1+1 redundant / gateway-with-forwarder; requires [yaml])
udsxml2tex --system system.yaml --format html --system-output-dir out/
udsxml2tex --system system.yaml --format pdf  --system-output-dir out/
udsxml2tex --system system.yaml --no-routing-inference  # explicit rules only

# Watch for file changes and auto-regenerate
udsxml2tex input.arxml --watch                  # requires [watch]

# Start browser mode (local web UI)
udsxml2tex --serve                              # requires [web]
udsxml2tex --serve --port 9000

# Parallel parsing of multiple ARXML files
udsxml2tex dcm.arxml cantp.arxml --parallel

# Incremental parse cache (skip re-parse when file unchanged)
udsxml2tex input.arxml --cache-dir .cache/

# Validate ARXML against XSD before parsing
udsxml2tex input.arxml --validate-xsd schema.xsd

# Inject custom Jinja2 template variables
udsxml2tex input.arxml --extra-vars project=MyProject --extra-vars rev=2.1

# Language selection (English / Japanese labels)
udsxml2tex input.arxml --lang ja

# Filter output to specific IDs
udsxml2tex input.arxml --filter-dids 0x1234,0x1235
udsxml2tex input.arxml --filter-services 0x22,0x2E
udsxml2tex input.arxml --filter-dtcs 0x010000

# Shell completion
udsxml2tex --generate-completion bash >> ~/.bashrc
udsxml2tex --generate-completion zsh  >> ~/.zshrc
udsxml2tex --generate-completion fish > ~/.config/fish/completions/udsxml2tex.fish

Interactive Mode

udsxml2tex -I

Step-by-step wizard covering ARXML type, file paths, ECU name, item selection, timing parameters, C source scanning, template, and output path. Settings can be saved as a reusable JSON config file.

Config File Mode

udsxml2tex --config udsxml2tex_config.json
udsxml2tex --config udsxml2tex_config.json --ecu-name "NewECU" -o other.tex

Browser Mode

pip install udsxml2tex[web]
udsxml2tex --serve         # opens http://127.0.0.1:8765 in your browser

Eight REST endpoints (/, /health, /samples, /parse, /generate, /validate, /diff, /chat) power a built-in single-file web UI with three tabs:

• Generate — drag-and-drop ARXML upload, format selector, DID/service filters, parse preview, diff highlighting, one-click built-in sample loading.
• Chat — multi-turn LLM chatbot against the most recently parsed spec, with token-by-token streaming responses (Server-Sent Events). Provider selector in the UI lets you choose Anthropic Claude API (cloud) or OpenAI-compatible (Ollama / llama.cpp / vLLM / LM Studio / OpenRouter / etc.). Spec JSON is reused via a server-side session so you don't re-upload between questions. Requires udsxml2tex[llm] on the server; API key + base URL fields override the server's environment per browser session.
• About — version, links, feature list.

The browser UI uses an academic/classic theme (Georgia serif, dark sidebar, flat borders). Multiple primary ARXML files can be uploaded and are automatically merged via parse_multi().

---

Python API

Parsing

from udsxml2tex import ArxmlParser, DemParser

# Single file
spec = ArxmlParser().parse("dcm_config.arxml")

# Multiple files merged
spec = ArxmlParser().parse_multi(["dcm.arxml", "cantp.arxml"])

# Parallel multi-file parse
spec = ArxmlParser().parse_multi(["a.arxml", "b.arxml"], parallel=True)

# Incremental cache
spec = ArxmlParser().parse("big.arxml", cache_dir=".cache/")

# Streaming parse (large files, low memory — DID + DTC only)
spec = ArxmlParser().parse_streaming("huge.arxml")

# Merge separate DEM ARXML
DemParser().parse("dem_config.arxml", spec)

# XSD validation before parsing
errors = ArxmlParser().validate_against_xsd("input.arxml", "schema.xsd")

# Check detected ARXML version
parser = ArxmlParser()
spec = parser.parse("input.arxml")
print(parser.arxml_version)   # e.g. "R4.2"

DoIP / OBD / Comm / AP parsers

from lxml import etree
from udsxml2tex import DoIpParser, ObdParser, CommArxmlParser, ApParser

root = etree.parse("doip.arxml").getroot()
spec.doip_config = DoIpParser().parse(root)

root = etree.parse("dcm.arxml").getroot()
spec.obd_config = ObdParser().parse(root)

root = etree.parse("comm.arxml").getroot()
spec.comm_config = CommArxmlParser().parse(root)

root = etree.parse("ap.arxml").getroot()
spec.ap_config = ApParser().parse(root)

Generating output

from udsxml2tex import TexGenerator

gen = TexGenerator()

# LaTeX (default template)
gen.generate(spec, "output.tex")

# Single-file HTML
gen.generate_html(spec, "output.html")

# Multi-page hierarchical HTML ZIP (sections/ directory layout)
gen.generate_html_zip(spec, "output.zip")
# Produces: index.html, sections/0_intro/, sections/1_low_layer/{2_datalink,3_network,...}/,
#            sections/2_high_layer/index.html, sections/2_high_layer/sid{XX}/,
#            sections/A_annex/index.html — all with relative nav links, academic CSS theme

# Structured multi-file LaTeX ZIP
gen.generate_structured_tex_zip(spec, "output_tex.zip")

# Markdown / RST / CSV / YAML / JSON
gen.generate_markdown(spec, "output.md")
gen.generate_rst(spec, "output.rst")
gen.generate_csv(spec, "output_csv/")
gen.generate_yaml(spec, "output.yaml")
gen.generate_json(spec, "output.json")

# DOCX (requires python-docx)
gen.generate_docx(spec, "output.docx")

# Format dispatcher
gen.generate_format(spec, "output", format_name="md")

# Session state-machine TikZ diagram
gen.generate_session_diagram(spec, "session_diagram.tex")

# UML sequence diagrams (SecurityAccess, RoutineControl, Upload/Download)
gen.generate_sequence_diagrams(spec, "diagrams/")

# Byte-level DID visualizations (bytefield LaTeX)
gen.generate_byte_diagrams(spec, "diagrams/")

# Compile to PDF
gen.compile_pdf("output.tex")

# Custom template and extra Jinja2 variables
gen.generate(spec, "output.tex",
             template_name="custom.tex.j2",
             extra_vars={"project": "MyProject", "revision": "2.0"})

Validation

from udsxml2tex import validate, UdsValidator, ValidationResult

# Convenience function
result = validate(spec)
print(result.summary())      # "3 warnings, 2 info"
print(result.has_errors())   # False

# Full validator with all 17 checks
result = UdsValidator().validate(spec)
for issue in result.issues:
    print(f"[{issue.severity}] [{issue.category}] {issue.message}")

Checks include: duplicate DID/DTC/Routine/Session/SecurityLevel IDs, DID byte overlap, unknown session/security refs, NRC completeness (ISO 14229-1 mandatory NRCs per service), DCM↔DEM DTC consistency, memory range overlap, P2 timeout sanity, security level parity, missing DTC descriptions, empty DID list, service-without-session, DID total-length mismatch.

Diff

from udsxml2tex import diff_specs, SpecDiffer

diff = diff_specs(spec_a, spec_b)
print(diff.to_markdown())

# Or with full API
diff = SpecDiffer().diff(spec_a, spec_b)
for entry in diff.entries:
    print(entry.kind, entry.category, entry.item_id, entry.detail)

Serialization

# JSON round-trip
json_str = spec.to_json()
spec2 = UdsSpecification.from_json(json_str)

# Save / load JSON file
spec.save_json("spec.json")
spec2 = UdsSpecification.load_json("spec.json")

# Plain dict (for custom serialization)
d = spec.to_dict()

# Merge two specs (other overrides duplicate IDs in self)
merged = spec_a | spec_b

JSON Schema / Pydantic export

from udsxml2tex import generate_json_schema, save_json_schema, generate_pydantic_models

# JSON Schema draft-07
schema = generate_json_schema()
save_json_schema("uds-specification.schema.json")

# Pydantic v2 model source code
src = generate_pydantic_models()
with open("uds_models.py", "w") as f:
    f.write(src)

Plugin system

from udsxml2tex import ParserPlugin, GeneratorPlugin, registry

class MyParser(ParserPlugin):
    def parse(self, root, spec):
        ...   # extend parsing

class MyGenerator(GeneratorPlugin):
    def generate(self, spec, output_path, **kwargs):
        ...   # custom output format

registry.register_parser(MyParser())
registry.register_generator("custom", MyGenerator())

i18n (Japanese labels)

from udsxml2tex import translate, Translator

print(translate("sessions", "ja"))          # "診断セッション"
t = Translator("ja")
print(t.t("security_levels"))               # "セキュリティアクセスレベル"

C source scanning

from udsxml2tex import scan_did_variables
from pathlib import Path

scan_did_variables(
    c_paths=[Path("src/app/")],
    dids=spec.dids,
    include_headers=True,
    transitive_depth=2,      # follow calls up to 2 levels deep (max 3)
)
# spec.dids[*].data_elements[*].global_variables is now populated

Visualizations (heatmaps & timing diagrams)

from udsxml2tex import (
    generate_session_service_heatmap,
    generate_security_did_heatmap,
    generate_timing_diagram,
    generate_all_visualizations,
)

# Standalone TikZ files (no runtime deps beyond LaTeX)
generate_session_service_heatmap(spec, "viz/", format="tikz")
generate_security_did_heatmap(spec, "viz/", format="tikz")
generate_timing_diagram(spec, "viz/", format="tikz")

# matplotlib-rendered PNG (requires udsxml2tex[viz])
generate_all_visualizations(spec, "viz/", format="both")    # TikZ + PNG

LLM analysis (Claude API)

# Requires `pip install udsxml2tex[llm]`. Auth: ANTHROPIC_API_KEY env var
# (default Anthropic backend) or no key for local servers.
from udsxml2tex.llm_integration import (
    LLMConfig,
    summarize_spec, query_spec, complete_nrc_descriptions, translate_text,
    chat_stream,
)

# === Anthropic Claude (default) ============================================
md = summarize_spec(spec, length="1page")
answer = query_spec(spec, "Which DIDs require security level 2?")
descriptions = complete_nrc_descriptions(spec)   # {0x22: "...", 0x35: "..."}
ja = translate_text(md, target_lang="ja")

# === Local Ollama (privacy-preserving — ARXML never leaves the machine) ====
ollama = LLMConfig(provider="openai", model="llama3.1:8b", base_url="ollama")
md_local = summarize_spec(spec, length="1page", config=ollama)
answer_local = query_spec(spec, "List DIDs in 0xF180–0xF1FF.", config=ollama)

# === Multi-turn streaming chat against any provider =========================
messages = [{"role": "user", "content": "Which DIDs require security level 2?"}]
for delta in chat_stream(spec, messages, config=ollama):     # or anthropic default
    print(delta, end="", flush=True)
# Append the assistant turn back to `messages` and call again to continue.

# === Persisted defaults: write ~/.udsxml2tex/llm.json once, then call without
# config= every time. Or LLMConfig.auto() reads it explicitly:
cfg = LLMConfig.auto()        # env vars + ~/.udsxml2tex/llm.json + defaults

The spec JSON is placed in the prompt with a 1-hour cache breakpoint, so repeated calls against the same spec only pay the cache-write cost on the first call. Model aliases: sonnet → claude-sonnet-4-6, opus → claude-opus-4-7, haiku → claude-haiku-4-5.

ISO 14229-1 version filter

from udsxml2tex.iso_versions import (
    SUPPORTED_ISO_VERSIONS,    # ('2006', '2013', '2020')
    iso_nrcs, iso_services, iso_sub_functions,
    filter_spec_by_iso_version,
)

# Inspect the standard tables
nrcs_2020 = iso_nrcs("2020")          # 55 NRCs
sids_2006 = iso_services("2006")      # 26 SIDs (no Authentication 0x29)
sf_19 = iso_sub_functions("2020", 0x19)  # 24 sub-functions for ReadDTCInformation

# Filter a parsed spec
notes = filter_spec_by_iso_version(spec, "2013", mode="warn")    # log only
notes = filter_spec_by_iso_version(spec, "2006", mode="strict")  # drop unsupported
for n in notes:
    print(n)

AUTOSAR version compatibility report

from udsxml2tex.autosar_compat import autosar_compat_report

parser = ArxmlParser()
spec = parser.parse("input.arxml")

report = autosar_compat_report(spec, parser=parser)
print(report.detected_version)        # e.g. "R4.2"
print(report.has_warnings)            # True if any feature predates the release
print(report.to_markdown())           # full report
report_dict = report.to_dict()        # for programmatic consumption

Multi-ECU systems

For diagnostic systems composed of multiple AUTOSAR ECUs:

from udsxml2tex.multi_ecu import (
    load_system_config,
    validate_system,
    generate_system_markdown,
)

# YAML config + per-ECU ARXML parsing + ARXML coverage-gap routing inference
system = load_system_config("system_redundant.yaml")
print(system.primary.spec.ecu_name)        # gateway ECU's spec
print(system.secondary.spec.ecu_name)      # endpoint ECU's spec
print(len(system.routing_rules))           # explicit + inferred rules

# Cross-ECU validator (returns the same ValidationResult as single-ECU validate())
result = validate_system(system)

# System integration document
md = generate_system_markdown(system)

See Multi-ECU systems below for the full YAML schema, validator check table, and topology diagram details.

---

pytest plugin

Install udsxml2tex and the plugin is auto-registered via the pytest11 entry point.

# conftest.py — no explicit import needed after pip install

# In your test file:
from udsxml2tex.pytest_plugin import UdsSpecAssertions

class TestMySpec(UdsSpecAssertions):
    def test_did_present(self, uds_spec):
        self.assert_did_present(uds_spec, 0x1234)

    def test_spec_valid(self, uds_spec):
        self.assert_valid(uds_spec)

    def test_custom(self, uds_spec_factory):
        spec = uds_spec_factory(num_dids=10, num_dtcs=5)
        assert len(spec.dids) == 10

---

LSP server

Provides completions and hover documentation for .arxml files in any LSP-compatible editor (VS Code, Neovim, Emacs, etc.):

pip install udsxml2tex[lsp]
python -m udsxml2tex.lsp_server --stdio       # stdio mode (VS Code)
python -m udsxml2tex.lsp_server --tcp --port 2087

---

Generated Document Structure

LaTeX / PDF (--format tex / --pdf)

1. Title Page — ECU name, date
2. Table of Contents
3. Document Overview — OSI layer mapping, generic UDS request/response sequence diagram
4. Transport Layer (ISO 15765-2 / CanTp) — channel overview, timing parameters, addressing & padding
5. Session Layer (ISO 14229-2) — DSL config, diagnostic sessions (ID, P2/P2*/S3 timers), access timing
6. Application Layer (ISO 14229-1)
   • Negative response common format & standard NRC code reference
   • Service Overview table — all services with session/security matrix
   • Per-service detail — message format, sub-functions, NRC list, UML sequence diagram
   • SecurityAccess (0x27) — Security Access Levels table + 4-state FSM diagram (ISO 14229-1 Annex I)
   • Data Identifiers (DIDs) — DID overview + data element layouts + C global variables
   • Memory Ranges — read/write address ranges with session/security constraints
   • IO Control DIDs, Periodic DIDs, DID Ranges, Dynamic DIDs
   • Authentication, ControlDTCSetting / ClearDTC, Named DTC Groups, Upload/Download Max Block Length
   • Multi-Client Configuration (ISO 14229-1 Annex J)
7. Diagnostic Event Manager (DEM) Configuration
   • DTC Status Byte tables, Severity Availability Mask
   • DEM DTC Definitions — value, severity, kind, significance, OBD DTC values
   • Combined DTC Definitions, Freeze Frame Classes, Extended Data Record Classes
   • Operation Cycles, Event Memory Configuration, Event Parameters, Indicators

HTML ZIP (--format html)

The HTML ZIP uses a sections/ directory hierarchy mirroring the structured LaTeX layout. All pages use a Georgia serif academic theme with a hierarchical sidebar navigation. Relative URLs are computed so the ZIP opens correctly without a web server. Mermaid diagrams (session FSM, security FSM, NRC check flowcharts) render offline via the bundled assets/mermaid.min.js.

spec.zip
├── index.html                                    Overview & statistics
├── assets/mermaid.min.js                         Bundled Mermaid v10 (offline diagram rendering)
├── sections/
│   ├── 0_intro/index.html                        Introduction, abbreviations, references
│   ├── 1_low_layer/
│   │   ├── index.html                            Network Protocol Layers (section index)
│   │   ├── 2_datalink/index.html                 Data Link Layer (CAN padding)
│   │   ├── 3_network/index.html                  Network Layer (CAN IDs)
│   │   ├── 4_transport/index.html                Transport Layer (PCI frames, timing)
│   │   └── 5_session/index.html                  Session Layer (sessions, S3 timeout, Mermaid FSM)
│   ├── 2_high_layer/
│   │   ├── index.html                            Application Layers (cross-ref matrices)
│   │   └── sid{XX}/index.html                    Per-service page (Mermaid NRC flow; sid27 also shows the security FSM)
│   └── A_annex/index.html                        Cross-reference tables (SID/DID/RID/NRC)

---

Supported ARXML Elements

DCM module

Container	Parameters extracted
DcmDsl	Protocol type, buffer sizes, connection mode, periodic rates
DcmDslProtocolRow	Priority, preempt timeout, trans type (multi-client)
DcmDslConnection	Rx/Tx addresses, connection mode, end-of-connection type
DcmDspSession	Session level, P2/P2* timers, CommCtrl option mask
DcmDspSecurity / DcmDspSecurityRow	Level, seed/key sizes, attempt counter, delay times, algorithm ref
DcmDspDid	DID identifier, read/write access, data elements (position, size, type, unit), read/write function names
DcmDspDidRange	Lower/upper limit, gaps, data length
DcmDspDynamicDid	DID identifier, max source elements
DcmDspRoutine	Routine ID, start/stop/result support, in/out parameters
DcmDspDtc	DTC value, severity, kind, extended data records, snapshot records
DcmDspGroupOfDTC	Group identifier (named DTC groups)
DcmDspMemoryRangeInfo	Start/end address, read/write access, session/security refs
DcmDspPeriodicDid	DID identifier, transmission mode, update period
DcmDspDidControl	Control mask size, freeze/reset/adjust support
DcmDspAuthentication	Role, white-list, certificate/PSK identity, attempt limit
DcmDspTimingRow	P2/P2*/S3 timing rows (ISO 14229-2)
DcmDspRequestFileTransfer	Max path/file size, format identifier, block size
DcmDspLinkControl	Fixed/specific baud rate records
DcmDspMemory	Max block length, compression/encrypting methods
DcmDsdService	SID, sub-functions, NRCs, session/security refs, addressing mode
DcmGeneral	Main function period, FIM trigger, dev error detect

CanTp module

Container	Parameters extracted
CanTpGeneral	Main function period, CAN-FD enabled, WFTmax
CanTpChannel / CanTpRxNSdu / CanTpTxNSdu	BS, STmin, N_As/Bs/Cs/Ar/Br/Cr, addressing format, padding, channel mode, FC DL

DEM module

Container	Parameters extracted
DemGeneral	Status bit flags, operation cycle storage, DTC status/severity/format masks
DemOperationCycle	Cycle ID, type, autostart
DemDTC + DemDTCAttributes	DTC value, severity, kind, significance, priority, aging, OBD DTC, WWH-OBD class, FF/EDR class refs
DemCombinedDTC	Combined DTC number, event references
DemEventParameter	Event ID, kind, confirmation threshold, debounce config, DTC ref, indicator refs
DemIndicator	Indicator ID, behaviour, failure/healing cycle thresholds
DemEnableCondition	Condition ID, initial status
DemStorageCondition	Condition ID, initial status, replacement event ref
DemPrimaryMemory / DemUserDefinedMemory / DemMirrorMemory / DemPermanentMemory	Max entries, displacement strategy, storage/FF triggers
DemFreezeFrameClass	DID references captured in snapshot
DemExtendedDataClass	Record number, data size, update trigger

Supports AUTOSAR R3.x and R4.x ARXML formats (auto-detected from namespace URI).

---

Requirements

• Python >= 3.9
• lxml >= 4.9.0
• Jinja2 >= 3.1.0
• LaTeX distribution (for compiling generated .tex files — TeX Live or MiKTeX)

---

Docker

A pre-built image is included via the repo Dockerfile (TeX Live + udsxml2tex[all]):

docker build -t udsxml2tex .
docker run --rm -v $(pwd):/work udsxml2tex /work/dcm.arxml --pdf -o /work/spec.pdf

---

GitHub Action

Use the action from any workflow to generate UDS specs in CI:

- uses: YutaroNakagama/udsxml2tex@main
  with:
    input: dcm.arxml
    format: pdf
    output: spec.pdf
    validate: 'true'

See .github/workflows/example-action-usage.yml for a full PR-triggered workflow with PDF artifact upload.

---

pre-commit

Three hook IDs are exposed for use in .pre-commit-config.yaml:

repos:
  - repo: https://github.com/YutaroNakagama/udsxml2tex
    rev: v0.24.0
    hooks:
      - id: udsxml2tex-validate         # ISO 14229-1 consistency checks on changed ARXML
      - id: udsxml2tex-regen-pdf        # auto-regenerate spec.pdf
        args: ['--ecu-name=MyECU', '-o=docs/spec.pdf']
      - id: udsxml2tex-regen-tex        # auto-regenerate the structured LaTeX ZIP

---

Multi-ECU systems

For diagnostic systems built from two or more AUTOSAR ECUs — typically a 1+1 redundant pair where one MCU faces the tester and forwards selected requests to the other MCU — declare the system in a YAML config and run with --system. Requires pip install udsxml2tex[yaml] (PyYAML).

udsxml2tex --system system_redundant.yaml --format html --system-output-dir out/

This produces (≥ 0.34.7 — Option B unified output):

out/                                # for --format html / --format tex / --format pdf
├── system_uds_spec.zip              ONE unified spec covering all ECUs
│                                   (per-section ECU interleaving — every chapter
│                                    contains an "ECU: <name>" sub-section per ECU)
├── system_unified/                  Extracted structured-LaTeX project (tex/pdf only)
│   ├── root.tex                        Unified root with title page + TOC + chapters
│   ├── sections/section.tex            Aggregator: \input's per-ECU interleaved blocks
│   ├── ecus/<name>/sections/...        Per-ECU section trees (headings demoted by 1)
│   ├── udsspec.cls / tikz-uml.sty / reference.bib
│   └── system.pdf                      Compiled PDF (—format pdf only)
└── system_topology.tex              Standalone TikZ topology figure

The HTML zip mirrors the single-ECU layout but every section page has one <h2>ECU: <name> sub-section per ECU; service pages cover the union of SIDs across all ECUs.

YAML config schema

name: ExampleRedundantSystem
description: 1+1 redundant MCU pair

ecus:
  primary:
    role: gateway        # gateway | endpoint | peer
    arxml_files:
      - primary/dcm.arxml
      - primary/cantp.arxml
    dem_arxml: primary/dem.arxml
    description: Tester-facing MCU

  secondary:
    role: endpoint
    arxml_files:
      - secondary/dcm.arxml
    description: Forwarded-only MCU

routing:                 # explicit forwarding rules (inferred ones are appended)
  - from: primary
    to: secondary
    match:
      sids: [0x22, 0x2E]      # ReadDID + WriteDID
      did_range: [0x2000, 0x2FFF]
    via: internal_can
    description: ADAS calibration DIDs are owned by the secondary MCU

topology:
  connections:
    - from: primary
      to: secondary
      medium: CAN
      description: 500 kbit/s internal CAN

A working sample lives at src/udsxml2tex/samples/system_redundant.yaml.

Python API

from udsxml2tex.multi_ecu import (
    load_system_config,
    validate_system,
    generate_system_markdown,
    generate_system_html,            # legacy single-page HTML overview
    generate_system_html_zip,        # 0.34.7+ unified browsable HTML site
    generate_system_structured_tex_zip,  # 0.34.7+ unified structured LaTeX project
    generate_topology_tikz,
)

# Load the config + parse each ECU's ARXML + run routing inference
system = load_system_config("system_redundant.yaml")

# Cross-ECU consistency checks (returns same ValidationResult as single-ECU)
result = validate_system(system)
print(result.summary())

# Unified outputs (Option B — per-section ECU interleaving)
generate_system_html_zip(system, "out/system_uds_spec.zip")
generate_system_structured_tex_zip(system, "out/system_uds_spec_tex.zip")

# Or use the legacy single-page system overview
md = generate_system_markdown(system)
html_overview = generate_system_html(system)
topo_tex = generate_topology_tikz(system)

Cross-ECU validator checks

Check	Severity
Routing rule references unknown ECU	error
Routing rule is a self-loop	error
Routing graph contains a cycle	error
Forwarded DID/RID/SID not on target ECU	warning
Target requires security level not on gateway	info
Target has session not configured on gateway	info

---

VS Code extension

A TypeScript-based VS Code extension lives under vscode-extension/. It wraps the udsxml2tex CLI as right-click context-menu commands on .arxml files. Build & install for local development:

cd vscode-extension
npm install && npm run compile
# Press F5 in VS Code with this folder open to launch a development host.

Commands exposed:

Command	What it runs
Generate UDS Spec / (PDF) / (HTML ZIP)	--format tex / --format pdf / --format html
Validate ARXML (ISO 14229-1)	--validate
Diff against ARXML/JSON	--diff
Open Browser UI	--serve
LLM: Summarize Spec	--llm-summarize
LLM: Ask Question About Spec	--llm-query

Configurable via udsxml2tex.executable, udsxml2tex.defaultEcuName, udsxml2tex.outputDirectory, and udsxml2tex.llmModel in VS Code settings.

---

License

MIT License