# udsxml2tex

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

[![PyPI version](https://badge.fury.io/py/udsxml2tex.svg)](https://badge.fury.io/py/udsxml2tex)
[![Python](https://img.shields.io/pypi/pyversions/udsxml2tex.svg)](https://pypi.org/project/udsxml2tex/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

`udsxml2tex` parses AUTOSAR diagnostic ARXML (DCM, CanTp, DEM, DoIP, COM, AP)
and renders a complete UDS specification in **LaTeX / PDF / HTML / Markdown
/ RST / CSV / YAML / JSON / DOCX**, 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

```bash
pip install udsxml2tex                  # core (LaTeX / Markdown / JSON / YAML)
pip install udsxml2tex[web]             # browser UI (--serve)
pip install udsxml2tex[llm]             # LLM analysis (Anthropic + OpenAI / Ollama)
pip install udsxml2tex[ecu-test]        # CAN/ISO-TP hardware testing
pip install udsxml2tex[all]             # everything
```

Other extras: `yaml`, `watch`, `docx`, `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.

---

## Quick start

```bash
# Single ARXML → LaTeX
udsxml2tex dcm.arxml -o spec.tex

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

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

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

# Multi-language output (English / German / Japanese in one run)
udsxml2tex dcm.arxml --langs en,ja,de -o spec.md --format md

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

# Requirement traceability (DOORS CSV → implementation coverage chapter)
udsxml2tex dcm.arxml --requirements doors_export.csv -o spec.tex
udsxml2tex dcm.arxml --requirements doors_export.csv --req-use-llm -o spec.md --format md

# Multi-CSV traceability with \cite + bibliography (LaTeX appendix)
udsxml2tex --repo bsw-project/ \
    --requirements doors_oem.csv \
    --requirements doors_supplier.csv \
    --requirements-bib sources.yaml \
    --pdf -o spec.tex

# Browser UI
udsxml2tex --serve                                         # http://127.0.0.1:8765
```

### Python API

```python
from udsxml2tex 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 24 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`, `csv`, `yaml`,
  `json`, `docx`, `odx`, `pdx`.
- Visualizations: heatmaps, timing diagrams, UML sequences, byte-level
  DID maps, session/security FSMs.

**Quality**

- `--validate` — 17 ISO 14229-1 consistency checks.
- `--diff` — semantic spec diff (ARXML or JSON).
- `--requirements FILE.csv` — load an IBM DOORS-style requirements export
  (`Object` / `Acceptance_*` / `CommentInternal` / `CommentCustomer` /
  `CommentToCustomer`), match each requirement against the parsed
  DID / RID / SID / Session / NRC / DTC / SecurityLevel set, and append
  a "Requirement Traceability" chapter to tex / html / md / rst output.
  Heuristic identifier-extraction by default; `--req-use-llm` switches
  to semantic matching via the configured LLM (with per-row heuristic
  fallback on failure). Flags **Accepted but not implemented** as errors,
  **Conditionally Accepted** rows as warnings. The flag may be repeated
  to fold several compliance matrices into one chapter, and
  `--requirements-bib YAML` attaches BibTeX-style metadata so the LaTeX
  output emits `\cite{key}` next to every requirement plus a
  `thebibliography` block at the end.
- `--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:
  `udsxml2tex --bootstrap-ollama` (Linux/macOS). The default model and
  `num_ctx` are now auto-selected from detected RAM + GPU VRAM (qwen2.5
  family, 0.5b → 32b) so low-spec laptops don't pull a model that
  forces them to swap; pass `--bootstrap-model` to override.

**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 three 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). A
    **Compliance Matrices** card accepts one or more DOORS-style CSVs
    plus an optional sources YAML, and the **Load sample bundle**
    button one-clicks the entire repo → CSV → tex → pdf demo flow
    against bundled samples without any local files.
  - **Chat** — multi-turn LLM Q&A (Anthropic / Ollama / OpenAI-compatible)
    with streaming responses; spec is cached server-side per session.
  - **ECU Test** — drive CAN/ISO-TP test runs from the browser.

**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 + `udsxml2tex[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`](docs/README_full.md)
- **Standards coverage matrices** (ISO ↔ AUTOSAR ECUC ↔ udsxml2tex,
  with `file:line` source citations):
  [`docs/standards/`](docs/standards/)
  — ISO 15765-2 (CanTp), ISO 14229-2 (session/timing),
  ISO 14229-1 (services, DTC/Dem), required-ARXMLs note.
- **Changelog**: [`CHANGELOG.md`](CHANGELOG.md)
- **Contributing**: [`CONTRIBUTING.md`](CONTRIBUTING.md)

---

## Requirements

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

---

## License

MIT
