- Essentials
- How tacho works
- How to setup
- Downloading files from tachograph
- 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 ATR (unique card key) with the company card number printed on the card. ATR 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.
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.
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.
2. Install the Tacho Bridge Application on your PC. Configure it with a unique App ident (you may use any value) and the address of your tacho-bridge channel.
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 Card 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 in the reader with their ATR number.
Now you need to configure their respectful company card numbers per each unique card ATR. For convenience, we recommend connecting cards one by one and after the card is identified in the application, link its company card number in the Application. To do this, click on the + button to the right side of the identified card and enter the company card number in the pop-up window, then click on the SAVE button.
Once the card has been linked its ATR will be replaced with the company card number used. Immediately the card will connect to the tacho-bridge channel with the company card number as ident and its icon will turn green.
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.
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 DDD slot 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.
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. 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.
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 can add custom attributes to the stored file by using the PUT /gw/devices/XXX/media API method.
Supported devices
Tacho functionality is fully supported only for these devices:
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 Card 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.
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 '422000000000000' is not online. The tachograph operation cannot be started. Request attempt 1/3" 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 started." 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.
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: at the moment, flespi does not have the ability to restore and continue an interrupted file download. After reconnecting the device to the channel, flespi will first try to cancel the current file download, in case of failure, it will skip the rest of the file that the device transmits and then resend the command to download the file.