Integration best practices

Emission & Transmission Strategy

This document outlines how devices record, optimize, and emit data, and provides best practices for backend integration to ensure data integrity and accurate journey construction.

1. Data Recording Logic

Data is captured based on the device configuration using two primary methods:

• Periodic: Data is recorded at fixed intervals (e.g., MDI_OBD_SPEED every 60 seconds).

• Event-Based: Specific triggers prompt the recording of a cluster of related fields.

Standard Event Triggers

Heading Policy (Directional Changes)

To optimize data without losing path accuracy, the Heading Policy triggers a record globally when:

1. The vehicle has traveled > 5km since the last report.

2. OR The last report was > 1 minute ago AND direction changed by > 40° (min. distance 250m).

3. OR The direction changed by > 50° (even if distance < 250m).

2. Optimization Strategy

To reduce data plan consumption, we use a "Change-Only" emission strategy.

The Golden Rule: If a field is scheduled to be recorded but its value has not changed since the last record, the field is omitted from the packet. The backend must interpret a missing field as: current_value = last_known_value.

Example: Mileage Tracking

Impact of Reboots

When a device reboots (due to configuration changes or >18h of continuous driving), the optimization cache is cleared. The first packet after a reboot will contain all configured fields, even if their values haven't changed.

3. Data Reliability & Deduplication

Because we prioritize "at-least-once" delivery, your backend may receive duplicate data. Use the following logic to handle it:

Device-to-Cloud Duplicates

If the device doesn't receive an ACK from the server, it re-sends the data.

• Solution: Monitor the recorded_at timestamp.

• Action: If a new packet arrives with a recorded_at value equal to or older than the current head for that device, drop it.

Cloud-to-Backend Duplicates

If your backend doesn't ACK our POST request, our notification service will retry.

• Solution: Every packet has a unique id.

• Action: Maintain a cache of recently processed IDs. If a duplicate id arrives, drop it.

4. Journey Construction & Engine Status Detection

Properly structuring trips and understanding vehicle state is crucial. MDI_JOURNEY_STATE is the primary boolean field used for trip tracking (True = Journey Started, False = Journey Ended).

Filtering Trip Noise

To ensure high-quality, actionable trip data, implement these backend rules:

1. Short Trips: Ignore journeys where MDI_JOURNEY_STATE remains true for less than 3 minutes. This safely filters out "forgotten item in the car" scenarios.

2. Engine Stalls/Stop-Start: We advise to not immediately terminate a journey. If an MDI_JOURNEY_STATE: true follows a false within 5 minutes, merge them into a continuous trip.

3. Underground Parking (Loss of Signal): If no data is received for 15 minutes, trigger a "soft end" for the journey on the backend. When the device eventually reconnects, use the MDI_JOURNEY_ID to reconcile and stitch the data together.

Engine Status vs. Movement (DIO_IGNITION)

If your specific use case requires detecting the actual engine status rather than just trip tracking, you should monitor the DIO_IGNITION field.

Important: DIO_IGNITION does not rely on a single hardware source. The device dynamically and intelligently determines ignition status using multiple fallback inputs, depending on their availability and reliability:

• Native OBD: Ignition signal directly from the vehicle's OEM stack (highest priority when available).

• Vehicle Telemetry: Ignition inferred via vehicle data (e.g., engine RPM MDI_OBD_RPM, engine parameters).

• External/Environmental Indicators: Ignition inferred via hardware sensors (e.g., external voltage behavior, accelerometer movement, GPS dynamics).

The device handles the complexity by prioritizing the most reliable available source and outputting the final state to DIO_IGNITION.