Metadata-Version: 2.4
Name: vss-translate
Version: 0.2.0
Summary: Translate between OEM-proprietary vehicle signals and the COVESA VSS standard
Author: vss-translate contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/vss-translate/vss-translate
Project-URL: Documentation, https://github.com/vss-translate/vss-translate#readme
Project-URL: Repository, https://github.com/vss-translate/vss-translate
Project-URL: Issues, https://github.com/vss-translate/vss-translate/issues
Keywords: automotive,vehicle,COVESA,VSS,CAN bus,OBD-II,connected car,vehicle signals
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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 :: Libraries
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: can
Requires-Dist: python-can>=4.0; extra == "can"
Requires-Dist: cantools>=39.0; extra == "can"
Provides-Extra: cli
Requires-Dist: click>=8.0; extra == "cli"
Provides-Extra: all
Requires-Dist: python-can>=4.0; extra == "all"
Requires-Dist: cantools>=39.0; extra == "all"
Requires-Dist: click>=8.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

# vss-translate

**A Babel for car data.** Translate between OEM-proprietary vehicle signal names and the open [COVESA Vehicle Signal Specification (VSS)](https://covesa.github.io/vehicle_signal_specification/) standard.

Every car manufacturer uses different names for the same data. Mercedes calls vehicle speed `MB_ESP_VehicleSpeed`, BMW calls it `BMW_DSC_VehicleSpeed`, Tesla calls it `TESLA_DI_vehicleSpeed`. The COVESA VSS standard defines it as `Vehicle.Speed`.

This library lets you write one codebase that works with any car brand.

## Install

```bash
pip install vss-translate
```

## Quick Start

```python
from vss_translate import SignalTranslator

t = SignalTranslator()

# OEM → VSS standard
result = t.to_vss("MB_ESP_VehicleSpeed", brand="mercedes")
print(result.target_signal)  # "Vehicle.Speed"

# VSS standard → OEM
result = t.from_vss("Vehicle.Speed", brand="bmw")
print(result.target_signal)  # "BMW_DSC_VehicleSpeed"

# Cross-brand translation (Mercedes → Tesla)
result = t.cross_brand("MB_ESP_VehicleSpeed", "mercedes", "tesla")
print(result.target_signal)  # "TESLA_DI_vehicleSpeed"

# With unit conversion (Tesla mph → VSS km/h)
result = t.to_vss("TESLA_DI_vehicleSpeed", brand="tesla", value=60)
print(f"{result.target_value:.1f} {result.target_unit}")  # "96.6 km/h"

# Auto-detect brand from signal names
detection = t.detect_brand(["MB_ESP_VehicleSpeed", "MB_ECM_EngineSpeed"])
print(detection.brand)  # "mercedes"
```

## Supported Brands

| Brand | Alias(es) | Signals |
|-------|-----------|---------|
| Mercedes-Benz | `mb`, `mercedes-benz`, `daimler` | 50+ |
| BMW | - | 30+ |
| Volkswagen Group | `vw`, `audi`, `skoda`, `seat`, `cupra` | 30+ |
| Tesla | `tsla` | 40+ |
| Toyota / Lexus | `lexus` | 20+ |
| Hyundai / Kia / Genesis | `kia`, `genesis`, `hkg` | 25+ |
| OBD-II (generic) | `obd`, `obdii` | 20+ |

## Features

- **Zero dependencies** for core functionality
- **Unit conversion** — automatic conversion between OEM and VSS units (mph↔km/h, psi↔kPa, bar↔kPa)
- **Brand detection** — auto-identify vehicle brand from signal name patterns
- **Fuzzy search** — find signals by keyword across all brands
- **Batch translation** — translate entire data snapshots at once
- **Cross-brand translation** — go from Mercedes signals directly to BMW signals (via VSS)
- **CLI tool** — command-line interface for quick lookups

## CLI Usage

```bash
# Translate OEM → VSS
vss-translate to-vss MB_ESP_VehicleSpeed -b mercedes

# Translate VSS → OEM
vss-translate from-vss Vehicle.Speed -b tesla

# Cross-brand with value conversion
vss-translate cross TESLA_DI_vehicleSpeed -s tesla -t mercedes -v 60

# Detect brand
vss-translate detect MB_ESP_VehicleSpeed MB_ECM_EngineSpeed

# List brands and coverage
vss-translate brands

# Search signals
vss-translate search "tire pressure" -b mercedes
```

## Why This Exists

The EU Data Act (enforceable 2025-2026) mandates that vehicle manufacturers share data with owners and third parties. But every OEM uses proprietary signal names and formats. There is no developer-friendly library to bridge this gap.

`vss-translate` uses the COVESA VSS open standard as the Rosetta Stone between brands.

## License

MIT
