Mission#
A Mission is defined as a set of Waypoints for a specific Vehicle to complete in a predefined order.
Each Waypoint has context data (e.g. timestamps / location) and one or more Waypoint Actions (i.e., passenger pickup). A
Mission is provided as part of the Vehicle object. However only the Mission object can be updated via the Fleet API (
using the UpdateVehicleMission request).
Each Mission has an id (used for versioning of Mission) and a set of Waypoints. Missions can contain anything from zero to tens of ordered Waypoints. When updating the Mission the latest Mission id must be provided and the new Mission with a new Mission id will be returned.
Functionality is provided to:
Query Current Mission of a Vehicle
Update Mission of a Vehicle
When a Mission is updated an Autonomous Driving (AD) Route is calculated and dispatched to the Vehicle.
Mission Object#
A Mission is a complex object containing extensive semantic information.
In this example we see a simple Mission containing Waypoints for a Ride Request. It contains two Waypoints (one with a single Waypoint Action and one with two Waypoint Actions).
// Example mission
{
"mission": {
"id": "95de2164-92c5-3ca0-80e9-e66f22c7afc5",
"waypoints": [
{
"actions": [
{
"pickup": {
"ride_id": "00eedc02-b670-41c5-af64-b066994b9ab7-ride",
"promised_arrival_time": {
"start_time": {
"seconds": "1710340713",
"nanos": 664000000
},
"end_time": {
"seconds": "1710340713",
"nanos": 664000000
}
}
}
}
],
"location": {
"labels": {
"de": "Fuhlsbüttler Straße 291",
"en": "Fuhlsbüttler Straße 291"
},
"location": {
"latitude": 53.599495,
"longitude": 10.041272
},
"heading": 40
},
"id": "96c85ba5-0b0d-4e52-b714-6d006e8020c8"
},
{
"actions": [
{
"dropoff": {
"ride_id": "00eedc02-b670-41c5-af64-b066994b9ab7-ride",
"promised_arrival_time": {
"start_time": {
"seconds": "1710340821",
"nanos": 664000000
},
"end_time": {
"seconds": "1710340821",
"nanos": 664000000
}
}
}
},
{
"rebalancing": {
"promised_arrival_time": {
"start_time": {
"seconds": "1710340821",
"nanos": 664000000
},
"end_time": {
"seconds": "1710340821",
"nanos": 664000000
}
}
}
}
],
"location": {
"labels": {
"de": "Elligersweg 23",
"en": "Elligersweg 23"
},
"location": {
"latitude": 53.604013,
"longitude": 10.043214
},
"heading": 270
},
"id": "bd9c2f54-783e-4421-ab7c-687fea3eb71d"
}
]
}
}
Waypoint#
A Waypoint is a particular place that a Vehicle is requested to go to.
Waypoints consist of the following information:
ID - the waypoint ID
Location - latitude / longitude, heading and label information of the place the Vehicle is requested to drive to.
Actions - a set of tasks (i.e., pick-up passengers or rebalance vehicle) that are requested to be completed at this Waypoint.
In the example below we show a set of two Waypoints each having a single Action.
// Example List of waypoints with a single action
[
{
"actions": [
{
"dropoff": {
"ride_id": "00eedc02-b670-41c5-af64-b066994b9ab7-ride",
"promised_arrival_time": {
"start_time": {
"seconds": "1710339813",
"nanos": 664000000
},
"end_time": {
"seconds": "1710339813",
"nanos": 664000000
}
}
}
}
],
"location": {
"labels": {
"de": "Elligersweg 23",
"en": "Elligersweg 23"
},
"location": {
"latitude": 53.604013,
"longitude": 10.043214
},
"heading": 85
},
"id": "422a287e-296f-4c0b-a47d-821bf3951d53"
},
{
"actions": [
{
"rebalancing": {
"promised_arrival_time": {
"start_time": {
"seconds": "1710340713",
"nanos": 664000000
},
"end_time": {
"seconds": "1710340713",
"nanos": 664000000
}
}
}
}
],
"location": {
"labels": {
"de": "Fuhlsbüttler Straße 291",
"en": "Fuhlsbüttler Straße 291"
},
"location": {
"latitude": 53.599495,
"longitude": 10.041272
},
"heading": 10
},
"id": "3e2a3193-694c-44b4-aa5a-9b36349305cf"
}
]
Waypoint Actions#
Waypoint Action is the task(s) that are to be completed at a specific Waypoint. Each Waypoint can have multiple Waypoint Actions. There are currently four main types of Waypoint Actions: Pickup, Drop-off, Rebalancing, Service Break.
For all Waypoint Actions there is a promised arrival time range - showing the time window that this action is expected
to be completed within. Additionally, pick-up and drop-off Waypoint Actions have an optional ride id attribute. This
is used to provide a link between the ordered ride and the Waypoint Action, which is useful in case a ride needs to be
cancelled due to an issue completing Waypoint Action or in case we need to remove the Waypoint Action due to a ride
cancellation.
Pickup#
Pickup Waypoint Action type is for the collection of Passengers. For Pickup Action a ride id can be provided.
{
"pickup": {
"ride_id": "00eedc02-b670-41c5-af64-b066994b9ab7-ride",
"promised_arrival_time": {
"start_time": {
"seconds": "1710340713",
"nanos": 664000000
},
"end_time": {
"seconds": "1710340713",
"nanos": 664000000
}
}
}
}
Drop-off#
Drop off Waypoint Action type is for the delivery of Passengers. For Drop off Action a ride id can be provided.
{
"dropoff": {
"ride_id": "00eedc02-b670-41c5-af64-b066994b9ab7-ride",
"promised_arrival_time": {
"start_time": {
"seconds": "1710340713",
"nanos": 664000000
},
"end_time": {
"seconds": "1710340713",
"nanos": 664000000
}
}
}
}
Rebalancing#
Rebalancing Waypoint Action type is for the Vehicle to be sent to any location (no passenger action). Rebalancing Actions are independent of rides (no ride id can be provided).
{
"rebalancing": {
"promised_arrival_time": {
"start_time": {
"seconds": "1710340713",
"nanos": 664000000
},
"end_time": {
"seconds": "1710340713",
"nanos": 664000000
}
}
}
}
Service Break#
Service Break Waypoint Action type is for the Vehicle to be sent to its break location (no passenger action). The Vehicle is not available for regular service during this time. Service Break Actions are independent of rides (no ride id can be provided).
{
"service_break": {
"promised_arrival_time": {
"start_time": {
"seconds": "1710340713",
"nanos": 664000000
},
"end_time": {
"seconds": "1710340713",
"nanos": 664000000
}
}
}
}
Multi Action Waypoints#
In addition to Waypoints with single Actions, it is possible to have multiple Actions for a single Waypoint.
First example shows a single Waypoint with 3 actions (each for a different ride). At this waypoint there are:
-Pickup of 2 rides -Drop off of 1 ride
// Waypoint with 2 pickups and a drop off
[
{
"actions": [
{
"pickup": {
"ride_id": "00eedc02-b670-41c5-af64-b066994b9ab7-ride",
"promised_arrival_time": {
"start_time": {
"seconds": "1710339813",
"nanos": 664000000
},
"end_time": {
"seconds": "1710339813",
"nanos": 664000000
}
}
}
},
{
"pickup": {
"ride_id": "b066994b9ab7-41c5-af64-00eedc02-b670-ride",
"promised_arrival_time": {
"start_time": {
"seconds": "1710339955",
"nanos": 664000000
},
"end_time": {
"seconds": "1710339955",
"nanos": 664000000
}
}
}
},
{
"dropoff": {
"ride_id": "41c5-af64-00eedc02-b670-b066994b9ab7-ride",
"promised_arrival_time": {
"start_time": {
"seconds": "1710339989",
"nanos": 664000000
},
"end_time": {
"seconds": "1710339989",
"nanos": 664000000
}
}
}
}
],
"location": {
"labels": {
"de": "Elligersweg 23",
"en": "Elligersweg 23"
},
"location": {
"latitude": 53.604013,
"longitude": 10.043214
},
"heading": 220
},
"id": "422a287e-296f-4c0b-a47d-821bf3951d53"
}
]
Mission Functionality#
Query Current Mission#
A Vehicle’s current Mission is returned with the GetVehicle response (Mission is part of Vehicle object).
Querying is important to ensure that changes are being made against the latest version of this Mission (changes made against an older version will be rejected).
Update Mission#
For the Update of a Vehicle’s Mission, a single endpoint is provided to be used for:
Adding Waypoints - Waypoints can be added when a Ride should be assigned to a Vehicle.
Editing Waypoints - Waypoints can have their location updated when a customer changes the drop-off location for their Ride.
Removing Waypoints - Waypoints can be removed when a customer cancels their Ride or when a Waypoint is no longer required.
Updating a Mission is complex due to the fact that updates need to be propagated through the backend services to the
Vehicle itself, which can have connectivity issues. Therefore, the Update Mission Service provides
extensive logic to ensure consistency between the Backend and the individual Vehicles. Extensive error responses are
provided for the UpdateVehicleMission endpoint and detailed in the API Reference.
In order to update a Vehicle’s Mission, we need to apply changes to the latest version of this Mission (precondition for changes being accepted). This is important for ensuring that all Waypoints of a Vehicle’s Mission are being considered when making additions / edits / deletions to the Waypoints in a Vehicle’s Mission. Before applying changes to a Vehicle’s Mission or after a Mission update has been rejected due to Mission changes - the latest Mission version should be requested.
Now we will go into detail of these use cases and explain any details needed when adding support for these.
Add Waypoints#
The first use case is adding single / multiple Waypoints, in the correct position, to the Mission of a Vehicle.
When adding Waypoints the following considerations need to be made:
Which existing Waypoint/s in the Mission should be preserved?
Which Waypoints do we want to add? Single Waypoint for Vehicle Rebalancing or a pair of Waypoints for provisioning a new Ride (Waypoints for pickup and dropoff)
Edit Waypoints#
The second use case is editing single / multiple existing Waypoints in the Mission of a Vehicle.
When editing Waypoints the following considerations need to be made:
Which existing Waypoint/s in the Mission should be edited?
Which changes are needed to these existing Waypoints (i.e. location update or a change in the Waypoint Actions)?
Whether the ordering of the Waypoints should be changed (i.e. Waypoint for Vehicle Rebalancing moved to position after Waypoint for Drop-Off).
Remove Waypoints#
The third use case is about removing single / multiple existing Waypoints in the Mission of a Vehicle. This would be needed, for example when:
Ride Request is no longer required and Waypoints for Pick-Up / Drop-Off should be removed.
Waypoint for Vehicle Rebalancing / Service Break is no longer needed.
When removing Waypoints the following considerations need to be made:
Which existing Waypoint/s in the Mission should be removed (single Waypoint or a pair of Waypoints for a Ride)?
Whether any new Waypoints should be added to ensure the Vehicle takes appropriate action after Waypoint removal (i.e. Waypoint added to send Vehicle to Rebalancing location when Waypoints for Ride are removed)?
Whether any changes to the remaining Waypoint/s order is needed?