- Essentials
- How tacho works
- How to setup
- Downloading files from tachograph
- Automatic tachograph files download
- Parsing tachograph data files
- Tachograph parameters
- Supported devices
- Troubleshooting
Essentials
Tacho functionality in flespi is designed to provide you with a simple and durable mechanism to remotely extract the data from the tachograph via a connected tracker. Extracted data from the tachograph is stored into the device for up to 10 years and is available via API for any further processing.
Tachograph authentication is provided via open source Tacho Bridge Application which is installed on the user’s computer to provide flespi with remote access to company cards. You may use this application as is or fork it and adapt to your company branding.
How tacho works
Tacho functionality is provided via the tacho-bridge channel, open source application Tacho Bridge Application, and its corresponding Tacho Bridge App and Tacho Bridge Card virtual devices.
Tacho-bridge channel provides an entry point for the locally installable Tacho Bridge Application to connect to your flespi account.
Tacho Bridge Application is installed on the user's computer or tacho card hotel server. Application is configured with its own unique ident and the address of the tacho-bridge channel it will establish the connection to. Ident is used to uniquely identify a corresponding Tacho Bridge App virtual device through which you will be able to track the current Application status and perform remote diagnostics or configuration.
For each company card, you create a corresponding Tacho Bridge Card device in your flespi account and configure the Application with the card information to link ICCID (Integrated Circuit Card Identification) with the company card number printed on the card. ICCID is used to identify the card in the reader while the company card number is used as a card identifier everywhere further in flespi. In the virtual flespi device linked to this card, you are able to track the online/offline status of the card in the reader’s slot and various logs and messages for transparent issues diagnostics.
When a tachograph needs to authenticate with a company card, flespi automatically provides it via the Tacho Bridge Application connected to the Tacho Bridge channel in the user's account. Each company card must be registered as a dedicated Tacho Bridge Card device in the user's account.
For the engineering behind this, link by link from the tachograph to the company card and back, see Authorization across half a continent.
The tacho-bridge channel and its App and Card devices respect your subaccount hierarchy and may be placed in the same account where devices representing trackers are registered. It can also be located higher in the hierarchy if you want to hide all or part of the tacho-related infrastructure from the device owner.
By creating multiple tacho-bridge channels in separate subaccounts you are able to create fully isolated tachograph authentication systems that are independent from each other.
How to setup
To activate tacho functionality in flespi you need:
-
Company card for tachograph authentication issued by the official authority (Ministry of Transport).
-
Smart card reader connected to the PC or tacho card hotel server, or a card rack connected to it over a serial (COM) port.
-
Tacho Bridge Application installed on your PC or server.
-
tacho-bridge channel in your flespi account.
-
Virtual Tacho Bridge App devices per each Application created in your flespi account.
-
Virtual Tacho Bridge Card devices per each Company card created in your flespi account.
-
Device that supports tacho functionality, registered in your flespi account and connected to the Tachograph in the vehicle.
-
Tachograph in the vehicle with driver cards inserted.
1. Create a channel configured with the tacho-bridge protocol. Copy its URI address where you will configure your Tacho Bridge Application to connect to. To restrict who can connect, fill in the Application authentication section of the channel with a username and password: every connection of the application and its cards must then present them.
2. Install the Tacho Bridge Application on your PC. Open the settings by clicking the gear icon and enter the address of your tacho-bridge channel in the Server address field. If the channel requires authentication, turn on Server authentication and enter the same username and password. The App ident is a unique identifier automatically generated during the first launch of the application and reused on every subsequent launch. It follows the format: TBA followed by 13 digits (e.g., TBA1234567890123). You may change the digits, but the TBA prefix must remain unchanged.
In the logs of your tacho-bridge channel, you should see attempts from the Application to connect and identify itself to the channel. If you do not see any connection attempts there please ensure that you configured the Application with the right server address and your PC has an Internet connection.
3. Create a Tacho Bridge App device in your flespi account with the same ident as you configured in the Application (see it in channel logs). You may do this directly from the channel by navigating to its IDENTS tab and clicking on the Create button to the right of the corresponding app ident. It’s important to specify the ‘Tacho Bridge App’ as the device type during device creation.
The Application will reconnect to the channel and the newly created device’s card should be in green color to indicate that it is now connected.
4. In the installed Application you see all inserted cards grouped by the reader or rack they sit in. A card that is not configured yet is shown as Unknown card with its ICCID number.
Now you need to configure the company card number for each unique card ICCID. You can pre-configure cards even if they are not physically connected: click the green Add card button and enter the Card number and optionally a Card name to make it easier to identify in the list. To link an inserted card, click Link next to it and either select a configured card and click Link to selected card, or enter a new card number and click Add and link. There is no limit to the number of cards you can create.
Once the card has been linked it is shown with the company card number. Immediately the card will connect to the tacho-bridge channel with the company card number as ident.
5. Create a Tacho Bridge Card device in your flespi account with the company card number as ident. You may do this directly from the channel by navigating to its IDENTS tab and clicking on the Create button to the right of the corresponding card ident. It’s important to specify ‘Tacho Bridge Card’ as device type during device creation.
When the card is inserted in the reader and the Application is running you may track its availability to flespi (and to Tachograph for authentication) by the green color of the corresponding device.
6. Open the properties of the tacho-enabled device in flespi and store the company card number in its configuration.
Now, if everything is configured correctly and has online status in flespi you may try to extract data from your Tachograph by activating the corresponding command.
Downloading files from tachograph
To download a file from the tachograph, you need to send the ‘Request tachograph file’ command to the device associated with the tracker. Please send command only using commands queue and with at least 20 minutes TTL (1 hour recommended) because tachograph commands usually are executing around 5-15 minutes.
You can do this directly from the Commands & Settings tab in the device by clicking on the “New command” and selecting “Request tachograph file”. Select the file type and click the “To queue” button to schedule command execution. Or copy its API call structure via the “>_” button and call it from your integration directly.
For the memory file you can select which data to request: overview, activities (for the last days or a specific time interval), events and faults, detailed speed and technical data. By default everything is requested.
Xirgo and BCE trackers have no such command: the tracker starts the upload by itself, and flespi stores every file it receives.
When the command is executed by the tracker device it will automatically authenticate the tachograph via the Tacho Bridge Card device with the same ident as the company card number configured in the tracker device. Thus it is essential that the Tacho Bridge Application that provides access to the physical card is active and the corresponding Tacho Bridge Card device is online in flespi during this phase.
Any progress or failure during command execution you may track in device logs where each step is verbosely reported.
Once the download is completed the file from the tachograph will be placed into device media storage and provided to you via a link. Before storing it, flespi checks the file structure: a damaged or incomplete file is rejected with “invalid tacho DDD file” in the device log, so the media storage keeps only valid files. The same link to the file will be stored in the command result as well. You may use that link to download this file into third-party storage if needed.
You can access all media files related to the device via the ‘MEDIA’ tab on the device page. To work with these files in your own application, embed Mediabox, which opens tachograph files in TachoBox.
You can fully utilize REST API to access or delete downloaded files or set up automatic files deletion and rotation. Files from tachograph are identified via type="tacho" attribute inside the file "meta" information.
To handle tachograph related device events via MQTT you have several options:
-
Subscribe to ‘request_tachograph_file’ command execution result to which the file link will be added upon successful command execution - via 'flespi/log/gw/devices/{id}/commands-queue/request_tachograph_file/processed' topic.
-
Subscribe to a new device message registered event and process messages with ‘media.tacho’ parameter that contains a link, name, size, and time of the file from tachograph - via '$filter/payload=exists%28%27media.tacho%27%29/flespi/message/gw/devices/{id}' topic.
-
Handle a media file uploaded event with detailed media information - via 'flespi/log/gw/devices/{id}/media_file_uploaded' topic.
-
You may also subscribe to 'flespi/log/gw/devices/{id}/tacho/communication' topic to receive all events about communication between flespi and tachograph.
You can add custom attributes to the stored file by using the PUT /gw/devices/XXX/media API method.
External Storage Integration: For automatic backup or long-term archival of tachograph files, you can use the S3 Media Upload stream to upload them directly to your AWS S3 or Oracle Cloud Object Storage bucket, with configurable path organization.
Automatic tachograph files download
After tachograph file download process is tested and confirmed you can enable automatic tachograph files retrieval by flespi with a single "Automatic file request" checkbox in device configuration. It works for Queclink, Ruptela, Teltonika, Squarell and Assistant Telematics trackers:
When checkbox is set flespi will automatically schedule 'request_tachograph_file' command for each specified slot when all conditions are met:
- Last automatic tachograph file download command for this slot was successfully performed at least "request interval" ago;
- Device is online and suitable for tachograph file retrieval operations (ignition is ON, etc);
- Corresponding Tacho Bridge Application infrastructure is online and available for authentication;
- After an unsuccessful automatic file request the next attempt is made after a delay that grows with each failure, until the download succeeds.
The request interval must be chosen wisely. The optimal solution is to download data once a week (default). The company card is a bottleneck and has a technical limitation (at the card level, not flespi) - only one device at a time can use the company card for authorization. When many devices (hundreds) compete for the use of 1-2 cards, this creates delays for other devices. Some may have poor connection quality or problems connecting with tachograph, which adds to the load on the queue. Therefore, default interval is the best option, which fully complies with all data download regulations with a 4-fold reinsurance in time.
The choice of file type should also be made wisely. The automatic download mechanism uses smart priority logic to avoid accumulating a common queue and getting stuck on downloading data that the tracker or tachograph cannot give for some reason. The smart mechanism uses the tracker's native capabilities provided by the protocol, as well as the number of repetitions and the conditions for "freezing" the tachograph data download. This allows for high-quality management of the tracker load and the queue among others. However, this mechanism is not a solution to all problems and it is not possible to foresee all possible problems. Therefore, if possible, it is necessary to select only the driver's slot used to avoid potential difficulties with downloading. The tachograph memory file does not depend on the driver cards and is downloaded whenever it is selected.
Automatically scheduled command operations you can track in device logs. If Tacho Bridge Application infrastructure is correctly provisioned you can expect that automatic system will durable download tachograph files into a stable flespi media storage within configured interval.
For a download schedule of your own, ask a flespi AI agent to run it, see Welcome to dark automation.
Parsing tachograph data files
During the download tachograph files are parsed to get the necessary data to form a correct file name and to fill the file metadata: plate_number, region, vin, driver_first_name, driver_last_name and driver_id. To get the full content of the file as structured JSON use the tacho-file-parse plugin, and to explore it in a browser use TachoBox. The system can work and analyze all types of files that can be downloaded remotely from a tachograph: driver file, memory file (VU file). For all generations of tachographs: G1, G2.1, G2.2. The manufacturer does not matter because the data inside the tachographs is regulated by a common standard.
Default name format.
The name formatting is dynamic depending on the file content. In accordance with the legislation of a particular country. The default file name format (for all countries except France and Spain) is the VDO format with the ddd extension. For example:
Memory file: M_20250801_1406_LT01STR_VINNUMBER00001001.ddd (M - memory file type, Date, time, vehicle registration number, VIN)
Driver file: C_20240808_1228_E_Smith1407_1200000000110200.ddd (C - driver file type, date, time, first letter of name, last name, driver card number)
Name format used for France.
Memory file: F_XX-NNN-ZZ_250801_1746.v1b (F - letter designation of the region, state registration number of the car, date and time). File extension v1b.
Driver file: F_1200000000110200_250801_1746.c1b (F - letter designation of the region, driver card number, date and time). File extension c1b.
Name format used for Spain.
Memory file: V_1234ABC_E_20250801_1745.tgd (V - memory file type, vehicle registration number, letter designation of the region of the country, date, time) File extension tgd.
Driver file: C_1200000000110200_E_20250801_1745.tgd (C - card file type, driver card number, letter designation of the country region, date, time) File extension tgd.
Tachograph parameters
Besides the files, trackers connected to the tachograph report its live data in device messages. The parameters have the same names and values in all flespi protocols, and the parameters of a driver have the number of the card slot at the end (.1 or .2):
- tacho.driver.activity.state.enum — current driver activity: 0 - rest, 1 - work, 2 - drive, 3 - available, 4 - not available, 5 - error
- tacho.driver.activity.state — the same as text: rest, work, drive, available, not available, error
- tacho.driver.activity.duration — duration of the current activity in seconds
- tacho.driver.card.code — driver card identifier
- tacho.driver.card.status — whether the driver card is in the slot
The set of reported parameters depends on the tracker and its connection to the tachograph. For example, to detect that the first driver is driving use the expression tacho.driver.activity.state.enum.1 == 2.
Supported devices
Tacho functionality is fully supported only for these devices:
Secondary URI. Teltonika, Xirgo, Xirgo-mqtt and BCE trackers upload files over a separate connection and need the Secondary URI option enabled in the channel configuration. Connection details and other specifics of each tracker are described on its protocol page.
A full list of devices with tacho functionality can also be found here. You can request integration of tacho functionality for other devices according to the integration instructions.
Troubleshooting
The process of downloading a file from a tachograph is quite a complex and multi-stage task with many remote parties involved (tachograph, tracker, flespi, application, company card). Our tacho functionality integration is specially designed to mitigate any possible issue and make this process as smooth and durable as possible.
During the execution of any command where a tachograph or company card is involved, we publish into the device logs all operations. By looking into device logs you should be able to quickly detect the party (tachograph, tracker, flespi, Tacho Bridge App, smart card reader, or company card) that is malfunctioning. All device logs related to the tacho functionality have “event_code”=340 (tacho communication) and their “tacho_code” property provides a more verbose description per each event.
For real cases of tachographs and trackers misbehaving, and how the device logs exposed them, see When your tachograph lies to you and ...And when the tracker lies too.
File download command execution is impossible without a correct configuration of all the parties involved. For example, the device log will display “The Company card '4220000000000000' is offline. The tachograph operation cannot be continued." if the card is not connected to the flespi. Or “The company card configuration field is not specified in the device settings. The tachograph operation cannot be continued." if the company card number is missing in the tracker configuration.
You can visually monitor if the tachograph is able to authenticate through the card by looking at the ‘connected’ status of the corresponding Tacho Bridge Card device. If the device is connected (green) then everything is correctly configured. If the device is not connected (white) check if the corresponding Tacho Bridge App is connected as well. If it is offline it means that the user did not start the local application or it is misconfigured with the wrong server address or ident. If the App is online while the Card is offline it means that either the card is not in the reader or its ident is incorrectly configured.
A common cause of a download error is correctly associated with incorrect tracker behavior or settings. The tachograph cannot correctly download a file if the ignition is off or there are failures in the physical connection of the tracker or tachograph. The tachograph may not always report that the ignition is off, so if the problem with downloading a file is repeated, you should pay attention to this. The ignition connection and the presence of a configured CAN bus that the tachograph uses in the vast majority of cases can be determined by the parameters that the tracker sends to the server or by the corresponding commands to obtain the connection status of the tachograph.
Here is the list of possible problems you may encounter and information on how they can be mitigated.
Problem: when the device downloads data from the black box, it may not respond to the tachograph file download command sent.
Solution: the command has a timeout of 5 minutes. If the tracker does not respond, flespi will make 2 more attempts and then the command will be rejected. To repeat the attempt, you need to put the command in the queue again.
Problem: the tracker's connection to the channel was broken during authentication.
Solution: flespi will try to restore authentication and continue the command execution. If the tracker stops responding for some reason or responds with an error, the current authentication will be rejected and the flespi will send the command again after some time.
Problem: the tracker's connection to the channel was broken while downloading a file.
Solution: On trackers that support it, flespi keeps the received part of the file, so if the tracker reconnects within 5 minutes the download resumes from where it stopped. Otherwise the file is downloaded again from the beginning.
Problem: the tachograph authentication fails with some combinations of a company card and a tachograph.
Solution: such a pair may work only over a specific card protocol. When authentication fails, flespi may open the next attempt with the other protocol (T=0 or T=1). Keep your Tacho Bridge Application up to date to use this.
Problem: authentication completes without errors, but the file never arrives.
Solution: check the expiry date of the company card. With an expired card, some trackers report no error and simply return no data.
Problem: the device log displays “The company card '4220000000000000' is in use by another device. Authentication cannot proceed at this time.”
Solution: only one device at a time can use the company card. Add more company cards or use a longer request interval if many devices share one card.