[Devel] Updated geolocation and navigation design document

[Philip Withnall]

Hi Andre,

Sorry for the delay in replying. Here are some responses, plus a few
more questions I have come up with while updating the document in
response to your feedback.

I am part-way through updating the document, and will continue to work
on it while awaiting your response, although I will not be able to
finalise the updated design until then.

As I can foresee replies to this e-mail getting quite long, please feel
free to delete paragraphs from it which have been addressed and which
you have no further comments on!

On Thu, 2015-11-19 at 12:42 +0000, Barkowski Andre (CM-CI1/PRM1) wrote:
> Hi Philip,
> 
> enclosed my feedback to the proposal. I focus on the section "use-
> cases", because later on it would result in repeating similar things
> (changes in Usecase lead to changes in requirements etc). With that,
> my feedback for chapter 5 onwards becomes somehow partial only. 
> 
> 
> General
> - we do not focus on releasing a build-in (OS) navi functionality,
> but exclusively going via connected backends, located in cloud, in
> apps, or in automotive domain (via a wrapping app). If we have
> established a design for that, it will be appropriate for a build-in
> Apertis OS solution, too. We only have to select one and to ship it
> as "build-in" App (as defined by Applications document)

I understand — and thank you for the separate e-mail which clarifies
this. I have amended the introduction of the document to restrict the
scope to what you suggest, and am going through and reworking the use
cases and requirements accordingly.

> LBS:
> - add UseCase (or a reference in some way): to set a (intermediate)
> destination (via scheme mechanism) which we do have already
> separately covered in our wiki (add a reference)

I have adapted the 'navigating via waypoints' use case to cover this.

> - add UseCase (or a reference in some way): to "imprint a tour"
> consisting of a set of coordinates (via an extended version of the
> scheme mechanism) 

A use case where an LBS application launches the navigation application
with a destination and multiple waypoints (using the URI scheme
mechanism for launching the navigation application)?

I believe this would be a more complex case of the use case above, or
am I misunderstanding?

> - add UseCase: to share/subscribe (updated) route-information 

As I've noted below, I cannot think of a use case where an LBS
application could usefully use that information, which is not already
implementable using the geolocation or geocoding APIs. Could you give
an example of the use case you have in mind?

> - add Usecase: for the requirement 5.29, e.g. that there is a country
> App, providing traffic rules valid for each country state, and
> provides a notification to the driver at point in time of crossing a
> country's frontier.

Added.

> - add UseCase: to add something into a route list (e.g. restaurants
> along the route from restaurant app) and this based on own interest
> of the user, specified in this app (e.g. via favorites) and under
> control of User by enabling this participation via settings.

Do you mean automatically? What is the user's participation in this use
case: are they specifically interacting with a restaurant app and ask
it to book them into a restaurant and add it as a navigation waypoint;
or do they just want to see nearby restaurants highlighted on the map
as they travel through an area?

I have a use case in the updated document which covers a restaurant
application adding a waypoint into the current navigation route, if the
user explicitly requests it (for example, by making a booking at the
restaurant). Does that cover what you mean?

> - add UseCase: for map-widget (with temporary integrated POI data)
> its integrated data sources (position, destination, route, etc) 

What is the use case for this? i.e. In what application context do you
imagine this widget being used? I have been trying to think of an LBS
application use case for exposing destination and waypoint information,
and cannot think of one.

> - add UseCase: for map-widget own responsibility in regard to
> look&feel of embedding the widget, of embedded additional data, its
> interaction on selection events, and the overall functionality 

Can you clarify this please? Do you mean that the map widget should
always have the same appearance, regardless of which application it is
embedded in?

> - add  UseCase: to explain a SDK service provided for LBS Apps to ask
> for input of a location which gets transformed to a geo-positon used
> for backend-server. "Type ahead search and completion for addresses"
> an optional extension / future feature

This (which is a description of reverse geocoding; please correct me if
I've misinterpreted) is covered by the 'viewing an address on the map'
use case, which I have reworded to apply to LBS applications rather
than the navigation application.

> NAVI:
> - add UseCase: which describes the installation / exchange of a Navi
> App, and with that the Technology/Backend used can be exchanged

Added.

> - add Usecase (or a reference in some way) : which shows the relation
> to sensor&Actuator API of a Navi App (e.g. use of vehicle speed or
> gyro / accelerometer data). Add a reference to this document

Added as 'navigation- and sensor-driven refinement of geolocation'.

> - add UseCase: which shows that a majority of Navi related
> configurations and parameter are (moved) into the App-internal scope
> (e.g. ambiguity resolution, routing parameter/preferences,
> handling/selection of alternative routes, consideration of traffic
> info, etc), instead of exposing them to external (SDK) API (similar
> like call-handling is a phone internal sequence, w/o coverage at SDK-
> API)

I have added a non-use-case for this.

> - add UseCase: explains how a Navi App can produce data for other
> (LBS) Apps  (becomes a backend replacement / a data server for SDK-
> API)

I believe this is covered already by the 'automotive backend' use case,
which considers the navigation application and automotive backend to be
fairly tightly coupled from the point of view of providing backend
services for the SDK APIs.

> - add UseCase (or a reference in some way): to handover/import POIs
> (e.g. Traffic information) which we do have already separately
> covered in our wiki (add a reference). Via that usecase one can also
> explain, how a user is able to select data sources to be used by a
> Navi App by loading the one of interest from Store (out of various
> alternative sources for traffic information)

I have made sure there is a cross-reference to the POI design from the
'POI data' non-use-case section. I believe selecting POI sources for
the navigation application should be internal to the navigation
application. For other APIs (such as POI feeding into geocoding), I
have updated the use cases to mention that the user should be able to
disable it on an application-by-application basis.

> Specific
> - 3.2.1 the sentence "functionality may be exposed directly by the
> backend and used by applications using specific APIs on the backend".
> To be honest, I would love to go for some SDK-APIs also for this
> extension. We can "tag" them as "product specific", but maybe
> something similar will be provided from other backends too. To having
> a "normalization" layer in-between is also beneficial from backwards
> compatibility point of view. If we have direct dependencies to App,
> we run short in compatibility tests. 

The point of this use case was that such backend-specific APIs expose
functionality which is //not// covered in the SDK API — if it were
covered in the SDK API, they would not be backend-specific APIs! I will
amend the document to clarify that the SDK APIs can be extended in
future if it seems appropriate to standardise some functionality from
multiple backends which was previously only available as backend-
specific APIs.

> - 3.5 sounds for me its a Navi-App internal feature and uses the app-
> internal User preferences for route calculation. 

Dropped.

> - 3.6. from my point of view it’s a valid use-case, but to be honest
> I do not see the specific topic which influences the requirements and
> API proposal for the scope of this document. For me it is similar
> like a Media Player app continues to render music if another App
> takes foreground focus.

The motivation for this use case was to ensure that routing is
implemented as an agent and application, rather than purely as an
application (which would stop being able to output audio if suspended
or moved to the background).

However, that's a navigation-application-internal feature, so I have
dropped the use case.

> - 3.7. sounds for me like a Navi-App internal feature
> - 3.8. sounds for me like a Navi-App internal feature

These use cases motivate geocoding APIs, and would be useful in an LBS
context. I will rephrase them to be in an LBS context, rather than a
navigation context.

> - 3.9 change the scenario from "Navi" to "LBS" app. But to be honest,
> this is not a first priority goal. This is very special for "address
> input", but since the SDK-API is for general purpose, one do not
> really know If the user types in a "address" or a "POI name". So
> "Eiffel Tower" is maybe not a valid address (in the meaning of city,
> street etc.), but it describes a location. Text-ahead search is maybe
> very challenging for that. This extended scope is very challenging
> for offline solution, because the database will increase to a
> significant size. This lead to online cloud based solution, which may
> have issues with availability or performance. However, lets keep the
> use case and see how far we come. 

Agreed. I will rephrase the use case to be LBS-only, and re-evaluate
the implementation suggestion to see how feasible it is.

> -  3.10 sounds for me like a Navi-App internal feature. However maybe
> a good example for stuff covered App internally including handling of
> preferences, user interaction for selections etc.
> - 3.11 & 3.12: can maybe changed to a usecase that an LBS App (e.g.
> Hotel) sets a new (Intermediate) destination. The LBS App sets the
> destination, an app change appears to the running Navi app, and
> within the context of the Navi app the dialog appears how to deal
> with this new destination (set as new, add as waypoint etc.)
> - 3.13 can maybe changed to a LBS App usecase, consuming the
> "estimated time left" information to recommend a restaurant for break

I have repurposed all of these to be LBS-only use cases.

> - 3.14 can maybe hanged to a LBS App usecase, subscribed for a new
> route-info available and updating the POIs (e.g. hazard spots) along
> the (new) route in this list

That's a use case for the POI system; I think the best way to implement
this would be for the navigation application to pull in a new set of
POIs every time it changes the routing (or waypoints or destination).

> - 3.15 can maybe modified to a usecase, where a traffic info App
> _imports_  traffic data to the Navi App. Which one to use is
> configurable from the User via system settings.

I think this is also something to be handled by the POI system, using
the TPEG data exported by traffic data applications. The navigation
application should pull that data in.

> - 3.16 sounds for me like a Navi-App internal feature. Extended infos
> like (speed limits, hazard spots etc to be discussed (if this is
> notification is independently provided via some notification API, or
> if this gets merged into a turn-by-turn direction info. So far I
> would expect the first

Dropped.

> - 3.17 may can be changed to LBS App, consuming it. However, we can
> also keep this in a sense, that a Navi app can replace the backend
> and produce road info for the SDK-API.

I have dropped this one, because I cannot think of a use case where an
LBS application would need to know road information.

> 3.18 from my point of view it’s a valid use-case, but to be honest I
> do not see the specific topic which influences the requirements and
> API proposal for the scope of this document. For me it is similar
> like a last User-Mode.
> 3.19 sounds for me like a Navi-App internal feature

Dropped. I have tried to think of use cases for where an LBS
application might need to be notified of the navigation destination
(and when it changes), but I can't think of any use cases which aren't
already handled by using geolocation or geofencing.

> 3.22 also a valid use-case, 3rd party navi apps has to use some
> system info APIs 

But third-party navigation applications are likely to come with their
own locale database, and all they need to be able to use that is the
vehicle's location, which they get from the geolocation API. I cannot
think of other use cases for exposing locale information to LBS
applications which are not served by the geolocation API, so I have
dropped this use case.

> 3.23 the part "The system must continue to provide an estimated
> vehicle location to apps, with suitably increasing error bounds"
> should be limited to what is feasible w/o a full blown navigation map
> (including its local street data). 
> All other parts, including dead reckoning should be left for 3.25.
> (an installed navigation App, consuming sensor / actuator data (e.g.
> vehicle speed and others), performs a map matching based on its own
> street data to process a dead reckoning and "provide" the more
> accurate location information for publishing to SDK-API (e.g.
> geoclue). 

Changed.

> 3.24. sounds for me like a Navi-App internal feature. From an App
> centric point of view, the usual use case would be that the user
> opens the "address-book" App, enter the name of their friend, and he
> will use the friend's address for navigation and by setting it as new
> destination an app-change to the navigation App appears.

That is a valid use case, but is now essentially identical to one of
the other use cases I have in the document (setting the navigation
destination from a calendar event), so I will drop this one.

> 3.25. maybe consuming sensor / actuator data (e.g. actual vehicle
> speed, 3D-gyroscope data etc.) should be included in the description
> 3.26. please add a sentence, that a consumer/producer relation can be
> enabled / disabled by the User via System settings 

Done.

> 4.1.: due to this use-case is mentioned in the section "NON-USE-
> CASE", one can misunderstand that these kind of usecases are not
> covered by our solution. But in fact it is, its only not part of this
> description. It would help to prevent misunderstanding, if these 2
> very different kind of "not in scope" could differentiated more
> clearly.

Good point. I have added an introduction to §4 to clarify that these
are non-use-cases //for this particular design//, and may be legitimate
use cases for other designs.

> 4.3. to be honest, looks like I do not understand the Use-case. We
> would like to have a libchamplain map widget loading map tiles from
> backend providing OSM street data. 

I was told that the automotive domain would definitely not be storing
2D map tiles for libchamplain, so they would not be sent over the
inter-domain communication link; this non-use-case documents that fact.

I think we are in agreement: libchamplain’s map tiles will be loaded
from a backend (in the CE domain) which provides OSM data.

> In regard to the chapter 5 Requirements, I am already very fine. This
> situation ("gap" in UseCases but "fitment" of requirements) forces me
> to think about it and to start the chat on mailing list. However,
> please find enclosed the remaining feedback to chapter 5 -
> requirements 
> 
> 5.5. from my point of the, the part (via points) for "routing API" is
> not needed. For me it is App internal. Initiating a route sets a new
> destination (via the already described scheme mechanism). Then an
> app-Change appears to the navigation App, receiving the new request
> and then the handling of the new destination  (in case a tour is
> already running, asking for if it shall be added as a waypoint or
> canceling the current tour) takes place, and also the routing
> parameters (like include traffic info, routing parameters like
> fast/short etc, selection of one out of alternative routes, etc).
> Beside that use-case, we should also provide a mechanism to "imprint"
> a tour into a navigation. This will be done "restricting" the freedom
> of the navigation app based on providing waypoints in addition to the
> destination location. Lets see this as an extension of our scheme
> mechanisms, not only carrying one coordinate but a set of it. The
> navigation App has to handles this as a one request, and adding this
> into its current tour like describes before for a single coordinate.
>  However, the resulting exposed "route-list-info" needs to cover
> waypoints. 
> So maybe it makes sense to distinguish between a "routing API" to set
> a destination (initiate a route calculation) and the "route-list
> info" to share and update details on the path.

I see. I have reworded that requirement and the following one to be
navigation-application-centric.

> 5.11. support of various vehicle types sounds for me like a Navi-App
> internal feature. We can even have different Apps serving best for a
> particular vehicle type.  In addition, change of vehicle
> characteristics (being a car or a truck) is not a primary use-case
> for us, because so far we are fixed build in. So even if the
> characteristics change over products groups, its more or less fixed
> for one installation. Maybe we do have some dynamics via the sensor /
> actuator API, like trailer connected etc.(but also vehicle dimensions
> like height, width, maximum speed, etc)
> 5.12 sounds for me like a Navi-App internal feature

I have dropped both of these.

> 5.13 exposed SDK-APIs providing TTS capabilities should be offered
> for Navi Apps to be used for their generated turn-by-turn instruction
> (and then with the style of voice of the system), but an App
> developer can decide to use its own engine internally.

I have dropped this, because as you say, it is internal to the
navigation application, which is able to use the SDK TTS API the same
as any other application on the system.

> 5.14. yes, this would be a requirement to App-Developers providing a
> Navi-App. To split our the Guidance part (into an Agent) to enable a
> independent lifecycle of this executable.

Similarly, I have dropped this.

> 5.15. for me, the mentioned requirements belongs to libchamplain. And
> in regard to the question (vector or raster), lets start what is
> available e.g. raster maps and lets see what we need to enhance over
> time (e.g. use of vector maps). This is somehow a detailed feature
> roadmap discussion about the specific scope of the map-widget, so let
> me left it out for this feedback 

That answers the open question, thank you.

> 5.16. please adopt the usecase mentioned (for LBS-Apps, instead of
> address Entry Navi destination input). We can also think about to
> embed this deeper into the keyboard. Similar like we support "forms",
> there could be a prepared one for covering the whole usecase for an
> App-developer.

Done.

> 5.17. for LBS-Apps, from my point of view this is more a lib-
> champlain feature. But maybe I am wrong.

libchamplain can give the latitude and longitude of a location on the
map, but this requirement is about the forward geocoding API to convert
that (latitude, longitude) pair into a postal address.

> 5.18. please keep in mind how to embed this into the keyboard. We
> have already features like "suggestions", "history" etc in scope of
> the keyboard.

I have added a sentence to mention that.

> 5.19. sounds for me like a Navi-App internal feature. This is also in
> some overlap with  5.5. - where waypoints are also mentioned.
> 5.20. sounds for me like a Navi-App internal feature. This is also in
> some overlap with 5.11., because vehicle types could be handled to
> some degree also as a parameter for routing algorithm. 
> 5.21. sounds for me like a Navi-App internal feature

Removed.

> 5.22. please change the use case mentioned to an LBS one (embedding a
> map view into the App screen) and adding service specific additional
> information (like animated weather map overlays within a weather map,
> route proposal from tour guides, or hotel from a hotel app)
> However, for me this is some kind of feature discussion for the map
> widget. Today we use libchamplain, is supports some features, others
> will follow. Today its 2D. We can think about if the API (from
> libchamplain) is well already, should be enhanced or if we should use
> a separate one for 3D. This can also be a roadmap discussion, when we
> enhance what.

The use case which motivated the requirement for a 3D map was
implementing a navigation application, but since that use case has been
removed, I don't think there is now a motivation for a 3D map API, so I
will drop this requirement. There might be individual applications
which would benefit from a 3D map, but I think a 2D map (i.e.
libchamplain) caters for 90% of all mapping use cases in LBS
applications, so it would be unnecessary effort to provide a 3D map API
in the SDK.

> 5.31. sounds for me like a Navi-App internal feature. But the Nav App
> can /dead-reckoning/ provide data (position with higher accuracy) -
> in the sense of exchanging the backend - to via the SDK-API to other
> Apps
> 5.32. same like 5.31

I have updated the wording in these to correspond to the requirements.

> 5.35. if I am right, then the mechanisms behind the transport of POI
> streams is the pipe approach already discussed in separately. Please
> bring this into relation to it. We had already some discussion in
> that regard at the point of time discussing the pipe mechanism. In an
> app-centric approach Business logic / policies belongs to the App who
> deals with the source. It is one bundle, covering HMI, logic,
> protocols etc. With that we leave it to the "provider" app (and its
> internal configuration done by the user via its HMI and preferences)
> to provide a reasonable amount of data. However, this freedom shall
> not lead to vulnerabilities, so malfunctional apps or attackers
> taking over a installed app, causing a deny of service attack needs
> to be handled well. With that we have to detect and terminate this
> kind of connections, but from my point of view this is easily
> possible by the consumer app by simple stopping consuming / closing
> the pipe. 

Yes, a lot of these considerations belong in the POI design, but I will
try and cross-reference to that design more clearly from the
Geolocation and Navigation design.

> Maybe we can collect all this Nav-App related requirements (like 5.5,
> 5.19, 5.11, 5.20, 5.12, 5.13, 5.14, 5.20, 5.21, etc) into one common
> (sub) chapter. Its maybe worth to keep & collect them to take care
> that a 3rd party, interesting in proving its solution to Apertis, get
> a better understanding what integration can be done / is expected.
> Please reflect if this would provide a benefit, and if so what should
> be addressed in this chapter.

Good suggestion. I have written a brief new chapter on this.

> Following some comments in regard to section 6 - existing solutions
> - please add a Reflection of what Genivi is doing

Added as section 6.8.

> - 6.5.4. from my point of view, NavIt could be an App-internal
> dependency for someone interested in create a nav App based on it. So
> it is worth to refer to it under the section Gnome, but from my point
> of view more in relation to an App then the Apertis System / OS.

Reworded slightly to reflect this.

> - 6.7. same like for Navit, NavServer can be used to create a Nav-
> App, but in contrast of an OSS solution it is a commercial one. Since
> the App Developer will align his solution accordant to the SDK-APIs
> available, from my point of view we can reflect as a second step if
> available solutions can fit to the defined SDK-APIs of the system
> instead of vice versa. 

Reworded slightly to reflect this.

> Following some comments in regard to section 7 - approach
> - 7.3. no, that’s not the way to go. For the use cases - which are
> pretty the same like the ones for 2D - and which focus on
> independence for LBS Apps to embed their content in a prepared map-
> view as also this map-view into the overall scene with full autonomy
> in regard to look&feel (clutter animations) -  as also in regard to
> reflect seamless transitions between 2D and 3D, we have to reflect
> which kind of framework does provide this freedom. We can reflect if
> libchamplain could/should be extended, we can discuss if
> opensceengraph provides a feasible framework for it or something on
> top, how do we get a clutter actor our of it and how can we influence
> the embedded POI animations etc. However, since this is not an urgent
> topic, if there is no immediate approach visible, we can put it onto
> the roadmap for later work.

Indeed, this part of the design can be removed as the use cases and
requirements which motivated it have been removed. I will condense the
design back down to a 2D map view (i.e. libchamplain), with navigation
applications implementing their own 3D view internally.

> - 7.6 please adopt it to a setup, where it gets realized as App,
> maybe even as "build-in" App if we like to deploy a prepared
> solution.

Yes, I will rework this section substantially.

> - 7.9. good to have a OSS solution. However, I would like to
> understand how this would fit in case we are interested to use a
> google service (as a variant)

OK, I will add in a Google geocoding option as a variant. My initial
thoughts are that this would become a backend for the same geocode-glib 
API, using the Google Maps Geocoding API. However, I will investigate
it further before writing up my recommendations in the design.

I will also add an alternative design for the address completion
component, using the Google Places API.

Are there any other alternative designs you want to be considered?

Philip

> -----Ursprüngliche Nachricht-----
> Von: Devel [mailto:devel-bounces at lists.apertis.org] Im Auftrag von
> Philip Withnall
> Gesendet: Donnerstag, 12. November 2015 17:40
> An: devel at lists.apertis.org
> Betreff: [Devel] Updated geolocation and navigation design document
> 
> Hi all,
> 
> Please find attached version 0.2.1 of the geolocation and navigation
> design document. This version incorporates feedback about swappable
> backends and the ability to back any of the APIs by an implementation
> in the automotive domain.
> 
> I have uploaded this version to the wiki as a draft. Further feedback
> is welcome and will be incorporated as normal.
> 
> https://wiki.apertis.org/File:Apertis-geolocation-navigation-design-0
> .2
> .1.pdf
> 
> Thanks,
> Philip
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 213 bytes
Desc: This is a digitally signed message part
URL: <http://lists.apertis.org/pipermail/devel/attachments/20151126/d3750609/attachment-0001.sig>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 5445 bytes
Desc: not available
URL: <http://lists.apertis.org/pipermail/devel/attachments/20151126/d3750609/attachment-0001.bin>