Documentation & Support
Sim Racing Telemetry can export recorded telemetry data in a comma-separated values (CSV) file. This is a simple textual file format that can be easily imported in other tools (like Microsoft Excel, LibreOffice, Matlab, etc) or easily read by custom computer programs.
Since the delimiter used for separate values in each row is the tab character, formally a tab-separated values (TSV) file is exported.
Here you can find the documentation of the exported data, including documentation of the system fields. System fields allow you to properly manage the exported data and re-create a correct telemetry stream. Game-dependent fields are not covered by this guide.
To correctly import the CSV files in a third-party software (like Microsoft Excel, LibreOffice, Matlab, etc), you must correctly configure the import options to match the file format. Opening the CSV file with a text editor will show you exactly how data are formatted. The following are the settings used by the exported CSV files:
.(the DOT character, not the comma or others)
An example of valid import options in LibreOffice:
Each row in the CSV file contains data of a specific “telemetry bin”. A “telemetry bin” contains telemetry data at a fixed distance on track (usually measured from the point where lap times begin to be measured, usually the finish-line), where near telemetry samples are “consolidated” in a single sample (this requires a relatively complex algorithm). The result is that you can pick a specific bin and you're able to get the corresponding telemetry data from all the available laps.
Some of the exported fields are important if you want to properly analyze or re-construct the telemetry stream.
| || If the row contains valid data (1) or not (0). Not valid rows can be ignored. Some laps - like the start race lap and the end race lap - contains only few valid rows. To simplify management in some software (e.g. math/statistics software usually import such CSV files as multi-dimensional matrixes), we always export all the telemetry bins of the laps, including invalid bins. When a row is not valid, all game-related fields are set to
| ||Car identifier string (as reported by the game).|
| ||Track identifier string (as reported by the game).|
| || Track length in metres (as reported by the game). The field
| ||0-based index of the lap in the CSV file. Each distinct lap in the file has a different index.|
| || 0-based lap number, as reported during a race. It's semantic is bound to
| || 0 for normal laps, 1 for “race-start” laps. It changes the semantic of several other fields (like the
| || 0-based index of the “telemetry bin” in the lap. Data, from different laps, with the same
| || The 0-based lap number as reported by the game. We suggest to use the
| ||Position of this sample in the track, This is reported as the distance of this bin on track, usually measured from the point where lap times begin to be measured.|
| || Lap time for the lap with index
Other fields are game-dependent and are not covered here (but see section Data Fields for some helpful generic information). In general, values set to
-1 are invalid.
For normal laps,
lapFlag is 0 and the
lapNum is the 0-based lap number.
But there's a special case that must be managed if you want to properly re-create the events during a race: in some races, the race begins before the normal finish-line (i.e. the start-line is before the normal finish-line - if the start-line is after the finish-line, this is not a problem as all the data are already consistent).
Such hundred of extra-metres are reported using:
lapFlagset to 1;
lapNumset to 0 (as it's definitely part of the first lap);
lap_timestarts counting (as such extra metres are part of the first lap time);
lap_distancereporting the right and normal position on track (i.e. the distance from the normal finish-line);
lapIndexis set to 0.
After crossing the normal finish-line, the “normal” data are then reported:
lapFlagis set to 0;
lapNumremains 0 (as we're still in the first racing lap);
lap_timeis not reset (as it's still counting the first racing lap time);
lap_distanceresets to always report the right position on track;
lapIndexincreases and is set to 1.
While the samples with
lapFlag set to 1 are not interesting from a telemetry point of view, they can contain important events of the race (like overtakes and changes in positions).
Depending on your needs, for simplicity you could ignore laps with
lapFlag set to 1 and you'll end working with simple, consistent and valid data.
To have mathematically consistent bins, each bin is associated to a unique “representative” position on track (specifically the one reported by
This usually doesn't match the exact last millimetre in the lap, so the
lap_time field is always a little bit behind the real registered lap time.
We could add this information in the future.
As not all games and tracks have the same number of sectors, exporting each sector as a separated column would produce CVS files harder to parse (the number and names of the columns wouldn't have a fixed layout anymore). We could add this information in the future (likely “packing” the data using a special format).
Most data fields are game-dependent and are not covered here.
In general, values set to
-1 are “invalid”.
Nevertheless, we try to manage all the data in a consistent way.
All the exported data use the unit of measures as defined by the standard International System of Units.
So - for example - all the velocities are exported in “metres/second”, while in the application they are converted in more useful units (for example: for the vehicle speed, we convert m/s to kilometres/hour for the metric system and to miles/hour for the imperial system; while we continue using m/s for suspension velocities; etc).
Conversions are often trivial: e.g. to convert from m/s to km/h you must simply multiply by 3.6. There are many online resources about units conversions.
For most vector data (like the Velocity for example), where possible we use a local coordinate reference frame (i.e. relative to the vehicle), with component X representing the “forward” (longitudinal) value, the component Y representing the “right” (lateral) value and the component Z representing the “up” (vertical) value.
For all parameters composed by multiple components (like the Velocity for example), we export only the single components. Inside the application, in addition to the single components, we show also the Euclidean norm (when this makes sense of course).
For example this is the case with the Velocity: the Velocity (V) value we show inside the application is the norm of the vector (VX, VY, VZ), but the real “telemetry data” acquired and exported are only the 3 components (i.e. the values of VX, VY and VZ - the “Velocity” scalar value is just computed by SRT and is not part of the source telemetry data). To compute the same value you can simply apply this formula (with all the P components set to 0).