66laps Developers

« Back to the developer homepage

OpenMotorsport

An open file format for motorsport.

Martin Galpin (m@66laps.com)

OpenMotorsport 2.0 will be announced very soon. This format is now deprecated. If you would like any information in the interim, please do not hesitate to e-mail m@66laps.com.

Introduction

OpenMotorsport is a freely available, open file format for storing and exchanging data recorded during motorsport. It is designed to be simple, compact and easy to parse with a variety of reference implementations available under liberal Open Source licenses.

Motivation

It is true that there is already a plethora of file formats used within motorsport. Every manufacturer of data logging equipment will generally ship a proprietary format - normally for use with their own data analysis software. The specification of these formats are rarely (if ever) published and experience from other fields (see OpenDocument, OOXML) demonstrates that over time, this leads to:

  • vendor lock-in (to logging equipment and software)
  • no interoperability between vendors or users
  • loss of data (through legacy formats and unsupported software)
  • stifled innovation

Most (but not all) data analysis software supports export to at least one standard format: Comma-separated values (CSV). However, despite numerous advantages, using CSV as a data exchange format poses a number of additional problems.

  • inefficient storage: representing numbers as a sequence of characters is wasteful
  • inflexible: flat files mean a single linear sampling interval for the entire session
  • no metadata: creates non-standard file headers that are difficult to read and write

Specification

Overview

An OpenMotorsport file consists of a standard ZIP archive (DEFLATE compression) containing a number of files. It must carry the file extension .om. The exact number and contents of the files will vary, however, a typical OpenMotorsport file will contain the following.

File Description
meta.xml Metadata about the recorded session (for example - circuit, driver, date and channels recorded.
data/ A directory containing the recorded data for each channel.
data/1.bin A binary file consisting of the recorded data for the channel identified as 1.
data/2.bin A binary file consisting of the recorded data for the channel identified as 2.
data/2.tms A binary file consisting of the recorded sample times for the channel identified as 2.

Metadata (meta.xml)

OpenMotorsport stores metadata associated with a session in an XML file called meta.xml. This file resides in the root of the archive.

The root openmotorsport element uses the default namespace http://66laps.org/ns/openmotorsport-1.0. It may contain the following elements: metadata, channels, markers.

An example is shown below.

<?xml version="1.0"?>
<openmotorsport xmlns="http://66laps.org/ns/openmotorsport-1.0">
  <metadata>
    <user>Michael Schumacher</user>
    <vehicle>
      <name>Mercedes MGP W01</name>
      <year>2010</year>
      <category>Formula One</category>
    </vehicle>
    <venue>
      <name>Brands Hatch</name>
      <configuration>Indy</configuration>
    </venue>
    <date>2010-07-19T03:51Z</date>
    <duration>13500</duration>
  </metadata>

  <channels>
    <channel id="0" units="mph" interval="10">
      <name>Speed</name>
      <description>Vehicle speed from FL wheelspeed sensor.</description>
    </channel>

    <group>
      <name>Acceleration</name>
      <channel id="1" units="g" interval="10">
        <name>Acceleration X</name>
        <description>Acceleration on the X-axis.</description>
      </channel>
      <channel id="2" units="g" interval="10">
        <name>Acceleration Y</name>
        <description>Acceleration on the Y-axis.</description>
      </channel>
      <channel id="3" units="g" interval="10">
        <name>Acceleration Z</name>
        <description>Acceleration on the Z-axis.</description>
      </channel>
    </group>
  </channels>

  <markers sectors="2">
    <marker time="2000" />
    <marker time="5000" />
    <marker time="7000" />
    <marker time="9000" />
    <marker time="11000" />
    <marker time="13500" />
  </markers>
</openmotorsport>

metadata element

The metadata element must contain at least four children. They are shown below:

Element Description
user This element names the user who recorded the session. Typically this will be the driver of the vehicle.
vehicle This element names the vehicle that recorded the session. It must contains at least one element name. It may also include the optional elements year, category and comments.
venue This element names the venue at which the data was recorded. It contains one mandatory element name and an optional element configuration for use at circuits with multiple track configurations (for example Silverstone National, Grand Prix and Arena).
date This element gives the date that the session was recorded. It is stored in a form compatible with ISO-8601. The truncated form (such as --06-10) should not be used. The time must always be in local time.

The following additional elements are optional.

Element Description
duration This element gives the total sampling duration for the session. It should be a relative time (in milliseconds) from when the first sample was recorded and until the last. Whilst this element is optional, it is recommended that it is always included because the duration can be used to identify incomplete laps.
comments This element gives an optional text comment for the session. For example, a description of track conditions.
datasource This element gives an optional datasource description for this session. For example, the logger number, device or simulation.

channels element

The channels element declares the channels that were recorded during a session.

The following elements are optional.

Element Description
channel This element declares a single channel.
group This element declares a group of related channels. It should contain at least one channel element.

channel element

The identifiers of each channel must correspond with a binary file (.bin) in the data/ directory of the archive. If the channel does not have a sampling interval, it must also correspond with a times file (.tms) at the same location.

A channel element must provide the following attributes.

Attribute Description
id This attribute is a unique identifier for this channel. No two channels can have the same id within a single OpenMotorsport file. The attributes value must should be a number.
name This element gives the channels name.

A channel element can also provide the following additional attributes.

Attribute Description
units This attribute gives the units of measurement. For a table of common units and their abbreviations, see units.
interval This attribute gives the sampling interval in milliseconds.
description This element gives a description of the channel.

group element

The group element can contain any number of channel elements.

Element Description
name This element gives the name of the group.
channel See channel.

markers element

The markers element contains an arbitrary number of marker children. It has a single optional attribute.

Attribute Description
sectors This attribute gives the number of sectors (specified in marker elements) per lap. If this attribute is not given, it is assumed that each marker represent a completed lap.

marker element

The marker element represents a specific time offset within a session. It might be the time at which a sector or lap is complete. If the sectors attribute of the marker element is provided then every nth marker represents a completed lap.

The marker element must provide a single attribute.

Attribute Description
time This attribute gives the time (in milliseconds) at which the marker occurred. It must be an offset from the beginning of the session.

It is worth noting that there is no definition of a lap in OpenMotorsport. This allows for a broader application outside of circuit racing where data is not represented by the boundaries of a lap. For example, in rallying, drag racing, or sprinting, the sectors attribute might be omitted and markers would only represent sector or split times. It is therefore is left to the individual implementation to decide the best approach for its application.

Data files

Sampled data is provided in binary files within the data directory of the archive. Data files must have a filename that corresponds to its channel identifier and carry the extension .bin.

The contents of the data file is consecutive 32-bit (single precision) (IEEE-754)[ieee754] floating point numbers, one for each data sample.

For example, a channel that sampled the consecutive values 1.0 2.0 3.0 4.0 would result the data file 0x000003F8 0x00000040 0x00004040 0x00008040.

Time files

If a channel does not specify a sample interval then it is expected to provide a corresponding binary file that contains the times at which each data sample was recorded. This file must also have a filename that corresponds to its channel identifier but carry the extension .tms.

The contents of the times file is consecutive 32-bit unsigned integer numbers, representing the time offset in milliseconds (from the beginning of the session) that the sample was recorded.

Appendix A: Common units of measurements

The following table provides common units of measurements and their abbreviations. For the purposes of interoperability, a standard abbreviation for a given unit should be used. Additionally, where possible, channels should be specified using the International System of Units (SI Units).

Quantity Name Abbreviation
angle degrees deg
acceleration feet per second squared ft/s2
acceleration gravity g
acceleration metres per second squared m/s2
angle radians rad
angular velocity degrees per second deg/s
angular velocity revolutions per minute rpm
angular velocity revolutions per second rps
angular velocity kilorevolutions per minute krev/min
angular velocity radians per second rad/s
consumption kilometres per litre km/l
consumption metres per cubic metre m/m3
consumption miles per US gallon usgal/mi
current amps amp
current milliamps mamp
current microamperes miamp
electronic resistance ohm ohm
energy calorie cal
energy kilocalorie kcal
energy joule j
energy kilowatt hour kw/h
energy foot-poundal ft-lb
force kilogram force kgf
force pound force lbf
force newtons n
force tonne force tonforce
frequency hertz Hz
frequency kilohetz KHz
length kilometre km
length metre m
length centimetre cm
length millimetres mm
length feet ft
length inches in
length mile mi
mass kilogram kg
mass gram gr
mass milligram mg
mass pounds lb
mass tonnes ton
mass US tonnes uston
power calorie cal/sec
power foot-poundals per second ft-lb/s
power horsepower hp
power kilowatt kw
pressure bar bar
pressure millibar mbar
pressure inches of mercury in/hg
pressure pascals pa
presure pounds per square inch psi
proportion percent %
proportion parts per million p/mill
proportion parts per one p/one
temperature centigrade c
temperature fahrenheit f
temperature kelvin k
time hours hour
time minutes min
time seconds sec
time milliseconds msec
time microseconds misec
torque kilogram force metre kgfm
torque newton meter nm
velocity kilometres per hour kph
velocity miles per hour mph
velocity metres per second m/s
velocity feet per second ft/sec
velocity metres per second m/sec
voltage kilovolt kvlt
voltage millivolt mvlt
voltage microvolt mivlt
voltage volts v
volume litre l
volume cubic metre m3
volume gallon gal
volume US gallon usgal
other gear gear

Appendix B: Extensibility

It is possible to extend the OpenMotorsport format using private XML namespaces.

For instance, consider a vendor that wants to include a calibration field within a channel element. This can be achieved using the following.

<?xml version="1.0"?>
<openmotorsport xmlns="http://66laps.org/ns/openmotorsport-1.0"
        xmlns:myvendor="http://myvendor.com/ns/channels-1.0">
  <!-- metadata -->
  <!-- markers -->

  <channels>
    <channel id="0" units="mph" interval="10">
      <name>Speed</name>
      <description>Vehicle speed from FL wheelspeed sensor.</description>
      <myvendor:configuration_field value="1.0" />
    </channel>
  </channels>
</openmotorsport>

Furthermore, additional assets (such as track maps or math definitions) can also be stored within the archive.

Appendix C: Reference implementations

The following libraries implement the OpenMotorsport specification.

  • Python (Apache License Version 2.0)

Appendix D: Version history

Date Version Description
10/09/2010 1.0.2 Introduces a duration element in metadata for the total sampling time (aids processing incomplete laps).
23/08/2010 1.0.1 There is now a common time unit (milliseconds). This is standard for sampling intervals, markers and sample times. This allows theoretical channels sampling at 1KHz.
17/08/2010 1.0 Initial release.

Appendix E: License

OpenMotorsport (Martin Galpin) is licensed under a Creative Commons Attribution 3.0 Unported License.

Creative Commons Attribution 3.0 Unported License