Automotive GPS Telemetry Ingestion
Production telematics pipeline for vehicle tracking. Features two-tier deduplication (Redis SET NX + MySQL unique constraint), native Traccar auto-normalization, and out-of-order stale packet protection for cellular dead zones.
Two-Tier Telematics Pipeline Architecture
Commercial vehicle trackers communicate using binary/text packets over raw TCP/UDP sockets. Nginx on port 443 expects HTTPS TLS and cannot decode raw tracker frames directly. The system utilizes a dedicated protocol gateway:
Listens on TCP/UDP socket ports (e.g. Teltonika Codec 8E, SinoTrack GT06, Queclink). Decodes binary frames into normalized JSON events and forwards to this API.
Receives normalized JSON at /api/v1/gps/telemetry, validates timestamps, prevents stale points from overwriting live coordinates, deduplicates packets, and pushes updates to Socket.IO.
Ingest telemetry feed from hardware GPS devices or Traccar forwarders.
Redis Cache::add() (6-hour performance layer) + MySQL UNIQUE(device_id, packet_id) (correctness layer).
Delayed points arriving out-of-order are stored in history but will never overwrite the vehicle's current live location.
Canonical Telemetry JSON Schema
| Field | Type | Required | Description |
|---|---|---|---|
| device_id | string | Yes | 15-digit IMEI or hardware serial mapped to vehicle. |
| latitude | float | Yes | Latitude coordinate (-90.0 to 90.0). |
| longitude | float | Yes | Longitude coordinate (-180.0 to 180.0). |
| packet_id | string | Optional | Protocol packet ID preferred. Deterministic hash generated as fallback. |
| device_recorded_at | string | Optional | Hardware GPS UTC timestamp (ISO 8601). Critical for route playback. |
| ignition | boolean|null | Optional | Engine ignition. Unknown/missing is preserved as null (STOPPED). |
| current_speed | float | Optional | Ground speed in km/h. Raw speed preserved; effective speed damped < 3 km/h. |
Integration Code Generators
curl -X POST "https://api.logistichubnepal.com/api/v1/gps/telemetry" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"device_id": "864201048591234",
"packet_id": "pkt_sim_101",
"protocol": "teltonika",
"source": "hardware_gps",
"latitude": 27.717245,
"longitude": 85.323961,
"current_speed": 48.5,
"heading": 135,
"ignition": true,
"fuel_level": 82,
"odometer": 154200.5,
"device_recorded_at": "2026-10-18T04:58:58.639Z"
}'Traccar Direct Webhook Auto-Normalization
Forward native JSON positions directly from Traccar to Laravel without an adapter layer.
Auto-Detected Webhook Payload
When Traccar posts with "position": { ... } and "device": { ... }, the controller automatically converts knots to km/h, extracts uniqueId, maps course and ignition, and handles optional attributes safely.
<entry key='forward.enable'>true</entry> <entry key='forward.url'>https://api.logistichubnepal.com/api/v1/gps/telemetry</entry> <entry key='forward.header'>X-Gateway-Secret: your-production-secret</entry>
Live Telemetry Tester
Transmit a test telemetry packet directly to api.logistichubnepal.com.
Gateway Observability & Hardware Pilot Health
Live ingest health statistics and device telemetry inspector for field testing.
Latency Measurement Notice: processing_latency_ms represents internal server-side PHP/Redis/DB execution time only. Actual end-to-end round-trip latency (Traccar → Cellular → TLS Handshake → Laravel) must be benchmarked under live network conditions during the hardware pilot.
10-Step Hardware Pilot Verification Checklist
Standard operating procedure for connecting the first physical Teltonika / Concox tracker on NTC/Ncell SIM.