Updated geolocation and navigation design document

12 Nov 2015

Hi Andre,

Replies inline. I’ve trimmed a few of the parts of the e-mail which we
agree on.

On Tue, 2016-01-26 at 13:03 +0000, Barkowski Andre (CM-CI1/PRM1) wrote:
> 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.

That is correct. I guess when I’ve been saying ‘POI service’ or ‘POI
system’ from the point of view of an application which is consuming POI
data (such as the navigation UI, or another application which needs to
display POIs), I would consider the ‘POI service/system’ to be the set
of all applications which are providing POIs over peer-to-peer
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.

Yes, although the metadata is limited to a description for the location
and what type of point it is (start, waypoint, waypoint which is for
routing only and isn’t a destination, final destination).

> 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.

Noted — I will include this in the next update to the document.

> 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.

OK. I think this fits with my proposed design and the Points of
Interest design as they currently stand, although I should clarify
things.

The route list API continues to provide only the list of roads to take
(i.e. the geometry of the route) as I described in my previous e-mail.

Applications which provide POIs query this API to find out the current
route, as described in the fourth paragraph of
https://wiki.apertis.org/Points_of_interest#Recommendations.

The navigation UI uses interface discovery to find applications which
provide POI data. It then queries them (via peer-to-peer connections)
for general and specific POIs, as described in the POI design.

The logic for working out what POIs to send to the navigation UI lies
within each application. The navigation UI does no filtering based on
content (though for security reasons it might want to apply some rate
limiting to prevent DoS attacks). It simply displays all the POIs it
receives.

It might be possible for an application to add metadata to a POI it
sends to the navigation UI to say ‘please add this POI as a waypoint’,
in which case the navigation UI could prompt the user about it (or add
the destination anyway, or ignore it — this policy is up to the
navigation UI developer). If the POI is added as a waypoint in the
route, the SDK route list API would signal an update to the route,
which would be received by the navigation UI and all applications
providing POIs to it. This would allow for the coupon use case — if a
restaurant gets added as a waypoint, the coupon application could start
emitting a POI for using coupons there.

If another application wants to display the same map view as the
navigation UI, showing the route and POIs on it, it has to make the
same API calls as the navigation UI: a call to the SDK route list API
to get the route; and interface discovery followed by peer-to-peer
retrieval of POIs from other applications.

So, in short, the ‘augmented route list’ is provided by a combination
of the route list API and the POI system (i.e. retrieving POIs from
other applications using peer-to-peer connections).

I hope that makes sense?

Philip

> -----Ursprüngliche Nachricht-----
> Von: Philip Withnall [mailto:philip.withnall@collabora.co.uk]
> Gesendet: Montag, 25. Januar 2016 15:56
> An: Barkowski Andre (CM-CI1/PRM1) <Andre.Barkowski@de.bosch.com>; dev
> el@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.o
> rg
> > /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.aperti
> s.
> 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@collabora.co.uk]
> > Gesendet: Mittwoch, 20. Januar 2016 16:57
> > An: Barkowski Andre (CM-CI1/PRM1) <Andre.Barkowski@de.bosch.com>;
> dev
> > el@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_inter
> es
> 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

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

Barkowski Andre (CM-CI1/PRM1)

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

Simon McVittie

Barkowski Andre (CM-CI1/PRM1)

Philip Withnall

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

Simon McVittie

Barkowski Andre (CM-CI1/PRM1)

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

Philip Withnall

Barkowski Andre (CM-CI1/PRM1)

tags

participants (3)