# How the TeslaMate Conversion Module Handles Unit Transformations

> Discover how the TeslaMate Convert module centralizes unit transformations for speed, distance, temperature, and time. Ensure consistent data across UI and database.

- Repository: [TeslaMate/teslamate](https://github.com/teslamate-org/teslamate)
- Tags: internals
- Published: 2026-06-16

---

**The `TeslaMate.Convert` module centralizes all unit normalization using pure functions and compile-time constants, ensuring consistent speed, distance, length, temperature, and time transformations across the UI and database.**

The `teslamate-org/teslamate` repository relies on the conversion module to normalize raw data received from the Tesla API into locale-appropriate units. Located in [`lib/teslamate/convert.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/convert.ex), this module implements total functions that return `nil` for `nil` inputs while preserving type safety through overloaded arithmetic for `Decimal`, float, and integer values.

## Core Architecture of the Conversion Module

The conversion module defines transformation factors as module attributes at compile time. All functions are **pure and side-effect free**, making them safe to call from LiveViews, background jobs, and API handlers without triggering database queries or external I/O.

The module handles **three numeric types** distinctly:
- `Decimal` structs for exact arithmetic
- Integers when precision is set to `0`
- Floats for standard floating-point rounding

This design ensures that TeslaMate maintains precision for financial or scientific calculations while allowing flexible formatting for display purposes.

## Speed and Distance Conversions

### Miles per Hour to Kilometres per Hour

The `mph_to_kmh/1` function converts vehicle speed data using the `@km_factor` constant. When the input is a `Decimal`, the function performs exact division using `Decimal` arithmetic; otherwise, it applies `round/1` to the result.

```elixir

# Convert API speed (mph) to km/h with Decimal precision

speed_mph = Decimal.new("55.2")
speed_kmh = TeslaMate.Convert.mph_to_kmh(speed_mph)

```

### Distance Transformations

Distance conversions support bidirectional transformation with configurable precision. The `miles_to_km/2` and `km_to_miles/2` functions in [`lib/teslamate/convert.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/convert.ex) handle three cases:
- `Decimal` values using `@km_factor_d` for exact conversion
- Integer rounding when precision is `0`
- Float rounding for all other precision levels

```elixir

# Convert odometer reading with 2-decimal precision

odometer_mi = 12345.678
odometer_km = TeslaMate.Convert.miles_to_km(odometer_mi, 2)

# => 19860.57

```

## Length and Temperature Transformations

### Metres to Feet and Inverse

For length conversions, `m_to_ft/1` and `ft_to_m/1` utilize the `@ft_factor` constant. The metre-to-feet function multiplies by the factor, while the inverse divides by it. Both functions support `Decimal` inputs through `Decimal.mult/2` and equivalent division operations.

### Celsius to Fahrenheit

The `celsius_to_fahrenheit/2` function implements the standard formula **(C × 9 / 5) + 32**. Like distance conversions, it provides a `Decimal` overload for exact arithmetic and falls back to float or integer rounding based on the specified precision parameter.

## Time Formatting with sec_to_str/1

Beyond unit transformations, the module handles temporal data through `sec_to_str/1`. This function decomposes a seconds value into weeks, days, hours, minutes, and seconds using a pre-computed `@divisor` list.

The implementation:
- Calculates components for each time unit
- Discards zero-valued components
- Returns at most two parts (e.g., `["2 wk", "3 d"]`)

This formatting appears throughout the TeslaMate dashboard when displaying charging durations or trip lengths.

```elixir

# Format charging duration for UI display

seconds = 9_864
TeslaMate.Convert.sec_to_str(seconds)

# => ["2 hr", "44 min"]

```

## Integration Across the Codebase

The conversion module integrates deeply into TeslaMate's data pipeline:

- **Vehicle Summary Serializer**: [`lib/teslamate/vehicles/vehicle/summary.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/vehicles/vehicle/summary.ex) imports conversion functions directly to transform OBD data before JSON serialization for the UI.

- **Vehicle State Management**: [`lib/teslamate/vehicles/vehicle.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/vehicles/vehicle.ex) aliases the module to convert speed, distance, and range values when preparing vehicle state for API responses.

- **LiveView Interfaces**: [`lib/teslamate_web/live/car_live/summary.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate_web/live/car_live/summary.ex) demonstrates UI-specific usage by calling `Convert.sec_to_str/1` to render charging session durations as human-readable strings like "2 hr 30 min".

## Summary

- The `TeslaMate.Convert` module in [`lib/teslamate/convert.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/convert.ex) provides pure, total functions for all unit transformations.
- Compile-time constants (`@km_factor`, `@ft_factor`, `@divisor`) ensure consistent conversion factors across the application.
- Functions handle `Decimal`, integer, and float inputs with appropriate arithmetic precision.
- The module supports speed (mph/kmh), distance (miles/km), length (m/feet), temperature (C/F), and time (seconds to formatted strings).
- Integration points include vehicle serializers, state managers, and Phoenix LiveViews for consistent data representation.

## Frequently Asked Questions

### How does TeslaMate handle precision in distance conversions?

The `miles_to_km/2` and `km_to_miles/2` functions accept a precision parameter. When set to `0`, they return rounded integers. For other values, they return floats rounded to the specified decimal places. `Decimal` inputs receive exact arithmetic treatment without rounding errors.

### What happens when conversion functions receive nil values?

All functions in the conversion module are **total functions**, meaning they safely return `nil` when the input is `nil`. This design prevents runtime exceptions in the vehicle data pipeline when the Tesla API temporarily returns incomplete telemetry.

### Where is the conversion module used in the TeslaMate UI?

The module appears in [`lib/teslamate_web/live/car_live/summary.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate_web/live/car_live/summary.ex) for formatting charging durations, and throughout `lib/teslamate_web/live/vehicle_live/*` templates for displaying converted speed, range, and temperature values to end users.

### Why does TeslaMate use Decimal arithmetic for some conversions?

The Tesla API occasionally returns high-precision floating-point values for odometer and speed readings. By using `Decimal` structs in `mph_to_kmh/1` and distance functions, TeslaMate avoids floating-point rounding errors that could accumulate in long-term mileage calculations or energy efficiency metrics.