🔧

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

Event	Associated Fields (Examples)
Idle In/Out	MDI_SHUTDOWN_TYPE_AND_REASON, MDI_EXT_BATT_VOLTAGE, MDI_EVENT
Over Speed	MDI_GPS_SPEED, MDI_MAX_SPEED_IN_LAST_OVERSPEED, MDI_OVERSPEED
Over RPM	MDI_OBD_RPM, MDI_RPM_MAX, MDI_RPM_AVERAGE
Journey On/Off	ODO_FULL_METER, MDI_JOURNEY_ID, MDI_JOURNEY_STATE, MDI_OBD_VIN
Tow Away	MDI_GPS_PDOP, MDI_TOW_AWAY, MDI_VEHICLE_STATE

Heading Policy (Directional Changes)

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

The vehicle has traveled > 5km since the last report.
OR The last report was > 1 minute ago AND direction changed by > 40° (min. distance 250m).
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

Time	Actual Value	Packet Content	Backend Interpretation
11:00	58	MDI_OBD_MILEAGE: 58	58
11:01	59	MDI_OBD_MILEAGE: 59	59
11:02	59	(Field Omitted)	59 (Last Known)
11:03	60	MDI_OBD_MILEAGE: 60	60

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 Best Practices

The MDI_JOURNEY_STATE is the primary field for trip tracking (True = Started, False = Ended).

Filtering Noise

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

Short Trips: Ignore journeys where JOURNEY_STATE is true for less than 3 minutes (filters "forgotten item" scenarios).
Engine Stalls: Do not end a journey if a JOURNEY_STATE: true follows a false within 5 minutes.
Underground Parking (Loss of Signal): If no data is received for 15 minutes, trigger a "soft end" on the backend. When the device reconnects, use MDI_JOURNEY_ID to reconcile the data.

Hybrid/Non-OBD Vehicles

If the vehicle does not provide ignition via OBD, ensure the IGNITION FALLBACK module is active to trigger journey states based on movement/voltage.