Thanks, Steve for the feedback on the API.
>From what I understand the problems you are trying to convey are thus:
1) The current API has some inconsistencies and/or awkwardness
2) The current API is not flexible enough to allow for the various
vendor specific configurations
And you propose solving these issues by changing the API so each
signal is essentially a word cloud of attributes, some defined by a
standard and some defined as vendor-specific.
Is this a correct interpretation of your question?
I don't think it is awkward in any way to have zone be an attribute of
the object. I consider zone to be a physical location in the vehicle
and an attribute of the signal similar to how coordinates (ie
lat/long) are an attribute of a point of interest. This is not an
uncommon pattern.
set() does not have a zone argument. That is true and it does make it
somewhat inconsistent with the other method calls. However, it would
be redundant if it were to have a zone argument. Assuming we change
set() so it is consistent with the other methods, usage would look
something like this:
var hvac = vehicle.get("HVAC", Zone.LeftFront);
hvac.targetTemperature = 20;
console.log("hvac zone is: " + hvac.zone); // "9" which corresponds to
Zone.LeftFront
vehicle.set("HVAC", hvac, Zone.LeftFront);
In this case both hvac object have the zone AND there is a zone
argument. Redundant. But it could get even more awkward. What if I
did this:
var hvac = vehicle.get("HVAC", Zone.LeftFront);
hvac.targetTemperature = 20;
vehicle.set("HVAC", hvac, Zone.RightFront);
Now hvac.zone and the zone argument are different. Which one will the API use?
Flexibility: As it is today the API allows for a lot of flexibility.
Remember, zone is just an Integer. While we have defined some common
zones, there's nothing stopping an OEM from using any unused integer
to represent something vendor-specific. The problem will always be
that the application writer won't necessarily know how to handle
vendor-specific things without having to refer to vendor-specific
documentation. This problem is not solved in the current or your
suggested approach. Consider the following in your approach with
regard to "primary" and "secondary" accelerometers. Let's assume that
the standard only defines one accelerometer. Let's assume the OEM
uses the "primary" accelerometer on the vehicle to implement that API.
How does the vendor represent the second in the current
implementation?
He could create a custom property called "AcclerationSecondary". He
could also zone the existing "Acceleration" property. For
Accelerometers at each wheel, he would zone them for Zone::FrontRight,
Zone::FrontLeft, Zone::RearRight and Zone::RearLeft.
Let's consider the following use-case and how it would be solved in
the current vs your proposed solution.
Application developer wants to display acceleration information to the
user regardless of how many accelerometers there are.
Current implementation:
var zoneList = vehicle.listZones("Acceleration");
for(var i=0; i< zoneList.length; i++)
{
var accel = vehicle.get("Acceleration", zoneList[i]);
$("#accelUL").append("<li>" + "acceration X: " + accel.x + "</li>");
}
Proposed change:
function findObjects(objName)
{
var items = [];
var supportedList = vehicle.supported();
for(var i=0; i < supportedList.length; i++)
{
var tags = supportedList[i].tags;
for(var n=0; n < tags.length; n++)
{
if(tags[n] == objName)
items.push(supportedList[i]);
}
}
return items;
}
var accelList = findObjects("Acceleration")
for(var i=0; i< accelList.length; i++)
{
var accel = vehicle.get(accelList[i].uid);
$("#accelUL").append("<li>" + "acceration X: " + accel.value.x + "</li>");
}
We can already see, unless we have a findObjects equivalent to
listZones in the API, the application developer is going to have to
write a lot of code. The situation gets worse if he wants to a
specific element in a specific zone. Consider the following use-case:
Application running in the rear left seat wants to display his seat
controls for his zone.
Current implementation:
/// Not currently implemented:
var zone = tizen.application.whatIsMyCurrentZone();
var mySeat = vehicle.get("Seat", zone);
mySeat.recline = 20;
vehicle.set("Seat", mySeat);
Proposed implementation:
function magicMapper(listOfAttributes)
{
/// API doesn't exist:
var zones = vehicle.possibleZones(); ///returns a list like:
["Left", "Front", "Rear", ...]
var supported = vehicle.supported();
/// We want attributes in *just* our list and *none* in the other
possible zones
var attributesWeDontWant = [];
for(var i=0; i<zones.length; i++)
{
/// do some magic to get the attributesWeDontWant
}
var theItem;
for(var i=0; i<supported.length; i++)
{
/// do some magic to make sure the supported item has what we
want and nothing we don't want.
/// for example we want where listOfAttribues = ["left", "front"]
we don't want to return an item for ["left", "front", "secondary",
"or", "other", "vendor", "overloaded", "attribute"].
theItem = weFoundIt;
}
return theItem;
}
var attributes = tizen.application.whatIsMyCurrentZone(); // returns a
list like ["rear", "left"]
attributes.push("seat");
attributes.push("recline");
var mySeat = magicMapper(zone);
vehicle.set(mySeat.uid, { "value" : 20 });
As we can see again without an API to map attributes, applications
developers are left writing lots of difficult, excessive and
problematic code.
These are two generic use cases. Do you have a specific use-case
which you think the current API is awkward and your proposed API would
be less awkward and can you provide the use-case with code examples
for both the current and proposed API?
This was an incredibly long response that's about to get longer. I'm
not sure changing the API now would be meaningful in light that the
w3c API is probably going to be the one we will be moving towards.
It's almost as if this argument should be had over there instead of
here. The W3C business group editors (which I am one) will have a
API-style proposal hopefully by the end of next week. I suggest
taking a look at that API and suggesting changes there. I can share
with you if you don't want to watch the github repo[1] or public
mailing list.
BR,
Kevron
[1] - https://github.com/w3c/automotive-bg
On Wed, Dec 11, 2013 at 1:12 PM, Gerken, Stephen
<[email protected]> wrote:
> Hi all,
>
> I've been asked to note some observations here for discussion, in regards
> the tizen.vehicle api exposed into the Tizen 3 wrt. Please cross-reference
> TIVI-2294.
>
> The AMB WRT plugin portion of wrt-plugins-ivi exports the vehicle namespace
> into Javascript as tizen.vehicle. Within this namespace, the plugin makes
> available the following API functions:
>
> supported()
> listZones(string Name)
> get(string Name, optional number Zone)
> set(string Name, optional object containing Value and Zone, optional
> callback Error)
> subscribe(string Name, optional callback Success, optional number Zone)
> getHistory(string Name, optional number Zone, optional time Begin, optional
> time End, optional callback Success, optional callback Error)
>
> The function supported() returns an array of strings representing valid
> names. The function get() accepts one valid name, and optionally a zone,
> returning vehicle data in a result tuple of the general form
> {valueName:x,sequence:y,time:z}. This set of functions is intended to be
> used to in Javascript for a WRT widget to retrieve arbitrary vehicle data,
> in the sense that a WRT widget is to use this API to retrieve data of a type
> not necessarily known to the AMB maintainer at compile time.
>
> There is some awkwardness in the separation of Name and Zone, in that both
> must be present to uniquely identify a datum of interest; in database terms,
> Name and Zone are components of a multi-field key. There is also some
> additional oddness in the manner in which Zone is implemented; in get(), the
> zone is provided as a parameter, while in set(), the zone is provided as a
> field of an object. Instead of having an API with multi-field keys, in which
> the multiple fields occur in different parameters and in different formats
> from call to call, it would be preferable to use a system having a
> single-field key.
>
> The Zone field is implemented around the assumption that it is advisable, or
> even possible, for the plugin maintainer to determine the segmentation of
> all vehicular data areas industry-wide. The existing implementation requires
> the AMB maintainer to define a matrix to accommodate all possible zones for
> all possible vehicles, which in turn mandates that all possible
> OEM-proprietary zones are included in GPL-licensed source code. This
> approach then requires the OEM plugin designer to assign every signal to
> some node of the AMB matrix of zones.
>
> While a certain Front/Middle/Back, Left/Center/Right segmentation is natural
> and obvious to web programmers familiar with such terms, those terms in no
> way capture the divisions of sensor categories in current vehicles. For
> example, accelerometry sensors subdivide into linear/rotational,
> x-axis/y-axis/z-axis, and primary/secondary. They may also subdivide into
> front-left, front-right, rear-left, and rear-right, if a vehicle has an
> independent accelerometry sensor set at each wheel. An AMB maintainer may
> not know whether or not any such vehicle exists; but any such lack of
> knowledge does not preclude the existence of such a vehicle. It is not
> advisable for Tizen to limit the segmentation of vehicle sensor classes to
> only those subdivisions of which any given maintainer is aware.
>
> Meanwhile, at the HMI level, a Javascript writer can only write explicit
> code the handle each independent case. Code written to handle such explicit
> cases frequently proves to be brittle when exposed to situations for which
> it was not explicitly designed.
>
> So overall, except for the omission of an unsubscribe() call, and issues of
> the assignment of signals into zones for use with a non-vehicle-specific
> HMI, and the requirement that all zone information from all OEMs be built
> into GPL-licensed source code, the API would work for circumstances in which
> the vehicle is completely known prior to AMB compilation. The resulting
> Javascript code will be complex, awkward to port across multiple vehicles,
> and use coding styles that are believed to produce buggy implementations.
> This situation is not believed ideal.
>
> A preferred approach alters the supported() function, with minor changes to
> set() and get(), minor simplification of subscribe() and getHistory(),
> addition of unsubscribe(), and removal of listZones(). The resulting API is
> more generalized. It absolves AMB from having any specific knowledge about
> how the signals passed through it relate to physical locations in the
> vehicle, while still allowing OEM plugins and HMI interfaces to communicate
> about zone-like locations via either a common, standards-based structure, or
> an OEM-specific proprietary structure, or both within the same vehicle.
>
> This preferred approach would be for the call to supported() to return
> objects, each object containing a unique identifier (UID) to be used in
> later calls, and a set of attributes or properties sufficient to
> individually describe a specific vehicle datum. In common popular parlance,
> each object would have a UUID and a tag cloud. For example, a vehicle
> accelerometer list, as a partial return from supported(), might be:
> [{uid:“00000001”,tags:[”Accelerometry”,”directionOfTravel”,”linear”,”primary”]},
>
> {uid:“00000002”,tags:[”Accelerometry”,”directionOfTravel”,”linear”,”secondary”]},
> {uid:“00000003”,tags:[”Accelerometry”,”roll”,”rotational”,”primary”]},
> {uid:“00000004”,tags:[”Accelerometry”,”pitch”,”rotational”,”primary”]}]
>
> The text nature of tags allow for field extension of the API by OEMs without
> requiring a fork and recompilation of AMB. From the standpoint of AMB
> passing data between sources and sinks, the tag cloud is a single text
> string (or array) originating in a source and delivered to a sink. AMB does
> not need to know or care that the tag cloud has any particular internal
> structure. AMB only needs to know that a message provided by a source has
> two text fields, one called uid and the other called tags.
>
> Using non-vendor-specific UIDs as primary keys into each vehicle datum
> simplifies the API in actual use, while using a flexible, text-based tag
> cloud approach allows a vehicle to communicate its actual sensor set from
> its AMB CAN plugins to the HMI independently of the knowledge level of the
> AMB maintainer. With this approach, the API function set consists of:
>
> supported() returns array [{uid:, tags:[]},{uid:, tags:[]},{uid:,
> tags:[]},...]
>
> get(string UID), returns {value:, status:, sequence:, time:}
>
> set(string UID, object {value}) returns boolean
>
> subscribe(string UID, callback Success) returns handle
> unsubscribe(handle returned from subscribe) returns boolean
> getHistory(string UID, time Begin, time End, callback Success, callback
> Error) returns undefined
>
> An appropriately chartered open standards committee would create a tag
> dictionary defining SI-based data formats to be exported to the HMI, and
> defining a set of location tags which collectively span, or form a basis
> for, the largest practical metric space in terms of different
> data-independent axes on which vehicle sensor signals may be described. As
> an example of the former, an open standards definition of the tag
> “Accelerometry” might state that an “Accelerometry” defines a data format,
> for which the data value is a signed integer in the range -4000 to +4000
> inclusive, representing an acceleration in centimeters per second squared.
> As an example of the latter, an open standards definition of the tag
> “secondary” might state that “secondary” refers to a sensor which is a
> backup to a primary sensor.
>
> An OEM working with this API would create an AMB CAN plugin, which would
> extract CAN signals from appropriate offsets within CAN frames as known to
> that OEM, apply the appropriate linear transformation of CAN data to conform
> to the relevant open standards data type, apply tags as appropriate to
> uniquely describe the CAN signal, and apply any UID which is unique within
> the vehicle. The OEM's use of open standards tags and data formats would
> maximize that OEM's ability to interface its data with any HMI also
> developed to the open standard tag set. An OEM needing customization of
> either data format, or location, not covered by the open standard, would be
> able to incorporate such customization into its AMB CAN plugin without
> needing to alter AMB itself. Such customization could complement and coexist
> with open standards tags.
>
> An HMI interacting with this API would begin by calling
> tizen.vehicle.supported(), and receiving an array of all objects available
> from registered sources. The HMI would search the tags of returned objects
> to determine which objects represent vehicle data of interest to the HMI. An
> HMI which parses object tag clouds for open standard tags would be maximally
> interoperable with multiple OEMs, but an HMI would not be restricted to
> parsing only open standard tags. If an HMI developer had knowledge of
> OEM-specific tags, the HMI could search for those tags as well, and modify
> its display according to that OEM-specific knowledge. Following HMI
> isolation of those objects with relevant tags, the HMI would extract the UID
> from each such object and use that UID in subsequent interactions with the
> API. Since the UIDs are discovered by the HMI at runtime, an OEM may alter,
> add, or remove UIDs in its AMB CAN plugin at any compilation thereof without
> affecting the operation of any subsequently connecting HMI. The ability of
> any OEM to add proprietary tags allows the API to operate at a dual level,
> in which the open standard tag set supports a common API, while each OEM
> retains the ability to extend an OEM-specific API not subject to outside
> disclosure.
>
> Sample pseudocode for a straightforward setting operation in the HMI would
> resemble:
>
> var allItems = tizen.vehicle.supported();
> var hvacItem = myTagFilter( allItems, [“HVAC”, “Temperature”, “Left”,
> “Front”, “Seat”] );
> var success = tizen.vehicle.set( hvacItem.uid,{value:22});
>
> A similar, but not necessarily identical, possible operation is:
>
> var allItems = tizen.vehicle.supported();
> var hvacItem = myTagFilter( allItems, [“HVAC”, “Temperature”, “Driver”,
> “Seat”] );
> var success = tizen.vehicle.set( hvacItem.uid,{value:22});
>
> The above example would locate the driver's seat correctly whether used in a
> right-hand-drive or in a left-hand-driver vehicle, while the earlier example
> would locate a specific seat positionally. In different circumstances,
> either may be desirable.
>
> As industry adopts the API, OEMs may propose specific tags to be considered
> for addition into the open standard without needing to alter AMB itself.
> This removal of zone-like information from AMB greatly reduces the
> maintenance burden on AMB, and frees industry from a dependency on AMB
> patches. This better enables Tizen to reach its stated goals, as presented
> in conference presentations in San Francisco and in Edinburgh, of moving
> away from past patterns of rigid, proprietary solutions and towards flexible
> frameworks within which solutions can be reused, leading to more
> cost-effective solutions coming to market in more reasonable timeframes.
>
>
> Thanks,
>
> Steve Gerken
> -------------------
> Linux Developer
> MSX, as broker for Jaguar Land Rover
>
> One World Trade Center, 121 SW Salmon Street, 11th Floor, Portland, Oregon,
> 97204
> Email: [email protected]
>
> _______________________________________________
> IVI mailing list
> [email protected]
> https://lists.tizen.org/listinfo/ivi
>
_______________________________________________
IVI mailing list
[email protected]
https://lists.tizen.org/listinfo/ivi
