path: root/api/franca/navigation/navigationcore/Guidance.fidl

// SPDX-License-Identifier: MPL-2.0
// Copyright (C) 2014, PCA Peugeot Citro�n, XS Embedded GmbH, TomTom International B.V., Continental Automotive GmbH, BMW Car IT GmbH,  Alpine Electronics R&D Europe GmbH, AISIN AW CO., LTD.,  Neusoft Technology Solutions GmbH, Jaguar Land Rover Limited, Visteon Corporation, Elektrobit Automotive GmbH
// This Source Code Form is subject to the terms of the
// Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with
// this file, you can obtain one at http://mozilla.org/MPL/2.0/.

package org.genivi.navigation.navigationcore
	
import org.genivi.CommonTypes.* from "../../CommonTypes.fidl"
import org.genivi.navigation.NavigationTypes.* from "../NavigationTypes.fidl"
import org.genivi.navigation.navigationcore.NavigationCoreTypes.* from "./NavigationCoreTypes.fidl"

<**
	@description : Guidance = This interface offers functions that implement the route-guidance functionality of a navigation system
**>

interface Guidance {
	version {
		major 4 
		minor 0
	}

	enumeration Side extends BasicEnum {
		LEFT = 128
		RIGHT = 131
		NOT_AVAILABLE = 2
	}

	enumeration LaneType extends BasicEnum { // Used by laneDirections and directionToFollow (into the UInt32 bitfield)
		LANE_INFO_BITMASK_STRAIGHT		= 1
		LANE_INFO_BITMASK_SLIGHTRIGHT	= 2
		LANE_INFO_BITMASK_RIGHT			= 4
		LANE_INFO_BITMASK_SHARPRIGHT	= 8
		LANE_INFO_BITMASK_RIGHTUTURN	= 16
		LANE_INFO_BITMASK_SLIGHTLEFT	= 32
		LANE_INFO_BITMASK_LEFT			= 64
		LANE_INFO_BITMASK_SHARPLEFT		= 128
		LANE_INFO_BITMASK_LEFTUTURN		= 256
	}
	
	enumeration PromptMode extends BasicEnum { 
		DISABLED_PROMPT					= 65
		AUTOMATIC_PROMPT				= 66
		MANUAL_PROMPT					= 67
	}
	
	enumeration ManeuverPhase extends BasicEnum { 
		CRUISE 				= 80
		MANEUVER_APPEARED 	= 81
		PRE_ADVICE 			= 82
		ADVICE 				= 83
		PASSED 				= 84
	}

	enumeration GuidanceStatus extends BasicEnum { 
		ACTIVE							= 96
		INACTIVE						= 97
	}
	
	enumeration ManeuverType extends BasicEnum { 
		STRAIGHT_ON					= 112
		CROSSROAD					= 113
		ROUNDABOUT					= 114
		HIGHWAY_ENTER				= 115
		HIGHWAY_EXIT				= 116
		FOLLOW_SPECIFIC_LANE		= 117
		DESTINATION					= 118
		WAYPOINT					= 119
		TURN						= 120
		BIFURCATION					= 121
	}
	
	enumeration ManeuverDirection extends BasicEnum { 
		STRAIGHT					    = 127
		LEFT							= 128
		SLIGHT_LEFT						= 129
		HARD_LEFT						= 130
		RIGHT							= 131
		SLIGHT_RIGHT					= 132
		HARD_RIGHT						= 133
		UTURN_RIGHT						= 134
		UTURN_LEFT						= 135
	}
	
	enumeration CalculationMode extends BasicEnum { 
		ALL_MANUAL						= 144
		ALL_AUTOMATIC					= 145
		TRAFFIC_MANUAL					= 146
		OFF_ROUTE_MANUAL				= 147
	}

	enumeration RoadProperty extends BasicEnum { 
		DEFAULT   						= 65534
		TOLL_ROADS   					= 369
	}
	enumeration RouteChangedCause extends BasicEnum { 
		TRAFFIC							= 528
		OFF_ROUTE						= 529
		MANUAL							= 530
	}

	enumeration ManeuverDirectionType extends BasicEnum { 
		DIRECTION					= 576
		EXIT_NUMBER					= 577
		ROAD_FORM					= 578
		LANE_INFO					= 579
	}

	enumeration LaneDivider extends BasicEnum { 
		DIVIDER_UNDEFINED				= 592
		DIVIDER_INTERRUPTEDLONG			= 593
		DIVIDER_INTERRUPTEDSHORT		= 594
		DIVIDER_SOLIDSINGLE				= 595
		DIVIDER_SOLIDDOUBLE				= 596
		DIVIDER_SOLIDINTERRUPTED		= 597
		DIVIDER_INTERRUPTEDSOLID		= 598
	}

	enumeration RoadForm extends BasicEnum {
		ROAD_REGULAR				= 561
		ROAD_HIGHWAY_MOTORWAY		= 562
		ROAD_FERRY					= 563
	}

	enumeration ManeuverDataAttribute extends BasicEnum {
		LENGTH				= 608 //value of type UInt16, when maneuver=ROUNDABOUT, expresses the length of the route segment between the entry to and the exit from the roundabout
		DIRECTION			= 576 //value of type ManeuverDirection
		EXIT_NUMBER			= 577 //when maneuver=ROUNDABOUT, value of type UInt16 that expresses the roundabout exit number, when maneuver=HIGHWAY_EXIT, value of type String that expresses the highway exit number
		ROAD_FORM			= 578 //value of type RoadForm
		LANE_INFO			= 579 //value of type LaneInfo[] 
		COORDINATE			= 613 //value of type Coordinate3D
	}

    union ManeuverDataValue {
	    ManeuverDirection enumValue
	    UInt16 uint16Value
	    String stringValue
	    RoadForm roadFormValue
	    LaneInfo[] laneInfoValue
	    Coordinate3D coordinate3DValue
    }
	
	map ManeuverData {
		ManeuverDataAttribute to ManeuverDataValue
	}	
	
	struct LaneInfo { //Note: To describe the divider on the left side of the left-most lane, use the following entry in LANE_INFO: (laneIndex=0xffffffff,laneDirections=0x00000000,directionToFollow=0x00000000,divider=type)
		UInt32 laneIndex //number of the individual lane. Counting starts from zero, beginning at the left-most lane in the direction of travel (independent of the driving side)
		UInt32 laneDirections //bitfield where each bit corresponds to a certain direction. A 1-bit indicates that the corresponding part of the lane arrow is drawn in the lane information on the street (see the LaneType bitmasks)
		UInt32 directionToFollow //bitfield where each bit corresponds to a certain direction. A 1-bit indicates that the corresponding part of the lane arrow matches the direction of the corresponding maneuver (see the LaneType bitmasks). At most one bit of this bitmask will be set.
		LaneDivider divider //indicates the type of divider between the given lane and the next one to the right, in the direction of travel
	}

	struct WaypointStruct {
		UInt32 waypointOffset //the offset of the way point in meters from the beginning of the route
		UInt32 travelTime //time to reach the waypoint in seconds from the current position
		Int32 direction //direction of the way point in degree relatively to the North. Range [0:360]
		Side side 
		Int16 timeZone //time zone of the way point. It is expressed as the time difference from the UTC in minutes
		Int16 daylightSavingTime //daylight saving time of the way point. It is expressed as the time difference from the UTC in minutes
		Boolean isDestination //if TRUE the way point is the destination
		UInt16 number //number of the next waypoint (related to the waypoint list, first way point index is 0)
	}

	<**
		@description : struct generated for DBus argument GetManeuversList_maneuversListElem6
	**>
	struct ManeuverItem {
		UInt32 offsetOfManeuver
		UInt32 travelTime
		ManeuverDirectionType direction
		ManeuverType maneuver
		ManeuverData maneuverData
	}

	<**
		@description : struct generated for DBus argument GetManeuversList_maneuversList
	**>
	struct Maneuver {
		RoadShield[] roadShieldsAfterManeuver // A road can have zero or more roadshields.
		String countryCodeAfterManeuver // ISO 3166‐1 alpha-3 country code (three-letter upper case).
		String stateCodeAfterManeuver // ISO 3166-2 Subdivision code (e.g., provinces or state) of country (up to three characters). An empty string when absent.
		String roadNumberAfterManeuver
		String roadNameAfterManeuver
		RoadProperty roadPropertyAfterManeuver
		Side drivingSide
		UInt32 offsetOfNextManeuver
		ManeuverItem[] items
	}

	<**
		@description : getVersion = This method returns the API version implemented by the server application
	**>
	method getVersion {
		out {
			Version ^version
		}
	}

	<**
		@description : startGuidance = This method starts the guidance for a given route
		The guidanceStatus will change to ACTIVE
	**>
	method startGuidance {
		in {

			<**
				@description : sessionHandle = Session handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle sessionHandle

			<**
				@description : routeHandle = Route handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle routeHandle
		}
	}

	<**
		@description : stopGuidance = This method stops the guidance
		The guidanceStatus will change to INACTIVE
	**>
	method stopGuidance {
		in {

			<**
				@description : sessionHandle = Session handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle sessionHandle
		}
	}

	<**
		@description : setVoiceGuidance = This method switch on/off the voice guidance
	**>
	method setVoiceGuidance {
		in {

			<**
				@description : activation of the voice guidance
			**>
			Boolean activate

			<**
				@description : kind of voice (to be defined)
			**>
			String voice
		}
		error {
			OK
			GUIDANCE_ERROR_VOICENOTALLOWED //the voice generation is inactive
		}
	}

	<**
		@description : getGuidanceDetails = This method retrieves guidance information 
	**>
	method getGuidanceDetails {
		out {

			<**
				@description : voiceGuidance = if TRUE voice guidance is active
			**>
			Boolean voiceGuidance

			<**
				@description : vehicleOnTheRoad = if TRUE the vehicle is located on the road network
			**>
			Boolean vehicleOnTheRoad

			<**
				@description : isDestinationReached = if TRUE the destination has been reached
			**>
			Boolean isDestinationReached

			<**
				@description : maneuver = enum(INVALID,CRUISE,MANEUVER_APPEARED,PRE_ADVICE,ADVICE,PASSED, ... )
			**>
			ManeuverPhase maneuver
		}
	}

	<**
		@description : playVoiceManeuver = This method plays or repeats the last voice guidance
	**>
	method playVoiceManeuver {
		error {
			OK
			GUIDANCE_ERROR_VOICENOTALLOWED //the voice generation is inactive
		}
	}

	<**
		@description : getWaypointInformation = This method retrieves the information on the remaining way points of the route. A point can be the final destination as well as a stage defined by the user. The returned waypoints are ordered by their 'number'.
	**>
	method getWaypointInformation {
		in {

			<**
				@description : requestedNumberOfWaypoints = the number of requested waypoints. If 0, all waypoints will be returned.
			**>
			UInt16 requestedNumberOfWaypoints
		}
		out {

			<**
				@description : numberOfWaypoints = the number of retrieved waypoints(NOTE: the number corresponds to the number of elements in the array)
			**>
			UInt16 numberOfWaypoints
			WaypointStruct [] waypointsList
		}
	}

	<**
		@description : This method retrieves the information on the final destination
	**>
	method getDestinationInformation {
		out {

			<**
				@description : offset = offset of the destination in meter from the beginning of the route
			**>
			UInt32 offset

			<**
				@description : travelTime = time to reach the destination in second
			**>
			UInt32 travelTime

			<**
				@description : direction = direction of the destination in degree relatively to the North. Range [0:360]
			**>
			Int32 direction

			<**
				@description : side = enum(LEFT,RIGHT,NOT_AVAILABLE)
			**>
			Side side

			<**
				@description : timeZone = time zone of the destination. It is expressed as the time difference from the UTC in minutes
			**>
			Int16 timeZone

			<**
				@description : daylightSavingTime = daylight saving time of the destination. It is expressed as the time difference from the UTC in minutes
			**>
			Int16 daylightSavingTime
		}
	}

	<**
		@description : getManeuversList = This method retrieves the list of next maneuvers
	**>
	method getManeuversList {
		in {

			<**
				@description : requestedNumberOfManeuvers = the number of requested maneuvers
			**>
			UInt16 requestedNumberOfManeuvers

			<**
				@description : maneuverOffset = the offset of the first maneuver to retrieve
			**>
			UInt32 maneuverOffset
		}
		out {

			<**
				@description : numberOfManeuvers = the number of retrieved maneuvers
			**>
			UInt16 numberOfManeuvers
			
			Maneuver[] maneuversList
		}
		error {
			OK
			GUIDANCE_ERROR_NOMANEUVER //there's no maneuver until the destination
		}
	}

	<**
		@description : setRouteCalculationMode = This method configures the way the navigation application wants the navigation core to behave of reroute trigger
	**>
	method setRouteCalculationMode {
		in {

			<**
				@description : sessionHandle = Session handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle sessionHandle

			<**
				@description : routeCalculationMode = enum(INVALID,ALL_MANUAL,ALL_AUTOMATIC,TRAFFIC_MANUAL,OFF_ROUTE_MANUAL)
			**>
			CalculationMode routeCalculationMode
		}
	}

	<**
		@description : skipNextManeuver = This method allows to jump behind the current maneuver
	**>
	method skipNextManeuver {
		in {

			<**
				@description : sessionHandle = Session handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle sessionHandle
		}
		error {
			OK
			GUIDANCE_ERROR_NOMANEUVER //there's no maneuver until the destination
		}
	}

	<**
		@description : getGuidanceStatus = This method retrieves the guidance status
	**>
	method getGuidanceStatus {
		out {

			<**
				@description : guidanceStatus = enum(INVALID,ACTIVE,INACTIVE)
				ACTIVE means that NavigationCore is providing guidance information
				INACTIVE means that NavigationCore is not providing guidance information
			**>
			GuidanceStatus guidanceStatus

			<**
				@description : routeHandle = Active route handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value. Should be ignored when guidanceStatus=INACTIVE
			**>
			Handle routeHandle
		}
	}

	<**
		@description : setVoiceGuidanceSettings = This method sets the voice guidance settings
	**>
	method setVoiceGuidanceSettings {
		in {

			<**
				@description : mode = enum(INVALID,DISABLED_PROMPT,AUTOMATIC_PROMPT,MANUAL_PROMPT, ... )
				MANUAL_PROMPT means that a client application can ask the NavigationCore to play the voice prompts
				AUTOMATIC_PROMPT means that the voice prompts will be requested by NavigationCore automatically
				DISABLED_PROMPT means that the client application will the voice generator component directly to play the messages (bypassing the NavigationCore)
			**>
			PromptMode promptMode
		}
		error {
			OK
			GUIDANCE_ERROR_VOICENOTALLOWED //the voice generation is inactive
		}
	}

	<**
		@description : getVoiceGuidanceSettings = This method returns the used voice guidance settings
	**>
	method getVoiceGuidanceSettings {
		out {

			<**
				@description : mode = enum(INVALID,DISABLED_PROMPT,AUTOMATIC_PROMPT,MANUAL_PROMPT, ... )
				MANUAL_PROMPT means that a client application can ask the NavigationCore to play the voice prompts
				AUTOMATIC_PROMPT means that the voice prompts will be requested by NavigationCore automatically
				DISABLED_PROMPT means that the client application will the voice generator component directly to play the messages (bypassing the NavigationCore)
			**>
			PromptMode promptMode
		}
	}

	<**
		@description : vehicleLeftTheRoadNetwork = This signal is emitted when the vehicle exits from the road network
	**>
	broadcast vehicleLeftTheRoadNetwork {
	}

        <**
                @description : vehicleReturnedToTheRoadNetwork = This signal is emitted when the vehicle returns to the road network
        **>
        broadcast vehicleReturnedToTheRoadNetwork {
        }

	<**
		@description : guidanceStatusChanged = This signal is emitted when the guidance status changes
	**>
	broadcast guidanceStatusChanged {
		out {

			<**
				@description : guidanceStatus = enum(INVALID,ACTIVE,INACTIVE)
				ACTIVE means that NavigationCore is providing guidance information
				INACTIVE means that NavigationCore is not providing guidance information
			**>
			GuidanceStatus guidanceStatus

			<**
				@description : routeHandle = Active route handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value. Should be ignored when guidanceStatus=INACTIVE.
			**>
			Handle routeHandle
		}
	}

	<**
		@description : waypointReached = This signal is emitted when the destination is reached
	**>
	broadcast waypointReached {
		out {

			<**
				@description : isDestination = flag. TRUE means that the way point is the destination
			**>
			Boolean isDestination
		}
	}

	<**
		@description : This signal is emitted each time a maneuver event is going
	**>
	broadcast maneuverChanged {
		out {

			<**
				@description : maneuver = enum(INVALID,CRUISE,MANEUVER_APPEARED,PRE_ADVICE,ADVICE,PASSED, ... )
			**>
			ManeuverPhase maneuver
		}
	}

	<**
		@description : positionOnRouteChanged = This signal is emitted when the position on the route changes
	**>
	broadcast positionOnRouteChanged {
		out {

			<**
				@description : offsetOnRoute = the current offset on the route in meters from the beginning of the route
			**>
			UInt32 offsetOnRoute
		}
	}

	<**
		@description : vehicleLeftTheRoute = This signal is emitted when the vehicle has left the route
	**>
	broadcast vehicleLeftTheRoute {
	}

	<**
	        @description : vehicleReturnedToTheRoute = This signal is emitted when the vehicle has returned to the route
	**>
	broadcast vehicleReturnedToTheRoute {
	}

	<**
		@description : positionToRouteChanged = This signal is emitted when the vehicle is off-the-road network and either the heading or the distance (or both) to the closest point on the active route changes
	**>
	broadcast positionToRouteChanged {
		out {

			<**
				@description : distance = distance in meters to the closest point on the active route
			**>
			UInt32 distance

			<**
				@description : direction = direction in degrees relatively to the closest point on the active route. Range [0:360]
			**>
			Int32 direction
		}
	}

	<**
		@description : activeRouteChanged = This signal is emitted when the active route changes
	**>
	broadcast activeRouteChanged {
		out {

			<**
				@description : changeCause = enum(INVALID,TRAFFIC,OFF_ROUTE,MANUAL,...)
			**>
			RouteChangedCause changeCause
		}
	}
}