startCircuitGuidance

Command

Send this JSON-RPC message in the BND_MESSAGE extra of an Intent with the action ACTION_RNC_BROADCAST, to BeNav's activity or receiver: see Sending commands.

Part of circuit navigation.

Command#

json

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "startCircuitGuidance",
  "params": {

    "requestFormat": "benav4"// , "fleex", "traceroute"
    "benav4": {
      // Paste the waypoints array of the original BeNav4 request
    },
    "traceRoute": {
    	"version": "1.0.0", // 1.1.0, 2.0.0, etc
    	"waypoints": [
    		// Paste the "waypoints" array from a "routingRoutes" of a traceRoute response.
    	]
  	},
    "fleex": {
      // Paste the "waypoints" array from the "routeData" object of the fleex response
    }
    "startUTurnThreshold": 3000, // From a "routingRoutes" element.
    "startPercentage": 0.0,
    "stopPercentage": 100.0,
    "blockStartPercentage": 100.0,
    "freeDriveAutoResumeDistance": 500,
    "hidePassedCircuit": true,
    "circuitPolylineStyle": 13001,
    "freeDriveAuto": false,
    "reroutingPopupTimeout": 20
  }
}

requestFormat: format name expected for the circuit.
The parser will need the matching root object.
Available formats:
- benav4
- traceRoute
- fleex
benav4
The original benav4 command for retrocompatibility.
Paste only the waypoints array of the original BeNav4 request. The other parameters are now common across all the formats and can be set as decribed below.

Original BeNav4 request#

json

{
    "method": "startCircuitNav",
    "id": 1506,
    "params": [
        [
            {
                "mPos": {
                    "mX": 2014107,
                    "mY": 48942550
                },
                "mAngle": 81,
                "mRadius": 5,
                "mAlertRadius": 50
            },
            {
                "mPos": {
                    "mX": 2027651,
                    "mY": 48941959
                },
                "mRadius": 5,
                "mAlertRadius": 50,
                "mIgnorePoint": true
            }
        ],
        30,
        false,
        3000,
        40.0,
        100.0,
        0.0,
        6
    ]
}

New request#

json

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "startCircuitGuidance",
  "params": {
    "requestFormat": "benav4",
    "benav4":
    {
		"waypoints": [
			{
				"mPos": {
					"mX": 2.014107,
					"mY": 48.94255
				},
				"mAngle": 81,
				"mRadius": 0,
				"mAlertRadius": 50
			},
            {
				"mPos": {
					"mX": 2.013523,
					"mY": 48.942584
				},
				"mRadius": 0,
				"mAlertRadius": 50
			}
		]
	},
    "startUTurnThreshold": 3000,
    "startPercentage": 40.0,
    "stopPercentage": 100.0,
    "blockStartPercentage": 0.0,

  }
}

traceRoute
Only the following object is needed from the traceRoute response:
- waypoints (from response)
Note: JSON data should be limited to avoid huge memory usage so we should only use the Waypoints array.
The internal route calculation will be done in Emergency mode and using the Fastest route criteria.
Additionally, the 'avoidUTurns' parameter will be set to false.

traceRoute request#

json

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "startCircuitGuidance",
  "params": {
    "requestFormat": "traceRoute",
    "traceRoute": {
      "waypoints": [
        {
          "usedDestinationIndex": 9,
          "polylineIndex": -1,
          "coordinate": {
            "lon": 7.412379837241479,
            "lat": 43.73119508920225
          },
          "angle": 276,
          "radius": 0,
          "uturn": false,
          "ignorePoint": false,
          "ignoreTrafficDirections": false,
          "ignoreRoadBlocks": false,
          "ignoreRestrictions": false,
          "avoidUTurn": "UNDEF",
          "useStartAngle": "YES",
          "useStopRoadSide": "UNDEF"
        },
        {
          "usedDestinationIndex": 10,
          "polylineIndex": -1,
          "coordinate": {
            "lon": 7.41113,
            "lat": 43.73127
          },
          "angle": 263,
          "radius": 0,
          "uturn": false,
          "ignorePoint": false,
          "ignoreTrafficDirections": false,
          "ignoreRoadBlocks": false,
          "ignoreRestrictions": true,
          "avoidUTurn": "UNDEF",
          "useStartAngle": "UNDEF",
          "useStopRoadSide": "UNDEF"
        }
      ]
    },
    "startUTurnThreshold": 3000,
    "startPercentage": 40,
    "stopPercentage": 100,
    "blockStartPercentage": 0
  }
}

fleex
Only the following object is needed from the traceRoute response:
- waypoints (from response)

fleex request#

json

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "startCircuitGuidance",
  "params": {
    "requestFormat": "fleex",
    "fleex": {
      "waypoints": [
        {
          "usedDestinationIndex": 0,
          "polylineIndex": 0,
          "poiId": 0,
          "longitude": 5.870304216516495,
          "latitude": 51.0795575,
          "angle": 210,
          "radius": 0,
          "uturn": false,
          "ignorePoint": false,
          "ignoreRestrictions": true,
          "ignoreRoadBlocks": true,
          "ignoreTrafficDirections": false,
          "avoidUTurn": "UNDEF",
          "useStartAngle": "UNDEF",
          "useStopRoadSide": "UNDEF",
          "offRoad": null,
          "message": null,
          "commands": null,
          "distanceFromStart": -1
        },
        {
          "usedDestinationIndex": 1,
          "polylineIndex": 1,
          "poiId": 0,
          "longitude": 5.87023286280173,
          "latitude": 51.079486759420064,
          "angle": 210,
          "radius": 0,
          "uturn": false,
          "ignorePoint": false,
          "ignoreRestrictions": true,
          "ignoreRoadBlocks": true,
          "ignoreTrafficDirections": false,
          "avoidUTurn": "YES",
          "useStartAngle": "YES",
          "useStopRoadSide": "UNDEF",
          "offRoad": null,
          "message": "Rechts",
          "commands": [
            {
              "type": "APP",
              "name": "WASTE_INSTRUCTION_EVENT",
              "params": [
                "duration=TO_NEXT",
                "collecting=RIGHT"
              ]
            },
            {
              "type": "APP",
              "name": "MESSAGE_EVENT",
              "params": [
                "duration=TO_NEXT"
              ]
            }
          ],
          "distanceFromStart": 16
        }
      ]
    },
    "startUTurnThreshold": 3000,
    "startPercentage": 0,
    "stopPercentage": 100,
    "blockStartPercentage": 100,
  }
}

Optional parameters#

startPercentage: Start offset in percentage of the total distance of the circuit (must be in range [0.0-100.0[).
stopPercentage: Stop offset in percentage of the total distance of the circuit (must be in range [0.0-100.0[ and > start offset).
blockStartPercentage: Defines roads of a section of the circuit to block. This section is defined by [blockStartPercentage, startPercentage]. Therefore, if blockStartPercentage >= startPercentage, it will have no effect. Default value is 100.0 (disabled).
freeDriveAuto: defines the behavior when there is a rerouting. Possible values:
- false: (default) the navigation will reroute to the last circuit position.
- true: the navigation will switch to "free drive" mode (no rerouting).
freeDriveAutoResumeDistance: Distance (in meters) over which navigation can be automatically resumed after a Free Drive (default is 500)
hidePassedCircuit: This option determines if circuit display should hide section between start and current vehicle's position (default true).

circuitPolylineClassID: classID of a custom polyline style (must be >= 10000).
reroutingPopupTimeout: timeout in seconds that'll close the rerouting popup and select the defaultReroutingBehavior.
If the value is 0, the defaultReroutingBehavior will be automatically selected without showing the popup.

Options are common for all formats, and if specified will override the option in the BeNav4 format (ex: startPercentage which is already in the command).

Responses#

Success#

json

{
    "id": "1",
    "result": {},
    "jsonrpc": "2.0"
}

Error#

json

{
  "jsonrpc": "2.0",
  "error": {
    "code": 1,
    "message": "JSON_FORMAT_ERROR"
  },
  "id": "1"
}