This specification defines a Vehicle Information API which offers a simple interface to get access to vehicle data. A typical use case of the Vehicle Information is the implementation of a tachometer application that allows view inforomation from the vehicle such as speed, tire pressure, and engine rotation speed (RPMs).

Introduction

The Vehicle Information API provides operations to get access to the vehicle data (henceforth "properties") available from vehicle systems and also to change (write) a number of properties. The API also allows users to request data that has been logged previously.

An example of use is provided below:

        navigator.vehicle.get("EngineSpeed", onsuccess, onerror);
          
        function onsuccess(value) {
                window.console.log(value.EngineSpeed);
        }
        function onerror(e) {
                window.console.error(e.message);
        }
  

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.

Terminology

The EventHandler interface represents a callback used for event handlers as defined in [[!HTML5]].

The concepts queue a task and fire a simple event are defined in [[!HTML5]].

The terms event handler and event handler event types are defined in [[!HTML5]].

Security and privacy considerations

This API must be only exposed to trusted content

Navigator Interface

readonly attribute Vehicle vehicle
The object that exposes the interface to vehicle information services.

Vehicle Information Interface

The Vehicle Infomration interface represents the initial entry point for getting access to the vehicle information services, i.e. Engine Speed and Tire Pressure.

void getSupported ()
Preturns supported properties.
SupportedPropertiesCallback successCallback
function to be called when method has completed successfully
VehiclePropertyErrorCallback errorCallback
this function is called when an error has occured
void get ()
fetch the current value for property. Upon success, the successCallback will be called with the value.
DOMString property
requested property to be retrieved
VehiclePropertyCallback success
function to be called when method has completed successfully
VehiclePropertyErrorCallback errorCallback
this function is called when an error has occured
void set ()
set the property to value. Upon success, the successCallback will be called with the result.
DOMString property
requested property to be retrieved
VehiclePropertyType value
corrisponding value to set
VehiclePropertyCallback success
function to be called when method has completed successfully
VehiclePropertyErrorCallback errorCallback
this function is called when an error has occured
void getHistory ()
get the property in series from startTime to endTime. Upon success, the successCallback will be called with the result.
DOMString property
requested property to be retrieved
Date startTime
beginning time for request
Date endTime
ending time for request
VehiclePropertyListCallback success
function to be called when method has completed successfully
VehiclePropertyErrorCallback errorCallback
this function is called when an error has occured

Steps

The getSupported method when invoked MUST run the following steps:

  1. Make a request to the system to get the vehicle information properties(s) supported by the system.
  2. Create a new array of DOMString for all supported properties in the system.
  3. When the request has been completed:
    1. call successCallback and pass into the function the DOMString array representing the supported properties.
    2. If an error has occured, construct a VehiclePropertyError object and set the message and code appropriatly for the error.

The get method when invoked MUST run the following steps:

  1. Make a request to the system to get the property indicated in the property parameter
  2. If the property is not supported construct a VehiclePropertyError object and set the code members to VehiclePropertyError.PROPERTY_UNAVAILABLE and message member to "Unsupported property".
  3. When the request has been completed:
    1. if successful invoke the successCallback and pass the VehiclePropertyType as the argument.
    2. if there has been an error, construct a VehiclePropertyError object and set the message and code appropriatly for the error.

The set method when invoked MUST run the following steps:

  1. Make a request to the system to set the property indicated in the property parameter to the value indicated in the value parameter.
  2. If the property is not supported construct a VehiclePropertyError object and set the code members to VehiclePropertyError.PROPERTY_UNAVAILABLE and message member to "Unsupported property".
  3. When the request has been completed:
    1. if successful invoke the successCallback and pass the VehiclePropertyType as the argument.
    2. if there has been an error, construct a VehiclePropertyError object and set the message and code appropriatly for the error.

The getHistory method when invoked MUST run the following steps:

  1. Make a request to the system to get the values for the property indicated in the property parameter after the time startTime and after the time endTime.
  2. If the property is not supported construct a VehiclePropertyError object and set the code members to VehiclePropertyError.PROPERTY_UNAVAILABLE and message member to "Unsupported property".
  3. When the request has been completed:
    1. if successful invoke the successCallback and pass the array of VehiclePropertyType as the argument.
    2. if there has been an error, construct a VehiclePropertyError object and set the message and code appropriatly for the error.

VehiclePropertyType Interface

The VehiclePropertyType interface represents the base interface for all vehicle properties.

readonly attribute Date timeStamp;
MUST return the type time at which this property was recieved.

VehiclePropertyError Interface

The VehiclePropertyError interface represents the an error returned by the vehicle information system. manager.

const unsigned short PERMISSION_DENIED = 1
const unsigned short PROPERTY_UNAVAILABLE = 2
const unsigned short TIMEOUT = 3
const unsigned short UNKNOWN = 10
readonly attribute unsigned short code
MUST return error code.
readonly attribute DOMString message
MUST return error message

VehiclePropertyCallback Callback

The VehiclePropertyCallback is called during the navigator.vehicle.get() operation

VehiclePropertyErrorCallback Callback

The VehiclePropertyErrorCallback is called during the navigator.vehicle.get() operation

VehiclePropertyListCallback Callback

The VehiclePropertyListCallback is called during the navigator.vehicle.getHistory() operation

SupportedPropertiesCallback Callback

The SupportedPropertiesCallback is called during the navigator.vehicle.getSupported() operation

VehicleSpeed Interface

The VehicleSpeed interface represents vehicle speed.

readonly attribute unsigned long VehicleSpeed
Must return Vehicle Speed in kilometers per hour.

EngineSpeed Interface

The EngineSpeed interface represents engine speed.

readonly attribute unsigned long EngineSpeed
Must return Engine Speed in rotations per minute.

VehiclePowerMode Interface

The VehiclePowerMode interface represents the current vehidle power mode.

const unsigned short VEHICLEPOWERMODE_OFF = 0
const unsigned short VEHICLEPOWERMODE_ACCESSORY1 = 1
const unsigned short VEHICLEPOWERMODE_ACCESSORY2 = 2
const unsigned short VEHICLEPOWERMODE_RUN = 3
readonly attribute octet VehiclePowerMode
Must return Vehicle Power mode (see VEHICLEPOWERMODE)

TripMeters Interface

The TripMeters interface represents the current trip meters.

attribute sequence unsigned long TripMeters
Must return trip meters. Changing any items in the array will reset the item's value to '0'.

Acceleration Interface

The Acceleration interface represents vehicle acceleration.

readonly attribute unsigned long X
Must return acceleration on the "X" axis as 1/1000 G (gravitational force).
readonly attribute unsigned long Y
Must return acceleration on the "Y" axis as 1/1000 G (gravitational force).
readonly attribute unsigned long Z
Must return acceleration on the "Z" axis as 1/1000 G (gravitational force).

Transmission Interface

The Transmission interface represents the current transmssion gear and mode.

const unsigned short TRANSMISSIONPOSITION_NEUTRAL = 0
const unsigned short TRANSMISSIONPOSITION_FIRST = 1
const unsigned short TRANSMISSIONPOSITION_SECOND = 2
const unsigned short TRANSMISSIONPOSITION_THIRD = 3
const unsigned short TRANSMISSIONPOSITION_FORTH = 4
const unsigned short TRANSMISSIONPOSITION_FIFTH = 5
const unsigned short TRANSMISSIONPOSITION_SIXTH = 6
const unsigned short TRANSMISSIONPOSITION_SEVENTH = 7
const unsigned short TRANSMISSIONPOSITION_EIGHTH = 8
const unsigned short TRANSMISSIONPOSITION_NINTH = 9
const unsigned short TRANSMISSIONPOSITION_TENTH = 10
const unsigned short TRANSMISSIONPOSITION_CVT = 64
const unsigned short TRANSMISSIONPOSITION_REVERSE = 128
const unsigned short TRANSMISSIONPOSITION_PARK = 255
const unsigned short TRANSMISSIONMODE_NORMAL = 0
const unsigned short TRANSMISSIONMODE_SPORT = 1
const unsigned short TRANSMISSIONMODE_ECONOMY = 2
const unsigned short TRANSMISSIONMODE_OEMCUSTOM1 = 3
const unsigned short TRANSMISSIONMODE_OEMCUSTOM2 = 4
readonly attribute octet GearPosition
Must return transmission gear position (see TRANSMISSIONPOSITION)
readonly attribute octet Mode
Must return transmission Mode (see TRANSMISSIONMODE)

CruiseControlStatus Interface

The CruiseControlStatus interface represents cruise control settings.

readonly attribute boolean Activated
Must return whether or not the Cruise Control system is active (true) or inactive (false)
readonly attribute unsigned short Speed
Must return target Cruise Control speed in kilometers per hour (kph)

WheelBrake Interface

The WheelBrake interface represents wheel brake status.

readonly attribute boolean Engaged
Must return Wheel Brake status: Engaged (true) or Disengaged (false)

LightStatus Interface

The LightStatus interface represents exterior light statuses.

readonly attribute boolean Head
Must return headlight status: on (true), off (false)
readonly attribute boolean RightTurn
Must return right turn signal status: on (true), off (false)
readonly attribute boolean LeftTurn
Must return left turn signal status: on (true), off (false)
readonly attribute boolean Brake
Must return Brake light status: on (true), off (false)
readonly attribute boolean Fog
Must return Fog light status: on (true), off (false)
readonly attribute boolean Hazard
Must return Hazard light status: on (true), off (false)
readonly attribute boolean Parking
Must return Parking light status: on (true), off (false)
readonly attribute boolean HighBeam
Must return HighBeam light status: on (true), off (false)

InteriorLightStatus Interface

The InteriorLightStatus interface represents interior light status.

readonly attribute boolean Passenger
Must return passenger interior light status: on (true), off (false)
readonly attribute boolean Driver
Must return Driver interior light status: on (true), off (false)
readonly attribute boolean Center
Must return Center interior light status: on (true), off (false)

Horn Interface

The Horn interface represents horn status.

readonly attribute boolean On
Must return Horn status: On (true) or off (false)

Fuel Interface

The Fuel interface represents vehicle fuel status.

readonly attribute unsigned short Level
Must return fuel level as a percentage of fullness
readonly attribute unsigned short Range
Must return estimated fuel range in kilometers
readonly attribute unsigned short InstantConsumption
Must return instant fuel consumption in milliliters of fuel per second
readonly attribute unsigned short InstantEconomy
Must return instant fuel 'economy' in kilometers per liter of fuel
attribute unsigned short AverageEconomy
Must return average fuel 'economy' in kilometers per liter of fuel since last reset. Setting this to any value should reset the counter to '0'

EngineOil Interface

The EngineOil interface represents engine oil status.

readonly attribute unsigned short Remaining
Must return remaining engine oil as percentage of fullness
readonly attribute long Temperature
Must return Engine Oil Temperature in Celcius
readonly attribute unsigned short Pressure
Must return Engine Oil Pressure in kPa

ExteriorBrightness Interface

The ExteriorBrightness interface represents brightness outside the vehicle.

readonly attribute unsigned long ExteriorBrightness
Must return the brightness outside the vehicle in lux

Temperature Interface

The Temperature interface represents temperature inside and outside the vehicle.

readonly attribute signed short Interior
Must return the temperature of the interior of the vehicle in celcius
readonly attribute signed short Exterior
Must return the temperature of the exterior of the vehicle in celcius

RainSensor Interface

The RainSensor interface represents intensity of rain.

readonly attribute unsigned short RainSensor
Must return level of rain intensity 0: No Rain - 10: Heaviest Rain

WindshieldWiper Interface

The WindshieldWiper interface represents the status of the windshield wiper.

const unsigned short WIPERSPEED_OFF = 0
const unsigned short WIPERSPEED_SLOWEST= 1
const unsigned short WIPERSPEED_FASTEST = 5
const unsigned short WIPERSPEED_AUTO = 10
readonly attribute unsigned short WindshieldWiper
Must return Level of windshield whiper speed (see WIPERSPEED)

DefrostDictionary Dictionary

unsigned short window
window id (see WindowStatus.WINDOWLOCATION)
boolean defrost
indicates whether defrost is active (true) for this window or inactive (false)

HVAC Interface

The HVAC interface to get status and control the vehicle HVAC system.

const unsigned short AIRFLOWDIRECTION_FRONTPANEL = 0
const unsigned short AIRFLOWDIRECTION_FLOORDUCT= 1
const unsigned short AIRFLOWDIRECTION_FRONT = 0x02
const unsigned short AIRFLOWDIRECTION_DEFROSTER = 0x04
attribute unsigned short AirflowDirection
Must return airflow direction. The value represents a bitmask of HVAC.AIRFLOWDIRECTION(s). For example:
        navigator.vehicle.get("HVAC", onsuccess, onerror);
          
        function onsuccess(value) {
            var hvacsettings = value;
            value.AirflowDirection = value.AIRFLOWDIRECTION_FRONT | value.AIRFLOWDIRECTION_DEFROSTER;
            navigator.vehicle.set("HVAC", value, onsetsuccess, onerror);
        }
        function onerror(e) {
            window.console.error(e.message);
        }
        function onsetsuccess() {
            window.console.log("success!");
        }
        
     
attribute unsigned short FanSpeed
Must return speed of the fan (0-7)
attribute unsigned short TargetTemperature
Must return target desired temperature in celcius
attribute boolean AirConditioning
Must return air conditioning on (true) / off (false)
attribute boolean AirRecirculation
Must return air recirculation on (true) / off (false)
attribute boolean Heater
Must return heater on (true) / off (false)
attribute DefrostDictionary Defrost
Must return the defrost status of all windows equiped with defrosters. This will return a dictionary of DefrostDictionary that represents each window and its defrost status
attribute boolean SteeringWheelHeater
ust return air recirculation on (true) / off (false).
attribute boolean SeatHeater
Must return seat heater status: on (true) / off (false)