# 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 two ways: a **WiCAN** OBD2 device (covered first
below), or the **Torque Pro** Android app with any ELM327 adapter — see
[Torque Pro](#torque-pro-no-wican-required) if you'd rather not buy hardware.

---

## 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 with severity levels and descriptions
- **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, parameters, 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.

### 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**
2. Click **"Configure"** on the LiveLink card
3. Copy the **Ingestion URL** (e.g., `https://mygarage.local/api/v1/livelink/ingest`)
4. Copy the **API Token** (click reveal, then copy)
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 in the **Devices** section
9. Click the device and **link it to a vehicle**

### 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 → Configure**
4. Scroll to **MQTT Subscription** section
5. Enable MQTT and configure:
   - **Broker Host**: Your MQTT broker IP
   - **Broker Port**: 1883 (default)
   - **Topic Prefix**: `wican` (must match WiCAN config)
6. Click **Test Connection** to verify
7. Click **Start** to begin subscribing
8. Link discovered devices to vehicles

---

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

✅ **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

**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 (deduplication prevents duplicates)

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

**Device commands:** Over MQTT, MyGarage can send `get_vbatt`, `get_autopid_data`, and `reboot` to a WiCAN device.

### Running Both Simultaneously

You can enable both HTTPS POST and MQTT at the same time. LiveLink's payload deduplication ensures the same telemetry isn't stored twice if it arrives through both channels.

---

## 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, drive sessions
and DTCs stay on the vehicle; only the ability to upload more is withdrawn.

---

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

---

## Using LiveLink

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

### 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
- 🔴 **WiCAN Offline** — No communication from device

**Gauge cards show:**
- Parameter name and current value
- Unit of measurement
- Warning indicator if threshold exceeded
- Session min/max values

**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**
- 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
- For manufacturer-specific codes (P1xxx), you can add custom descriptions

**Bundled DTC database:** MyGarage includes ~3,000 SAE J2012 standard DTC definitions covering generic OBD2 codes (P0xxx, P2xxx, B0xxx, C0xxx, U0xxx).

**Guidance on common codes:** for the codes that turn up most often, the DTC
detail also lists likely **causes**, the **symptoms** you would expect to notice,
and suggested **next steps**. It is a starting point for deciding whether
something needs a shop, not a diagnosis.

### 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 an odometer reading
that has gone up. 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 the LiveLink settings modal control this:

- **Stop before a new drive** (default 15 minutes). How long the vehicle can sit
  still, while still connected, 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.

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 to CSV** button

---

## Device Management

### Viewing Devices

Navigate to **Settings → Integrations → LiveLink → Configure** to see all discovered devices.

**Device information displayed:**
- Device ID (12-character hex from MAC address)
- Hardware version (e.g., WiCAN-OBD-PRO)
- Firmware version (with update badge if newer available)
- Linked vehicle (or "Unlinked")
- Device status (Online/Offline)
- ECU status (Online/Offline)
- WiFi signal strength (RSSI)
- Battery voltage
- Last seen timestamp

### 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. Click a device row to expand details
2. Click **"Generate Device Token"**
3. Copy the token (shown once)
4. Update the WiCAN device to use this token instead of the global token

Per-device tokens can be revoked without affecting other devices.

### 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"** 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.

### Unlinking a Device

To move a device to a different vehicle:

1. Click the device to expand
2. Click **"Unlink"** or change the vehicle dropdown to "None"
3. Historical data remains with the original vehicle
4. 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.

---

## 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:**
- ✅ Manual entries always take precedence
- ✅ Duplicate entries for the same day are skipped
- ✅ LiveLink entries integrate with service reminders and fuel economy calculations

**Odometer units.** A standard `A6-ODOMETER` PID reports kilometres, per SAE
J1979. A custom autopid reports whatever the dash shows, which on a US-market
car is usually miles. LiveLink infers the unit from the key shape and you can
override it per device in **LiveLink settings -> Odometer units**. Set it if
recorded mileage looks wrong. Changing it after a device has recorded readings
is refused, with the conversion named, because it would only affect later
readings and leave the stored ones in the other unit.

**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.

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

Navigate to **Settings → Integrations → LiveLink → Configure → 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.

### Storage Monitoring

The settings page shows:
- Row count in telemetry table
- Estimated database size

⚠️ If row count exceeds 50 million, consider reducing retention period or migrating to PostgreSQL.

### Manual Purge

Click **"Purge Old Data"** to immediately delete telemetry older than your retention period. A confirmation dialog shows how many records will be deleted.

---

## Alerts & Notifications

LiveLink integrates with MyGarage's notification system (7 backends, e.g. Discord, ntfy, email).

### Alert Types

| Alert | Description | Default |
|-------|-------------|---------|
| **New device discovered** | WiCAN with valid token first connects | On |
| **Device offline** | No data received for configured timeout | On (15 min) |
| **Firmware update available** | Newer WiCAN firmware detected | On |
| **Threshold breach** | Parameter exceeds warning_min/warning_max | Per-parameter |

### Configuring Thresholds

1. Go to **Settings → Integrations → LiveLink → Configure**
2. Find the parameter in the **Parameters** section
3. Set **Warning Min** and/or **Warning Max** values
4. Example: Coolant temp warning at 105°C, battery voltage warning below 12.0V

### Alert Cooldown

To prevent notification spam, alerts honor a configurable cooldown (an admin setting) — the same alert won't fire again until it expires.

---

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

### 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. **Device enabled?** — Check the device isn't disabled in MyGarage
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. When MyGarage subscribes, it receives old retained messages from other devices.

**Solution:**
1. Stop Mosquitto: `docker stop mosquitto`
2. Delete persistence: Remove `mosquitto.db` from the data directory
3. Start Mosquitto: `docker start mosquitto`
4. Delete 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. An admin can also trigger a backfill manually.

---

## 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
- ✅ **Configure storage_interval** for stable parameters (e.g., odometer every 60s)
- ✅ **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).