# startGuidance

Command (Guidance).

Starts navigation with specified points

Hands a complete navigation job to BeNav. A client application that already knows where its driver
has to go can delegate routing, guidance, map display and voice instructions rather than building any
of it, and follow what happens through the RNC notifications.

BeNav computes the route from the points supplied, then either opens the route-preview screen for
the driver to choose between alternatives, or starts guiding immediately when there is nothing to
choose. From that point BeNav owns the driving experience and reports progress back through
[`onNavigationProgressChanged`](https://docs.benomad.com/benav-rnc/notifications/on-navigation-progress-changed.md), [`onViaPointReached`](https://docs.benomad.com/benav-rnc/notifications/on-via-point-reached.md),
[`onDestinationReached`](https://docs.benomad.com/benav-rnc/notifications/on-destination-reached.md) and [`onGuidanceStopped`](https://docs.benomad.com/benav-rnc/notifications/on-guidance-stopped.md), so the client application can
track the journey without drawing a map itself.

**Worth knowing**

- There is one guidance session at a time. Calling `startGuidance` again replaces the
  session in progress.
- The command answers **twice**: first with the computed routes and their ETAs, then
  again once the preview is on screen or guidance has actually started. The second answer is the one
  that means the driver is being guided.
- `departure` is optional: the current position is used when it is omitted.
  `destination` is required unless `waypoints` are supplied.
- BeNav must already be running; a command sent to a stopped application is refused.

**Example: delegating a delivery round**

A dispatch application holds the day's drops. For each one it sends `startGuidance` with
the customer address as the destination, then listens to [`onNavigationProgressChanged`](https://docs.benomad.com/benav-rnc/notifications/on-navigation-progress-changed.md) to
show a live ETA to the customer and to [`onDestinationReached`](https://docs.benomad.com/benav-rnc/notifications/on-destination-reached.md) to mark the drop as served
before sending the next one.

The driver never types an address, and the dispatch application never implements routing.

## Command

```json
{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "startGuidance",
    "params": {
        "departure": {
            "id": "1",
            "lon": -2.0495297,
            "lat": 48.138885,
            "angle": 156,
            "radius": 10,
            "alertRadius": 20,
            "avoidUTurn": false,
            "useStartAngle": false,
            "useStopRoadSide": false,
            "ignoreTrafficDirections": false,
            "ignoreRoadBlocks": false,
            "ignoreRestrictions": false,
            "ignorePoint": false
        },
        "waypoints": [
            {
                "id": "2",
                "lon": -1.94697,
                "lat": 48.11179513,
                "angle": 257,
                "radius": 10,
                "alertRadius": 20,
                "avoidUTurn": false,
                "useStartAngle": true,
                "useStopRoadSide": true,
                "ignoreTrafficDirections": false,
                "ignoreRoadBlocks": false,
                "ignoreRestrictions": false,
                "ignorePoint": false
            }
        ],
        "destination": {
            "id": "3",
            "lon": -1.686886,
            "lat": 48.1099,
            "angle": 156,
            "radius": 10,
            "alertRadius": 20,
            "avoidUTurn": false,
            "useStartAngle": false,
            "useStopRoadSide": true,
            "ignoreTrafficDirections": false,
            "ignoreRestrictions": false,
            "ignorePoint": false
        },
        "enableRoutePreview": true,
        "avoidUTurns": true,
        "startUTurnThreshold": 3000,
        "continueIfMapMatchFailed": true,
        "alternativeRoutes": true,
        "optimizeRoute": "FAST"
    }
}
```

- `departure` **Optional** departure point. If not specified the current or the last known position will be used. If there is no position available the command will return an error.
- `destination` Destination point. **Mandatory unless** `waypoints` is non-empty - omitting it with waypoints present selects the `TO_UNDEF_STOP_TRIP` optimisation mode.
- `waypoints` **Optional** array of waypoints (see below for definition).

Optional parameters:

- `optimizeRoute` Optimizes the `waypoints` to have a faster/shorter route.

  - Optimization search mode: \[`FAST`\|`MEDIUM`\|`BEST`\]. **Omit the field for no optimisation** - the waypoints are then used in the order given. If the field is present but holds an unrecognised value it falls back to `BEST`.
  - The type of trip optimization depends on the waypoints in parameter:

    - `TO_UNDEF_STOP_TRIP` Set the departure and the waypoints, but not the destination.
    - `TO_FIXED_STOP_TRIP` Set the departure, the waypoints and the destination.
    - `ROUND_TRIP`: set the departure and the destination with the same point.  
      The waypoints will be optimized.
- `enableRoutePreview`: if `true` the route preview window will always be displayed even if no alternative is found.  \[`true`\|`false`\] Default is `false`.
- `avoidUTurns` If `true`, the routing algorithm will try to avoid U-turns on each waypoint if possible. Default is `false`
- `startUTurnThreshold` Determines, at start point or any via point for which an avoid U-turn restriction is set, the threshold (in seconds in FASTEST mode or meters in SHORTEST mode) of the difference of ETA between avoiding a U-turn or not, above which U-turn is allowed (default=3000).
- `alternativeRoutes` If enabled, search for alternative routes (up to 2 alternatives may be found).  
  Possible values \[`true`\|`false`\], default is `false`.
- `continueIfMapMatchFailed` If `true` (default), map-match failures are **not reported** and the guidance proceeds with whatever matched. Set it to `false` to have every unmatched point - **including the departure and the destination** - returned in the `MAP_MATCHING_FAILED` payload below.
- `waypoint` definition:

  - Mandatory parameters

    - `id` Unique identifier of the point.
    - `lat` / `lon` WGS84 coordinates.
  - Optional parameters:  
    If some parameters are not set or `undefined`, navigation will **choose** some option (`true`\|`false`) automatically for the best result.

    - `angle` GPS heading that will be used by the map-matching algorithm.
    - `radius` Radius in meters of the waypoint that will be used by the map-matching algorithm.
    - `alertRadius` Alert radius in meters that defines the distance from which the waypoint should be considered as reached.
    - `avoidUTurn` Defines if a U-turn should be avoided (if possible) by route planner at this location. If not specified it'll be `undefined`.
    - `useStartAngle` If `true` and location is on is on a two way road, location's angle will be used as a general direction for departure from location. If not specified it'll be `undefined`.
    - `useStopRoadSide` Defines if route planner must arrive on this waypoint on waypoint's side if waypoint is on a 2 way road. If not specified it'll be `undefined`.
    - `ignoreTrafficDirections` Defines if traffic directions should be ignored by route planner between this waypoint and next one. If not specified it'll be `undefined`.
    - `ignoreRoadBlocks` Defines if road blocks should be ignored by route planner between this waypoint and next one. If not specified it'll be `undefined`.
    - `ignoreRestrictions` Defines if forbidden maneuvers and blocked passages should be ignored by route planner between this waypoint and next one. If not specified it'll be `undefined`.
    - `ignorePoint` **Accepted but ignored on this variant** - the value is always treated as `false`.

## Responses

> **Note:** `startGuidance` answers **twice** with the same `id`. The first response carries the computed routes and their ETAs (below). The second is a plain `{"result": {}}` sent once the route preview has been drawn, or once guidance has actually started - that second response is the one that means the command finished.

### Success

A successful call returns the per-route ETAs. `etas` and `error` are **mutually exclusive** on a given route: when a route carries an error its `etas` is omitted.

```json
{
    "id": "1",
    "result": {
        "routes": [
            {
                "routeId": "rnc_id",
                "etas": [
                    {
                        "id": "1",
                        "eta": 0,
                        "distance": 0
                    },
                    {
                        "id": "3",
                        "eta": 2147,
                        "distance": 38144
                    }
                ]
            }
        ]
    },
    "jsonrpc": "2.0"
}
```

### Error

#### Map matching failed

When `continueIfMapMatchFailed` is `false` and one or more points could not be map-matched, the route carries an error instead of its ETAs:

```json
{
    "id": "1",
    "result": {
        "routes": [
            {
                "routeId": "rnc_id",
                "error": {
                    "code": -32005,
                    "message": "MAP_MATCHING_FAILED",
                    "data": {
                        "ids": [
                            "2"
                        ]
                    }
                }
            }
        ]
    },
    "jsonrpc": "2.0"
}
```

- `code` Internal code, can be used to contact support.
- `message` Explicit message with details of the error.
- `id` List of `id` of all the `waypoint` that failed to be map-matched.

#### Computing errors

Other computing errors without data can be sent if the navigation could not compute a route for another reason.

```
INVALID_NMEA_PARSER       =  1, //!< Invalid NMEA parser (null)
INTERNAL_ERROR            =  2, //!< Internal error
NOT_ENOUGH_MEMORY         =  3, //!< Not enough memory on device
ALREADY_IN_PROCESS        =  4, //!< Method Start has been called during Start process
DEPT_NOT_ACCESSIBLE       =  5, //!< A departure has been specified but it is not accessible
DEST_NOT_ACCESSIBLE       =  6, //!< A destination has been specified but it is not accessible
NO_ROAD_NETWORK           =  7, //!< Missing data for path computation in SVSs
TRANSP_MODE_NOT_SUPPORTED =  8, //!< Transportation mode is not supported by SVSs
NO_PATH                   =  9, //!< No route found from departure to destination : SVSs are probably not connex
INVALID_ROUTE_SVS         = 10, //!< Invalid route SVS (null or not dynamic)
INVALID_START_ARGUMENTS   = 11, //!< Start() method called with invalid arguments
LOADING_MAP_FAILED        = 12  //!< Failed to download an SVS file
```