Metadata-Version: 2.4
Name: udsxml2tex
Version: 0.18.1
Summary: Convert AUTOSAR DCM/CanTp/DEM arxml to LaTeX UDS (ISO 14229 / 15765) specification documents
Author: udsxml2tex contributors
License: MIT
Project-URL: Homepage, https://github.com/YutaroNakagama/udsxml2tex
Project-URL: Repository, https://github.com/YutaroNakagama/udsxml2tex
Project-URL: Changelog, https://github.com/YutaroNakagama/udsxml2tex/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/YutaroNakagama/udsxml2tex/issues
Keywords: autosar,arxml,uds,dcm,dem,cantp,iso14229,iso15765,latex,tex,diagnostics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Classifier: Typing :: Typed
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/DEM arxml to LaTeX UDS specification documents**

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

## Features

### DCM — Application Layer (ISO 14229-1)

- Diagnostic sessions (P2/P2* timing)
- Security access levels (seed/key sizes, attempt counters, algorithm refs)
- 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, sessions
- 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)
- 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)
- ClearDiagnosticInformation notifications
- Multi-client / multi-protocol configuration (ISO 14229-1 Annex D)
- Access Timing Parameters (ISO 14229-2)
- DSL buffer sizes, protocol type, connection mode

### 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
- Event memory configuration (Primary, Mirror, Permanent)
- Indicators (MIL / warning lamp behaviour)

### Output and tooling

- **Multiple output formats** — LaTeX (.tex), HTML, and direct PDF compilation
- **ARXML validation** — pre-parse checks with detailed warnings
- **Interactive mode** — step-by-step guided generation via CLI wizard
- **Config file support** — save/load generation settings as JSON
- **Dry-run mode** — preview parsed specification summary without file output
- **NRC 0x22 detail extraction** from C source code (heuristic pattern matching)
- Per-service UML sequence diagrams (NRC decision flow)
- Customizable via Jinja2 templates and `udsspec` document class
- Available as CLI command, interactive wizard, and Python API
- Merges multiple arxml files (e.g. DCM + CanTp + DEM)

## 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

# Merge a separate DEM arxml file
udsxml2tex dcm_config.arxml --dem dem_config.arxml -o 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, DemParser, TexGenerator

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

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

# Optionally merge a separate DEM arxml
DemParser().parse("dem_config.arxml", spec)

# 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, 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 configuration, diagnostic sessions (ID, P2/P2*/S3 timers), access timing parameters
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 level detail table
     - RoutineControl (0x31) — routine overview + parameter tables
     - LinkControl (0x87) — supported baud rates table
   - **Data Identifiers (DIDs)** — DID overview + data element layouts
   - **Memory Ranges** — read/write address ranges with session/security constraints
   - **IO Control DIDs** — control modes and mask sizes
   - **Periodic DIDs** — transmission modes and update periods
   - **DID Ranges** — consecutive DID blocks
   - **Dynamic DIDs** — DynamicallyDefineDataIdentifier configuration
   - **Authentication** (ISO 14229-1:2020 §9.6) — role, white-list, certificate/PSK
   - **ControlDTCSetting / ClearDTC** — CDTC status mask, default DTC group
   - **Named DTC Groups** — DcmDspGroupOfDTC entries
   - **Upload/Download Max Block Length** (ISO 14229-1 §13)
   - **DCM General Configuration** — function period, FIM trigger, error detection
   - **Multi-Client Configuration** (ISO 14229-1 Annex D) — protocol rows and connections
7. **Diagnostic Event Manager (DEM) Configuration**
   - DEM General Configuration
   - DTC Status Byte — Availability Mask table (ISO 14229-1 §11.3.1)
   - DTC Severity Availability Mask (ISO 14229-1 Annex C.3.1)
   - DEM DTC Definitions — value, severity, kind, significance, OBD DTC values
   - Combined DTC Definitions
   - Freeze Frame Classes (ISO 14229-1 §11.3.3)
   - Extended Data Record Classes (ISO 14229-1 §11.3.4)
   - Operation Cycles
   - Event Memory Configuration
   - Event Parameters, Indicators, Enable/Storage Conditions

## 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) |
| `DcmDspDidRange` | Lower/upper limit, gaps, data length |
| `DcmDspDynamicDid` / `DcmDspDDDID` | 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 for ClearDTC/ReadDTC) |
| `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 access timing) |
| `DcmDspRequestFileTransfer` | Max path/file size, format identifier, block size |
| `DcmDspClearDTCNotification` | Notification class |
| `DcmDspLinkControl` | Fixed/specific baud rate records |
| `DcmDspMemory` | Max block length, compression/encrypting methods |
| `DcmDspCDTC` | ControlDTCSetting status mask |
| `DcmDspClearDTC` | Clear DTC group |
| `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` | DTC value; via `DemDTCAttributes`: severity, kind, significance, priority, aging, OBD DTC, WWH-OBD class, freeze frame/extended data 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/freeze frame triggers |
| `DemFreezeFrameClass` | DID references captured in snapshot (ISO 14229-1 §11.3.3) |
| `DemExtendedDataClass` | Record number, data size, update trigger (ISO 14229-1 §11.3.4) |

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
