Overview
The ABRP (A Better Routeplanner) destination lets WiCAN push live vehicle and battery telemetry directly to ABRP so trip planning and energy prediction models stay up to date. Instead of generic JSON (used by the standard HTTPS destination) the ABRP integration sends a compact URL‑encoded form payload containing only the fields ABRP cares about.
Key characteristics:
- Form encoded payload –
application/x-www-form-urlencodedbody (lighter than JSON for small key sets). - ABRP token required – Each vehicle profile in ABRP uses a distinct API token.
- Depends on Grouping – Grouping must be Enabled; otherwise no consolidated telemetry is produced.
- Automatic field mapping – Internal WiCAN parameter names are translated to ABRP’s expected keys.
- Multiple destinations compatible – ABRP destination can run alongside MQTT / HTTPS / other types.
Supported devices: WiCAN-PRO
Feature area: Automate → Destinations → Type: ABRP API
Quick Start
- Automate tab → Ensure Grouping = Enable.
- Add Destination → Type =
ABRP API. - Paste your ABRP API Token (from ABRP Settings → Live Data / OBD).
- Cycle (ms) = 5000 (recommended start; must be ≥ 1000).
- Cert Set =
default. - Tick Enabled.
- Submit Changes (bottom of page).
- Open ABRP app → vehicle → verify live SOC / speed updates after first interval.
1. How It Works
When enabled the firmware:
- Builds the grouped telemetry snapshot.
- Maps internal keys (speed, soc, voltage, etc.) to ABRP field names.
- URL‑encodes the set into a single line form body.
- Sends an HTTPS POST to ABRP’s telemetry endpoint (
/1/tlm/sendor the build’s configured path).
Differences vs generic HTTPS destination:
| Aspect | ABRP Destination | Generic HTTPS |
|---|---|---|
| Body Format | Form URL‑encoded | JSON |
| Auth | ABRP API token | Optional Bearer token / none |
| Fields | Curated vehicle metrics | All grouped parameters |
| Mapping | Internal→ABRP key translation | No translation |
2. Prerequisites
| Item | Description |
|---|---|
| ABRP Account | Free or premium at https://abetterrouteplanner.com |
| Vehicle added | Select or create the vehicle to receive data |
| API Token | ABRP Settings → Live Data → copy token (per vehicle) |
| Grouping Enabled | Automate top section → Grouping = Enable |
| Network Access | Device must reach the Internet |
| (Optional) Custom Cert Set | Only if intercepting traffic via private CA/proxy |
3. Adding the Destination
- Automate → Add Destination.
- Type =
ABRP API. - Enter API Token (exact string, no spaces). Mandatory.
- Cycle (ms) ≥ 1000 (start with 5000–10000 to reduce bandwidth & ABRP load).
- Cert Set =
default. - Tick Enabled.
- Submit Changes.
- Wait one interval; check ABRP Live Data view.
4. Field Mapping (Illustrative)
| Internal | ABRP Key | Notes |
|---|---|---|
| soc | soc | State of charge (%) |
| soh | soh | State of health (%) |
| speed | speed | km/h (fallback: vehicle_speed) |
| vehicle_speed | speed | Used only if speed absent |
| latitude | lat | Degrees |
| longitude | lon | Degrees |
| elevation | elevation | Meters |
| is_charging | is_charging | 1 charging / 0 not |
| battery_current | current | Amps (sign convention: discharge negative) |
| battery_voltage | voltage | Volts |
| battery_temp | batt_temp | °C |
| ambient_temp | ext_temp | °C |
| power | power | kW |
| car_model | car_model | ABRP vehicle code |
Only available values are sent; missing metrics are silently omitted. Custom PIDs are excluded unless mapped in firmware.
5. Payload Format
Content-Type: application/x-www-form-urlencoded
Example (wrapped for readability):
utc=1730000000&soc=54.1&speed=23.4&lat=40.71278&lon=-74.00611&voltage=398.2¤t=-42.3&power=16.8&is_charging=0&car_model=tesla:model3:2021
Notes:
utc= epoch seconds (UTC)- Units normalized before send (speed km/h, temps °C, power kW)
- Current sign: negative = discharge (typical convention)
6. Rate, Backoff & Recommendations
| Setting | Recommendation | Rationale |
|---|---|---|
| Cycle (ms) | 5000–10000 | Good balance of freshness vs rate limits |
| Minimum Cycle | 1000 | Firmware enforced lower bound |
| Network Errors | Automatic backoff | Reduces retry storms |
Lowering the interval increases bandwidth and may not materially improve ABRP predictions unless you need near real‑time nav overlays.
7. Verifying Data
- Open ABRP web or mobile.
- Select the target vehicle.
- Ensure Live Data / OBD input is enabled.
- Observe SOC, speed, position changes (moving or charging may be required for updates).
If no data after 2–3 intervals, proceed to Troubleshooting.
8. Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
| 401 Unauthorized | Bad / expired token | Re-copy from ABRP; trim spaces |
| No updates | Grouping off or high cycle | Enable grouping; lower cycle |
| Missing specific fields | PID not enabled or unsupported profile | Enable Standard/Specific PID; update firmware |
| Position missing | No GPS feed | Ensure GNSS data available |
| Charging status wrong | Mapping mismatch or outdated firmware | Update firmware; verify PIDs |
| Sporadic posts | WiFi instability / backoff | Improve signal; lengthen cycle |
| TLS failure | Clock drift | Ensure NTP sync (System tab) |
9. Best Practices
- Dedicated token per device (revocation & auditing).
- Avoid unnecessary proxies; they add latency.
- Start with higher cycle; decrease only if really needed.
- Keep firmware updated for new mappings.
- Request additional mappings via issue with internal + desired ABRP names.
10. Minimal Checklist (TL;DR)
- Grouping = Enable.
- Add Destination → Type = ABRP API.
- Paste API Token.
- Cycle = 5000 ms.
- Cert Set = default.
- Enable + Submit.
- Verify in ABRP.
11. Security Notes
- Treat API token as a secret.
- Rotate when a device is retired or transferred.
- Never publish raw token in screenshots/logs.
12. Version
Document version: 1.1 (reformatted to match HTTPS guide structure).