# LiveLink

Real-time vehicle telemetry monitoring. LiveLink connects your vehicle's onboard diagnostics to MyGarage, providing live data, drive session tracking, diagnostic trouble codes, and automatic odometer updates.

Telemetry can reach MyGarage from a **WiCAN** OBD2 device (covered first
below), from the **Torque Pro** Android app with any ELM327 adapter (see
[Torque Pro](#torque-pro-no-wican-required) if you'd rather not buy hardware),
or from any MQTT sensor, such as a Mopeka propane tank sensor (see
[MQTT Sensors and Devices](#mqtt-sensors-and-devices)).

---

## What is LiveLink?

LiveLink is MyGarage's integration with [WiCAN](https://www.meatpi.com/products/wican) OBD2 devices from MeatPi Electronics. These WiFi-enabled adapters plug into your vehicle's OBD2 port and transmit decoded telemetry data to MyGarage.

**Key capabilities:**
- **Real-time telemetry** — Speed, RPM, coolant temperature, and dozens of other parameters
- **Drive sessions** — Automatic detection of engine start/stop with trip statistics
- **Diagnostic codes** — Monitor and track DTCs
- **Odometer sync** — Automatic odometer updates when your vehicle supports the PID
- **Historical charts** — Visualize telemetry trends over time
- **Alerts** — Notifications for threshold breaches, device offline, and firmware updates

---

## Why Use LiveLink?

- **Monitor Vehicle Health** — Catch issues early by watching coolant temp, battery voltage, and engine parameters
- **Track Drive History** — See every trip with duration, distance, and performance stats
- **Automatic Odometer** — No more manual odometer entries when LiveLink captures the reading
- **DTC Awareness** — Know when a check engine light appears and what it means
- **Data Ownership** — All telemetry stays on your server, not in a third-party cloud

---

## Hardware Requirements

### WiCAN PRO (Recommended)

| Requirement | Details |
|-------------|---------|
| **Device** | WiCAN PRO (ESP32-S3, 8MB PSRAM) |
| **Firmware** | v4.40 or newer for HTTPS POST |
| **Connection** | WiFi (2.4GHz) |
| **Vehicle** | OBD2 port (1996+ vehicles in North America) |

The **WiCAN PRO** supports both HTTPS POST and MQTT transport methods.

### Standard WiCAN

The standard WiCAN (non-PRO) has limited flash memory and does **not** support HTTPS POST. However, it can work with LiveLink via **MQTT** if you have an MQTT broker on your network.

| Feature | WiCAN PRO | Standard WiCAN |
|---------|-----------|----------------|
| HTTPS POST | ✅ Yes | ❌ No |
| MQTT | ✅ Yes | ✅ Yes |
| Memory | 8MB PSRAM | 4MB Flash |

---

## Getting Started

**Admin only:** The LiveLink setup panel and global settings (ingestion token, MQTT, firmware, device list) are visible to admins only. Per-device actions such as linking a device or issuing a device token also require ownership of the device's linked vehicle.

### The LiveLink Card

**Settings → Integrations → LiveLink** has one tab per source: **WiCAN**,
**Torque**, **Mosquitto** (your MQTT broker), one per sensor type you have added
(such as **Mopeka**), and one per MQTT device you created. A dot shows each
tab's status, and the tab's **{source} settings** button (for example **WiCAN
settings**) opens that source's settings and devices.

The gear at the top of the card opens **LiveLink settings**: the master switch,
data retention, drive detection and alerts. **Add source** adds a sensor or an
MQTT device.

### Turn LiveLink On

LiveLink is off on a new install. Open **LiveLink settings** (the gear) and
switch on **Enable LiveLink**. While it is off, nothing from any source (WiCAN,
Torque, MQTT or an SD-card backfill) is stored, and no new device is discovered.
An install that was already receiving MQTT or Torque data is switched on when it
upgrades.

### Prerequisites

1. WiCAN device installed in your vehicle's OBD2 port
2. WiCAN connected to your WiFi network
3. MyGarage accessible from WiCAN (same network or via reverse proxy)

### Quick Setup (HTTPS POST)

1. Navigate to **Settings → Integrations → LiveLink** and make sure LiveLink is on (see above)
2. On the **WiCAN** tab, click **WiCAN settings**
3. Copy the **Ingestion URL** (e.g., `https://mygarage.local/api/v1/livelink/ingest`)
4. Under **Global API Token**, click **Generate** and copy the token. It is shown only once; **Regenerate** replaces it, and devices using the old token stop sending until you update them
5. Open your WiCAN's web UI (browse to its IP address)
6. In WiCAN settings, configure:
   - **HTTPS POST URL**: Paste the ingestion URL
   - **Authorization Header**: `Bearer YOUR_TOKEN`
   - **Push Interval**: 5 seconds recommended
7. Save and reboot WiCAN
8. Return to MyGarage: your device should appear under **Devices** in **WiCAN settings**
9. Pick its vehicle in the device's **Vehicle** dropdown

### Quick Setup (MQTT)

1. Ensure you have an MQTT broker running (e.g., Mosquitto)
2. Configure your WiCAN to publish to the broker:
   - **MQTT Broker**: Your broker's IP/hostname
   - **Topic Prefix**: `wican` (default)
   - **Enable AutoPID MQTT output**
3. In MyGarage, go to **Settings → Integrations → LiveLink** and make sure LiveLink is on (see above)
4. On the **Mosquitto** tab, click **Mosquitto settings**
5. Switch on **Enable MQTT Subscription** and fill in:
   - **Broker Host**: Your MQTT broker IP
   - **Port**: 1883 (default)
   - **Username** and **Password** if your broker needs them, and **Use TLS/SSL** if it uses TLS
6. Click **Save**. The switch starts and stops the subscriber, and saving a
   broker change restarts it. **Test** checks the connection
7. On the **WiCAN** tab, open **WiCAN settings** and check **WiCAN MQTT topic prefix** is `wican` (it must match the WiCAN config)
8. Link discovered devices to vehicles in the same drawer

---

## Configuring Your WiCAN Device

WiCAN has its own web-based configuration interface. MyGarage does **not** configure WiCAN directly — you must access the device's web UI.

### Accessing the WiCAN Web UI

1. Find the device's IP address (check your router's DHCP leases or use the IP shown in MyGarage)
2. Open a browser and navigate to `http://<device_ip>`
3. Default credentials are printed on the device or in WiCAN documentation

### AutoPID Configuration

AutoPID tells WiCAN which OBD2 parameters to poll. You can:

- **Use a vehicle profile** — WiCAN includes profiles for many makes/models
- **Add custom PIDs** — For manufacturer-specific parameters (like odometer on some vehicles)
- **Set polling interval** — How often to request each PID (typically 1-5 seconds)

**Important:** For MQTT output, ensure AutoPID is configured to publish **decoded JSON**, not raw CAN frames.

**Units.** Over HTTPS a WiCAN declares each reading's unit once per boot, and
MyGarage keeps them per device, so they survive a MyGarage restart. A speed
declared in mph is stored as km/h. Speed is otherwise expected in km/h, as the
standard PID sends it, so a custom speed PID in mph that declares no unit is
read as km/h.

✅ **Correct format (decoded):**
```json
{"odometer": 87458.0, "engine coolant temperature": 91.5}
```

❌ **Incorrect format (raw CAN):**
```json
{"bus":"0","type":"rx","frame":[{"id":631,"dlc":8,"data":"FF0000010000AAA7"}]}
```

### Vehicle-Specific PIDs

Some parameters like **odometer** are not part of the standard OBD2 specification. You may need to:

1. Search for your vehicle's manufacturer-specific PIDs
2. Add them as custom PIDs in WiCAN's AutoPID configuration
3. Test and verify the decoded values are correct

Community PID databases:
- [WiCAN Vehicle Profiles](https://github.com/meatpiHQ/wican-fw/tree/main/vehicle_profiles)
- [OBD2 PID Wiki](https://en.wikipedia.org/wiki/OBD-II_PIDs)

---

## Transport Methods

LiveLink supports two ways to receive data from WiCAN devices.

### HTTPS POST

WiCAN pushes data directly to MyGarage's ingestion endpoint.

**How it works:**
1. WiCAN polls OBD2 PIDs on a cycle (e.g., every 5 seconds)
2. WiCAN packages telemetry into a JSON payload
3. WiCAN sends an HTTPS POST to MyGarage with Bearer token authentication
4. MyGarage processes and stores the data

**Pros:**
- ✅ Simple setup — no broker needed
- ✅ Secure — TLS encryption, token authentication
- ✅ Works over the internet (if MyGarage is publicly accessible)

**Cons:**
- ❌ Requires WiCAN PRO (standard WiCAN doesn't support HTTPS POST)
- ❌ Higher latency (new connection each request)
- ❌ Requires public endpoint or tunnel for remote access

### MQTT Subscription

MyGarage subscribes to topics on an MQTT broker where WiCAN publishes.

**How it works:**
1. WiCAN publishes telemetry to MQTT topics (e.g., `wican/<device_id>/can/rx`)
2. MyGarage's MQTT subscriber listens for messages
3. Messages are processed and stored using the same pipeline as HTTPS POST

**Retained messages are ignored.** A broker replays its retained messages on
every reconnect, which used to restamp a dead device's last values as new. Only
a retained `offline` from a device's last will still counts.

**Topic structure:**
```
wican/{device_id}/can/status  → ECU online/offline
wican/{device_id}/battery     → Device battery voltage
wican/{device_id}/can/rx      → Telemetry parameters
```

**Pros:**
- ✅ Works with standard WiCAN (non-PRO)
- ✅ Lower latency (persistent connection)
- ✅ Works purely on LAN — no public endpoint needed
- ✅ Can run alongside HTTPS POST (see [Running Both Simultaneously](#running-both-simultaneously))

**Cons:**
- ❌ Requires MQTT broker setup (e.g., Mosquitto)
- ❌ Additional infrastructure to maintain

**Device commands:** While the broker is connected, an online WiCAN's row in **WiCAN settings** has a **Check battery voltage** button.

### Running Both Simultaneously

You can enable both HTTPS POST and MQTT at the same time, but pick one for
telemetry. MyGarage drops a reading only when the same device sends the same
parameter with the same timestamp, and the two channels stamp readings
differently (an HTTPS upload carries the device's time, an MQTT message gets
the time it arrived), so a reading sent both ways is stored twice.

---

## Torque Pro (No WiCAN Required)

[Torque Pro](https://torque-bhp.com/) is an Android OBD2 app that works with any
cheap ELM327 Bluetooth adapter. Its built-in **Web Upload** feature can send
telemetry straight to MyGarage, so you get live data, drive sessions and trip
history without buying a WiCAN device.

Each Torque source gets its own upload URL and token, so you can connect more
than one phone to the same vehicle and revoke them individually.

### Setting Up a Torque Source

1. Go to the vehicle detail page
2. Open **Vehicle Settings**
3. Click **Torque Source**
4. Click **Add source**, give it a label (e.g. "My Phone"), and click **Create**
5. Copy the **Upload URL** — this is the full address to paste into Torque

> **Copy the token now.** The device token is shown once, at creation, and
> cannot be retrieved afterwards. If you lose it, revoke the source and create
> a new one.

Then in Torque Pro, open its web-upload settings (**Data Logging & Upload** in
current versions), enable uploading to a web server, and paste the Upload URL
into the web server address field. Start a session and Torque uploads while you
drive.

### ⚠️ Set Torque to Metric

**In Torque Pro, set units to metric for all values** (Settings → Units).

MyGarage stores telemetry in metric internally and expects Torque's values in
metric. If Torque uploads imperial readings they are taken at face value, and
every speed, temperature and distance imported will be wrong. This is the single
most common cause of nonsense Torque data.

Your MyGarage display units are unaffected — you can still read everything in
MPH and °F. This setting is only about what Torque puts on the wire.

### How It Works

Torque sends telemetry as an HTTP **GET** with the readings encoded in the query
string. MyGarage accepts that, and also accepts POST for other tools. Tokens are
redacted from the server logs, so an upload URL never appears in plaintext there.

### Managing and Revoking Sources

The Torque Source panel lists each source with its device ID and when it was last
seen. Click **Revoke** to cut a source off — Torque will no longer be able to
upload until you configure it with a new source.

Revoking keeps everything the source already sent. Its telemetry and drive
sessions stay on the vehicle; only the ability to upload more is withdrawn.

Admins can also add a Torque source for any vehicle from the **Torque** tab's
**Torque settings** in Settings → Integrations → LiveLink.

---

## Trips & Location (Torque Only)

Torque Pro can report GPS position alongside its OBD2 readings. When it does,
MyGarage records those points and builds them into trips.

**This is Torque-only.** WiCAN devices do not report position, so a WiCAN-only
setup records no location data at all, whatever the setting below says.

### What You Get

- **Trips** — a sub-tab on the vehicle's LiveLink tab, listing each drive session
  that carried GPS points, with its route drawn on a map.
- **Last known location** — a card on the vehicle's Overview showing where it was
  last seen.
- **GPS distance** — for Torque sessions, trip distance is calculated from the
  GPS track rather than the odometer.

### Turning It Off

Location tracking is **on by default** for every vehicle, but it does nothing
until a Torque source actually sends GPS.

To turn it off, open the vehicle's **LiveLink → Trips** tab and switch off
**Location tracking**. It is a per-vehicle setting, so turning it off on one
vehicle leaves the others unchanged. Telemetry, drive sessions and DTCs keep
working — only position stops being recorded.

Switching it off stops new points being stored. Points already recorded stay
until they age out (see below).

### How Long Points Are Kept

Location points are pruned on the same schedule and the same retention setting as
raw telemetry — **90 days by default**, adjustable in LiveLink settings. The
prune runs once a day.

There is no button to delete location history on demand; shortening the retention
window is the way to clear it out sooner.

---

## MQTT Sensors and Devices

Any device that publishes numbers to your MQTT broker can feed LiveLink. Set up
the broker first (see [Quick Setup (MQTT)](#quick-setup-mqtt), steps 3 to 6).
A sensor or device stores nothing until it is linked to a vehicle.

These sources send readings only. They never record a drive, so a sensor on a
parked trailer does not create trips.

### Propane Tanks (Mopeka)

Mopeka Pro Check sensors talk Bluetooth, so you need a gateway nearby (an
ESPHome board or a Home Assistant bridge, for example) that republishes their
readings to MQTT. Each tank is added as its own sensor:

1. In **Settings → Integrations → LiveLink**, click **Add source**
2. Under **Mopeka**, click **Add sensor**
3. Enter a **Name** (e.g. "Front tank"), pick the **Vehicle**, and paste the
   **Level topic**: the exact MQTT topic the tank's level arrives on
4. MyGarage listens to the broker and fills in the **Other readings**
   (temperature, battery and so on) from what it hears next to the level.
   Check them, clear any you don't want, and click **Add sensor**

Your tanks then share a **Mopeka** tab. **Mopeka settings** lists each tank with
its readings, and lets you rename it, change its vehicle, add another tank or
delete one. Deleting a tank also deletes all of its readings, so only an admin
can do it.

**Offline alerts:** a sensor has no status topic, so it counts as online while
its readings arrive and alerts once when it has been quiet for the **Device
Offline Timeout**. The alert says to check the sensor, not the vehicle battery.
The next live reading re-arms it.

**Alerts:** each tank has its own **Alerts** lines in **Mopeka settings**. The
level warns below **Low** (25% on a new sensor) and again below **Critical**
(10%), and the sensor battery warns below **Low** (20%). Leave a line blank to
switch it off, then click **Save alerts**. Each line sends one notification when
the reading drops below it, and does not send again until the reading has
climbed 5 points back above the Low line, as it does after a refill. These
notifications follow the **Parameter threshold breaches** switch (see
[Alerts & Notifications](#alerts--notifications)).

On the vehicle's **Live** tab each tank gets its own card, drawn at its level in
your accent colour with its other readings beside it. Below a line the tank
changes colour and is labelled **Low** or **Critical**.

### Other MQTT Devices

1. In **Settings → Integrations → LiveLink**, click **Add source**
2. Under **Blank device**, enter a **Device ID**, pick the **Vehicle**, add an
   optional **Label**, and click **Create device**
3. The device gets its own tab. Open its settings, and under **Advanced: topic
   mappings** add a **Topic**, a **Parameter key** and a **Unit** for each
   reading, then click **Add mapping**

Topics must be exact: `+` and `#` are refused. To see what a device publishes,
use **Discover topics** in **Mosquitto settings**: enter a **Topic prefix** and
click **Discover** to list the topics heard, each with a sample value. It
needs MQTT switched on with a broker set, and shows the broker's reason when the
broker refuses. Only
numbers can be mapped (on/off style values such as `ON`, `TRUE` or `OPEN` count
as 1 and 0); a sample that is not a number is flagged.

Each reading in a device's settings has a switch for whether it is shown on the
**Live** tab. Hiding a reading does not stop it being stored.

---

## Using LiveLink

Once a device is linked to a vehicle, a **LiveLink** tab appears on that vehicle's detail page.

Its sub-tabs depend on what the linked sources send: **Live** and **Charts**
always, **DTCs** with a WiCAN, **Sessions** with a WiCAN or Torque, and
**Trips** with Torque.

### Live Tab

Real-time telemetry display with gauge cards for each parameter.

**Status indicators:**
- 🟢 **Vehicle Running** — ECU online, data flowing
- 🔵 **Vehicle Parked** — ECU offline, WiCAN still connected
- 🔴 **Device Offline**: no communication from the device
- 🟢 **Connected**: shown instead of Running or Parked when only sensors are linked, such as a propane tank sensor

**Gauge cards show:**
- Parameter name and current value
- Unit of measurement
- Warning indicator if threshold exceeded
- Time of the reading

Propane tanks get their own cards (see [Propane Tanks](#propane-tanks-mopeka)).

**Refresh rate:** Dashboard polls every 5 seconds when the tab is active.

### DTCs Tab

Monitor diagnostic trouble codes reported by the vehicle's ECU.

**Features:**
- Filter by: **Active**, **Cleared**, or **All** (active and cleared codes together)
- Color-coded severity: 🔵 Info, 🟡 Warning, 🔴 Critical
- First seen / Last seen timestamps
- User-editable notes per DTC
- **Search Online** button — opens external search for the code

**Where codes come from:** codes are recorded when a WiCAN linked to the
vehicle sends them, over [HTTPS POST](#https-post) or [MQTT](#mqtt-subscription),
under the `DIAGNOSTIC_TROUBLE_CODES` key. Stock WiCAN firmware doesn't poll for
codes, so the tab stays empty unless your device's firmware or profile sends
them. Only values shaped like a code (such as `P0301`) are kept.

**Descriptions:** the built-in list covers the generic (SAE) codes, which mean
the same on every make, such as P0xxx, P2xxx, B0xxx, C0xxx and U0xxx.
Manufacturer-specific codes (P1xxx, P30xx to P33xx, and B, C or U codes whose
second character is 1 or 2) mean different things on different makes, so the
card says the code is manufacturer-specific instead of guessing. To look one
up, use **Search Online** and add your make to the search.

### Sessions Tab

Drive session history with statistics for each trip.

**Session data:**
- Start and end time
- Duration
- Distance traveled, read from the finest distance signal the device publishes
- Average and max speed
- Average and max RPM
- Coolant temperature range
- **Idle time** - how much of the session was spent stopped with the engine running
- **Harsh acceleration and braking counts** - derived from the speed trace

**Session detection:** a drive is recorded when the vehicle actually moves.
Movement means a speed at or above 5 km/h (about 3 mph), or, on a reading that
carries no speed, an odometer reading that has gone up. A reading under 5 km/h
never opens a drive, even when the odometer moved with it, so a car creeping in a car
park doesn't open a drive. An engine running while the vehicle sits still does
not open a drive on its own, so a remote start, a winter warm-up or an idle in
the driveway is not recorded as a trip.

Before v3.3.0 a session opened whenever the device connected, so a parked vehicle
checking in became a drive. On the instance this was developed against that was
2,921 of 3,262 recorded sessions. Those rows are kept rather than deleted: the
Sessions tab hides the ones in which nothing moved and says how many it is
holding back, and one click shows them again.

Two settings in **LiveLink settings** (the gear on the LiveLink card) control this:

- **Stop before a new drive** (default 15 minutes). How long the vehicle can sit
  still, connected or with the engine off, before the next movement counts as a
  separate drive. A fuel stop or a charging stop stays one drive; a longer stop
  becomes two. This is deliberately not the five-minute session timeout: a stationary EV
  reports neither speed nor RPM, so a five-minute window would split a drive at
  every school pickup.
- **How drives are detected** (default **By movement**). Switching to **By device
  connection** restores the pre-v3.3.0 rule. It is an escape hatch for a device
  whose speed and odometer readings MyGarage does not recognise, not a feature.
  Settings shows a warning naming any device in that state.

A configurable grace period (0-300s, default 60s) still delays ending a session
after WiFi drops, preventing phantom micro-sessions.

**Drives uploaded from a buffer.** A WiCAN that was out of WiFi range uploads
what it buffered when it gets back, with the original times. A reading more than
5 minutes away from when it arrives counts as a replay: it never joins or holds
open the drive in progress, and the replayed readings are built into closed
drives of their own, by their times. A device whose clock runs more than 5
minutes fast gets one warning in the log, and its drives aren't recorded until
the clock is fixed.

Trip-computer (OBC) values from the most recent drive session can auto-fill a new fuel record via the fuel form's **Auto-fill from last drive** button.

### Charts Tab

Historical telemetry visualization.

**Features:**
- Time range selector: 1h, 6h, 24h, 7d, 30d
- Multi-parameter overlay (select multiple metrics)
- Color-coded legend
- Min/max/avg statistics per series
- **Export CSV** button

---

## Device Management

### Viewing Devices

Each source's settings list its devices: open the source's tab in **Settings → Integrations → LiveLink** and click its settings button (for WiCAN, **WiCAN settings**). MQTT sensors are covered in [MQTT Sensors and Devices](#mqtt-sensors-and-devices).

**Device information displayed:**
- Label (click it to rename) and Device ID
- Device status (online/offline), and for a WiCAN its ECU status
- Linked vehicle (or "Unlinked")
- Firmware version for a WiCAN, with an **Update** badge if a newer one is available

### Linking a Device to a Vehicle

1. In the Devices section, find the unlinked device
2. Click the vehicle dropdown
3. Select the vehicle to link
4. The vehicle's detail page will now show the LiveLink tab

### Per-Device Tokens

For enhanced security, you can generate tokens scoped to specific devices:

1. In the WiCAN's row, click the key icon (**Generate device token**)
2. Copy the token (shown once)
3. Update the WiCAN device to use this token instead of the global token

Per-device tokens can be revoked without affecting other devices. Clicking the key icon again (**Revoke device token**) sends the device back to the global token.

### Firmware Updates

LiveLink checks GitHub daily for new WiCAN firmware releases, matched to your device's track (OBD vs PRO). When an update is available:

- An update badge appears on the device row
- Click **Open device UI** (the link icon in the row) to access WiCAN's web interface
- Update firmware through WiCAN's built-in updater

⚠️ MyGarage cannot update WiCAN firmware directly — you must use the device's web UI.

**Notifications fire once per release.** Since v3.5.0 you are told about a
given firmware version one time per device, not every day until you update.
The next release notifies you again.

**Skipping a version.** If you do not intend to install a release, click
**"Skip this version"** on the device row. The row then shows
**Skipped v{version}** and that version never notifies again, while the update
badge stays visible so you do not forget the device is behind. **Resume update
notifications** undoes it, though a version you were already notified about
will not notify a second time. Skipping is per device and admin only.

### Unlinking a Device

To move a device to a different vehicle:

1. In the device's vehicle dropdown, choose **Unlinked**
2. Historical data remains with the original vehicle. A drive still open is
   ended at its last movement
3. Link the device to the new vehicle

**Note:** Deleting a device removes only the device record. Telemetry, sessions, and DTCs are retained with the vehicle. A propane tank sensor is the exception: deleting it deletes its readings too.

---

## Odometer Integration

When your WiCAN configuration includes an odometer PID, LiveLink automatically updates your vehicle's odometer records.

**How it works:**
1. At the end of each drive session, LiveLink captures the odometer reading
2. A new entry is created in the vehicle's odometer history
3. The entry is marked with a **LiveLink** badge to distinguish from manual entries

**Behavior:**
- ✅ LiveLink never changes an entry it did not make: a manual entry, a service visit's, a fuel-up's or a tire's stays as it is
- ✅ LiveLink keeps one entry of its own per day and updates it as the odometer climbs; a reading no higher than what is already recorded adds nothing
- ✅ A vehicle's current odometer is the highest reading of its latest day, whichever record entered it
- ✅ LiveLink entries integrate with service reminders and fuel economy calculations

**Odometer units.** A standard `A6-ODOMETER` PID reports kilometres, per SAE
J1979. A WiCAN follows its firmware's naming: `ODOMETER` is kilometres and
`ODOMETER_MI` is miles, and a unit the device declares in its HTTPS config wins
over both. `ODOMETER_MI` is read as miles from any source. Odometers are stored
in whole kilometres. You can override the unit per device: click **Device
settings** (the sliders icon) in the device's row and set **Odometer units**.
Set it if recorded mileage looks wrong. Changing it after a device has recorded
readings is refused, because it would only affect later readings and leave the
stored ones in the other unit; the refusal names the repair tool instead.

**Upgrading to v3.10.0.** Earlier versions read a WiCAN's named odometer keys
(such as `ODOMETER`) as miles. The upgrade records how each WiCAN with no unit
set read its odometer before, so it keeps reading the same way. If a device has
been read in the wrong unit all along, `repair_wican_odometer_unit.py` converts
that device's stored odometer readings, either way (`--to km` or `--to mi`).
Back up first, start MyGarage in maintenance mode (`MYGARAGE_MAINTENANCE_MODE=1`)
so no reading lands halfway, then run it. It only reports what it would change
until you add `--apply`:

```bash
docker exec -w /app mygarage python tools/repair_wican_odometer_unit.py --device-id <device id> --to km
```

See [Troubleshooting](Troubleshooting) for the other repair tools.

**Drive distance is measured separately from the odometer.** Many dongles report
their odometer coarsely: one WiCAN stepped only every 24 km, which recorded no
distance at all for any trip shorter than that, and most trips are shorter than
that. LiveLink now reads distance from the finest distance signal the device
publishes, such as the standard `31-DISTANCESINCECODECLEAR` PID, which resolves
to 1 km. A device whose odometer is already at least that fine is unchanged, and
a distance counter is never used as a session's odometer reading.

**Torque records no odometer until you choose one.** In **Torque settings**,
open the source's **Device settings** and pick its **Odometer parameter**. Torque
keeps its own running total, which drifts when the phone misses a trip.
Torque sends `TORQUE_ODOMETER` in kilometres whatever its display units say, so
while it's the odometer parameter, **Odometer units** is disabled for that
device and the API refuses `mi`.

**Upgrading to v3.10.0 with Torque.** A Torque device set to miles with
`TORQUE_ODOMETER` as its odometer has stored that odometer 1.609x high since the
switch. The upgrade logs a WARNING naming each one. Back up, start MyGarage in
maintenance mode, then repair it; it's a dry run until you add `--apply`:

```bash
docker exec -w /app mygarage python tools/repair_wican_odometer_unit.py --device-id <device id> --key TORQUE_ODOMETER --to km
```

It rescales everything stored since the switch and clears the unit. If it can't
find the switch, it asks for `--switch-at`. `backfill_livelink_odometer.py`
refuses such a device until it's repaired.

**If odometer isn't syncing:**
- Verify your vehicle supports the odometer PID (not all do)
- Check WiCAN's AutoPID includes the correct odometer PID for your make/model
- Some vehicles require manufacturer-specific PIDs
- Check **Odometer units** on the device if the reading lands far below the real
  one: a miles value read as kilometres is discarded by the "must be higher"
  guard, silently before v3.3.0 and with a log line since

---

## Data Retention

LiveLink can generate significant amounts of data. Configure retention to balance history vs storage.

### Settings

Open **LiveLink settings** (the gear on the LiveLink card) and find **Data Retention**.

| Setting | Options | Default |
|---------|---------|---------|
| **Raw telemetry retention** | 30 / 60 / 90 / 180 / 365 days | 90 days |
| **Daily aggregation** | Enable/Disable | Enabled |

### Daily Aggregation

When enabled, LiveLink creates daily summary records containing:
- Min, max, and average values for each parameter
- Sample count

Daily aggregates survive retention cleanup, enabling long-term trend analysis even after raw data is purged.

---

## Alerts & Notifications

LiveLink sends its alerts through MyGarage's notification services (Discord, ntfy, email and the others under **Settings → Notifications**).

### Alert Types

Each alert has a switch under **Alerts & Notifications** in **LiveLink settings**. Switched off, that alert is not sent.

| Alert | Description | Default |
|-------|-------------|---------|
| **New device discovered** | A WiCAN first reaches MyGarage, over HTTPS (with a valid token) or MQTT | On |
| **Device goes offline** | No data received for the **Device Offline Timeout**; covers sensors too (see [Propane Tanks](#propane-tanks-mopeka)) | On (15 min) |
| **Firmware update available** | Newer WiCAN firmware detected | On |
| **Parameter threshold breaches** | A reading crosses one of its alert lines, such as a propane tank's (see [Propane Tanks](#propane-tanks-mopeka)) | On |

### Alert Cooldown

To prevent notification spam, alerts honor a configurable cooldown (an admin setting): the same alert won't fire again until it expires. An alert no notification service accepted is tried again once per cooldown. A propane tank's alert lines work differently: one notification per crossing (see [Propane Tanks](#propane-tanks-mopeka)).

### Alert Units

Alert lines are stored in metric, and a threshold alert shows the reading and
the line in your units (see [Units](Units)). A reading whose quantity MyGarage
doesn't know prints as it was stored.

---

## Troubleshooting

### Device Not Discovered

**Symptoms:** WiCAN is configured but doesn't appear in MyGarage

**Check:**
1. **Token** — Ensure the Bearer token in WiCAN matches MyGarage exactly
2. **URL** — Verify the ingestion URL is correct and reachable from WiCAN
3. **Network** — WiCAN must be able to reach MyGarage (same network or routed)
4. **Firewall** — Ensure no firewall blocking the connection
5. **WiCAN logs** — Check WiCAN's web UI for HTTP error codes
6. **LiveLink enabled?** With **Enable LiveLink** off, no new device is discovered

### No Telemetry Data

**Symptoms:** Device appears but no gauges or charts

**Check:**
1. **Device linked?** — Telemetry is only stored for devices linked to vehicles
2. **AutoPID configured?** — WiCAN needs PIDs to poll
3. **Decoded output?** — Ensure AutoPID outputs decoded JSON, not raw CAN frames
4. **LiveLink enabled?** With **Enable LiveLink** off, nothing is stored
5. **Values rejected?** — LiveLink drops readings that fail range or rate-of-change checks (garbage from partial ECU wakes); rejected values are logged

### MQTT Connection Failed

**Symptoms:** MQTT status shows "error" or "disconnected"

**Check:**
1. **Broker running?** — Verify Mosquitto or your broker is active
2. **Host/port correct?** — Double-check broker address and port
3. **Authentication** — If broker requires auth, ensure credentials are correct
4. **Firewall** — Port 1883 (or your configured port) must be accessible
5. **TLS mismatch** — If broker requires TLS, enable it in MyGarage

### Phantom Devices

**Symptoms:** Unknown device IDs appear that you don't recognize

**Cause:** MQTT brokers retain messages, and before v3.10.0 MyGarage created a
device from an old retained message when it subscribed. Retained messages are
ignored now, so they no longer create devices.

**Solution:** delete the phantom devices from MyGarage's device list.

### Data Gaps

**Symptoms:** Missing telemetry during certain times

**Cause:** WiCAN only transmits live data when connected to WiFi. When your vehicle is away from home, no live data reaches MyGarage.

**Backfill:** If your WiCAN logs to an SD card while offline, MyGarage pulls that data to fill the gaps automatically when the device reconnects. To set it up, open the device's **Device settings** in **WiCAN settings**, enter its **Device address (IP or hostname)**, switch on **Auto SD backfill** and click **Save**. **Pull SD logs now** runs a backfill on demand. The address must be a private
(LAN) one, and MyGarage checks it again at every pull.

---

## Best Practices

### Security

- ✅ **Use per-device tokens** for each WiCAN to limit blast radius if compromised
- ✅ **Use HTTPS** with valid certificates for HTTPS POST
- ✅ **Regenerate tokens** if you suspect they've been exposed
- ❌ **Don't share tokens** publicly or in screenshots

### Performance

- ✅ **Set reasonable polling intervals** — 5 seconds is usually sufficient
- ✅ **Monitor database size** and adjust retention as needed
- ✅ **Use daily aggregation** for long-term trends

### Reliability

- ✅ **Keep WiCAN firmware updated** — fixes bugs and improves stability
- ✅ **Use static IP or DHCP reservation** for WiCAN devices
- ✅ **Monitor device status** — investigate if devices go offline unexpectedly

---

## Need Help?

- **Common Questions** — See [FAQ](FAQ.md#livelink--telemetry)
- **Detailed Troubleshooting** — See [Troubleshooting Guide](Troubleshooting.md#livelink-issues)
- **WiCAN Documentation** — [meatpihq.github.io/wican-fw](https://meatpihq.github.io/wican-fw/)
- **Community** — [GitHub Discussions](https://github.com/homelabforge/mygarage/discussions)

---

**Next**: Learn about [Document Management](Documents) or explore [Authentication](Authentication).