Overview

The HTTPS destination feature lets the WiCAN device push a unified JSON payload of selected CAN / OBD parameters and derived metrics to one or more remote web endpoints over a TLS‑encrypted connection. It is designed for users who already operate an HTTPS API (cloud ingest service, custom webhook receiver, serverless function, SIEM collector, etc.) and want a simple, firewall‑friendly way to receive periodic or event‑driven vehicle telemetry without opening inbound ports to the device.

Key characteristics:

• Encrypted transport (TLS) – Prevents on‑path interception or tampering compared to plain HTTP.
• Outbound only – The device initiates all connections, so no special port‑forwarding is required.
• Configurable cadence – Adjustable cycle interval (ms) or event‑only mode (firmware dependent) to balance freshness vs. bandwidth / power.
• Single consolidated payload – Grouping aggregates multiple PIDs / custom parameters into one compact JSON object per POST to reduce overhead.
• Multiple parallel destinations – You can enable several HTTPS endpoints alongside MQTT or other destination types.
• Flexible trust model – Use the built‑in public CA bundle or supply a custom certificate set for private PKI / mTLS scenarios.

Typical use cases:

1. Forwarding near real‑time vehicle health data to a fleet management backend.
2. Storing raw or partially processed metrics in a time‑series database (InfluxDB, Timescale via an ingest microservice).
3. Feeding anomaly detection or alerting pipelines (serverless function triggers on each POST).
4. Securely bridging on‑prem OT networks to a cloud analytics platform via an HTTPS collector.

Compared with MQTT:

• MQTT excels at bi‑directional, topic‑based streaming and low latency at scale.
• HTTPS POST is simpler to integrate with existing REST / webhook stacks and often easier to traverse restrictive corporate networks.

Supported devices: WiCAN-PRO

HTTPS Integration

This guide shows how to stream grouped PID / telemetry JSON from the device to one or more HTTPS endpoints.

Quick Start (60‑Second Version)

1. Automate tab → Set Grouping = Enable.
2. Click Add Destination → Type = HTTPS POST.
3. Paste URL beginning with https:// (e.g. https://api.example.com/ingest).
4. Cycle (ms) = 5000 (or 0 for event‑only pushes if firmware supports events).
5. Auth = Bearer Token (optional) → enter token only.
6. Cert Set = default (unless using private CA, then pick your custom set).
7. Tick Enabled.
8. Scroll (or jump) to bottom → press Submit Changes.
9. Verify server receives JSON after first cycle.

1. What the HTTPS Destination Does

When enabled, WiCAN periodically (or on certain trigger events if supported) sends an HTTPS POST to each configured destination. The body is a consolidated JSON containing all enabled / selected parameters (see Grouping below). Multiple destination types (MQTT, HTTPS, etc.) can run concurrently.

1.1 Mandatory: Grouping Must Be Enabled

At the top of the Automate page you will see:

Grouping: Disable | Enable

Set it to Enable. If left disabled, the HTTPS destination will not send the combined multi‑PID JSON described here.

With grouping enabled the device aggregates selected outputs from:

• Standard PIDs (built‑in / common set)
• Specific PIDs (vehicle profile specific)
• Custom PIDs (user defined)

All are merged into a single JSON object that is POSTed to every enabled destination (only URL, query params, and auth differ per destination).

Illustrative examples (reflecting actual firmware behavior). The device sends the full context payload (config + status + telemetry) once per boot cycle on the first successful POST for each enabled HTTPS destination. Subsequent periodic/event posts contain only the autopid_data block. Simply disabling/re‑enabling a destination in the UI without rebooting does not resend config / status.

Initial POST after device boot (includes configuration + status + initial telemetry sample):

{
    "autopid_data": {
        "TestCustom": 127.5
    },
    "config": {
        "0C-EngineRPM": { "class": "speed", "unit": "rpm" },
        "0D-VehicleSpeed": { "class": "speed", "unit": "km/h" },
        "COOLANT_TMP": { "class": "temperature", "unit": "°C" },
        "ENGINE_RPM": { "class": "frequency", "unit": "RPM" },
        "FUEL": { "class": "none", "unit": "%" },
        "FUEL_PRESSURE": { "class": "pressure", "unit": "kPa" },
        "INTAKE_AIR_TMP": { "class": "temperature", "unit": "°C" },
        "MAF": { "class": "none", "unit": "g/s" },
        "ODOMETER": { "class": "distance", "unit": "km" },
        "SPEED": { "class": "speed", "unit": "km/h" },
        "STFT": { "class": "none", "unit": "%" },
        "THROTTLE": { "class": "none", "unit": "%" },
        "TestCustom": { "class": "none", "unit": "none" }
    },
    "status": {
        "device_id": "device_id",
        "fw_version": "4.40",
        "git_version": "v4.40p",
        "hw_version": "WiCAN-OBD-PRO",
        "ecu_status": "online",
        "sta_status": "Connected",
        "sta_ip": "192.168.0.146",
        "wifi_mode": "BLEStation"
        /* many additional fields (network creds, tokens, topics, etc.) omitted for brevity */
    }
}

Subsequent periodic / event POSTs (telemetry only – sampled at the configured cycle or trigger interval):

{
    "autopid_data": {
        "0C-EngineRPM": 4147,
        "0D-VehicleSpeed": 0,
        "COOLANT_TMP": 155,
        "ENGINE_RPM": 4147,
        "FUEL": 62.35,
        "FUEL_PRESSURE": 300,
        "INTAKE_AIR_TMP": -40,
        "MAF": 34.81,
        "SPEED": 0,
        "STFT": -100,
        "THROTTLE": 33.73,
        "TestCustom": 127.5
    }
}

Example of another later telemetry-only POST (values change over time / per cycle):

{
    "autopid_data": {
        "0C-EngineRPM": 4200,
        "0D-VehicleSpeed": 5,
        "COOLANT_TMP": 156,
        "ENGINE_RPM": 4200,
        "FUEL": 62.10,
        "FUEL_PRESSURE": 300,
        "INTAKE_AIR_TMP": -39,
        "MAF": 35.10,
        "SPEED": 5,
        "STFT": -98,
        "THROTTLE": 34.00,
        "TestCustom": 127.5
    }
}

Notes:

• Top-level keys config and status appear only on the first payload after a cold boot / reboot. Re-enabling a destination mid-session does not resend them.
• All telemetry fields are flattened inside autopid_data (no nested params wrapper in the current implementation).
• status may include sensitive values (SSIDs, usernames, tokens, topics). Protect your ingest endpoint, avoid verbose logs of the full first payload in production, or filter/redact sensitive keys server-side.
• Field names for custom PIDs may be namespaced or normalized; always log a real sample before designing strict schemas.

2. Add a New HTTPS Destination

1. Open the device web UI (e.g. http://wican.local).
2. Go to Automate in the left sidebar.
3. Click Add Destination.
4. Set Type to HTTPS POST.
5. Fill in the fields described below.
6. Tick Enabled (right side checkbox) when you’re ready.
7. Scroll to the bottom of the page and press Submit Changes (button is disabled until something changed). Collapsing a destination does NOT persist—use the submit button.

You can configure up to the max number shown (commonly 6) and they execute independently.

3. Field Breakdown

3.1 Authentication Handling

Currently implemented UI options:

• None: Sends no Authorization header.
• Bearer Token: Adds Authorization: Bearer <token> automatically.

(Internally the firmware also supports API key headers or basic auth for other use cases; these may surface in later UI builds.)

3.2 Query Parameters

Each added pair is appended as ?k=v or &k=v. Avoid large sensitive values here (they appear in logs on the server side). If you need secrecy use headers instead (Bearer token).

3.3 Certificate Set

Select which CA trust set to use for validating the HTTPS server:

• default – Embedded public root bundle (Let’s Encrypt, DigiCert, GlobalSign, etc.).
• Custom – Created under System → Certificates (Certificate Manager). Create a set, upload CA (and optionally client cert/key for mutual TLS), then return here and select it.

Self‑signed / Private PKI:

1. Go to System tab → Certificates section.
2. Add a new set name (e.g. corp_root).
3. Upload the CA (or the exact server certificate if acting as its own CA).
4. (Optional) Upload client cert + key if your server requires mTLS.
5. Save, then refresh destinations list (it auto‑loads sets) and pick corp_root.

If the wrong set is selected you will see TLS failures (certificate verify errors) and no data will arrive.

4. Example Configurations

4.1 Generic JSON Ingest (Public CA)

• Destination: https://collector.example.com/iot/telemetry
• Cycle: 5000
• Auth: Bearer Token → MY_SUPER_TOKEN
• Query Params: (none)
• Cert Set: default

Resulting request (simplified example):

POST /iot/telemetry HTTP/1.1
Host: collector.example.com
Authorization: Bearer MY_SUPER_TOKEN
User-Agent: ESP32 WiCAN/1.0
Content-Type: application/json

{"device_id":"...","ts":1730000000,"can":[...],"metrics":{...}}

4.2 With Query Parameters

Add param: source = wican_pro and env = prod. URL becomes: https://collector.example.com/iot/telemetry?source=wican_pro&env=prod.

4.3 Private CA / mTLS

• Upload your internal CA certificate chain.
• Select that named Cert Set.
• Destination can now be e.g. https://ingest.internal.lan/data (assuming DNS resolves and network route exists via WiFi / VPN).
• (Optional) If using mutual TLS, include client certificate & key in the set; the server can then validate the device identity.

5. Payload Content

Schema can evolve; inspect live traffic early. Common elements:

If integrating with a backend, start by logging the raw body you receive, then map fields to your database.

6. Troubleshooting

6.1 Inspecting From Server Side

Run a simple test receiver during development:

# Python quick HTTPS test (self-signed) – run on your server
# (Generate certs separately or use a dev reverse proxy.)

Or use a public request bin service to view incoming bodies (for initial debugging only—avoid sensitive data).

7. Best Practices

• Start with cycle 5000–10000 ms; only reduce if your backend needs higher resolution.
• Use Bearer tokens (short‑lived if possible); rotate regularly.
• Prefer private CA + VPN for sensitive or proprietary data.
• Keep firmware updated—TLS root bundle and HTTP stack improvements ship over time.
• Log and sample first; then implement filtering server side to reduce storage cost.

8. Minimal Checklist (TL;DR)

1. Automate → Grouping = Enable.
2. Add Destination → Type = HTTPS POST.
3. URL starts with https://.
4. Cycle = 5000 ms (or 0 if event‑only use case).
5. Auth (optional) = Bearer Token.
6. Query Params (optional).
7. Cert Set = default (or custom one you created).
8. Tick Enabled.
9. Press Submit Changes.
10. Verify server logs first payload.

9. Removing or Disabling

Uncheck Enabled to pause without losing settings. Use Delete to remove entirely.

10. Footnotes & Notes

• Cycle ≥ 1000 ms (or 0 for event only) per current firmware rule.
• HTTPS requires a cert set: either default or a custom set.
• Specialized destination types (e.g. ABRP_API) may mandate tokens; those are outside the scope of this generic HTTPS guide.

Document version: 1.2 (updated examples for boot-only config/status behavior, clarified re-enable semantics, added sensitive fields note).