Execute a Ride

After a Ride is assigned to a Vehicle’s Mission, we provide functionality to stay informed about the progress of this Ride. The provided updates include:

• Mission events containing information about the Waypoint Actions that have been completed

  • ETA updates in the RouteUpdated event

• Continuous updates of the Vehicle’s location

Receive Mission Events

Vehicles emit updates while they follow the instructions provided to it, the so-called Mission Events. These events are important to understand the current state of a Vehicle and are indicators for the progress of a Ride.

To receive these events we set up the stream SubscribeToFleetMissionEvents when preparing a Fleet for service. To identify relevant events for the Ride, we filter events for a Vehicle by vehicle_id and look for events concerning the Waypoints (see waypoint_id in event) and Waypoint actions (see ride_id in event).

Expected Flow of Events During Ride

Given a Ride with one pickup and drop-off location, the Vehicle starts fulfilling the Ride as soon as the pickup Waypoint is next in its Mission.

This overall process is visualized in the diagram below for a drop-off. The diagram focuses on the events that are relevant to a single Ride.

        graph TB
    start([Pickup Waypoint is next in Mission])

    subgraph route-updated [VehicleRouteUpdated]
    end

    subgraph pickup [Pickup]
        direction LR

        pu-waypoint-reached[WaypointReached]
        boarding-prep-started[BoardingPreparationStarted]
        boarding-prep-success([SendBoardingPreparationSuccessful or NFC authentication])
        boarding-prep-completed[BoardingPreparationCompleted]
        others[...]
        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 --> picked-up
        picked-up --> others
        others --> pu-waypoint-completed
    end

    subgraph route-updated1 [VehicleRouteUpdated]
    end

    drive([Vehicle drives to next Waypoint in the Mission until drop-off Waypoint is next])

    subgraph drop-off [Drop-Off]
        direction LR

        do-waypoint-reached[WaypointReached]
        droppedoff[DroppedOff]
        do-waypoint-completed[WaypointCompleted]

        do-waypoint-reached --> droppedoff
        do-others[...]
        droppedoff --> do-others
        do-others --> do-waypoint-completed
    end

    subgraph route-updated2 [VehicleRouteUpdated]
    end

    start --> route-updated
    route-updated --> pickup
    pickup --> route-updated1
    route-updated1 --> drive
    drive --> route-updated2
    route-updated2 --> drop-off
    

The Vehicle drives to the pickup location and sends out a WaypointReached event as soon as it arrived. It also sends a BoardingPreparationStarted event indicating that it is waiting for the passenger to be authenticated. Based on the chosen operation mode, this can either be fulfilled by the Vehicle using a NFC module or an API request. When the Vehicle is available for Boarding (after passenger authentication or after open doors requested), the Vehicle sends a BoardingPreparationCompleted event and the doors of the Vehicle are opened ready for the passenger to board.

In case the boarding preparation is handled by the API user, the user has to issue a SendBoardingPreparationSuccessful command to the vehicle to indicate that the passenger is ready to board and to trigger the opening of the doors. You can skip this step if the boarding preparation is handled by the Vehicle.

grpcurl -H "authorization: Bearer $ACCESS_TOKEN" -import-path . -proto fleet_state.proto  --emit-defaults \
-d "{\"ride_id\": \"$RIDE_ID\", \"vehicle_id\": \"$VEHICLE_ID\"}" \
fleet-api.int.eu-central-1.moia-group.io:443 moia.fleet.state.v1beta4.FleetStateService/SendBoardingPreparationSuccessful

Once the passenger has boarded successfully and an Operator has successfully completed a Cabin Safety Check, a PickedUp event is emitted. The Vehicle then performs all other Waypoint Actions at this Waypoint as instructed in the Mission before it is ready to continue driving, indicated by a WaypointCompleted event. Upon completing all the actions for this Waypoint, the Waypoint and corresponding Waypoint Actions are removed from the Mission.

After completing the Waypoint with Pickup Waypoint Action, the next Waypoint in the Mission changes so a VehicleRouteUpdated event is sent. This event holds information on the ETA to the next location, route length and the path to get there.

Until the Vehicle arrives at the drop-off location, it will follow the instructions provided in its Mission.

As the vehicle approaches the next Waypoint with a Drop-Off Waypoint Action, the Vehicle sends a WaypointReached event to indicate its arrival at the Waypoint location, opens the door and lets the passenger deboard. Once the passenger has deboarded and an Operator has successfully completed a Cabin Safety Check, the Vehicle will confirm this with a DroppedOff event.

Mission Updates During Execution

Completed Waypoints & Waypoint Actions will be removed automatically from the Mission and a new ID will be assigned, to mark that the Mission data has changed. This is expected behaviour and there is no action required to remove completed Waypoints or Waypoint Actions.

Continuous Location Updates

We can receive continuous live updates by calling the streaming method SubscribeToVehicleTelemetryMovement for the Vehicle which is executing the Ride.

grpcurl -H "authorization: Bearer $ACCESS_TOKEN"  -import-path .  -proto fleet_state.proto -emit-defaults \
-d "{ \"vehicle_id\": \"$VEHICLE_ID\" }" \
-max-time 30 \
fleet-api.int.eu-central-1.moia-group.io:443 moia.fleet.state.v1beta4.FleetStateService/SubscribeToVehicleTelemetryMovement