Fuel Analysis

This guide covers the end-to-end setup required to enable the Fuel Analysis plugin for a client's fleet. The integration allows real-time fuel data forwarding, vehicle synchronization, and automatic refuel detection.

Overview

The Fuel Analysis plugin connects FMDP with the TrackSynQ Fuel Analysis service through:

1. Fuel Data Forwarding — Real-time fuel level data from devices is forwarded to the Fuel Analysis API
2. Vehicle Sync — Vehicles are automatically synced every 30 minutes to keep the Fuel Analysis service updated
3. Auto Refuel Capture — Daily analysis detects refueling events from fuel level patterns

Prerequisites

Before setting up the integration, ensure:

• The client has devices with fuel sensors (analog fuel rod or LV-CAN200)
• The Fuel Analysis plugin is enabled for the client's application
• Access to both the Super Admin Portal and Management Portal

Step 1: Create the FuelAnalysis Backend Server

Portal

Super Admin Portal → Configurations → Backends

Navigate to Super Admin Portal → Configurations → Backends and click Add New.

Configure the backend with the following settings:

Field	Value
Name	FuelAnalysis
Protocol	https
Host	See environment table below
Port	443
Endpoint	/fuelanalysis/v3/fueldata/datapoints
Backend Type	FuelAnalysis
Enabled	true
Forwarding Option	processed_data
Timeout	30
Maximum Retry Count	1

Environment-specific Host Values

Environment	Host
Dev	apis.dev.services.tracksynq.com
Production	apis.services.tracksynq.com

HTTP Headers

Add the following HTTP header:

Header Name	Header Value
x-api-key	The Fuel Analysis API key (contact DevOps for the key)

Step 2: Create Vehicle Custom Fields

Portal

Management Portal → Configurations → Custom Fields

Navigate to Management Portal → Configurations → Custom Fields and create the following custom fields with Asset Type set to Vehicle:

fuel_tank_capacity

Field	Value
Asset Type	Vehicle
Name	fuel_tank_capacity
Label	Fuel Tank Capacity
Field Type	String
Min	0
Max	1000

fuel_unit

Field	Value
Asset Type	Vehicle
Name	fuel_unit
Label	Fuel Unit
Field Type	String
Placeholder	LITER

fuel_tank_calibration

Field	Value
Asset Type	Vehicle
Name	fuel_tank_calibration
Label	Fuel Tank Calibration
Field Type	String

auto_refuel_capture_lookback_days

Field	Value
Asset Type	Vehicle
Name	auto_refuel_capture_lookback_days
Label	Auto Refuel Capture Lookback Days
Field Type	String
Min	1
Max	100
Regex	^[1-9][0-9]?$|^100$

Step 3: Set Up Device and Vehicle Groups

Portal

Management Portal → Groups

Create dedicated device and vehicle groups to organize assets for fuel analysis:

Device Group

1. Navigate to Management Portal → Groups → Device Groups
2. Click Add New
3. Set the group name to Fuel Analysis
4. Add all devices that have fuel sensors to this group

Vehicle Group

1. Navigate to Management Portal → Groups → Vehicle Groups
2. Click Add New
3. Set the group name to Fuel Analysis
4. Add all vehicles associated with fuel sensor devices to this group

tip

Grouping fuel-sensor devices and their vehicles together makes it easier to manage backend assignments and troubleshoot forwarding issues.

Step 4: Assign Backend to Devices

Portal

Management Portal → Devices

Assign the FuelAnalysis backend to each device in the "Fuel Analysis" device group:

1. Navigate to Management Portal → Devices
2. Search/filter by the Fuel Analysis group name
3. Select a device from the list
4. In the device form, find the Backend Servers section
5. Add the FuelAnalysis backend created in Step 1
6. Click Save
7. Repeat for each device in the group

tip

Only assign the FuelAnalysis backend to devices that have fuel sensors configured. Devices without fuel data will generate errors in the forwarding logs.

Step 5: Populate Vehicle Custom Fields

Portal

Management Portal → Vehicles

For each vehicle in the Fuel Analysis vehicle group, populate the custom fields created in Step 2:

1. Navigate to Management Portal → Vehicles
2. Search/filter by the Fuel Analysis vehicle group
3. Select a vehicle
4. Fill in the custom fields:
   • fuel_tank_capacity — Enter the tank capacity in liters (e.g. 45)
   • fuel_unit — Set to LITER
   • fuel_tank_calibration — Add calibration data if available
   • auto_refuel_capture_lookback_days — Set lookback period (default: 30)
5. Click Save
6. Repeat for all vehicles in the group

Step 6: Verify the Integration

After completing the setup, verify the integration is working correctly:

Fuel Data Forwarding

• Check the backend's forwarding logs for successful 200 OK responses
• If you see 404 errors with "Vehicle is not registered", wait for the next vehicle sync cycle (every 30 minutes)

Vehicle Sync

• Vehicles should appear in the Fuel Analysis service within 30 minutes of setup
• Vehicle identifier format: {clientId}_{plateNumber}

Auto Refuel Capture

• Refuel events are detected daily based on fuel level patterns
• A significant increase in fuel percentage (e.g., from 20% to 80%) triggers a refuel detection

Troubleshooting

Issue	Cause	Solution
404 "Vehicle is not registered"	Vehicle not yet synced	Wait 30 minutes for the next sync cycle
401 Unauthorized	Invalid API key	Verify the x-api-key header value
No fuel data forwarded	Device not assigned to backend	Check device backend assignment (Step 4)
Fuel percentage always 0	Device fuel sensor not configured	Check device variable mapping for fuel percentage
No refuel events detected	Lookback days too short or no significant fuel increase	Increase auto_refuel_capture_lookback_days or verify fuel data patterns

Architecture Reference

┌──────────────────────────────────────────────────────────────────────┐
│  FMDP Platform                                                       │
│                                                                      │
│  🔌 Device ──▶ ⚙️ Adapter ──▶ 📡 Forwarder (FuelAnalysis Backend)    │
│                                       │                              │
│                                       ▼                              │
│                          Fuel Analysis Service                        │
│                          POST /fueldata/datapoints                    │
│                                                                      │
├──────────────────────────────────────────────────────────────────────┤
│  Integration Workers                                                 │
│                                                                      │
│  🔄 VehicleSyncWorker (every 30 min) ──▶ POST /vehicles/sync         │
│  ⛽ AutoRefuelCaptureWorker (daily)   ──▶ POST /refuel/autorefuelcapture │
└──────────────────────────────────────────────────────────────────────┘

Related Documentation

• Plugins Overview — Plugin framework and management
• Backends Configuration — General backend setup guide
• Custom Fields — Custom field configuration at client level
• Device Groups — Device and vehicle group management
• Devices — Device configuration and backend assignment
• Vehicles — Vehicle management and custom fields