[Devel] Updated geolocation and navigation design document

[Barkowski Andre (CM-CI1/PRM1)]

Hi Philip,

let me focus in this email on the "route_list" vs "central POI service"

if I understood you right, than
• the "central POI service" is a reference to the existing https://wiki.apertis.org/Points_of_interest
There a no changes suggesting to that design, nor copying parts of it into a new design.
That’s fine for me.  

However, my understanding of https://wiki.apertis.org/Points_of_interest design is, that only the control flow runs via a central SDK service, but if allowed it establishes a private point-to-point channel (pipe) between producer App and consumer App (w/o any SDK service inbetween anymore). With that, the content itself (the POIs) are untouched form the so called "central POI service", the POIs are neither stored/cached, nor distributed by them. With that, the "SDK-Service" (central POI service) does _not_ return points of interest like restaurants, filling stations and tourist attractions. As also there is no capability to define filters in that request, since in an app-centric approach the policies are belonging to the Source/Producer App. The SDK service itself only establishes private point to point connections.

• Route list: a list of objects which describe the route for a navigation, i.e. the roads to take; this might include alternative routes; it _does_ include Point objects like intermediate destinations on the route

so there are point type objects already included in that structure as also attributes/metadata for each object for further details. 

Please note, that the navigation "route-list" is something different than the navigation "guidance". The guidance focus on detailed description of turns ahead, the route-list has a different focus - it describes the complete trip. So that’s 2 APIs and different structures/objects. I would recommend to adopt the document accordingly.

And what I am talking about now is, that apps shall be able to augment the route list returned by the SDK-API . The route list exposed via the route-list SDK-API for sure gets provided (and updated) by the navigation app (somehow similar like it can do it for the geo-position to geo-clue), but Apps can augment data to it. 

The APIs realizing this capability have second priority for me, but nevertheless I like to cover it right from the beginning  from conceptual point of view.

With "create some functionality" I do mean the samples provided to explain use-cases where Apps consume and augment POIs to the route list:
-  a Weather App may consumes Intermediate Destination Information from Route List to show entries on top of the user stored locations in its UI to inform the User about weather at this places
- a gasoline station app adds a refueling stop into the route list for a location to be reached at a time where the car runs low on fuel
- a restaurant app may uses information of gasoline stations in the route list to add recommended cafeterias into the route list to align the breaks for the driver
- a restaurant app may decides to add restaurant POIs as recommendations into the route list for a location to be reached at a time where a break would be wise
- a installed “coupon” app may add available discounts available at a POI location available in route list.

The major thing is, in an app centric approach, the policies are coupled with the source of the data. Its _not_ the navigation app which orchestrates the other apps - like in a systemic client-server model, what to deliver. This limits the capabilities to fantasy provided by the navigation app developer as also his capabilities and development work. In an app-centric approach its completely vice versa, each app focus on its essential service, a navigation calculates the route. That’s it. And a restaurant app deals the POI, and handles all policies and User Interaction to choose/handle them, even though they may finally gets used to set a new destination or they land in the route list. 

So please take care, that https://wiki.apertis.org/Points_of_interest is following that principle. 

I have enclosed some remaining comments in green

Rgds
Andre



-----Ursprüngliche Nachricht-----
Von: Philip Withnall [mailto:philip.withnall at collabora.co.uk] 
Gesendet: Montag, 25. Januar 2016 15:56
An: Barkowski Andre (CM-CI1/PRM1) <Andre.Barkowski at de.bosch.com>; devel at lists.apertis.org
Betreff: Re: AW: AW: AW: AW: [Devel] Updated geolocation and navigation design document

Hi Andre,

On Fri, 2016-01-22 at 17:16 +0000, Barkowski Andre (CM-CI1/PRM1) wrote:
> Hi Philip,
> I feel we are still not fully on the same page. We closed some gaps
> lately (in regard to the assist-window), but it seems to me that we
> still have a gap in regard to POI handling itself.
> So summarize, let me go one step back and start with
> -       POI service is _not_ equal to route-list.
> I am talking about a route list, you are talking about a central poi
> service.

To check, what do you mean by the terms ‘POI service’ and ‘route list’?

I interpret them as:
 • POI service: an SDK service which returns points of interest like
restaurants, filling stations and tourist attractions
 • Route list: a list of points which describe the plotted route for a
navigation, i.e. the roads to take; this might include alternative
routes; it does not include nearby POIs

Andre: hope this is answered above

> Let me add:
> -       we do _not_ need a central POI service, or vice versa I am
> not aware about a related requirement.

All suggestions I have made about POI handling in the context of the
Geolocation and Navigation document have been references to the
existing https://wiki.apertis.org/Points_of_interest design. I am not
suggesting changes to that design, nor am I suggesting copying parts of
it into this design (or any of the navigation APIs).

Andre: I see.

> We do have the already mentioned 3 Use cases and the mechanisms
> discussed covers the use-cases already perfectly
> 1) for in app UI browsing: libchamlain. We have it, fine.

Yes.

> 2) for app import / handover: Pull mode for various types of content
> – also TPEG based POI data - 
> https://wiki.apertis.org/Points_of_interest
> (For completion there is also a push mode for various types of
> content – so far no need for TPEG support -  https://wiki.apertis.org
> /Data_sharing )
> again, we have it designed already.

Yes.

> 3) now we add the route-list to the SDK-API, where I also ask to
> provide capabilities to add POIs to it (independent from the navi-
> app)

I think this is covered by the SDK navigation route guidance API (§7.6
of version 0.3.1 of the document), if we are using the same meaning for
‘route list’ (see above).

Andre: see above, I think we do need 2 API scopes, one for “route-list” one for “guidance”

> In any case we do need the route list, it has originally nothing to
> do with the POI discussion. Apps shall be able to consume information
> about the current route and to create some functionality. That the
> purpose of the route list essentially.

What do you mean by ‘create some functionality’?

In the design as it stands currently, applications cannot augment the
route list returned by the SDK navigation route guidance API. They can
augment the list of POIs returned by the POI API (https://wiki.apertis.
org/Points_of_interest).

Andre: see above, I do mean things like that 
-  a Weather App may consumes Intermediate Destination Information from Route List to show entries on top of the user stored locations in its UI to inform the User about weather at this places
- a gasoline station app adds a refueling stop into the route list for a location to be reached at a time where the car runs low on fuel
- a restaurant app may uses information of gasoline stations in the route list to add recommended cafeterias into the route list to align the breaks for the driver
- a restaurant app may decides to add restaurant POIs as recommendations into the route list for a location to be reached at a time where a break would be wise
- a installed “coupon” app may add available discounts available at a POI location available in route list.
 

> Based on that scope, I am asking for the additional functionality to
> add Metadata/Content from Apps directly to it, especially POIs. Its
> neither a first priority nor will it dramatically change the design.
> Its simple an add-on. We can even decide to implement it later.

For clarity, which API do you mean by ‘it’?

Andre: I do mean the capability for Apps to augment POIs into the Route-List

> Similar stuff is valid for the guidance & assist window discussion.
> The APIs for the “guidance”  (which is “just another notification
> style API for a dedicated purpose”) as also the assist window (which
> is just another system chrome application where for example the data
> exposed via the guidance notification style SDK-API lands in) are
> optional and don’t have side effects to other SDK-APIs. So we can
> implementation wise realize it in a later step, its not of first
> priority. However, I like to have a common understanding about the
> overall scope early.
> If we provide capabilities to add metadata into an available route-
> list to Apps, other Apps (than the navi app) can add additional
> content/ additional metadata to available content, for example POIs
> into a currently shared route list. Since we have already
> libchamplain and also the Point_of_interest and sharing mechanisms
> design, My focus is on just one more method for that route-list. I am
> _not_ talking about any big thing, especially not about a central POI
> service.
> I would like to propose we serialize the discussion. How about first
> finalizing the solution for the route list, including POIs into it
> from Apps via an SDK API.
> Then reflect, for what a central POI service could be beneficial ?
> I have embedded some comments below in green.

I’ve put a few replies below too.

> -----Ursprüngliche Nachricht-----
> Von: Philip Withnall [mailto:philip.withnall at collabora.co.uk]
> Gesendet: Mittwoch, 20. Januar 2016 16:57
> An: Barkowski Andre (CM-CI1/PRM1) <Andre.Barkowski at de.bosch.com>; dev
> el at lists.apertis.org
> Betreff: Re: AW: AW: AW: [Devel] Updated geolocation and navigation
> design document
> 
> > Please keep also in mind, that the navigation app itself is somehow
> > special in regard to their output. Beside provides some UI to
> control
> > its functions like all the other apps (e.g. media player), the
> “route
> > guidance” information is very special. In addition to a black box
> > build-in solution for the route guidance - like all the smartphone
> > Smartphone solutions realizing today – (on prompt the guidance is
> > only acoustic or an app-change transition to the navigation app
> > appears) we will go a step forward for this driver related
> > information. The guidance will be presented to the user independent
> > of the current App in use in foreground. So you can “leave” the
> navi-
> > app but the guidance shall continue. In fact we influence the
> > internal design by requesting an agent to be provided by the app-
> > developer to deliver these data. And that’s not only an acoustical
> > prompt, its also data which gets finally a visual representation
> > (turn icons, lane information, etc). In this approach via an SDK-
> API
> > the rendering gets done by some system service. Its more like a
> > “notification”/“dialog-box”/“status framework” stuff (please have a
> > look to the running status framework and the relation to assist
> > framework too). So the navigation App provides its data as output
> to
> > some SDK-API. In fact part of this is the route list, which finally
> > land in that guidance dialog. Lets call it assistance window –
> driver
> > related information.
> I see. The way I would recommend doing this in the design is to
> implement the guidance UI separately from the navigation UI. It could
> potentially be part of the same application bundle, or part of a
> different one, or even implemented as part of the system chrome.
> Andre: to be honest, this all is optional. A navi app developer can
> decide to implement the guidance in its local app-bundle scope. Then
> the UI appears within its own App Screen Area.
> However, since it is beneficial (independent from the POI or Assist
> Window Discussion) that the guidance portion is separated from the
> rest of the full-fledge App (because it enables us to handle a
> separated executable with its own lifecycle, which means we can keep
> only that part running in background instead of the Full App) we
> should ask for an Agent for it. The App developer can decide to do so
> or not. So the requirement for isolating the Guidance into an Agent
> is already valid w/o all the discussion about POIs and/or Assist
> Window.
> On top of that we like to also support an assist window solution as
> part of our system. Therefore we will provide a notification style
> similar API for driver related information. Guidance data will be
> covered by it, and if a Navi App developer decided to use this SDK-
> API, the guidance information will land there (but also information
> from route list will land in such an assist window). Similar like
> mentioned above, we like to ask the developer to provide an agent for
> the guidance data. However, the assist window (the UI for the
> guidance) is finally a system chrome element and not deployed with
> the App bundle. It belongs to the OS and gets distributed with it.

OK, we would have to add a separate SDK API for handling guidance
notifications, similar to the existing org.freedesktop.Notifications
API for handling other notifications from applications. I will include
a recommendation for that in the next update to the document.
Andre: agreed

> The guidance UI would take data from the SDK points of interest API,
> and from the SDK navigation route guidance API (§7.6). This would
> allow
> it to render the route (from the guidance API), and points of
> interest
> along the way (from the PoI API).
> The navigation UI (where the driver chooses their destination and
> plans
> the route) may retrieve points of interest from the SDK, or may
> choose
> not to if the developer thinks they will be distracting.
> i.e. The SDK API you are suggesting for the data from the guidance UI
> is effectively the points of interest API plus the navigation route
> guidance API.
> Andre: like said, its not the “points_of_interest” API, its from the
> route-list API.
> > To this route list, other apps can directly add further data. This
> is
> > _not_ forwarded to the navi-app, it does not modify the route list
> > nor does it gets stored by the navi-app. The navi app don’t has any
> > interest in getting and managing it. This data, gets provided by
> the
> > source app to the rout–list and with that finally rendered to the
> > user by some system service (assist window). On the other hand,
> other
> > apps can consume this enriched route list again for their build-in
> > functions and policies. Its all outside the navigation, the navi
> only
> > provides the initial foundation.
> That’s possible due to the split between the navigation UI and the
> guidance UI. The navigation UI can choose to not query for points of
> interest, or can heavily filter the PoI requests it makes.
> Conversely,
> the guidance UI can query for lots of PoIs.
> If other applications want to display something similar to the
> guidance
> UI, they must make the same navigation route guidance API and PoI API
> queries as made by the guidance UI. This should be simple to do, and
> allows each application to further customise the points of interest
> they display.
> Andre:
> to be honest, the use-cases behind that stuff is _not_ that another
> app will do something similar like the guidance UI.

Sorry, when I said “if other applications want to display something
similar to the guidance UI” I meant something more like “if other
applications want to display the current route, or the current route
plus nearby POIs”.

Andre:  I would expect this is build-in behind the scene into libchamplain. So by using libchamplain, Apps get this information already embedded. Similar like they get the current vehicle position (from geoclue) already well embedded into libchamplain. The usecases for Apps to use route list information is the stuff mentioned above. Let me repeat to prevent misunderstanding:
-  a Weather App may consumes Intermediate Destination Information from Route List to show entries on top of the user stored locations in its UI to inform the User about weather at this places
- a gasoline station app adds a refueling stop into the route list for a location to be reached at a time where the car runs low on fuel
- a restaurant app may uses information of gasoline stations in the route list to add recommended cafeterias into the route list to align the breaks for the driver
- a restaurant app may decides to add restaurant POIs as recommendations into the route list for a location to be reached at a time where a break would be wise
- a installed “coupon” app may add available discounts available at a POI location available in route list.


> Other Apps uses information form that API for their essential
> service, e.g. if an App of a weather service does know intermediate
> destinations from the route list, it may decides to show entries on
> top of the stored locations for current destination and intermediate
> destinations (in todays list you have the current positon for example
> as a default, this app could extend that approach depending on stuff
> from the route list).
> Or if a gasoline station app adds a refueling stop into the route
> list for a location to be reached at a time where the car runs low on
> fuel, a restaurant app may uses this information to add recommended
> cafeterias into the route list to align the breaks for the driver.
> Or if a restaurant app decides to add restaurant POIs as
> recommendations into the route list for a location to be reached at a
> time where a break would be wise, a installed “coupon” app may add
> available discounts available at this location. 
> etc.

I don’t think I can fully understand these points without agreeing on
the terminology at the top of the e-mail.
Andre:  ok, hope my comments given where helpful in that regard.

In the current version of the design, these use cases are handled by:
 • The gasoline station application exposes gasoline stations as points
of interest via the POI API (https://wiki.apertis.org/Points_of_interes
t).
 • The restaurant application exposes restaurants as points of interest
via the POI API (https://wiki.apertis.org/Points_of_interest).
 • The navigation application contains the logic to:
  - Detect where in the route the vehicle is likely to need refuelling,
query the POI API (https://wiki.apertis.org/Points_of_interest) for
gasoline stations, and add them to the route.
  - Detect when in the route the driver is likely to need food, query
the POI API (https://wiki.apertis.org/Points_of_interest) for
restaurants, and add them to the route.

I can’t think of a sensible way of handling coupons at the moment. They
don’t really fit into any of the existing APIs.

The design is this way round, rather than allowing the restaurant and
gasoline applications to ‘insert’ recommendations into the route list
because it leaves the navigation application in charge of which
restaurants (for example) are shown. It means the code for determining
when is ‘a good time to stop for food’ is in one place (the navigation
application) rather than many (each restaurant application), each of
which could end up using different definitions of when is ‘a good time
to stop for food’ in order to gain competitive advantage.

Andre: like said above, the design philosophy is an app-centric solution is, to bundle the policy / logic within the provider app. So its not one central intelligence, orchestrating all others, its vice versa all the others are providing things accordant to their implemented logic. Apps can compete in providing the same service with another policy or using another service with a similar policy. The user decides by choosing the App which fits best his needs. And he can do in the smallest granularity, per App . So he is able to adopt the overall solution by making dedicated decisions per source (App). 

(Above, I am using ‘navigation application’ to mean the entire
navigation application bundle, including any UIs, agents, or services
which it provides.)

Philip
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.apertis.org/pipermail/devel/attachments/20160126/ce40cc47/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 6749 bytes
Desc: not available
URL: <http://lists.apertis.org/pipermail/devel/attachments/20160126/ce40cc47/attachment-0001.bin>