Shedsoft

 

Accessing iRacing's API data from iRDDU

iRDDU does the heavy lifting of extracting data from iRacing to use in controls on your dashboards, all you need to do is tell it which ones to use.  In addition it allows you to modify the values using formulae and a number of built in functions to do things like store the maximum value a number has reached or convert a string to all capital letters.

In order to distinguish between the different parts of a function iRDDU needs API fields to be specified in a particular format.  To make this easier I've implemented a dialogue to enable you to select from the available options.  It's accessible from any editor property that allows a function to be used; namely the main Formula property of a control and most of the parameters available on script commands like SetValue, SetDimensions, SetVisibility and the like.  To access it click in the property's text box and a button will appear to the right containing three dots, click that button and the Edit Formula dialogue will appear.

Edit Formula windowThe Formula Editor and Simple Fields

At the top is the formula box where you enter the formula which tells iRDDU where to get it's data.  It's a free text field and currently there's no validation to stop you entering rubbish.  That's an omission I'll correct in a future update.

The simplest formula is a single value.  This could be a literal; a number or string or an API field.

Numeric literals are simply entered as the number using the British/US standard of a dot as the decimal point.  Strings are delimited by double quotes, for example "Shedsoft" or "Stirling's Bend".

The various types of data field are identified by a pair of square brackets.  Within those brackets the identifier is split into two parts, a source ID and the field name.  The most common source ID is SIM which tells iRDDU to look for the field in the API.  For example [SIM|Speed] would ask the API for the current speed.

Below the formula box is a list of fields and functions split into categories.  It's not a definitive list, iRacing often add new fields to the API and I can't promise to keep it completely up to date.

The categories group together fields of specific types.  The generic sim fields are those I've built into iRDDU itself to make it as sim agnostic as I can.  I stil lintend to add support for other sims and when I do I will make sure all of the generic fields are supported from the new sim.  That means that if you restrict yourself to these fields then any dashboard you build now will work just as well in another sim when the new adapter is added.

If you click on any of the fields a simple description will appear in the box to the right.  To add a field to the formula  select it, place the cursor in the formula where you want it to appear and press the "Add Field" button.  The field will appear in the formula perfectly formatted and ready to give you your chosen data.

You will notice that some of the fields have an extra identifier after the | character - IR:.  This tells iRDDU that the field identifier is native to a specific sim's API.  Of course at the moment it only supports iRacing so IR is the only option but eventually i hope you'll be able to access other sim's data in the same way.

Modifying Data Values - Inbuilt Functions

iRDDU contains a number of functions designed to modify the data returned by the API or use it to create new values.  The available functions are listed under the "Inbuilt Functions" category.  Each one has a description in the formula editor so I'll not go through them one by one but here are a couple of examples to show the basic idea.

Abs( [SIM|Speed] )

This gets the current speed of the car (in metres per second) and returns it's absolute value, in other words it strips off any decimal component leaving a whole number.

Max( [SIM|RPM] )

This is more interesting.  The Max function remembers the highest value it has been passed and returns it.  What I've done here would return the highest RPM the engine has reached so would be perfect for use as a rev counter tell-take on an analogue gauge, I've used it as such on my Lotus 49 dash.

Driver Indexed Fields and the Session String

Many of the fields in the API refer to other drivers, for example best laptime in session, last laptime in session, driver name, club etc.  iRDDU gives you the ability to refer to individual drivers based on several different criteria making it possible to build race position screens or even a surrogate F3 screen.

The driver refernce takes the form of a suffix to the field identifier of the form #{id}.  For example to get the best lap of the session for the driver at the top of the leaderboard:

[SIM|BestLap#P1]

The # tells iRDDU to treat the field as driver indexed, the letter says how to work out the driver and the number is the offset to the driver in question.  For the above example P means Position and 1 tells iRDDU to look at the driver currently in P1.  #P2 would obviously be the driver in 2nd, P3 the third etc.

If you want to look for a driver relative to the local driver's position you can use #R (Relative).  The following example returns the name of the driver two places behind you:

[SIM|DriverName#R-2]

#R returns data based on the driver's position in the session results, #T however looks at current track position like iRacing's F3 screen.  You must be getting the gist by now, the following gives you the last lap time of the driver in front of you:

[SIM|LastLap#T1]

There is one other type of driver index, #ME returns the driver data for the local driver.  So to get your own best lap time:

[SIM|BestLap#ME]

One useful little feature of the IR specific fields is the ability to access the iRacing session string within the API.  It's returned in a rather nice text based format called YAML and provides most of the less frequently updated data items like laptimes, track names and the like.  iRDDU provides generic fields as shortcuts for much of the data in the session string but there is a lot of useful data not covered.

A full explanation of either YAML or the session string is out of the scope of this manual but iRDDU allows you to pass parameterised queries to it to get specific values that aren't otherwise supported by generic fields.  For example, to get the initials of the driver in P1:

[SIM|IR:DriverInfo/Drivers/{3}/Initials#P1]

If you look at the abbreviated version of the DriverInfo section below you can see how iRDDU works it's way through the hierarchy to find the correct field. 

DriverInfo:
  Drivers:
  - CarIdx: 5
    UserName: Stirling Moss
    AbbrevName: Moss, S
    Initials: SM
    UserID: 77777
etc...

The only odd bits are the {3} and the #P1.  Most of the data stored within the session string can only be accessed by specifying things like session number, driver position or car index.  These are dynamic things so you can't simply hard code them to a value or you'll still be displaying data on the warmup during the race. 

iRDDU does the hard work for you by allowing you to specify a driver index like you would for mroe conventional driver indexed fields.  When it tries to access the data it works out the current session number, driver position and car index and replaces the {#} in your field ID for the correct value.  In this example I've kept it simple and we only need the car index to identify the driver.  iRDDU replaces the {3} with Stirling's car index - which is 5 - and retrieves the value at DriverInfo/Drivers/5/Initials.  In this case SM.

If you're accessing other areas of the session string you might need the session number or driver position.  If so then use the approriate substitution string from the following list:

{1} = Session number
{2} = Selected Driver position
{3} = Selected Driver Car Index 

Formulae

If you've done any programming at all you'll be familiar with the concept of a formula or expression.  It consists of a number of data items linked together by operators to calculate some value.  As usual a couple of examples are better than a description.  First an example of a string formula to concatenate some values together:

"Leader: " + UpperCase( [SIM|DriverName#P1] )

When faced with this iRDDU takes the string literal "Leader" and adds the name of the driver in first position to the end after converting it to capitals.

A numeric example.  This calculates the 7% qualifying cut-off time time for the current session.

[SIM|BestLap#P1] * 1.07

The normal mathematical rules apply so * and / are calculated first followed by + and - and you can use parentheses to force precedence.  To calculate how close you are to the 7% limit above:

( [SIM|BestLap#P1] * 1.07 ) - [SIM|BestLap#ME]

All of the laptime fields return a value in seconds so the above would return how many seconds behind the qualifying cutoff point your best lap is.

The following operators are available:

+ * / - Basic arithmetic operators.  When applied to strings + concatenates.
( ) Force precedence in a formula.
= Comparison - EQUALS.  Compares the two values on either side and returns a number; 1 if they are the same, - if not.
< > Comparison = LESS THAN and GREATER THAN.  Works the same as = but return whether the value on the left is less than or greater than that on the right.  For example:

[SIM|RPM] > 10000


Returns 1 if the RPM is greater than 10000.
& Logical operator - AND.  Returns 1 if the values on either side are both non zero.  It's effectively a way of linking together more than one comparison.  For example:

[SIM|RPM] > 5999.9999 & [SIM|RPM] < 7000

Returns 1 if the RPM is between 6000 and 7000.
| Logical operator - OR.  The same as & but returns 1 if either (or both) of the values are non zero.

Keeping Track of Events - State Variables

The iRacing API gives you the curent state of the world, it has little or no concept of history.  You will though on occasion want to compare the current state to a fixed point in the past; the start of the current lap, the last time you exited the pits etc.  iRDDU automatically saves a number of the more useful data values for every car in the session enabling you to do some quite useful things like calculate the time distance between two cars or how much fuel you've used in the current stint.

iRDDU keeps track of the state variables but continually monitoring all the time the sim is active, irrespective of whether a dashboard is running or not.  Clearly though it can't monitor while it's not running so if you start iRDDU halfway through the session it'll only have that amount of data.  Better to start it before joining the session.

State variables are maintained at three different points in time; Start of Run, Start of Stint and Start of Lap along with a fourth option giving the same data in real time to simplify comparisons. 

To access the different state variables you specify RUN, STINT, LAP or NOW as a in the same way you migtht a sim identifier.  The obligatory example below returns the amount of fuel remaining (in litres) the last time you left the pitlane:

[SIM|STINT:FuelLevel#ME]

More useful though is to do a bit of arithmetic:

[SIM|STINT:FuelLevel#ME] - [SIM|LAP:FuelLevel#ME]

Now you know how much fuel you've used in the current stint.  From that of course we can work out things like fuel per lap:

( [SIM|STINT:FuelLevel#ME] - [SIM|LAP:FuelLevel#ME] ) / ( [SIM|LAP:LapsCompleted] - [SIM|STINT:LapsCompleted] )

The state variables you can choose from are:

SessionTime The session time when the sample was stored.
SessionTimeRemaining The time remaining in the session
FuelLevel The volume of fuel remaining in litres.
LapsCompleted Number of laps completed in the current session up to this point.
DistanceCovered Distance covered in the current session in metres.

Unfortunately the API only returns fuel information for the local car so you can't monitor how much fuel the other cars are using I'm afraid.  Of course you can keep track of how many laps they've completed since their last stop...