racer home

Logging - telemetry analysis

 

Home What is the car doing numerically?


Dolphinity Organiser - free planning, project management and organizing software for all your action lists

Introduction

No simulation can do without telemetry logging. For the really hardcore crowd, it gives you numerical data on what the car is doing. Racer v0.5.2 introduced some basic logging options. Racer v0.8.34 is capable of more logging in binary formats such as RTD for high-end analysis.

How logging works

In racer.ini, you can set log.enable to 1 to start logging by default. Alternatively, press Shift-F3 while driving to turn logging on (use Shift-F3 to turn logging off again).

With log.period you can define the interval with which logging lines should be generated. Notice that the timestep at which the sim is running may not correspond nicely with this value, so try to make the log interval nicely dividable with the timestep (debug.ini's timing.integration_time). While logging, the log file will fill up quite quickly, and you may notice a performance drop.

With the log.groups section you can define per group of variables whether they'll be included or not. Take out unnecessary groups to avoid excessive log files.

The output format is decided by log.type. Here, 0 is ASCII, 1 is PI Toolbox (requires a license dongle from Cosworth) and is Racer's native binary format, RTD (Racer Telemetry Data). For the last format, you can convert the binary files later on to ASCII using RTD2ASCII. Note that not all types will output exactly the same signals; small variations are possible.

Logging in ASCII format

If racer.ini's log.type is set to 0, the log output is in a plain ASCII text file. A file in data/dump/ is generated, with the prefix taken from debug.ini's log.filename ('default' is a nice name).

With log.period you can define the interval with which logging lines should be generated. Notice that the timestep at which the sim is running may not correspond nicely with this value, so try to make the log interval nicely dividable with the timestep (debug.ini's timing.integration_time). While logging, the log file will fill up quite quickly, and you may notice a performance drop.

With the log.groups section you can define per group of variables whether they'll be included or not. Take out unnecessary groups to avoid excessive log files.

WHAT DOES THE OUTPUT LOOK LIKE?

The log file is in plain ASCII format to allow for other people to build useful utilities that allow more easy processing of the logged data.

The first line in the log file is always a line stating the log file generation time. The 2nd line states the field names of the data to come. The first field is always 'time', indicating the time in milliseconds at which the snapshot was taken (in simtime, not realtime; the last one wouldn't be very useful). After the 'time' field, the fields depend on which groups have been selected in log.groups. Each group that is enabled (for example, log.groups.steering=1) will be added to the log (both the fields and the values). The less groups, the faster performance will be, so try not to enable all groups unnecessarily.

The groups are described below. Note that there is always a column 'time', giving the time in seconds.

Group Variable outputs & units   Description
ai

AI related data. ai_line_delta gives a small number indicating the amount the driver is off the AI driving line (F3 to toggle the best line).

For example: if the current u is 0.5 (middle of the road), and the car is at 0.2, the result is 0.2-0.5 = -0.3. So negative numbers mean the car is left to the best line.

  Available since v0.8.9.
surface Adds surface_x_w<n>, surface_y_w<n> and surface_z_w<n> for all wheels. These are the surface intersection coordinates in world coordinates. If a spline is used, this will be the spline intersection (unless use_mesh_hits=1 is used).   Since v0.8.35.
suspension susp<n>.length (in meters, larger numbers means more rebound) and susp<n>_f_arb (in Newtons, positive forces push the body up, so in a right-hand turn the ARB forces on the right front wheel will be positive, and negative on the left front wheel).   Suspension lengths for each wheel, and ARB (anti-roll bar) forces for each wheel.
slip_angle sa<n> (in radians). Positive for a right-hand turn.   Slip angles for each wheel.
slip_ratio sr<n> (normalized). Positive for acceleration.   Slip ratios for each wheel (sr<n>).
tire_forces fx<n>, fy<n> and fz<n>. All in Newtons. Fx is positive for acceleration, Fy positive for right-hand turn and Fz negative for a loaded tire.  

Tire forces for each wheel (fx<n>, fy<n>, fz<n>). Axis system is NOT Racer's default (Racer's default axis system is OpenGL's system). Here: Fx=longitudinal (Z in Racer), Fy=lateral (X in Racer), Fz=load (Y in Racer).

steering steer<n> for each wheel (in degrees, NOT radians; positive for a left-hand turn). Also m_s for aligning moment (in Nm; positive when turning right, giving a push to the steer in a counter-clockwise direction).   Steering input, and force feedback (steer<n>, m_s). Force feedback is the sum of the aligning torques at the steering wheels. The aligning torque is the tire's Mz moment (from the Pacejka tire model calculations) plus caster and kingpin forces, summed and divided by the steering ratio, plus any caster effects.
controls throttle, brake and clutch. Normalized from 0..1. These are the raw control engine inputs: no auto-clutch and other effects such as ABS are included.   Throttle, brake and clutch (varying from 0..1).
orientation yaw, pitch and roll. All in radians. Pitch is negative for nose dives and positive for acceleration. Yaw increases when rotating the car clockwise. Roll is normally positive when turning left (assuming normal car roll centers).   Yaw, pitch and roll (Euler angles, so of limited use when the car tips over).
position

x, y and z. In meters in world coordinates. Also exports odo, an odometer in meters, londistlap (distance along the track longitudinally, resetting to 0 each time you cross start/finish), lap (the lap index, starting at -1 before the first start/finish crossing, 0 for the first lap etc) and u, the normalized lateral position on the track (0..1).

v0.9.0RC6 also adds start_lights which is the image index used in the race start lights sequence. A low number means just starting; it goes up until it reaches the highest image and stays there for the remainder of the race.

  Car position and odometer and such.
velocity vx, vy and vz. In m/s and in world coordinates.   The true velocity of the car.
angular_velocity dvx (pitching), dvy (yawing) and dvz (rolling). In radians/sec. dvx>0 when braking (nose dive), dvy>0 in a left-hand turn, dvz>0 at the start of a left-hand turn (all using a right-handed coordinate system, with XYZ in the Racer/OpenGL axis system).   Angular velocity of the car (dvx, dvy and dvz) (in body coordinates).
acceleration ax, ay and az. Units are m/s^2 (=m*s^-2). ax is positive in a left-hand turn. ay is positive when accelerating upward, az is positive when accelerating.   Linear acceleration of the car (ax, ay and az in m/s^2) (in body coordinates).
engine rpm (pure engine RPM), gear (0=neutral, 1=reverse, 2=1st, 3=2nd etc) and torque (in Nm). Racer v0.9.0RC6 also adds fuel, for the remaining fuel in liters.   Engine characteristics.

What to do with the output

There is a 3rd party telemetry analyzer available through the RSC forums; visit this link. An alternative would be WinDARAB.

Also, you can use a professional tool like MATLAB if you have it (it's a commercial tool) and can work with it. Tools to convert log files from and to MATLAB are available; see Log2Mat (Racer to MATLAB) and Mat2Log (MATLAB to Racer).

Logging in RTD format

If racer.ini's log.type is set to 1, the log output is a binary file. The file will be generated in data/dump/, with the prefix taken from debug.ini's log.filename ('default' is a nice name).

More info on the RTD format can be found here.

 


Dolphinity Organiser - free planning, project management and organizing software for all your action lists

(last updated April 2, 2013 )