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.

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

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

11
private const val TAG = "Navigation"
12

13
fun 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:

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

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

12
fun 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

36
private 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

47
fun 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:

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

12
private const val TAG = "Guidance"
13

14
fun 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:

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

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

12
fun 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

54
fun 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:

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

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

11
fun 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

34
fun 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

Driving with a route