Developer

Driving with a route

Request Access

Driving with a route

The GuidanceManager provides navigation guidance during active trips. It delivers turn-by-turn instructions and lane guidance to help drivers navigate their routes.

Starting navigation

Before observing guidance information, start navigation on a planned trip:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.trip.TripManager
3import com.tomtom.automotive.integration.client.api.trip.startnavigation.StartNavigationCallback
4import com.tomtom.automotive.integration.client.api.trip.startnavigation.StartNavigationFailure
5import com.tomtom.automotive.integration.client.api.trip.startnavigation.StartNavigationParameters
6import com.tomtom.automotive.integration.client.api.trip.startnavigation.StartNavigationResponse
7import com.tomtom.automotive.integration.client.common.Callback
8import com.tomtom.automotive.integration.client.common.Result
9import com.tomtom.automotive.integration.client.common.SdkReleasable
10

11private const val TAG = "Navigation"
12

13fun startNavigation(tripManager: TripManager, tripId: String) {
14    tripManager.startNavigation(
15        StartNavigationParameters(tripId),
16        object : StartNavigationCallback {
17            override fun onNavigatedTrip(response: Result<StartNavigationResponse, StartNavigationFailure>) {
18                when (response) {
19                    is Result.Success -> {
20                        val trip = response.value.navigatedTrip
21                        Log.d(TAG, "Navigation started for trip: ${trip.id}")
22                    }
23                    is Result.Failure -> {
24                        Log.e(TAG, "Failed to start navigation: ${response.failure}")
25                    }
26                }
27            }
28            
29            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
30                Log.e(TAG, "Navigation unavailable: ${reason.devMessage}")
31            }
32        }
33    )
34}

Observing next instruction

Subscribe to receive updates about the next maneuver:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.guidance.GuidanceManager
3import com.tomtom.automotive.integration.client.api.guidance.observenextinstruction.InstructionInfo
4import com.tomtom.automotive.integration.client.api.guidance.observenextinstruction.NextInstructionListener
5import com.tomtom.automotive.integration.client.api.model.guidance.InstructionInformation
6import com.tomtom.automotive.integration.client.common.Callback
7import com.tomtom.automotive.integration.client.common.SdkReleasable
8

9private const val TAG = "Guidance"
10private var observeNextInstructionReleasable: SdkReleasable? = null
11

12fun observeNextInstruction(guidanceManager: GuidanceManager) {
13    observeNextInstructionReleasable = guidanceManager.observeNextInstruction(
14        object : NextInstructionListener {
15            override fun onNextInstructionChange(instructionInfo: InstructionInfo) {
16                val instruction = instructionInfo.instruction
17                if (instruction != null) {
18                    val distance = instruction.distanceToNextInstruction
19                    val info = instruction.instruction
20                    Log.d(TAG, "Next instruction in ${distance.meters}m: ${getInstructionDescription(info)}")
21                    
22                    // Get road shields if available
23                    info.getRoadShields()?.forEach { shield ->
24                        Log.d(TAG, "Road shield: ${shield.roadNumber}")
25                    }
26                }
27            }
28            
29            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
30                Log.e(TAG, "Instruction updates unavailable: ${reason.devMessage}")
31            }
32        }
33    )
34}
35

36private fun getInstructionDescription(info: InstructionInformation): String {
37    return when (info) {
38        is InstructionInformation.TurnInstruction -> "Turn ${info.direction}"
39        is InstructionInformation.ForkInstruction -> "Fork ${info.direction}"
40        is InstructionInformation.RoundaboutInstruction -> "Roundabout exit ${info.roundabout.exitNumber}"
41        is InstructionInformation.ExitHighwayInstruction -> "Exit highway ${info.direction}"
42        is InstructionInformation.DestinationArrivalInstruction -> "Arrive at destination"
43        else -> info.toString()
44    }
45}
46

47fun unObserveNextInstruction() {
48    observeNextInstructionReleasable?.release()
49    observeNextInstructionReleasable = null
50}

Instruction types

The InstructionInformation sealed interface has the following implementations:

  • TurnInstruction - Turn at a road junction
  • RoundaboutInstruction - Enter and navigate a roundabout
  • ExitRoundaboutInstruction - Exit a roundabout
  • ForkInstruction - Fork in a bifurcation
  • FollowRoadInstruction - Continue following the current road
  • MergeInstruction - Merge onto highway/expressway
  • ExitHighwayInstruction - Take a highway exit
  • SwitchHighwayInstruction - Switch highways via exit ramp
  • TollgateInstruction - Approaching toll booth or ETC terminal
  • DestinationArrivalInstruction - Arrival at destination
  • WaypointArrivalInstruction - Arrival at waypoint
  • DepartureInstruction - Starting point of trip
  • BorderCrossingInstruction - Crossing international border
  • EntryAutoTransportInstruction - Enter vehicle transport (ferry, car train)
  • ExitAutoTransportInstruction - Exit vehicle transport
  • EnterCarpoolLaneInstruction - Enter carpool/HOV lane
  • ExitCarpoolLaneInstruction - Exit carpool/HOV lane

Fetching road shield assets

Road shields can be displayed as drawable resources:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.asset.AssetManager
3import com.tomtom.automotive.integration.client.api.asset.getdrawable.GetDrawableCallback
4import com.tomtom.automotive.integration.client.api.asset.getdrawable.GetDrawableFailure
5import com.tomtom.automotive.integration.client.api.asset.getdrawable.GetDrawableParameters
6import com.tomtom.automotive.integration.client.api.asset.getdrawable.GetDrawableResponse
7import com.tomtom.automotive.integration.client.api.model.drawable.Density
8import com.tomtom.automotive.integration.client.api.model.guidance.RoadShield
9import com.tomtom.automotive.integration.client.common.Callback
10import com.tomtom.automotive.integration.client.common.Result
11

12private const val TAG = "Guidance"
13

14fun fetchRoadShieldAsset(assetManager: AssetManager, roadShield: RoadShield) {
15    val drawableHandle = roadShield.getDrawableHandle(Density(2f))
16    
17    assetManager.getDrawable(
18        GetDrawableParameters(drawableHandle),
19        object : GetDrawableCallback {
20            override fun onResult(result: Result<GetDrawableResponse, GetDrawableFailure>) {
21                when (result) {
22                    is Result.Success -> {
23                        val drawableResource = result.value.drawable
24                        Log.d(TAG, "Road shield fetched: $drawableResource")
25                    }
26                    is Result.Failure -> {
27                        Log.e(TAG, "Failed to fetch road shield: ${result.failure}")
28                    }
29                }
30            }
31            
32            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
33                Log.e(TAG, "Asset manager unavailable: ${reason.devMessage}")
34            }
35        }
36    )
37}

Audio announcements

The Instruction object includes an audioAnnouncementPhase field that indicates the timing phase of the audio guidance:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.guidance.GuidanceManager
3import com.tomtom.automotive.integration.client.api.guidance.observenextinstruction.InstructionInfo
4import com.tomtom.automotive.integration.client.api.guidance.observenextinstruction.NextInstructionListener
5import com.tomtom.automotive.integration.client.api.model.guidance.AudioAnnouncementPhase
6import com.tomtom.automotive.integration.client.common.Callback
7import com.tomtom.automotive.integration.client.common.SdkReleasable
8

9private const val TAG = "Guidance"
10private var observeAudioReleasable: SdkReleasable? = null
11

12fun observeAudioAnnouncements(guidanceManager: GuidanceManager) {
13    observeAudioReleasable = guidanceManager.observeNextInstruction(
14        object : NextInstructionListener {
15            override fun onNextInstructionChange(instructionInfo: InstructionInfo) {
16                val instruction = instructionInfo.instruction
17                if (instruction != null) {
18                    val phase = instruction.audioAnnouncementPhase
19                    when (phase) {
20                        AudioAnnouncementPhase.FOLLOW -> {
21                            Log.d(TAG, "Audio: Follow instruction")
22                            // Play follow announcement
23                        }
24                        AudioAnnouncementPhase.FAR_AWAY -> {
25                            Log.d(TAG, "Audio: Far away announcement")
26                            // Play far away announcement
27                        }
28                        AudioAnnouncementPhase.EARLY -> {
29                            Log.d(TAG, "Audio: Early announcement")
30                            // Play early announcement
31                        }
32                        AudioAnnouncementPhase.MAIN -> {
33                            Log.d(TAG, "Audio: Main announcement")
34                            // Play main announcement
35                        }
36                        AudioAnnouncementPhase.CONFIRMATION -> {
37                            Log.d(TAG, "Audio: Confirmation announcement")
38                            // Play confirmation announcement
39                        }
40                        AudioAnnouncementPhase.UNHANDLED, null -> {
41                            Log.d(TAG, "Audio: No announcement phase")
42                        }
43                    }
44                }
45            }
46            
47            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
48                Log.e(TAG, "Audio announcements unavailable: ${reason.devMessage}")
49            }
50        }
51    )
52}
53

54fun unObserveAudioAnnouncements() {
55    observeAudioReleasable?.release()
56    observeAudioReleasable = null
57}

Audio announcement phases

The AudioAnnouncementPhase enum represents different timing phases for audio guidance:

  • FOLLOW - Announcement at any distance beyond far away
  • FAR_AWAY - Earliest announcement about upcoming maneuver
  • EARLY - Prepare for upcoming maneuver
  • MAIN - Short time before the maneuver
  • CONFIRMATION - At the time of the maneuver itself

Lane guidance

Lane guidance helps drivers choose the correct lane for upcoming maneuvers:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.guidance.GuidanceManager
3import com.tomtom.automotive.integration.client.api.guidance.observenextlaneguidance.LaneGuidanceInfo
4import com.tomtom.automotive.integration.client.api.guidance.observenextlaneguidance.NextLaneGuidanceListener
5import com.tomtom.automotive.integration.client.common.Callback
6import com.tomtom.automotive.integration.client.common.SdkReleasable
7

8private const val TAG = "Guidance"
9private var observeNextLaneGuidanceReleasable: SdkReleasable? = null
10

11fun observeNextLaneGuidance(guidanceManager: GuidanceManager) {
12    observeNextLaneGuidanceReleasable = guidanceManager.observeNextLaneGuidance(
13        object : NextLaneGuidanceListener {
14            override fun onNextLaneGuidanceChange(laneGuidanceInfo: LaneGuidanceInfo) {
15                val lanes = laneGuidanceInfo.lanes
16                Log.d(TAG, "Lane guidance: ${lanes.size} lanes")
17                
18                lanes.forEachIndexed { index, lane ->
19                    lane.laneDirections.forEach { direction ->
20                        val marking = direction.laneMarking
21                        val shouldFollow = direction.hasToBeFollowed
22                        Log.d(TAG, "Lane $index: $marking (follow: $shouldFollow)")
23                    }
24                }
25            }
26            
27            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
28                Log.e(TAG, "Lane guidance unavailable: ${reason.devMessage}")
29            }
30        }
31    )
32}
33

34fun unObserveNextLaneGuidance() {
35    observeNextLaneGuidanceReleasable?.release()
36    observeNextLaneGuidanceReleasable = null
37}

Lane marking types

The LaneMarking enum represents the direction arrow or marking for each lane:

  • STRAIGHT
  • SLIGHT_RIGHT
  • RIGHT
  • SHARP_RIGHT
  • RIGHT_U_TURN
  • SLIGHT_LEFT
  • LEFT
  • SHARP_LEFT
  • LEFT_U_TURN