Waypoint Actions

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 Pickup, Drop-off and ServiceBreak Waypoint Actions, there is a promised arrival time range - showing the time window that this action is expected to be completed within. Additionally, pickup and drop-off Waypoint Actions have a mandatory 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.

Pickup Waypoint Action#

For Pickup Action, a ride id and a promised arrival time window should 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
      }
    }
  }
}

Pickup Flow#

The pickup flow for a Waypoint with a single Pickup Waypoint Action is visualized in the diagram below.

        graph TB
    subgraph pick-up [Pick-Up]
        direction TB

        pu-waypoint-reached[WaypointReached]
        boarding-prep-started[BoardingPreparationStarted]
        boarding-prep-success([SendBoardingPreparationSuccessful or NFC Authentication])
        boarding-prep-completed[BoardingPreparationCompleted]
        cabin-safety-check-started([Cabin Safety Check Started])
        cabin-safety-check-completed([Cabin Safety Check Completed])
        picked-up[PickedUp]
        pu-waypoint-completed[WaypointCompleted]

        pu-waypoint-reached --> boarding-prep-started
        boarding-prep-started --> boarding-prep-success
        boarding-prep-success --> boarding-prep-completed
        boarding-prep-completed --doors open<br/>passenger boarding--> cabin-safety-check-started
        cabin-safety-check-started -- doors closed--> cabin-safety-check-completed
        cabin-safety-check-completed --> picked-up
        picked-up --> pu-waypoint-completed
    end

The flow follows the following steps:

  • Vehicle arrives and stops at Waypoint, with WaypointReached event sent.

  • Vehicle waits for passenger to be authenticated - sending BoardingPreparationStarted event as soon as ready for authentication. Based on the chosen operation mode, this can either be fulfilled by the Vehicle using an NFC module or by the API user.

  • When authentication is completed and the Vehicle can be boarded, the Vehicle sends a BoardingPreparationCompleted event and the doors of the Vehicle are opened ready for passengers to board.

  • Once the passenger has boarded, a Cabin Safety Check needs to be completed by an Operator.

  • On starting the Cabin Safety Check, the doors will be closed (opening them would restart the cabin safety check).

  • Following successful completion of the Cabin Safety Check, a PickedUp event is emitted.

  • The Vehicle is then ready to continue driving (as no other Waypoint Actions at this Waypoint), indicated by a WaypointCompleted event.

  • Upon completion of this Waypoint, the Waypoint and corresponding Waypoint Action are removed from the Mission.

Drop-off#

Drop off Waypoint Action type is for the delivery of Passengers.

Drop-off Waypoint Action#

For Drop-off Action, a ride id and promised arrival time window should 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
      }
    }
  }
}

Drop-off Flow#

This process is visualized in the diagram below for a Waypoint with a single drop-off Waypoint Action.

        graph TB
   subgraph drop-off [Drop-Off]
        direction TB

        do-waypoint-reached[WaypointReached]
        cabin-safety-check-started([Cabin Safety Check Started])
        cabin-safety-check-completed([Cabin Safety Check Completed])
        droppedoff[DroppedOff]
        do-waypoint-completed[WaypointCompleted]

        do-waypoint-reached --doors open</br>passnge deboarding --> cabin-safety-check-started
        cabin-safety-check-started --doors closed--> cabin-safety-check-completed
        cabin-safety-check-completed --> droppedoff
        droppedoff --> do-waypoint-completed
    end

The flow follows the following steps:

  • Vehicle arrives and stops at Waypoint, with WaypointReached event sent.

  • Doors are immediately opened so deboarding can commence.

  • Once the passenger has deboarded, a Cabin Safety Check needs to be completed by an Operator.

  • On starting the Cabin Safety Check, the doors will be closed (opening them would restart the cabin safety check).

  • Following successful completion of the Cabin Safety Check, a DroppedOff event is emitted.

  • The Vehicle is then ready to continue driving (as no other Waypoint Actions at this Waypoint), indicated by a WaypointCompleted event.

  • Upon completion of this Waypoint, the Waypoint and corresponding Waypoint Action are removed from the Mission.

Rebalancing#

Rebalancing Waypoint Action type is for the Vehicle to be sent to any location (no passenger action).

Rebalancing Waypoint Action#

Rebalancing Actions are independent of rides (no ride id can be provided).

{
  "rebalancing": {}
}

Rebalancing Flow#

This process is visualized in the diagram below for a Waypoint with a single Rebalancing Waypoint Action.

        graph TB
    subgraph rebalancing [Rebalancing]
        direction TB

        rb-waypoint-reached[WaypointReached]
        update-mission([UpdateMission by Client])
        route-updated[VehicleRouteUpdated]
        departs-next-waypoint([Vehicle travels to Next Waypoint])

        rb-waypoint-reached --vehicle waits--> update-mission
        update-mission --> route-updated
        route-updated --vehicle starts driving--> departs-next-waypoint
    end

The flow follows the following steps:

  • Vehicle arrives and stops at Waypoint, with WaypointReached event sent.

  • Vehicle waits for Mission Update at this location.

  • Expectation that doors are not opened and no passengers board the vehicle.

  • When the Vehicle should move to a new Waypoint, a successful Mission update must be sent, confirmed by UpdateVehicleMissionResponse.

  • Route is calculated to new next Waypoint and VehicleRouteUpdated event is sent for new Vehicle Route.

  • Vehicle departs from Waypoint (no event issued).

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 Waypoint Action#

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
      }
    }
  }
}

Service Break Flow#

This process is visualized in the diagram below for a Waypoint with a single Service Break Waypoint Action.

        graph TB
    subgraph service-break [Service Break]
        direction TB

        rb-waypoint-reached[WaypointReached]
        update-mission([UpdateMission by Client])
        route-updated[VehicleRouteUpdated]
        departs-next-waypoint([Vehicle Departs to Next Waypoint])

        rb-waypoint-reached --vehicle waits--> update-mission
        update-mission --> route-updated
        route-updated --vehicle starts driving--> departs-next-waypoint
    end

The flow follows the following steps:

  • Vehicle arrives and stops at Waypoint, with WaypointReached event sent.

  • Vehicle waits for Mission Update at this location.

  • Expectation that doors are not opened and no passengers board the vehicle.

  • When the Vehicle should move to a new Waypoint, a Mission update must be sent.

  • Route is calculated to new next Waypoint and VehicleRouteUpdated event is sent for new Vehicle Route.

  • Vehicle departs from Waypoint (no event issued).

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"
  }
]