udsxml2tex 0.22.0

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	Self-contained HTML with CSS
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

• 14+ ISO 14229-1 consistency checks (--validate) — duplicate IDs, byte overlap, session/security refs, NRC completeness, DCM↔DEM consistency, memory range overlap, P2 sanity
• Spec diff (--diff FILE) — compare two ARXML/JSON specs with ADDED/REMOVED/CHANGED entries and Markdown report

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
• Watch mode (--watch) — auto-regenerate on file changes
• Dry-run mode (--dry-run) — preview parsed summary without file output
• Session state-machine diagram (TexGenerator.generate_session_diagram()) — TikZ diagram
• UML sequence diagrams (--sequence-diagrams DIR) — SecurityAccess, RoutineControl, Upload/Download flows
• Byte-level DID diagrams (--byte-diagrams DIR) — bytefield LaTeX package visualizations
• 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
• AUTOSAR R3.x / R4.x dual support — namespace auto-detection

---

Installation

pip install udsxml2tex

Optional dependency groups

pip install udsxml2tex[web]     # --serve browser mode (FastAPI + uvicorn)
pip install udsxml2tex[yaml]    # --format yaml (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[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/

# 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

Six REST endpoints (/parse, /generate, /validate, /diff, /health, /) power a built-in single-file web UI with drag-and-drop ARXML upload, format selector, DID/service filters, parse preview, and diff highlighting.

---

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")

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

# 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

---

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

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
   • 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 D)
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

---

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)

---

License

MIT License