APIs: The vehicle module

Webinos API Specifications

1 Jul 2011

Authors

• Simon Isenberg (BMW Forschung & Technik) <Simon.Isenberg@bmw.de>

Abstract

Table of Contents

• 1. Introduction
• 2. Interfaces
  • 2.1. VehicleError
  • 2.2. Address
  • 2.3. VehicleEvent
  • 2.4. LatLng
  • 2.5. POI
  • 2.6. SuccessCallback
  • 2.7. ErrorCallback
  • 2.8. VehicleDataHandler
  • 2.9. VehicleInterface
  • 2.10. Vehicle
  • 2.11. DestinationCallback
  • 2.12. ClimateControlEvent
  • 2.13. ControlEvent
  • 2.14. NavigationEvent
  • 2.15. ParkSensorsEvent
  • 2.16. ShiftEvent
  • 2.17. TripComputerEvent
• 3. Features
• 4. Full WebIDL

Summary of Methods

1. Introduction

2. Interfaces

        interface VehicleError : Error{
                const short ACCESS_DENIED = 1;
                const short NOT_AVAILABLE = 2;
                const short UNKNOWN = 0;
        };

        [NoInterfaceObject]
        interface Address{
                attribute DOMString country;
                attribute DOMString? region;
                attribute DOMString? county;
                attribute DOMString city;
                attribute DOMString street;
                attribute DOMString streetNumber;
                attribute DOMString? premises;
                attribute DOMString additionalInformation;
                attribute DOMString postalCode;
        };

        [NoInterfaceObject]
        interface VehicleEvent : Event{
        
        };

        [NoInterfaceObject]
        interface LatLng{
                attribute double latitude;
                attribute double longitude;
        };

        [NoInterfaceObject]
        interface POI{
                attribute DOMString? name;
                attribute LatLng? position;
                attribute Address address;
        };

        [Callback=FunctionOnly, NoInterfaceObject]
        interface SuccessCallback{
                void onSuccess();
        };

        [Callback=FunctionOnly, NoInterfaceObject]
        interface ErrorCallback{
                void onError(in VehicleError error);
        };

        interface VehicleDataHandler{
                void handleVehicleData(in VehicleEvent data);
        
        };

        [NoInterfaceObject]
        interface VehicleInterface : EventTarget {
                const DOMString FUEL_UNLEADED = "unleaded";
                const DOMString FUEL_PREMIUM = "premium";
                const DOMString FUEL_DIESEL = "diesel";
                const DOMString TRANSMISSION_AUTOMATIC = "automatic";
                const DOMString TRANSMISSION_MANUAL = "manual";         
                readonly attribute DOMString brand;
                readonly attribute DOMString model;
                readonly attribute DOMString year;
                readonly attribute DOMString fuel;
                readonly attribute DOMString transmission;
                void get(DOMString vehicleDataId, VehicleDataHandler handler, in ErrorCallback errorCB);
                void requestGuidance(in SuccessCallback successCallback, in ErrorCallback errorCallback, POI[] destinations);
                void findDestination(DestinationCallback destinationCallback, in ErrorCallback errorCallback, DOMString search);
        };

        [NoInterfaceObject] interface Vehicle {
                readonly attribute VehicleInterface vehicle;
        };

        webinoscore::Webinos implements Vehicle;

        [Callback=FunctionOnly, NoInterfaceObject]
        interface DestinationCallback {
                 void handleResults(in POI[] pois);
        };

        [NoInterfaceObject]
        interface ClimateControlEvent : VehicleEvent{
                const DOMString CLIMATE_ALL = "climate-all";
                const DOMString CLIMATE_DRIVER = "climate-driver";
                const DOMString CLIMATE_PASSENGER_FRONT = "climate-passenger-front";
                const DOMString CLIMATE_PASSENGER_REAR_LEFT = "climate-passenger-rear-left";
                const DOMString CLIMATE_PASSENGER_REAR_RIGHT = "climate-passenger-rear-right";
                readonly attribute DOMString zone;
                readonly attribute unsigned short desiredTemperature; 
                readonly attribute boolean acStatus;
                readonly attribute unsigned short ventLevel;
                readonly attribute boolean ventMode;
                void initClimateControlEvent(boolean bubbles, boolean cancelable, DOMString zone, short desiredTemperature, boolean acStatus, short ventLevel, short ventMode);
        };

 webinos.vehicle.addEventListener("climate", climateHandler, null);
 function climateHandler(data){
                console.log(data.zone + " desired temperature is " + data.desiredTemperature + "° C");                 
        }                               
 

        interface ControlEvent : VehicleEvent{
                const DOMString LIGHTS_FOG_FRONT = "lights-fog-front";
                const DOMString LIGHTS_FOG_REAR = "lights-fog-rear";
                const DOMString LIGHTS_SIGNAL_LEFT = "lights-signal-left";
                const DOMString LIGHTS_SIGNAL_RIGHT = "lights-signal-right";
                const DOMString LIGHTS_SIGNAL_WARN = "lights-signal-warn";      
                const DOMString LIGHTS_PARKING = "lights-parking";
                const DOMString LIGHTS_HIBEAM = "lights-hibeam";
                const DOMString LIGHTS_HEAD = "lights-head";
                const DOMString WHIPER_FRONT_WASH = "whiper-front-wash";
                const DOMString WHIPER_REAR_WASH = "whiper-rear-wash";
                const DOMString WHIPER_AUTOMATIC = "whiper-automatic";
                const DOMString WHIPER_FRONT_ONCE = "whiper-front-once";
                const DOMString WHIPER_REAR_ONCE = "whiper-front-once";
                const DOMString WHIPER_FRONT_LEVEL1 = "whiper-front-level1";
                const DOMString WHIPER_FRONT_LEVEL2 = "whiper-front-level2";
                readonly attribute DOMString conrolId;
                readonly attribute boolean active;
                void initControlEvent(boolean bubbles, boolean cancelable, DOMString controlId, boolean active);
        };

        webinos.vehicle.addEventListener("lights-hibeam", lightHandler, false);
      function lightHandler(cEvent){
                if(cEvent.controlId == "lights-hibeam"){
                        if(cEvent.active == true){
                                console.log("Hibeam turned on");
                        }else{
                                console.log("Hibeam turned off");
                        }
                }
        }
 

        interface NavigationEvent : VehicleEvent{
                const DOMString DESTINATION_REACHED = "destination-reached";
                const DOMString DESTINATION_CHANGED = "destination-changed";
                const DOMString DESTINATION_CANCELLED = "destination-cancelled";        
                
                readonly attribute DOMString type;
                readonly attribute Address address;

                void initNavigationEvent(boolean bubbles, boolean cancelable, DOMString navigationEventId, Address destination);  
        };

        interface ParkSensorsEvent : VehicleEvent{
                const DOMString PARKSENSENSORS_FRONT = "parksensors-front";
                const DOMString PARKSENSENSORS_REAR = "parksensors-rear";
                readonly attribute DOMString position;
                readonly attribute unsigned short left;
                readonly attribute unsigned short midLeft;      
                readonly attribute unsigned short midRigth;
                readonly attribute unsigned short rigth;
                void initParkSensorsEvent(boolean bubbles, boolean cancelable, DOMString position, short left, short midLeft, short midRight, short right);
        };

        webinos.vehicle.addEventListener("parksensor-front", psHandler, false);
        webinos.vehicle.addEventListener("parksensor-rear", psHandler, false);
        function psHandler(psEvent){
                if(psEvent.left == 20){
                        console.log("obstacle on the left in" + psEvent.position + " is close");
                }
        }
 

        interface ShiftEvent : VehicleEvent{
                const DOMString SHIFT = "shift";
                const short GEAR_ONE = 1;
                const short GEAR_TWO = 2;
                const short GEAR_THREE = 3;
                const short GEAR_FOUR = 4;              
                const short GEAR_FIFE = 5;
                const short GEAR_SIX = 6;
                const short GEAR_SEVEN = 7;
                const short GEAR_EIGHT = 8;
                const short GEAR_REVERSE = -1;
                const short GEAR_NEUTRAL = 0;
                const short GEAR_PARKING = -2;          
                readonly attribute short gear;
                void initShiftEvent(boolean bubbles, boolean cancelable, short gear);
        };

 // registering an Event for a Shift
 webinos.vehicle.addEventListener("shift", shiftHandler);
 function shiftHandler(e){
   document.getElementById("info").innerHTML = e.gear;
  webinos.vehicle.removeEventListener("shift", shiftHandler);
 }                              
 

        interface TripComputerEvent : VehicleEvent{
                const DOMString TRIPCOMPUTER = "tripcomputer";
                readonly attribute float averageConsumption1;
                readonly attribute float averageConsumption2;
                readonly attribute float averageSpeed1;
                readonly attribute float averageSpeed2;
                readonly attribute float tripDistance;
                readonly attribute float milage;
                readonly attribute float range;
                void initTripComputerEvent(boolean bubbles, boolean cancelable, float averageConsumption1, float averageConsumption2, float averageSpeed1, float averageSpeed2, float tripDistance, float mileage, float range);
        };

var latestConsumption = 0;
webinos.vehicle.addEventListener("tripcomputer", tripDataHandler, false);
      
function tripDataHandler(data){
        //Calculating, if the fuel efficiency increased, since the last update
        var gap = latestConsumption - data.averageConsumption1;
        if(gap < 0){
            console.log("Thumbs down. You decreased your fuel efficiency");
        } else if (gap > 0){
            console.log("Thumbs up. You increased your fuel efficiency");
        } else {
            console.log("nothing changed");
        }
        latestConsumption = data.averageConsumption1;
      
        if (data.range < 20){
            console.log("You really need " + webinos.vehicle.fuel + "soon.");   
        }
}
 

3. Features

4. Full WebIDL

module vehicle{
        interface VehicleError : Error{
                const short ACCESS_DENIED = 1;
                const short NOT_AVAILABLE = 2;
                const short UNKNOWN = 0;
        };
        [NoInterfaceObject]
        interface Address{
                attribute DOMString country;
                attribute DOMString? region;
                attribute DOMString? county;
                attribute DOMString city;
                attribute DOMString street;
                attribute DOMString streetNumber;
                attribute DOMString? premises;
                attribute DOMString additionalInformation;
                attribute DOMString postalCode;
        };
        
        [NoInterfaceObject]
        interface VehicleEvent : Event{
        
        };
        [NoInterfaceObject]
        interface LatLng{
                attribute double latitude;
                attribute double longitude;
        };
        [NoInterfaceObject]
        interface POI{
                attribute DOMString? name;
                attribute LatLng? position;
                attribute Address address;
        };

        [Callback=FunctionOnly, NoInterfaceObject]
        interface SuccessCallback{
                void onSuccess();
        };
        [Callback=FunctionOnly, NoInterfaceObject]
        interface ErrorCallback{
                void onError(in VehicleError error);
        };
        
        interface VehicleDataHandler{
                void handleVehicleData(in VehicleEvent data);
        
        };
        
        [NoInterfaceObject]
        interface VehicleInterface : EventTarget {
                const DOMString FUEL_UNLEADED = "unleaded";
                const DOMString FUEL_PREMIUM = "premium";
                const DOMString FUEL_DIESEL = "diesel";
                const DOMString TRANSMISSION_AUTOMATIC = "automatic";
                const DOMString TRANSMISSION_MANUAL = "manual";         
                readonly attribute DOMString brand;
                readonly attribute DOMString model;
                readonly attribute DOMString year;
                readonly attribute DOMString fuel;
                readonly attribute DOMString transmission;
                void get(DOMString vehicleDataId, VehicleDataHandler handler, in ErrorCallback errorCB);
                void requestGuidance(in SuccessCallback successCallback, in ErrorCallback errorCallback, POI[] destinations);
                void findDestination(DestinationCallback destinationCallback, in ErrorCallback errorCallback, DOMString search);
        };
        
        [NoInterfaceObject] interface Vehicle {
                readonly attribute VehicleInterface vehicle;
        };
        webinoscore::Webinos implements Vehicle;
        [Callback=FunctionOnly, NoInterfaceObject]
        interface DestinationCallback {
                 void handleResults(in POI[] pois);
        };
        [NoInterfaceObject]
        interface ClimateControlEvent : VehicleEvent{
                const DOMString CLIMATE_ALL = "climate-all";
                const DOMString CLIMATE_DRIVER = "climate-driver";
                const DOMString CLIMATE_PASSENGER_FRONT = "climate-passenger-front";
                const DOMString CLIMATE_PASSENGER_REAR_LEFT = "climate-passenger-rear-left";
                const DOMString CLIMATE_PASSENGER_REAR_RIGHT = "climate-passenger-rear-right";
                readonly attribute DOMString zone;
                readonly attribute unsigned short desiredTemperature; 
                readonly attribute boolean acStatus;
                readonly attribute unsigned short ventLevel;
                readonly attribute boolean ventMode;
                void initClimateControlEvent(boolean bubbles, boolean cancelable, DOMString zone, short desiredTemperature, boolean acStatus, short ventLevel, short ventMode);
        };
        interface ControlEvent : VehicleEvent{
                const DOMString LIGHTS_FOG_FRONT = "lights-fog-front";
                const DOMString LIGHTS_FOG_REAR = "lights-fog-rear";
                const DOMString LIGHTS_SIGNAL_LEFT = "lights-signal-left";
                const DOMString LIGHTS_SIGNAL_RIGHT = "lights-signal-right";
                const DOMString LIGHTS_SIGNAL_WARN = "lights-signal-warn";      
                const DOMString LIGHTS_PARKING = "lights-parking";
                const DOMString LIGHTS_HIBEAM = "lights-hibeam";
                const DOMString LIGHTS_HEAD = "lights-head";
                const DOMString WHIPER_FRONT_WASH = "whiper-front-wash";
                const DOMString WHIPER_REAR_WASH = "whiper-rear-wash";
                const DOMString WHIPER_AUTOMATIC = "whiper-automatic";
                const DOMString WHIPER_FRONT_ONCE = "whiper-front-once";
                const DOMString WHIPER_REAR_ONCE = "whiper-front-once";
                const DOMString WHIPER_FRONT_LEVEL1 = "whiper-front-level1";
                const DOMString WHIPER_FRONT_LEVEL2 = "whiper-front-level2";
                readonly attribute DOMString conrolId;
                readonly attribute boolean active;
                void initControlEvent(boolean bubbles, boolean cancelable, DOMString controlId, boolean active);
        };
        interface NavigationEvent : VehicleEvent{
                const DOMString DESTINATION_REACHED = "destination-reached";
                const DOMString DESTINATION_CHANGED = "destination-changed";
                const DOMString DESTINATION_CANCELLED = "destination-cancelled";        
                
                readonly attribute DOMString type;
                readonly attribute Address address;

                void initNavigationEvent(boolean bubbles, boolean cancelable, DOMString navigationEventId, Address destination);  
        };
        interface ParkSensorsEvent : VehicleEvent{
                const DOMString PARKSENSENSORS_FRONT = "parksensors-front";
                const DOMString PARKSENSENSORS_REAR = "parksensors-rear";
                readonly attribute DOMString position;
                readonly attribute unsigned short left;
                readonly attribute unsigned short midLeft;      
                readonly attribute unsigned short midRigth;
                readonly attribute unsigned short rigth;
                void initParkSensorsEvent(boolean bubbles, boolean cancelable, DOMString position, short left, short midLeft, short midRight, short right);
        };
        interface ShiftEvent : VehicleEvent{
                const DOMString SHIFT = "shift";
                const short GEAR_ONE = 1;
                const short GEAR_TWO = 2;
                const short GEAR_THREE = 3;
                const short GEAR_FOUR = 4;              
                const short GEAR_FIFE = 5;
                const short GEAR_SIX = 6;
                const short GEAR_SEVEN = 7;
                const short GEAR_EIGHT = 8;
                const short GEAR_REVERSE = -1;
                const short GEAR_NEUTRAL = 0;
                const short GEAR_PARKING = -2;          
                readonly attribute short gear;
                void initShiftEvent(boolean bubbles, boolean cancelable, short gear);
        };
        interface TripComputerEvent : VehicleEvent{
                const DOMString TRIPCOMPUTER = "tripcomputer";
                readonly attribute float averageConsumption1;
                readonly attribute float averageConsumption2;
                readonly attribute float averageSpeed1;
                readonly attribute float averageSpeed2;
                readonly attribute float tripDistance;
                readonly attribute float milage;
                readonly attribute float range;
                void initTripComputerEvent(boolean bubbles, boolean cancelable, float averageConsumption1, float averageConsumption2, float averageSpeed1, float averageSpeed2, float tripDistance, float mileage, float range);
        };
};