How to parse tachograph file data?

Using plugins to parse downloaded tachograph files (driver cards and vehicle unit memory files) and extract their structured data: driver activity, work period, vehicle usage, etc

The tacho-file-parse plugin type parses raw tachograph files downloaded from driver cards and vehicle unit memory into structured JSON. Tachograph files store data in a strict binary format defined by EU Regulation 2016/799 — driver identity, daily activity records, work period locations, vehicle usage history, border crossings, cargo operations, and more. 

The plugin decodes all of this into clean, human-readable JSON that follows the original data structure defined by the regulation. The result can be used to build driver activity timelines, work and rest period charts, route maps, compliance reports, and any other analysis based on tachograph data.

How to use

Click on the "+" button in the Telematics Hub -> Plugins section to create a new plugin:

In the window that appears, enter the name of the plugin in the Name field. In the Type ID field, select tacho-file-parse. 

Good practice recommendations: 

  • We recommend adding the exists('media.tacho') filter to the Validate message field. This will reduce the load on the plugin and eliminate false positives for all device messages. 
  • It is advisable to leave the required flag unchanged (false), since if a parsing error occurs, the file message will not be registered.

Then we need to assign this plugin to the right devices. Go to the Plugins tab for the required device and click the "+" button:

Once the file is uploaded, the plugin processes it automatically. Head to the Logs & Messages tab — a "media file updated" entry confirms successful processing. The parsed output is stored in the content field of the corresponding file entity in flespi. The content field is returned with the file in the device media listing and is not displayed in the log object. A parsed file can add a megabyte or more to the listing, so request only the fields you need.

How to get extracted data from a plugin via API

The file's output can be obtained using the REST API request with specific file UUID. To find specific file UUID you can look device logs for media file updated events:

Data structure:

The plugin processes tachograph files and produces structured JSON data compliant with EU Regulation 2016/799. Two file types are fully supported for all tachograph generations and versions (Gen1, Gen2v1, Gen2v2): driver card files and vehicle unit memory files. Workshop, control and company card files are rejected with an error, as well as corrupted or truncated files.

The top-level object of the result shows the file type and the tachograph generation. The size of the result depends on the generation and the amount of data in the file: usually from 600 KB to 1.4 MB for a driver card file and from 400 KB to 1 MB for a memory file with 90 days of activities.

A file is parsed when it is uploaded. To parse a file that is already stored, for example after assigning the plugin to the device, resend the message with this file: it triggers the plugin and the file is parsed again.

Here is the driver file example as a demonstration with sections missing from the GEN 2v2 Stoneridge tacho. 

{
  "DF_Tachograph": {
    "EF_ICC": {
      "CardIccIdentification": {
        "cardApprovalNumber": "",
        "cardExtendedSerialNumber": {
          "manufacturerCode": 18,
          "monthYear": "0325",
          "serialNumber": 2,
          "type": 1
        },
        "cardPersonaliserID": 18,
        "clockStop": 0,
        "embedderIcAssemblerId": "4154001812",
        "icIdentifier": 14085
      }
    },
    ...
    "EF_Vehicles_Used": {}
  },
  "DF_Tachograph_G2": {
    "EF_Application_Identification_V2": {...},
    ...
    "EF_Border_Crossings": {...}
  }
}

Driver file

Driver card file stores data from the driver's perspective — their personal activity, vehicles they used, places they visited. The card travels with the driver between vehicles.

 The data is organized into two top-level objects:

  • DF_Tachograph — Gen1 data (present on all driver cards).
  • DF_Tachograph_G2 — Gen2 data (present on Gen2 cards only).

Both objects are worth reading on a Gen2 card: days driven in vehicles with a Gen1 tachograph exist only in DF_Tachograph, while days present in both objects need to be deduplicated by the consumer.

Each of them containing named sections that correspond to the Elementary Files (EF) defined by EU Regulation 2016/799:

  • EF_Identification — card details and driver's personal info (name, date of birth, card number, validity dates, issuing authority)
  • EF_Driver_Activity_Data — chronological activity records per day (driving, work, break/rest, availability, distance)
  • EF_Places — work period locations (country, odometer, GNSS coordinates for Gen2)
  • EF_Vehicles_Used — history of vehicles the driver operated (VIN, registration number, odometer range, first/last use dates)
  • EF_Events_Data — recorded events such as speeding or power supply interruptions (type, begin/end time, vehicle)
  • EF_Faults_Data — equipment faults logged during operation (type, timestamps, vehicle)
  • EF_Driving_Licence_Info — driving licence number, issuing authority and country
  • EF_Control_Activity_Data — last control inspection details (type, period, inspector card number, vehicle)
  • EF_Current_Usage — current session info (session open time, current vehicle registration)
  • EF_Specific_Conditions — special regime records such as ferry/train crossings and out-of-scope periods
  • EF_Application_Identification — card type and capacity metadata (number of records slots for events, faults, vehicles, places)
  • EF_ICC / EF_IC — chip hardware identification (serial number, manufacturer, IC identifier)
  • EF_Card_Download — date of the last card download
  • EF_CA_Certificate, EF_Card_Certificate — digital certificates for card authenticity verification (EF_Card_Certificate is present in Gen1 data)

Gen2-only sections:

  • EF_Vehicle_Units_Used — vehicle unit hardware records (manufacturer, software version, timestamps)
  • EF_GNSS_Places — accumulated driving GNSS waypoints recorded every ~3 hours
  • EF_CardMA_Certificate, EF_Link_Certificate — digital certificates of the Gen2 card application

Gen2v2-only sections:

  • EF_Application_Identification_V2 — extended capacity metadata (border crossings, load operations, VU configuration slots)
  • EF_Border_Crossings — border crossing events with GNSS coordinates, countries entered/left, and authentication status
  • EF_Load_Unload_Operations — cargo loading and unloading operations with GNSS location and odometer
  • EF_Load_Type_Entries — cargo type entries logged by the driver
  • EF_Places_Authentication — authentication status records for each place entry
  • EF_GNSS_Places_Authentication — authentication status records for each GNSS accumulated driving point

Memory file

Vehicle unit (VU) memory file stores data from the vehicle's perspective — every driver who used this vehicle, speed data, detailed technical events, calibration history, and sensor records. It stays with the vehicle.

The data is placed into one top-level object that shows the tachograph generation: VU_Tachograph for Gen1 and VU_Tachograph_G2 for Gen2. The structure is the same for both generations, with differences only where the regulation itself has them.

{
  "VU_Tachograph_G2": {
    "VuOverview": {...},
    "VuActivities": [{...}, {...}, ...],
    "VuEventsAndFaults": {...},
    "VuDetailedSpeed": {...},
    "VuTechnicalData": {...}
  }
}

A section is present only if it was downloaded from the tachograph:

  • VuOverview — VIN, vehicle registration, date and time of the download, the period available for download, card slots status, company locks, control and download activity, certificates
  • VuActivities — array with one element per downloaded day: date, odometer at midnight, driver activity changes, card insertions and withdrawals, work period places, specific conditions
  • VuEventsAndFaults — events, faults, overspeeding control data and events, time adjustments
  • VuDetailedSpeed — per-second speed for the minutes when the vehicle was moving, the biggest structure in the result
  • VuTechnicalData — vehicle unit identification, calibration history, paired sensors; for Gen2 also coupled external GNSS, used cards, ITS consents and power supply interruptions

Every element of VuActivities contains all the data the tachograph recorded for one day. Gen2 adds VuGNSSADRecords with vehicle positions, and Gen2v2 adds VuBorderCrossingRecords and VuLoadUnloadRecords.

When reading the result, note that:

  • changeTime of an activity change is the number of minutes since 00:00 UTC of its DateOfDayDownloaded.
  • An empty card slot is not present in a record: a missing slot key means there was no card in that slot.
  • While a card is still inserted, the withdrawal fields of its VuCardIWData record hold zeros or filler values such as 16777215 km. Skip such records when calculating the driver distance.

Viewing the result

To explore parsed files in a browser without writing code, use TachoBox.

Change log

Subscribe to the tacho-file-parse plugin change log to stay in sync with any updates.

More plugin types

Find a comprehensive list of available plugin types here.


See also
A free no-code app for automating your trackers, built by a flespi AI agent. Each automation runs on standard flespi components in its own subaccount.
Using the ai-driving-events plugin to review the video and images of vehicle cameras with AI: reset false ADAS and DSM alarms of the device and detect driving events in the footage.