Metadata-Version: 2.4
Name: udsxml2tex
Version: 0.12.0
Summary: Convert AUTOSAR DCM/CanTp arxml to LaTeX UDS specification documents
Author: udsxml2tex contributors
License: MIT
Project-URL: Homepage, https://github.com/YutaroNakagama/udsxml2tex
Project-URL: Repository, https://github.com/YutaroNakagama/udsxml2tex
Keywords: autosar,arxml,uds,dcm,cantp,iso15765,latex,tex,diagnostics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml>=4.9.0
Requires-Dist: Jinja2>=3.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# udsxml2tex

**Convert AUTOSAR DCM/CanTp arxml to LaTeX UDS specification documents**

A Python library that parses AUTOSAR DCM (Diagnostic Communication Manager) and CanTp (CAN Transport Protocol) arxml configuration files and automatically generates ISO 14229 (UDS) / ISO 15765 (UDS on CAN) specification documents in LaTeX format.

## Features

- Automatically extracts UDS specification data from DCM arxml files
  - Diagnostic sessions
  - Security access levels
  - UDS service list (SID, supported sessions, NRCs, etc.)
  - DID (Data Identifier) definitions
  - Routine Control definitions
- Parses CanTp arxml for transport layer configuration
  - Channel parameters (Block Size, STmin, channel mode)
  - ISO 15765-2 timing parameters (N\_As, N\_Bs, N\_Cs, N\_Ar, N\_Br, N\_Cr)
  - Addressing format and padding configuration
- **Multiple output formats** — LaTeX (.tex), HTML, and direct PDF compilation
- **ARXML validation** — pre-parse validation with detailed error messages and warnings
- **Interactive mode** — step-by-step guided generation via CLI
- **Config file support** — save/load generation settings as JSON
- **Dry-run mode** — preview parsed specification summary without generating output
- NRC 0x22 detail auto-extraction from C source code
- ISO 14229-1 standard NRC common format table (automatically included)
- Full message format definitions for 24 UDS services including LinkControl (0x87)
- Customizable via Jinja2 templates and document class
- Available as CLI command, interactive wizard, and Python API
- Supports merging multiple arxml files (DCM + CanTp)

## Installation

```bash
pip install udsxml2tex
```

From source (for development):

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

## Usage

### CLI (Direct Mode)

```bash
# Basic conversion
udsxml2tex input.arxml

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

# Override ECU name
udsxml2tex input.arxml --ecu-name "MyECU"

# Merge and convert multiple files (DCM + CanTp)
udsxml2tex dcm_config.arxml cantp_config.arxml -o merged_spec.tex

# Generate HTML output
udsxml2tex input.arxml --html -o spec.html

# Generate LaTeX and compile directly to PDF
udsxml2tex input.arxml --pdf -o spec.tex

# Dry run — preview parsed data without generating output
udsxml2tex input.arxml --dry-run

# Verbose logging
udsxml2tex input.arxml -v
```

### Interactive Mode

Launch an interactive wizard that guides you through the entire generation process:

```bash
udsxml2tex -I
```

The wizard will ask you:

1. **ARXML type** — DCM, CanTp, or both
2. **File paths** — path to each ARXML file
3. **ECU name**
4. **Item selection** — which SIDs, DIDs, routines, and sessions to include
5. **Timing parameters** — whether to include P2/P2\* and CanTp timing
6. **NRC 0x22 details** — for services supporting conditionsNotCorrect:
   - Free-text description, or
   - Path to C source code for automatic extraction
7. **Document class** — use default `udsspec.cls` or specify a custom `.cls`
8. **Output path**
9. **Save config** — optionally save all settings to a JSON file for reuse

### Config File Mode

Use a previously saved configuration file to reproduce a generation run:

```bash
# Run from config file
udsxml2tex --config udsxml2tex_config.json

# Override specific settings on top of config
udsxml2tex --config udsxml2tex_config.json -o different_output.tex --ecu-name "NewECU"
```

Config files are JSON and can be created via interactive mode or manually:

```json
{
  "arxml_type": "dcm",
  "dcm_arxml_path": "/path/to/dcm_config.arxml",
  "cantp_arxml_path": "",
  "include_services": [16, 34, 39],
  "include_dids": [61840, 61841],
  "include_routines": [],
  "include_sessions": [],
  "include_timing_params": true,
  "include_cantp_timing": true,
  "nrc22_details": {"34": "Flash memory is busy"},
  "ecu_name": "MyECU",
  "output_path": "output/uds_spec.tex",
  "cls_file_path": "",
  "template": "uds_spec.tex.j2",
  "template_dir": ""
}
```

### Python API

```python
from udsxml2tex import ArxmlParser, TexGenerator

# Parse ARXML (DCM + CanTp)
parser = ArxmlParser()
spec = parser.parse("path/to/dcm_config.arxml")

# Or merge multiple files
spec = parser.parse_multi(["dcm_config.arxml", "cantp_config.arxml"])

# Validate before parsing (returns list of warnings)
warnings = parser.validate("path/to/dcm_config.arxml")

# Generate LaTeX
generator = TexGenerator()
generator.generate(spec, "output/uds_spec.tex")

# Get as string
tex_content = generator.generate_string(spec)

# Generate HTML
html_path = generator.generate_html(spec, "output/uds_spec.html")

# Compile LaTeX to PDF (requires pdflatex or latexmk)
pdf_path = generator.compile_pdf("output/uds_spec.tex")
```

You can also use the config/interactive components programmatically:

```python
from udsxml2tex import GenerationConfig, InteractiveSession
from udsxml2tex.interactive import generate_from_config

# Load and run from config
config = GenerationConfig.load("udsxml2tex_config.json")
generate_from_config(config)

# Or launch interactive mode from code
session = InteractiveSession()
session.run()
```

### Custom Templates

You can use your own LaTeX templates:

```python
generator = TexGenerator(template_dir="my_templates/")
generator.generate(spec, "output.tex", template_name="custom.tex.j2")
```

```bash
udsxml2tex input.arxml --template-dir my_templates/ --template custom.tex.j2
```

### Document Class (`udsspec.cls`)

The generated documents use the `udsspec` document class, which encapsulates all package imports, page layout, header/footer styling, and custom commands. The `.cls` file is automatically copied alongside the output `.tex` file during generation.

When creating a custom template, use `\documentclass{udsspec}` and configure metadata via the following commands:

```latex
\documentclass{udsspec}

\ecuname{MyECU}              % ECU name (appears in header and title)
\docversion{2.0}             % Document version (default: 1.0)
\docresponsible{John Doe}    % Responsible person (header field)
\docauthor{Jane Smith}       % Author (header field)
\docfooter{CONFIDENTIAL}     % Footer text (default: Generated by udsxml2tex)
```

The class provides the following commands for use in document body:

| Command | Example | Output |
|---------|---------|--------|
| `\serviceid{10}` | `\serviceid{10}` | `10`₁₆ |
| `\hexval{FF}` | `\hexval{FF}` | `FF`₁₆ |

Custom column types `C{width}` (centered) and `L{width}` (left-aligned) are also available.

## Compiling to PDF

### Via CLI (recommended)

```bash
# Compile to PDF directly
udsxml2tex input.arxml --pdf -o output.tex
```

### Manual compilation

The generated `.tex` file can be compiled to PDF using `pdflatex`:

```bash
# Basic compilation
pdflatex output.tex

# Full compilation (recommended — resolves cross-references and TOC)
pdflatex output.tex && pdflatex output.tex
```

> **Note:** A LaTeX distribution with `pdflatex` is required (e.g., [TeX Live](https://www.tug.org/texlive/), [MiKTeX](https://miktex.org/)). The `udsspec.cls` document class and `tikz-uml.sty` style file are bundled with the generated output, so no additional package installation is needed.

## Generated Document Structure

The document is structured according to the OSI reference model:

1. **Title Page** — ECU name, date
2. **Table of Contents**
3. **Document Overview** — OSI layer mapping overview
4. **Transport Layer (ISO 15765-2 / CanTp)** — Channel overview, timing parameters, addressing & padding
5. **Session Layer (ISO 14229-2)** — Diagnostic sessions (ID, P2/P2* timers)
6. **Application Layer (ISO 14229-1)**
   - Negative Response common format & standard NRC code reference (ISO 14229-1)
   - UDS Services — Service overview + per-service details (sub-functions, NRCs)
     - SecurityAccess (0x27) includes security access levels
     - RoutineControl (0x31) includes routine overview + parameter details
   - Data Identifiers (DIDs) — DID overview + data element details

## Supported arxml Structure

The following AUTOSAR module configuration elements are parsed:

| Module | Element | Description |
|--------|---------|-------------|
| DCM | `DcmDsl` | Diagnostic Session Layer (protocol, timing) |
| DCM | `DcmDsp` | Diagnostic Service Processing (sessions, security, DIDs, routines) |
| DCM | `DcmDsd` | Diagnostic Service Dispatcher (service table) |
| CanTp | `CanTpGeneral` | Main function period |
| CanTp | `CanTpChannel` | Channel mode, RxNSdu/TxNSdu (BS, STmin, N\_As/N\_Bs/N\_Cs/N\_Ar/N\_Br/N\_Cr, padding, addressing) |

Supports AUTOSAR R4.x arxml format.

## Requirements

- Python >= 3.9
- lxml >= 4.9.0
- Jinja2 >= 3.1.0
- LaTeX distribution (for compiling the generated .tex files)

## License

MIT License
