rFactor Pro Terrain Server

The rFactor Pro™ Terrain Server is a pseudo SimWB device that supports access to the Terrain Server track data.
Support for the Terrain server is provided by 2 I/O tasks (input and output) on the SimWB side and a separate executable and libraries provided by rFactor Pro.
The SimWB output I/O task queries the terrain server via the Terrain Server API to set wheel position, orientation and speed for each of the 4 vehicle wheel.
During the input sub cycle, the input I/O task will read the results computed by the Terrain Server and update the SimWB RTDB with the values.
SimWB ships our own version of rFPro Terrain Server. The current version of rFPro Terrain Server that we ship is 2020.1.

Reference Information Terrain Server I/O tasks

I/O Module License:

ICS-SWB-1249.

I/O Device Mapping

As with any other SimWB I/O devices, connection between the RTDB and the Terrain Server is done via the GUI mapping dialog.
The I/O mapping is divided into three sections:

Initial configuration: sets initial values for the wheel configuration such as radius and width, contact point geometry, track data axes and initial track name and CPU affinity where the Terrain Server should run.
Query: Set the parameters for the query to the Terrain Server.
Response: Get the response computed by the Terrain Server.

Initial Configuration: This section provides the values to initialize the Terrain Server configuration. The initial values can be entered as constants in the mapped Points\|Initial value column (by double-clicking the field on this column) or will be provided the RTDB item initial value when the parameter is mapped to an RTDB item. The RTDB item initial value is provided by the default value in the item configuration panel or by associated initial condition value set specified when running the test. ChassisPoint.[n]: Define the position of the chassis point. A maximum of 25 points can be configured. ContactPoint.[n]: Define the position of the tires contact point. This is optional, a default position of (0,0,0) with a weighting of 1 is assumed if not provided, a maximum of 10 contact points with associated weighting can be configured. Terrain Server Run CPU: The CPU affinity for Terrain Server process. If you want to use multiple CPUs, use comma separated values. Please note that if you use multiple CPUs here, you need to specify 'NumCalcThreads' in 'rFactorPro HD Terrain Server.ini' accordingly. For example, if 'NumCalcThreads=2', then you can specify CPUs to something like '4,5'. If not set, we use thedefault value set in rfProTSAPIInitialize.ini. See 'Configuration Files' section below. Terrain Server Surface Directory: Absolute path of the directory where Terrain Server track data resides. By default this is /usr/local/ccursim/RFPRO-TerrainSrv if not provided. Terrain Server Axes : The axes the track data uses; 0 (RFactor Axes), 1 (ISO Axes). By default the axes are set to ISO axes. The value you specify here will depend on how your track data is formatted. Track name : The name of the track to load into the Terrain Server initially. No default is assumed for this parameter. Tyre[n] : Define the radius and width of the each tire. Default is 0.3 for radius and 0.25 for width when not provided.

Query (Output): This section provides mapping of the parameters to issue a query to the Terrain Server. At a minimum , WheelOri[0-2] for each tire need to be mapped to RTDB variables so that a valid query can be submitted to the Terrain Server. DataReady: This is a handshake parameter between the output I/O task and the model. The I/O task will wait for this value to be != 0 before it sends the query data to the Terrain Server. It is the responsibility of the model that sets query values to set the value as early as possible during the model sub cycle so that the Terrain Server executable will have ample time to compute the result before the response is read in the next input cycle. TyreQuery[n]: n from 0 to 3 Define the values of the query parameters for each wheel (n [0-3]). mDT: The time delta to extrapolate the center position of the wheel to the next physics frame. mExtrapolateWheel: Whether the extrapolation should be performed. mDownVector: Unit vector (x,y,z) of 'down' (world coordinates). Typically should be set to conform to the chassis orientation mDownVectorValid: Whether the Down Vector should be used. Necessary for good results from the SD mesh data unless the wheel rotation about its axle has already been removed mVelocity: Linear velocity of wheel center (world coordinates). mVelocityValid: Whether the Velocity Vector should be used. Necessary for good results from the SD mesh data unless the wheel rotation about its axle has already been removed mWheelOri[m] m from 0 to 2 : Orientation of wheel (world coordinates). These values should provided at a minimum for a valid query to the Terrain Server. ChassisQuery Define the values of the query parameters for the chassis. mDT: The time delta to extrapolate. mExtrapolatePos: Whether the extrapolation should be performed. mOri[m] m from 0 to 2 : Orientation of chassis (world coordinates). These values should provided at a minimum for a valid query to the Terrain Server. mVelocity: Linear velocity of chassis (world coordinates). mVelocityValid: Whether the Velocity Vector should be used. ChassisGroupQuery Define the values of the query parameters for the chassis. mGroupID: The ID of the group to which this offset applies. mOffset: Offset in local chassis coordinates applied to each point in the group before querying. mOri[m] m from 0 to 2 : Orientation of group (local chassis coordinates).

Response (Input): This section provides the values to initialize the Terrain Server configuration. The initial values can be entered as constants in the mapped Points\|Initial value column or will be provided the RTDB item initial value when the parameter is mapped to an RTDB item. The RTDB item initial value is provided by the default value in the item configuration panel or by associated initial condition value set specified when running the test. TyreResult[n]: n from 0 to 3 Define the values of the response from the Terrain Server corresponding to the query issued during the previous output cycle. mResultValid: Any result data valid? If false, no valid data could be calculated and the result should be ignored. The I/O task will only update the RTDB variables when the result is valid. mHDValid: Data calculated from HD surface data. Otherwise calculated from SD mesh data. mHeight: Vertical position of the contact patch (world coordinates). mNormal: Unit vector (x,y,z) at normal to road surface (world coordinates). mPatchCentre: The position of the center of the contact patch (world coordinates) mPatchCentreValid: Whether mPatchCentre results are valid and should be used. The mPatchCentre mapped RTDB variables will only be updated when the result is valid. mSurfaceGain: Friction multiplier. should be exactly 1.0 for 'average' asphalt. mSurfaceType: 0=dry, 1=wet, 2=grass, 3=dirt, 4=gravel, 5=rumblestrip. mTerrainName: The material prefix from the TDF file. ChassisPointResult[n]: n from 0 to 3 Define the values of the chassis response from the Terrain Server corresponding to the query issued during the previous output cycle. mHeight: Vertical position of the chassis point (world coordinates). mLocalHeight: The position of the center of the chassis point(world coordinates). mNormal: Unit vector (x,y,z) at normal to chassis point (world coordinates). mResultValid: Any result data valid? If false, no valid data could be calculated and the result should be ignored. The I/O task will only update the RTDB variables when the result is valid. mSurfaceGain: Friction multiplier. mSurfaceType: 0=dry, 1=wet, 2=grass, 3=dirt, 4=gravel, 5=rumblestrip. mTerrainName: The material prefix from the TDF file.

Run-Time Considerations

As mentioned before, the model is responsible for setting the DataReady Variable to != 0 as early as possible during the model sub cycle. This is to allow the Terrain Server as much time as possible to process the query before the next input sub cycle.
On a modern CPU (~ 3.0 GHz) , the Terrain Server requires around 80% of the CPU to process the response for a 4 wheel query.
The Terrain Server should thus run on a dedicated CPU (shielded) to eliminate preemption from other processes sharing the same CPU. This will maximize the time available to the Terrain Server and ensure maximum determinism in the query/response cycle.

I/O Task Internal Variables

The Terrain Server SimWB I/O tasks creates a few internal variables for the purpose of monitoring the behavior of the I/O tasks / Terrain Server system. Those variables will be automatically logged when data logging is enabled for the test run.

delta_uSec: The interval in micro seconds between the time the query was sent to the Terrain Server and the time the response was read. This is the maximum amount of time that the Terrain Server has to execute the query. The earlier in the cycle the query is sent , the more time the Terrain Server will have to process it.

qrystartofFrame_uSec: The time in micro seconds from the start of the SimWB cycle to the time the query was sent to the Terrain Server.

resultErrorCount: The number of invalid results from the Terrain Server. I.e the number of times mResultValid was 0. when the result is valid.

resultOverruns: The number of overruns in response from the Terrain Server. An overrun occurs when the input I/O task will try to get the response and the Terrain Server is not ready. This means that the Terrain Server did not have enough time to compute the response corresponding to the last query.

Example Cycle

Contrary to all SimWB output I/O tasks, The Terrain Server output I/O task runs during the model cycle. An output I/O task running during the output cycle (after all the model(s) have finished execution) is always guaranteed that all output variables values will be stable since only the models are supposed to set output variables. Nevertheless, in order to allow more time for the Terrain Server execution, the Terrain I/O uses a communication variable (DataReady) to indicate when the query variables calculated by the model are ready to be used.

Notice how the rfpro_ts_out process runs concurrently with the TS_Linear10 model. rfpro_ts_out will wait until the DataReady is set before querying the Terrain Server.
Also, the rfpro_ts_out should be run on a different CPU from the model that sets the DataReady variable so that it can start running as soon as the variable is set. rfpro_ts_out would be preempted by the model and prevented to run if both were configured to run on the same CPU.

Configuration Files

SimWB's Terrain Server interface uses 2 configuration files for controlling the Terrain Server.Both these files are located under '/usr/local/ccursim/bin'

rFactorPro HD Terrain Server.ini: Controls logging and debugging settings
rfProTSAPIInitialize.ini : Control the default CPU, path of the tracks, etc.