Pairing the Companion App

The Companion App is ev_pro_companion, a Flutter phone app for remote vehicle monitoring and control. It pairs by scanning a QR code from the Car App.

Prerequisites

• The Car App is installed, paired to the vehicle, receiving vehicle data, and able to reach the relay.
• The installed license permits Companion App access.
• The phone can grant camera permission for QR scanning.
• Bluetooth permission is required for T-Box pairing paths and proximity behavior.
• T-Box hardware is required for proximity auto-lock/unlock and T-Box-backed access while the head unit path is unavailable.

TODO: Product clarification needed — What public download channels and minimum Android/iOS versions should be documented for the Companion App?

What pairing enables

Confirmed by the Companion App source:

• Vehicle dashboard state, including battery/range/lock status where published by the Car App or T-Box.
• Remote command UI for lock, unlock, trunk, remote launch, and alarm paths.
• Camera screens backed by WebRTC signaling.
• Notifications for sentry/security, charging, charge target, and trip events.
• Home-screen widgets and app icon quick actions.
• Optional biometric/device-passcode protection before sensitive commands.
• Proximity settings and BLE advertising when a T-Box proximity secret is available.

Caution

Remote commands and camera availability depend on vehicle state, license, relay connectivity, Car App state, and whether the target path is the awake Car App or the T-Box. The Companion App may show a feature even when the current vehicle/connection cannot execute it.

Without T-Box

The Companion App can pair in car-only mode using a QR that contains the Car App identity and pairing token. This path uses Cloud bootstrap pairing and does not provide proximity auto-unlock.

Use this mode when you only need phone access while the Car App/head-unit path is running and reachable through the relay.

With T-Box

T-Box pairing modes include a T-Box ID and can provide the Companion App with a proximity secret. With a paired T-Box, the Companion App can advertise proximity tokens over BLE and the T-Box can decide lock/unlock behavior from RSSI and challenge/response logic.

Use this mode for proximity auto-lock/unlock and T-Box-backed access. It still depends on the T-Box being installed, powered, provisioned, and connected according to the product-approved hardware requirements.

Pairing steps

1. Open the Companion App and choose the QR scan flow.
2. Open the pairing/share QR screen in the Car App if that screen is available in the installed version.
3. Scan the QR code with the Companion App.
4. Grant camera permission for QR scanning.
5. Grant Bluetooth permissions if the pairing mode or proximity feature requires them.
6. Wait for the Companion App to finish relay pairing and enter the paired/dashboard state.

Proximity behavior

Proximity auto-unlock/auto-lock requires T-Box. The Companion App advertises a signed BLE token; the T-Box scans BLE advertisements, tracks RSSI stability, runs challenge/response checks, and triggers lock/unlock GPIO actions according to its proximity engine.

TODO: Product clarification needed — What default proximity distance/sensitivity values should be documented for end users?

Troubleshooting

QR scan fails

• Confirm the Companion App has camera permission.
• Generate a fresh QR in the Car App.
• Keep the Car App QR screen open while pairing completes.

Pairing is rejected

The Companion App maps relay pair_rejected errors to user-facing text. Common causes are license/entitlement failures, stale pairing tokens, or too many paired companions.

TODO: Product clarification needed — What exact public messages should be documented for each relay pairing rejection reason?

Proximity does not work

• Confirm T-Box is paired and visible in the Companion App.
• Confirm the pairing QR included T-Box data or re-pair after adding T-Box.
• Confirm Bluetooth permissions remain enabled on the phone.
• Confirm the T-Box is installed, powered, and within the product-approved proximity range.