### Example gradle.properties File

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

An example of how your `gradle.properties` file might look after adding the Mapbox Downloads token.

```text
org.gradle.jvmargs=-Xmx1536M
android.useAndroidX=true
android.enableJetifier=true
MAPBOX_DOWNLOADS_TOKEN=sk.epe9nE9peAcmwNzKVNqSbFfp2794YtnNepe9nE9peAcmwNzKVNqSbFfp2794YtnN.-HrbMMQmLdHwYb8r
```

--------------------------------

### Installation Configuration

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/example/windows/CMakeLists.txt

Defines installation paths and rules for the executable, ICU data, libraries, and assets.

```cmake
# === Installation ===
# Support files are copied into place next to the executable, so that it can
# run in place. This is done instead of making a separate bundle (as on Linux)
# so that building and running from within Visual Studio will work.
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
# Make the "install" step default, as it's required to run.
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()

# Fully re-copy the assets directory on each build to avoid having stale files
# from a previous install.
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

# Install the AOT library on non-Debug builds only.
install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)
```

--------------------------------

### Start Navigation

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Launches a full-screen turn-by-turn navigation view with the specified waypoints and options.

```APIDOC
## startNavigation

Launches a full-screen turn-by-turn navigation view with the specified waypoints. Requires at least 2 waypoints and supports up to 25. Note: drivingWithTraffic mode is limited to 3 waypoints maximum.

### Method

POST

### Endpoint

`/startNavigation` (This is a conceptual endpoint for the plugin's method call)

### Parameters

#### Request Body

- **wayPoints** (List<WayPoint>) - Required - A list of WayPoint objects defining the route.
- **options** (MapBoxOptions) - Optional - Configuration options for the navigation session.

#### WayPoint Object

- **name** (String) - Optional - Name of the waypoint.
- **latitude** (double) - Required - Latitude of the waypoint.
- **longitude** (double) - Required - Longitude of the waypoint.
- **isSilent** (bool) - Optional - If true, arrival at this waypoint will not trigger an announcement.

#### MapBoxOptions Object

- **initialLatitude** (double) - Optional - The initial latitude for the map.
- **initialLongitude** (double) - Optional - The initial longitude for the map.
- **zoom** (double) - Optional - The initial zoom level of the map.
- **tilt** (double) - Optional - The initial tilt angle of the map.
- **bearing** (double) - Optional - The initial bearing (rotation) of the map.
- **enableRefresh** (bool) - Optional - Enables map refresh.
- **alternatives** (bool) - Optional - Enables alternative routes.
- **voiceInstructionsEnabled** (bool) - Optional - Enables voice instructions.
- **bannerInstructionsEnabled** (bool) - Optional - Enables banner instructions.
- **allowsUTurnAtWayPoints** (bool) - Optional - Allows U-turns at waypoints.
- **mode** (MapBoxNavigationMode) - Required - The navigation mode (e.g., driving, walking, cycling).
- **mapStyleUrlDay** (String) - Optional - URL for the day map style.
- **mapStyleUrlNight** (String) - Optional - URL for the night map style.
- **units** (VoiceUnits) - Optional - The units for voice instructions (e.g., imperial, metric).
- **simulateRoute** (bool) - Optional - Simulates the route for testing.
- **language** (String) - Optional - The language for voice instructions.

### Request Example

```json
{
  "wayPoints": [
    {
      "name": "Home",
      "latitude": 37.77440680146262,
      "longitude": -122.43539772352648,
      "isSilent": false
    },
    {
      "name": "Store",
      "latitude": 37.76556957793795,
      "longitude": -122.42409811526268,
      "isSilent": false
    }
  ],
  "options": {
    "mode": "drivingWithTraffic",
    "simulateRoute": true,
    "voiceInstructionsEnabled": true,
    "bannerInstructionsEnabled": true,
    "units": "metric",
    "language": "en"
  }
}
```

### Response

This method typically does not return a value directly but initiates the navigation UI. Errors or events during navigation are handled via callbacks or streams (not detailed here).
```

--------------------------------

### Start Navigation via Controller

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

Triggers the navigation process using the initialized controller.

```dart
    _controller.startNavigation();
```

--------------------------------

### MapBoxNavigation Singleton Initialization and Configuration

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Demonstrates how to get the singleton instance of MapBoxNavigation, set default navigation options, and retrieve the current default options and platform version.

```APIDOC
## MapBoxNavigation Singleton

The main entry point for the navigation SDK. Provides methods to configure navigation options, start navigation sessions, listen for route events, and control navigation state.

### Initialization and Default Options

```dart
import 'package:flutter_mapbox_navigation/flutter_mapbox_navigation.dart';

// Get the singleton instance
final navigation = MapBoxNavigation.instance;

// Set default options for all navigation sessions
navigation.setDefaultOptions(MapBoxOptions(
  initialLatitude: 36.1175275,
  initialLongitude: -115.1839524,
  zoom: 13.0,
  tilt: 0.0,
  bearing: 0.0,
  enableRefresh: false,
  alternatives: true,
  voiceInstructionsEnabled: true,
  bannerInstructionsEnabled: true,
  allowsUTurnAtWayPoints: true,
  mode: MapBoxNavigationMode.drivingWithTraffic,
  mapStyleUrlDay: "https://url_to_day_style",
  mapStyleUrlNight: "https://url_to_night_style",
  units: VoiceUnits.imperial,
  simulateRoute: false,
  language: "en",
));

// Retrieve current default options
final currentOptions = navigation.getDefaultOptions();

// Get platform version
final platformVersion = await navigation.getPlatformVersion();
print('Running on: $platformVersion');
```

### Parameters

- **initialLatitude** (double) - Optional - The initial latitude for the map.
- **initialLongitude** (double) - Optional - The initial longitude for the map.
- **zoom** (double) - Optional - The initial zoom level of the map.
- **tilt** (double) - Optional - The initial tilt angle of the map.
- **bearing** (double) - Optional - The initial bearing (rotation) of the map.
- **enableRefresh** (bool) - Optional - Enables map refresh.
- **alternatives** (bool) - Optional - Enables alternative routes.
- **voiceInstructionsEnabled** (bool) - Optional - Enables voice instructions.
- **bannerInstructionsEnabled** (bool) - Optional - Enables banner instructions.
- **allowsUTurnAtWayPoints** (bool) - Optional - Allows U-turns at waypoints.
- **mode** (MapBoxNavigationMode) - Required - The navigation mode (e.g., driving, walking, cycling).
- **mapStyleUrlDay** (String) - Optional - URL for the day map style.
- **mapStyleUrlNight** (String) - Optional - URL for the night map style.
- **units** (VoiceUnits) - Optional - The units for voice instructions (e.g., imperial, metric).
- **simulateRoute** (bool) - Optional - Simulates the route for testing.
- **language** (String) - Optional - The language for voice instructions.

### Response Example

```json
{
  "platformVersion": "1.0.0",
  "defaultOptions": {
    "initialLatitude": 36.1175275,
    "initialLongitude": -115.1839524,
    "zoom": 13.0,
    "tilt": 0.0,
    "bearing": 0.0,
    "enableRefresh": false,
    "alternatives": true,
    "voiceInstructionsEnabled": true,
    "bannerInstructionsEnabled": true,
    "allowsUTurnAtWayPoints": true,
    "mode": "drivingWithTraffic",
    "mapStyleUrlDay": "https://url_to_day_style",
    "mapStyleUrlNight": "https://url_to_night_style",
    "units": "imperial",
    "simulateRoute": false,
    "language": "en"
  }
}
```
```

--------------------------------

### Install Flutter Assets

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/example/linux/CMakeLists.txt

Installs the Flutter assets directory to the application's data directory. This is typically used for UI assets and resources.

```cmake
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)
```

--------------------------------

### MapBoxNavigationView Widget Example

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Demonstrates how to embed the MapBoxNavigationView widget in a Flutter application. Includes setup for navigation options, route building, and event handling for navigation progress and status updates.

```dart
import 'package:flutter/material.dart';
import 'package:flutter_mapbox_navigation/flutter_mapbox_navigation.dart';

class NavigationScreen extends StatefulWidget {
  @override
  _NavigationScreenState createState() => _NavigationScreenState();
}

class _NavigationScreenState extends State<NavigationScreen> {
  MapBoxNavigationViewController? _controller;
  MapBoxOptions _navigationOption = MapBoxOptions(
    zoom: 15.0,
    voiceInstructionsEnabled: true,
    bannerInstructionsEnabled: true,
    mode: MapBoxNavigationMode.drivingWithTraffic,
    simulateRoute: true,
    language: "en",
  );
  bool _routeBuilt = false;
  bool _isNavigating = false;
  String? _instruction;

  final _home = WayPoint(
    name: "Home",
    latitude: 37.77440680146262,
    longitude: -122.43539772352648,
  );

  final _store = WayPoint(
    name: "Store",
    latitude: 37.76556957793795,
    longitude: -122.42409811526268,
  );

  @override
  void dispose() {
    _controller?.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Embedded Navigation')),
      body: Column(
        children: [
          // Control buttons
          Row(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              ElevatedButton(
                onPressed: _isNavigating ? null : _buildOrClearRoute,
                child: Text(_routeBuilt ? "Clear Route" : "Build Route"),
              ),
              SizedBox(width: 10),
              ElevatedButton(
                onPressed: _routeBuilt && !_isNavigating
                    ? () => _controller?.startNavigation()
                    : null,
                child: Text('Start'),
              ),
              SizedBox(width: 10),
              ElevatedButton(
                onPressed: _isNavigating
                    ? () => _controller?.finishNavigation()
                    : null,
                child: Text('Stop'),
              ),
            ],
          ),

          // Instruction banner
          Container(
            padding: EdgeInsets.all(10),
            color: Colors.grey[800],
            width: double.infinity,
            child: Text(
              _instruction ?? "Instructions will appear here",
              style: TextStyle(color: Colors.white),
              textAlign: TextAlign.center,
            ),
          ),

          // Embedded navigation view
          Expanded(
            child: MapBoxNavigationView(
              options: _navigationOption,
              onRouteEvent: _onRouteEvent,
              onCreated: (MapBoxNavigationViewController controller) async {
                _controller = controller;
                controller.initialize();
              },
            ),
          ),
        ],
      ),
    );
  }

  void _buildOrClearRoute() {
    if (_routeBuilt) {
      _controller?.clearRoute();
      setState(() => _routeBuilt = false);
    } else {
      var wayPoints = <WayPoint>[_home, _store];
      _controller?.buildRoute(
        wayPoints: wayPoints,
        options: _navigationOption,
      );
    }
  }

  Future<void> _onRouteEvent(RouteEvent e) async {
    switch (e.eventType) {
      case MapBoxEvent.progress_change:
        var progressEvent = e.data as RouteProgressEvent;
        if (progressEvent.currentStepInstruction != null) {
          setState(() => _instruction = progressEvent.currentStepInstruction);
        }
        break;
      case MapBoxEvent.route_built:
        setState(() => _routeBuilt = true);
        break;
      case MapBoxEvent.route_build_failed:
        setState(() => _routeBuilt = false);
        break;
      case MapBoxEvent.navigation_running:
        setState(() => _isNavigating = true);
        break;
      case MapBoxEvent.navigation_finished:
      case MapBoxEvent.navigation_cancelled:
        setState(() {
          _routeBuilt = false;
          _isNavigating = false;
        });
        break;
      default:
        break;
    }
  }
}

```

--------------------------------

### Initialize and Configure MapBoxNavigation Singleton

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Get the singleton instance of MapBoxNavigation and set default options for navigation sessions. This includes setting initial map parameters and enabling/disabling various navigation features.

```dart
import 'package:flutter_mapbox_navigation/flutter_mapbox_navigation.dart';

// Get the singleton instance
final navigation = MapBoxNavigation.instance;

// Set default options for all navigation sessions
navigation.setDefaultOptions(MapBoxOptions(
  initialLatitude: 36.1175275,
  initialLongitude: -115.1839524,
  zoom: 13.0,
  tilt: 0.0,
  bearing: 0.0,
  enableRefresh: false,
  alternatives: true,
  voiceInstructionsEnabled: true,
  bannerInstructionsEnabled: true,
  allowsUTurnAtWayPoints: true,
  mode: MapBoxNavigationMode.drivingWithTraffic,
  mapStyleUrlDay: "https://url_to_day_style",
  mapStyleUrlNight: "https://url_to_night_style",
  units: VoiceUnits.imperial,
  simulateRoute: false,
  language: "en",
));

// Retrieve current default options
final currentOptions = navigation.getDefaultOptions();

// Get platform version
final platformVersion = await navigation.getPlatformVersion();
print('Running on: $platformVersion');
```

--------------------------------

### Start Navigation with WayPoints

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

Initiates navigation by defining a list of WayPoint objects and calling the startNavigation method.

```dart
    final cityhall = WayPoint(name: "City Hall", latitude: 42.886448, longitude: -78.878372);
    final downtown = WayPoint(name: "Downtown Buffalo", latitude: 42.8866177, longitude: -78.8814924);

    var wayPoints = List<WayPoint>();
    wayPoints.add(cityHall);
    wayPoints.add(downtown);
    
    await MapBoxNavigation.instance.startNavigation(wayPoints: wayPoints);
```

--------------------------------

### Install AOT Library Conditionally

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/example/linux/CMakeLists.txt

Installs the Ahead-Of-Time (AOT) compiled library only for non-Debug build types. This optimizes performance for release builds.

```cmake
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Configure CMake Minimum Version

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/linux/CMakeLists.txt

Sets the minimum required CMake version for the project. Ensure CMake 3.10 or later is installed.

```cmake
cmake_minimum_required(VERSION 3.10)
```

--------------------------------

### Start Free-Drive Mode

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Initiates passive navigation without a destination. Supports optional configuration for initial coordinates, zoom level, and voice settings.

```dart
import 'package:flutter_mapbox_navigation/flutter_mapbox_navigation.dart';

// Start free drive mode
await MapBoxNavigation.instance.startFreeDrive();

// Or with custom options
await MapBoxNavigation.instance.startFreeDrive(
  options: MapBoxOptions(
    initialLatitude: 37.7749,
    initialLongitude: -122.4194,
    zoom: 15.0,
    voiceInstructionsEnabled: true,
    language: "en",
  ),
);
```

--------------------------------

### Start Full-Screen Navigation

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Launch a full-screen turn-by-turn navigation view. Requires at least two waypoints. Note that `drivingWithTraffic` mode is limited to a maximum of three waypoints.

```dart
import 'package:flutter_mapbox_navigation/flutter_mapbox_navigation.dart';

// Define waypoints
final home = WayPoint(
  name: "Home",
  latitude: 37.77440680146262,
  longitude: -122.43539772352648,
  isSilent: false,
);

final store = WayPoint(
  name: "Store",
  latitude: 37.76556957793795,
  longitude: -122.42409811526268,
  isSilent: false,
);

// Create waypoints list
var wayPoints = <WayPoint>[];
wayPoints.add(home);
wayPoints.add(store);

// Configure navigation options
var options = MapBoxOptions(
  mode: MapBoxNavigationMode.drivingWithTraffic,
  simulateRoute: true,  // Set to false for real navigation
  voiceInstructionsEnabled: true,
  bannerInstructionsEnabled: true,
  units: VoiceUnits.metric,
  language: "en",
);

// Start navigation
await MapBoxNavigation.instance.startNavigation(
  wayPoints: wayPoints,
  options: options,
);
```

--------------------------------

### Get Navigation Progress

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Retrieve real-time navigation progress information including remaining distance in meters and remaining duration in seconds.

```APIDOC
## Get Navigation Progress

### Description
Retrieve real-time navigation progress information including remaining distance in meters and remaining duration in seconds.

### Method
`getDistanceRemaining()` and `getDurationRemaining()`

### Endpoint
N/A (These are method calls within the SDK)

### Parameters
None

### Request Example
```dart
// Get remaining distance (in meters)
double? distanceRemaining = await MapBoxNavigation.instance.getDistanceRemaining();
if (distanceRemaining != null) {
  double miles = distanceRemaining * 0.000621371;
  print('Distance remaining: ${miles.toStringAsFixed(1)} miles');
}

// Get remaining duration (in seconds)
double? durationRemaining = await MapBoxNavigation.instance.getDurationRemaining();
if (durationRemaining != null) {
  int minutes = (durationRemaining / 60).round();
  print('Duration remaining: $minutes minutes');
}
```

### Response
#### Success Response
- **distanceRemaining** (double?) - The remaining distance to the destination in meters.
- **durationRemaining** (double?) - The estimated remaining time to the destination in seconds.

#### Response Example
```json
{
  "distanceRemaining": 5000.5,
  "durationRemaining": 600.0
}
```
```

--------------------------------

### Multi-Stop Navigation and Dynamic Stop Addition

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Configure and start navigation with multiple waypoints, including silent stops. You can also add new waypoints dynamically during an active navigation session.

```dart
import 'package:flutter_mapbox_navigation/flutter_mapbox_navigation.dart';

// Define multiple waypoints
final origin = WayPoint(
  name: "Origin",
  latitude: 38.9111117447887,
  longitude: -77.04012393951416,
  isSilent: true,  // Pass through silently
);

final stop1 = WayPoint(
  name: "Coffee Shop",
  latitude: 38.91113678979344,
  longitude: -77.03847169876099,
  isSilent: true,
);

final stop2 = WayPoint(
  name: "Grocery Store",
  latitude: 38.91040213277608,
  longitude: -77.03848242759705,
  isSilent: false,  // Announce arrival
);

final destination = WayPoint(
  name: "Destination",
  latitude: 38.90894949285854,
  longitude: -77.03651905059814,
  isSilent: false,
);

// Build waypoints list
var wayPoints = <WayPoint>[];
wayPoints.add(origin);
wayPoints.add(stop1);
wayPoints.add(stop2);
wayPoints.add(destination);

// Start multi-stop navigation (must use driving mode, not drivingWithTraffic)
await MapBoxNavigation.instance.startNavigation(
  wayPoints: wayPoints,
  options: MapBoxOptions(
    mode: MapBoxNavigationMode.driving,
    simulateRoute: true,
    allowsUTurnAtWayPoints: true,
    units: VoiceUnits.metric,
    language: "en",
  ),
);

// Add a new stop during navigation (after 10 seconds)
await Future.delayed(const Duration(seconds: 10));
var gasStation = WayPoint(
  name: "Gas Station",
  latitude: 38.911176544398,
  longitude: -77.04014366543564,
  isSilent: false,
);
await MapBoxNavigation.instance.addWayPoints(wayPoints: [gasStation]);
```

--------------------------------

### Start Free Drive Mode

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Enables free-drive mode for passive navigation without a set destination. Useful for exploring with map tracking while driving. You can optionally provide custom options to configure the initial map state and voice instructions.

```APIDOC
## Start Free Drive Mode

### Description
Enables free-drive mode for passive navigation without a set destination. Useful for exploring with map tracking while driving.

### Method
`startFreeDrive()`

### Endpoint
N/A (This is a method call within the SDK)

### Parameters
#### Request Body
- **options** (MapBoxOptions) - Optional - Custom options to configure the free-drive mode, such as initial location, zoom level, and voice instruction settings.
  - **initialLatitude** (double) - Optional - The initial latitude for the map view.
  - **initialLongitude** (double) - Optional - The initial longitude for the map view.
  - **zoom** (double) - Optional - The initial zoom level for the map view.
  - **voiceInstructionsEnabled** (bool) - Optional - Whether to enable voice instructions.
  - **language** (string) - Optional - The language for voice instructions.

### Request Example
```dart
// Start free drive mode
await MapBoxNavigation.instance.startFreeDrive();

// Or with custom options
await MapBoxNavigation.instance.startFreeDrive(
  options: MapBoxOptions(
    initialLatitude: 37.7749,
    initialLongitude: -122.4194,
    zoom: 15.0,
    voiceInstructionsEnabled: true,
    language: "en",
  ),
);
```

### Response
N/A (This method does not return a value directly, but initiates a navigation session.)
```

--------------------------------

### Configure Mapbox Downloads Token

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

Add your Mapbox Downloads token with the `downloads:read` scope to your `gradle.properties` file to allow downloading Mapbox binaries. For security, consider adding this to your global Gradle properties.

```text
MAPBOX_DOWNLOADS_TOKEN=sk.XXXXXXXXXXXXXXX
```

--------------------------------

### Configure .netrc for Mapbox API Token

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

Add these lines to your .netrc file in your home directory to configure Mapbox API access. Replace PRIVATE_MAPBOX_API_TOKEN with your actual token that has the DOWNLOADS:READ scope.

```bash
machine api.mapbox.com
  login mapbox
  password PRIVATE_MAPBOX_API_TOKEN
```

--------------------------------

### Link Dependencies and Include Directories

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/example/windows/runner/CMakeLists.txt

Links necessary libraries and specifies include directories for the application. Add any application-specific dependencies here.

```cmake
# Add dependency libraries and include directories. Add any application-specific
# dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter flutter_wrapper_app)
target_link_libraries(${BINARY_NAME} PRIVATE "dwmapi.lib")
target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")
```

--------------------------------

### Apply Standard Build Settings

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/linux/CMakeLists.txt

Applies standard build settings configured in the application-level CMakeLists.txt. This can be removed for full control.

```cmake
apply_standard_settings(${PLUGIN_NAME})
```

--------------------------------

### Set Source Include Directories and Library Dependencies

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/linux/CMakeLists.txt

Specifies include directories for source files and links necessary libraries. Add plugin-specific dependencies here.

```cmake
target_include_directories(${PLUGIN_NAME} INTERFACE
  "${CMAKE_CURRENT_SOURCE_DIR}/include")
target_link_libraries(${PLUGIN_NAME} PRIVATE flutter)
target_link_libraries(${PLUGIN_NAME} PRIVATE PkgConfig::GTK)
```

--------------------------------

### Apply Standard Build Settings

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/example/windows/runner/CMakeLists.txt

Applies a standard set of build settings to the application target. This can be removed if custom build settings are required.

```cmake
# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})
```

--------------------------------

### Project and Build Configuration

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/example/windows/CMakeLists.txt

Sets the project name, minimum CMake version, and defines build configuration types for Debug, Profile, and Release modes.

```cmake
cmake_minimum_required(VERSION 3.14)
project(flutter_mapbox_navigation_example LANGUAGES CXX)

# The name of the executable created for the application. Change this to change
# the on-disk name of your application.
set(BINARY_NAME "flutter_mapbox_navigation_example")

# Explicitly opt in to modern CMake behaviors to avoid warnings with recent
# versions of CMake.
cmake_policy(SET CMP0063 NEW)

# Define build configuration option.
get_property(IS_MULTICONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
if(IS_MULTICONFIG)
  set(CMAKE_CONFIGURATION_TYPES "Debug;Profile;Release"
    CACHE STRING "" FORCE)
else()
  if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
    set(CMAKE_BUILD_TYPE "Debug" CACHE
      STRING "Flutter build mode" FORCE)
    set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
      "Debug" "Profile" "Release")
  endif()
endif()
```

--------------------------------

### Initialize Flutter Engine and Run App

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/example/web/index.html

This JavaScript code is responsible for loading the main Dart entry point and initializing the Flutter engine. It includes logic for service workers and ensures the application runs after the engine is ready.

```javascript
flutter_mapbox_navigation_example  // The value below is injected by flutter build, do not touch. var serviceWorkerVersion = null; window.addEventListener('load', function(ev) { // Download main.dart.js 
_flutter.loader.loadEntrypoint({ serviceWorker: { serviceWorkerVersion: serviceWorkerVersion, }, onEntrypointLoaded: function(engineInitializer) { engineInitializer.initializeEngine().then(function(appRunner) { appRunner.runApp(); }); } }); });
```

--------------------------------

### Multi-Stop Navigation and Dynamic Stops

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Enables navigation through multiple waypoints and demonstrates how to add new stops dynamically during an ongoing navigation session.

```APIDOC
## Multi-Stop Navigation

Navigate through multiple waypoints with support for adding stops dynamically during navigation. Silent waypoints pass through without announcements.

### Method

POST

### Endpoint

`/startNavigation` (for initial multi-stop) and `/addWayPoints` (for dynamic stops)

### Parameters

#### startNavigation (for initial multi-stop)

- **wayPoints** (List<WayPoint>) - Required - A list of WayPoint objects defining the route. Maximum 25 waypoints. For `driving` mode, up to 25. For `drivingWithTraffic`, maximum 3.
- **options** (MapBoxOptions) - Optional - Configuration options for the navigation session. Note: `drivingWithTraffic` mode is limited to 3 waypoints.

#### WayPoint Object

- **name** (String) - Optional - Name of the waypoint.
- **latitude** (double) - Required - Latitude of the waypoint.
- **longitude** (double) - Required - Longitude of the waypoint.
- **isSilent** (bool) - Optional - If true, arrival at this waypoint will not trigger an announcement.

#### MapBoxOptions Object

- **mode** (MapBoxNavigationMode) - Required - The navigation mode. Use `MapBoxNavigationMode.driving` for multi-stop routes exceeding 3 waypoints.
- **simulateRoute** (bool) - Optional - Simulates the route for testing.
- **allowsUTurnAtWayPoints** (bool) - Optional - Allows U-turns at waypoints.
- **units** (VoiceUnits) - Optional - The units for voice instructions (e.g., imperial, metric).
- **language** (String) - Optional - The language for voice instructions.

#### addWayPoints

- **wayPoints** (List<WayPoint>) - Required - A list of WayPoint objects to add to the current route.

### Request Example (Initial Multi-Stop Navigation)

```json
{
  "wayPoints": [
    {
      "name": "Origin",
      "latitude": 38.9111117447887,
      "longitude": -77.04012393951416,
      "isSilent": true
    },
    {
      "name": "Coffee Shop",
      "latitude": 38.91113678979344,
      "longitude": -77.03847169876099,
      "isSilent": true
    },
    {
      "name": "Grocery Store",
      "latitude": 38.91040213277608,
      "longitude": -77.03848242759705,
      "isSilent": false
    },
    {
      "name": "Destination",
      "latitude": 38.90894949285854,
      "longitude": -77.03651905059814,
      "isSilent": false
    }
  ],
  "options": {
    "mode": "driving",
    "simulateRoute": true,
    "allowsUTurnAtWayPoints": true,
    "units": "metric",
    "language": "en"
  }
}
```

### Request Example (Adding a new stop during navigation)

```dart
// Assuming navigation has already started with the above waypoints
await MapBoxNavigation.instance.addWayPoints(wayPoints: [
  {
    "name": "Gas Station",
    "latitude": 38.911176544398,
    "longitude": -77.04014366543564,
    "isSilent": false
  }
]);
```

### Response

These methods typically do not return a value directly but modify the navigation state or UI. Events and errors during navigation are handled via callbacks or streams (not detailed here).
```

--------------------------------

### List Bundled Libraries

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/linux/CMakeLists.txt

Defines a list of absolute paths to libraries to be bundled with the plugin. This can include prebuilt or externally built libraries.

```cmake
set(flutter_mapbox_navigation_bundled_libraries
  ""
  PARENT_SCOPE
)
```

--------------------------------

### MapBoxNavigationViewController Usage

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Demonstrates how to use the MapBoxNavigationViewController to build routes, start/stop navigation, and access navigation progress data. The controller is typically received via the onCreated callback.

```dart
import 'package:flutter_mapbox_navigation/flutter_mapbox_navigation.dart';

MapBoxNavigationViewController? _controller;

// Controller is received via onCreated callback in MapBoxNavigationView
// onCreated: (MapBoxNavigationViewController controller) {
//   _controller = controller;
//   controller.initialize();
// }

// Build a route between waypoints
var wayPoints = <WayPoint>[
  WayPoint(name: "Start", latitude: 38.9111, longitude: -77.0401),
  WayPoint(name: "End", latitude: 38.9089, longitude: -77.0365),
];
bool success = await _controller!.buildRoute(
  wayPoints: wayPoints,
  options: MapBoxOptions(
    mode: MapBoxNavigationMode.driving,
    simulateRoute: true,
  ),
);

// Start navigation after route is built
await _controller!.startNavigation();

// Get remaining distance in meters
double distance = await _controller!.distanceRemaining;

// Get remaining duration in seconds
double duration = await _controller!.durationRemaining;

// Clear the current route
await _controller!.clearRoute();

// Start free drive mode
await _controller!.startFreeDrive();

// End navigation
await _controller!.finishNavigation();

// Dispose when done
_controller!.dispose();
```

--------------------------------

### Flutter and Plugin Build Rules

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/example/windows/CMakeLists.txt

Includes the Flutter managed directory, the application runner, and generated plugin build rules.

```cmake
# Flutter library and tool build rules.
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})

# Application build; see runner/CMakeLists.txt.
add_subdirectory("runner")

# Generated plugin build rules, which manage building the plugins and adding
# them to the application.
include(flutter/generated_plugins.cmake)
```

--------------------------------

### MapBoxOptions Configuration

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Provides comprehensive configuration options for customizing navigation behavior, map appearance, voice instructions, and route preferences. Options can be created directly or copied from existing ones.

```dart
import 'package:flutter_mapbox_navigation/flutter_mapbox_navigation.dart';

final options = MapBoxOptions(
  // Initial map position
  initialLatitude: 37.7749,
  initialLongitude: -122.4194,

  // Map camera settings
  zoom: 15.0,          // 0-22, higher = more zoomed in
  bearing: 0.0,        // Direction camera faces (degrees clockwise from north)
  tilt: 0.0,           // Camera angle from nadir (0-60 degrees)

  // Navigation mode
  mode: MapBoxNavigationMode.drivingWithTraffic,  // or driving, walking, cycling

  // Voice and UI settings
  voiceInstructionsEnabled: true,
  bannerInstructionsEnabled: true,
  units: VoiceUnits.metric,  // or VoiceUnits.imperial
  language: "en",  // ISO 639-1 code, e.g., "de-DE", "es", "fr"

  // Route options
  alternatives: true,           // Show alternative routes
  allowsUTurnAtWayPoints: true, // Allow U-turns at intermediate waypoints
  enableRefresh: false,         // Enable route refresh

  // Map styles (custom Mapbox style URLs)
  mapStyleUrlDay: "mapbox://styles/mapbox/navigation-day-v1",
  mapStyleUrlNight: "mapbox://styles/mapbox/navigation-night-v1",

  // UI settings
  animateBuildRoute: true,
  longPressDestinationEnabled: true,  // Allow setting destination via long press
  showReportFeedbackButton: true,     // iOS only
  showEndOfRouteFeedback: true,       // iOS only
  enableOnMapTapCallback: false,      // Receive tap events

  // Simulation (for testing)
  simulateRoute: false,  // Set true to simulate driving the route

  // Padding for embedded view
  padding: EdgeInsets.all(20),
);

// Create options from existing options
var newOptions = MapBoxOptions.from(options);
newOptions.simulateRoute = true;
newOptions.language = "de-DE";
```

--------------------------------

### Define Executable Target and Source Files

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/example/windows/runner/CMakeLists.txt

Defines the main executable target for the Windows application and lists all necessary source files. Ensure BINARY_NAME in the top-level CMakeLists.txt is consistent for `flutter run`.

```cmake
cmake_minimum_required(VERSION 3.14)
project(runner LANGUAGES CXX)

# Define the application target. To change its name, change BINARY_NAME in the
# top-level CMakeLists.txt, not the value here, or `flutter run` will no longer
# work.
#
# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME} WIN32
  "flutter_window.cpp"
  "main.cpp"
  "utils.cpp"
  "win32_window.cpp"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
  "Runner.rc"
  "runner.exe.manifest"
)
```

--------------------------------

### Configure iOS info.plist

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

Required configuration for iOS to enable embedded views.

```xml
    <dict>
        ...
        <key>io.flutter.embedded_views_preview</key>
        <true/>
        ...
    </dict>
```

--------------------------------

### MapBoxOptions Configuration

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Configuration options for customizing navigation behavior, map appearance, voice instructions, and route preferences.

```APIDOC
## MapBoxOptions

### Description
Complete configuration options for customizing navigation behavior, map appearance, voice instructions, and route preferences.

### Configuration Fields
- **initialLatitude** (double) - Initial map latitude.
- **initialLongitude** (double) - Initial map longitude.
- **zoom** (double) - Map zoom level (0-22).
- **mode** (MapBoxNavigationMode) - Navigation mode (driving, walking, cycling).
- **voiceInstructionsEnabled** (bool) - Enable voice instructions.
- **units** (VoiceUnits) - Units for voice instructions (metric/imperial).
- **language** (String) - ISO 639-1 language code.
- **simulateRoute** (bool) - Enable route simulation for testing.
```

--------------------------------

### MapBoxNavigationViewController API

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Methods for controlling the navigation lifecycle, including building routes, starting/stopping navigation, and retrieving progress data.

```APIDOC
## MapBoxNavigationViewController

### Description
Controller for the embedded navigation view providing methods to build routes, start/stop navigation, and access navigation progress data.

### Methods
- **buildRoute**(wayPoints: List<WayPoint>, options: MapBoxOptions) - Builds a route between waypoints.
- **startNavigation**() - Starts navigation after route is built.
- **distanceRemaining** - Returns remaining distance in meters.
- **durationRemaining** - Returns remaining duration in seconds.
- **clearRoute**() - Clears the current route.
- **startFreeDrive**() - Starts free drive mode.
- **finishNavigation**() - Ends navigation.
- **dispose**() - Disposes the controller.
```

--------------------------------

### Add Android Manifest Permissions

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

Include these location and network state permissions in your app's `AndroidManifest.xml` file to enable navigation features.

```xml
<manifest>
    ...
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    ...
</manifest>
```

--------------------------------

### Integrate Flutter Tool Build Steps

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/example/windows/runner/CMakeLists.txt

Ensures that the Flutter tool's build steps are executed as part of the main application target. This is a mandatory step for Flutter Windows projects.

```cmake
# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### Set MBXAccessToken in Info.plist

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

Configure your application's Info.plist to include your Mapbox API access token. This token is required for Mapbox APIs and vector tiles.

```xml
<key>MBXAccessToken</key>
<string>YOUR_MAPBOX_ACCESS_TOKEN</string>
```

--------------------------------

### Update MainActivity for FragmentActivity

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

Modify `MainActivity.kt` to extend `FlutterFragmentActivity` instead of `FlutterActivity` to resolve `ViewModelStoreOwner` issues.

```kotlin
//import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity() {
}
```

--------------------------------

### Enable Background Modes in Info.plist

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

Configure your application's Info.plist to enable background location updates and audio playback. This ensures continuous navigation and instructions even when the app is not in the foreground.

```xml
<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
  <string>location</string>
</array>
```

--------------------------------

### Register Route Event Listener

Source: https://context7.com/eopeter/flutter_mapbox_navigation/llms.txt

Register a callback to receive real-time navigation events. This includes progress updates, route building status, arrival notifications, and navigation state changes.

```APIDOC
## Register Route Event Listener

### Description
Register a callback to receive real-time navigation events including progress updates, route building status, arrival notifications, and navigation state changes.

### Method
`registerRouteEventListener(Function(RouteEvent) callback)`

### Endpoint
N/A (This is a method call within the SDK)

### Parameters
#### Request Body
- **callback** (Function(RouteEvent)) - Required - A function that will be called when a route event occurs. The function receives a `RouteEvent` object containing the event type and data.

### Request Example
```dart
// Register the event listener
MapBoxNavigation.instance.registerRouteEventListener(_onRouteEvent);

Future<void> _onRouteEvent(RouteEvent e) async {
  // Get remaining distance and duration
  double? distanceRemaining = await MapBoxNavigation.instance.getDistanceRemaining();
  double? durationRemaining = await MapBoxNavigation.instance.getDurationRemaining();

  switch (e.eventType) {
    case MapBoxEvent.progress_change:
      var progressEvent = e.data as RouteProgressEvent;
      print('Distance traveled: ${progressEvent.distanceTraveled} meters');
      print('Current leg: ${progressEvent.legIndex}');
      break;

    case MapBoxEvent.route_building:
      print('Building route...');
      break;

    case MapBoxEvent.route_built:
      print('Route built successfully');
      break;

    case MapBoxEvent.route_build_failed:
      print('Failed to build route');
      break;

    case MapBoxEvent.navigation_running:
      print('Navigation started');
      break;

    case MapBoxEvent.on_arrival:
      print('Arrived at destination');
      // Auto-finish navigation after arrival
      await Future.delayed(const Duration(seconds: 3));
      await MapBoxNavigation.instance.finishNavigation();
      break;

    case MapBoxEvent.navigation_finished:
    case MapBoxEvent.navigation_cancelled:
      print('Navigation ended');
      break;

    case MapBoxEvent.user_off_route:
      print('User went off route, recalculating...');
      break;

    case MapBoxEvent.faster_route_found:
      print('A faster route was found');
      break;

    default:
      break;
  }
}
```

### Response
N/A (This method registers a listener and does not return a value directly.)

### Event Types
- **MapBoxEvent.progress_change**: Fired when the user's progress along the route changes.
- **MapBoxEvent.route_building**: Fired when the SDK is in the process of building a route.
- **MapBoxEvent.route_built**: Fired when a route has been successfully built.
- **MapBoxEvent.route_build_failed**: Fired when the SDK fails to build a route.
- **MapBoxEvent.navigation_running**: Fired when the navigation session starts.
- **MapBoxEvent.on_arrival**: Fired when the user arrives at the destination.
- **MapBoxEvent.navigation_finished**: Fired when the navigation session ends normally.
- **MapBoxEvent.navigation_cancelled**: Fired when the navigation session is cancelled by the user or programmatically.
- **MapBoxEvent.user_off_route**: Fired when the user deviates from the planned route.
- **MapBoxEvent.faster_route_found**: Fired when a faster route option becomes available.
```

--------------------------------

### Profile Build Flags

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/example/windows/CMakeLists.txt

Configures linker and compiler flags for the Profile build mode by inheriting from Release settings.

```cmake
# Define settings for the Profile build mode.
set(CMAKE_EXE_LINKER_FLAGS_PROFILE "${CMAKE_EXE_LINKER_FLAGS_RELEASE}")
set(CMAKE_SHARED_LINKER_FLAGS_PROFILE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE}")
set(CMAKE_C_FLAGS_PROFILE "${CMAKE_C_FLAGS_RELEASE}")
set(CMAKE_CXX_FLAGS_PROFILE "${CMAKE_CXX_FLAGS_RELEASE}")
```

--------------------------------

### Add Mapbox Access Token XML

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

Create a `mapbox_access_token.xml` file in `android/app/src/main/res/values/` and add your Mapbox access token as a string resource named `mapbox_access_token`.

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
    <string name="mapbox_access_token" translatable="false" tools:ignore="UnusedResources">ADD_MAPBOX_ACCESS_TOKEN_HERE</string>
</resources>
```

--------------------------------

### Build Navigation Route

Source: https://github.com/eopeter/flutter_mapbox_navigation/blob/master/README.md

Constructs a route by adding multiple WayPoint objects to a list and invoking the buildRoute method on the controller.

```dart
        var wayPoints = List<WayPoint>();
                            wayPoints.add(_origin);
                            wayPoints.add(_stop1);
                            wayPoints.add(_stop2);
                            wayPoints.add(_stop3);
                            wayPoints.add(_stop4);
                            wayPoints.add(_origin);
                            _controller.buildRoute(wayPoints: wayPoints);
```