startGuidance

Command

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, onViaPointReached, onDestinationReached and onGuidanceStopped, 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.

Command#

{
    "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#

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.

{
    "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:

{
    "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