Vehicle Web API style

I've just submitted a pull request with a basic API pattern.  This is
based on a recommendation from another w3c editor (Zoltan Kis from the
SysApps group) with modifications by Justin and myself.

What it is:

Basic API structure.  Here's the basic example:

 var vehicle = navigator.vehicle;

        vehicle.vehicleSpeed.get().then(function(vehicleSpeed) {
          console.log("vehicle speed: " + vehicleSpeed.speed);
        },
        function(error) {
          console.log("There was an error");
        });

        var vehicleSpeedSub =
vehicle.vehicleSpeed.subscribe(function(vehicleSpeed) {
          console.log("vehicle speed changed to: " + vehicleSpeed.speed);
          vehicle.vehicleSpeed.unsubscribe(vehicleSpeedSub);
        });

        var i = vehicle.climateControl.zones.indexOf(Zone.Driver);

        if(i != -1)
        {
          var value = {};
          value["acStatus"] = true;
          vehicle.climateControl.set(value, Zone.Driver).then(function(){
            console.log("successfully set acStatus");
          },
          function(error) {
            console.log("there was an error");
          });
        }

Vehicle is the main interface object.  It has 'n' members that
represent interfaces to specific vehicle data types (ie vehicleSpeed).
 These members can also be "undefined" if they are not supported and
the documentation specifies that.  Applications can discover what is
supported simply by introspecting the Vehicle object:

function listSupported(obj) {
   var propList = "";
   for(var propName in obj) {
      if(typeof(obj[propName]) != "undefined") {
         propList += (propName + ", ");
      }
   }
   return propList;
}

var supported = listSupported(vehicle);

or you can just check before you use:

if(vehicle.vehicleSpeed !== undefined)
  console.log("We support speed!");

For zones I tried to design around the following use-cases:

1) The Seat Position Application running in each zone wants to set
Seat Position.

var myZone = navigator.someAPI.whatIsMyCurrentZone();

vehicle.seat.set({"recline" : 30, myZone }).then(successCb, errorCb);

2) Driver wants to use an Application to activate child lock for his
child in the back seat.

vehicle.door.set({"childLock" : true}, Zone.RearRight).then(...);

3) Driver wants to set the temperature for the front of the car in a
3+ zone vehicle.

for(var zone in vehicle.climateControl.zones)
{
  if(zone & Zone.Front)
    vehicle.climateControl.set({"targetTemperature" : 16}, zone);
}

The zone API is an attempt at balancing flexibility with structure.
It is not so flexible that anything is possible but not too flexible
that developers cannot know where a given data type is located
physically in a vehicle.


What it's not:

It is not a complete API. 99% of the vehicle data types we are working
on are not yet defined.  The idea is Justin and I will add them from
the work done by various members of the group.

If you want to take a look at the spec, you can either clone my fork
(https://github.com/tripzero/automotive-bg) or go to the spec here
https://github.com/tripzero/automotive-bg/blob/master/vehicle_spec.html,
click on the "Raw" button, download the html file and then open it in
a browser.

As for editing the spec, I'm following the pattern that editors should
edit in their own fork and then do a pull request (for example
https://github.com/w3c/automotive-bg/pull/3).  The entire group can
view the change and make comments inline.  If there are no issues, the
editors will then merge the pull request into the mainline tree.

-Kevron

Received on Friday, 20 December 2013 23:25:41 UTC