diff --git a/agency/README.md b/agency/README.md index 8b035e31..2d426556 100644 --- a/agency/README.md +++ b/agency/README.md @@ -365,21 +365,22 @@ The reservation method enum describes the different ways in which a passenger ca | payment_methods | `{ [string]: number }` | Optional | Breakdown of different payment methods used for a trip, e.g. cash, card | ## Trip -| Field | Type | Required/Optional | Field Description | -|------------------------|---------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| trip_id | UUID | Required | UUID for the trip this payload pertains to | -| provider_id | UUID | Required | Provider which managed this trip | -| reservation_method | Enum | Required | Way the customer created their reservation, see [reservation-method](#reservation-method) | -| reservation_time | Timestamp | Required | Time the customer *requested* a reservation | -| reservation_type | Enum | Required | Type of reservation, see [reservation-type](#reservation-type) | -| quoted_trip_start_time | Timestamp | Required | Time the trip was estimated or scheduled to start, that was provided to the passenger | -| dispatch_time | Timestamp | Conditionally Required | Time the vehicle was dispatched to the customer (required if trip was dispatched) | -| trip_start_time | Timestamp | Conditionally Required | Time the trip started (required if trip started) | -| trip_end_time | Timestamp | Conditionally Required | Time the trip ended (required if trip was completed) | -| distance | Float | Conditionally Required | Total distance of the trip in meters (required if trip was completed) | -| cancellation_reason | string | Conditionally Required | The reason why a *driver* cancelled a reservation. (required if a driver cancelled a trip, and a `driver_cancellation` event_type was part of the trip) | -| fare | [Fare](#fare) | Conditionally Required | Fare for the trip (required if trip was completed) | -| accessibility_options | Enum[] | Optional | The **union** of any accessibility options requested, and used. E.g. if the passenger requests a vehicle with `wheelchair_accessible`, but doesn’t utilize the features during the trip, the trip payload will include `accessibility_options: ['wheelchair_accessible']`. See [accessibility-options][accessibility-options] | +| Field | Type | Required/Optional | Field Description | +|-------------------------------|--------------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| trip_id | UUID | Required | UUID for the trip this payload pertains to | +| provider_id | UUID | Required | Provider which managed this trip | +| reservation_method | Enum | Required | Way the customer created their reservation, see [reservation-method](#reservation-method) | +| reservation_time | Timestamp | Required | Time the customer *requested* a reservation | +| reservation_type | Enum | Required | Type of reservation, see [reservation-type](#reservation-type) | +| quoted_trip_start_time | Timestamp | Required | Time the trip was estimated or scheduled to start, that was provided to the passenger | +| requested_trip_start_location | `{ lat: number, lng: number }` | Conditionally Required | Location where the customer requested the trip to start (required if this is within jurisdictional boundaries) | +| dispatch_time | Timestamp | Conditionally Required | Time the vehicle was dispatched to the customer (required if trip was dispatched) | +| trip_start_time | Timestamp | Conditionally Required | Time the trip started (required if trip started) | +| trip_end_time | Timestamp | Conditionally Required | Time the trip ended (required if trip was completed) | +| distance | Float | Conditionally Required | Total distance of the trip in meters (required if trip was completed) | +| cancellation_reason | string | Conditionally Required | The reason why a *driver* cancelled a reservation. (required if a driver cancelled a trip, and a `driver_cancellation` event_type was part of the trip) | +| fare | [Fare](#fare) | Conditionally Required | Fare for the trip (required if trip was completed) | +| accessibility_options | Enum[] | Optional | The **union** of any accessibility options requested, and used. E.g. if the passenger requests a vehicle with `wheelchair_accessible`, but doesn’t utilize the features during the trip, the trip payload will include `accessibility_options: ['wheelchair_accessible']`. See [accessibility-options][accessibility-options] | **Endpoint:** `/trips` **Method:** `POST` diff --git a/general-information.md b/general-information.md index 7a713060..92fa1696 100644 --- a/general-information.md +++ b/general-information.md @@ -10,6 +10,7 @@ This document contains specifications that are shared between the various MDS AP - [Costs and currencies](#costs-and-currencies) - [Definitions](#definitions) - [Devices](#devices) + - [Modalities](#modalities) - [Geographic Data](#geographic-data) - [Stop-based Geographic Data](#stop-based-geographic-data) - [Intersection Operation](#intersection-operation) @@ -22,8 +23,10 @@ This document contains specifications that are shared between the various MDS AP - [Timestamps](#timestamps) - [UUIDs](#uuids) - [Accessibility Options](#accessibility-options) - - [Modalities](#modalities) - [Vehicle States](#vehicle-states) + - [Micromobility Vehicle States](#micromobility-vehicle-states) + - [Taxi Vehicle States](#taxi-vehicle-states) + - [Vehicle Events](#vehicle-events) - [Micromobility Vehicle States & Events](#micromobility-vehicle-states--events) - [Taxi Vehicle States & Events](#taxi-vehicle-states--events) - [Trip State Notes](#trip-state-notes) @@ -72,6 +75,13 @@ Additionally, `device_id` must remain constant for the device's lifetime of serv [Top][toc] +## Modalities +A Modality is an operational model for a form of transportation in MDS. Given the nature of the differing operational flows, and need for regulators to capture this information, each modality may have different state machines, and different data requirements throughout MDS. +| `modality` | Description | +|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `micromobility` | This mode includes e-scooters, and dockless pedal bikes that are available for rent by consumers through a micromobility operator within an agency's jurisdiction | +| `taxi` | This mode includes franchise taxi service operators who operate and are regulated within an agency's jurisdiction | + ## Geographic Data References to geographic datatypes (Point, MultiPolygon, etc.) imply coordinates encoded in the [WGS 84 (EPSG:4326)][wgs84] standard GPS or GNSS projection expressed as [Decimal Degrees][decimal-degrees]. @@ -234,38 +244,49 @@ This enum represents the accessibility options available on a given vehicle, or |-------------------------|---------------------------------------| | `wheelchair_accessible` | This vehicle is wheelchair accessible | -## Modalities -| `modality` | Description | -| --------------- | ------------------------------------------------------------ | -| `micromobility` | **FIXME** add some descriptor about micromobility | -| `taxi` | **FIXME** add some descriptor about taxi | - ## Vehicle States This table describes the list of vehicle conditions that may be used by regulators to assess the disposition of individual vehicles and fleets of vehicles. Some of these states describe vehicles in the Public Right-of-Way (PROW), and others represent vehicles that are not. One state (`unknown`) implies that PROW status is unknown. In a multi-jurisdiction environment, the status of a vehicle is per-jurisdiction. For example, a vehicle may be in the `on_trip` status for a county that contains five cities, and also in the `on_trip` status for one of those cities, but `elsewhere` for the other four cities. In such a condition, generally a Provider would send the device data to the over-arching jurisdiction (the county) and the vehicle state with respect to each city would be determined by the Agency managing the jurisdictions. -| `vehicle_state` | In PROW? | Description | -| --- | --- | --- | -| `removed` | no | Examples include: at the Provider's warehouse, in a Provider's truck, or destroyed and in a landfill. | -| `available` | yes | Available for rental via the Provider's app. In PROW. | -| `non_operational` | yes | Not available for rent. Examples include: vehicle has low battery, or currently outside legal operating hours. | -| `reserved` | yes | Reserved via Provider's app, waiting to be picked up by a rider. | -| `on_trip` | yes | In possession of renter. May or may not be in motion. | -| `elsewhere` | no | Outside of regulator's jurisdiction, and thus not subject to cap-counts or other regulations. Example: a vehicle that started a trip in L.A. has transitioned to Santa Monica. | -| `unknown` | unknown | Provider has lost contact with the vehicle and its disposition is unknown. Examples include: taken into a private residence, thrown in river. | +### Micromobility Vehicle States + +| `vehicle_state` | In PROW? | Description | +|-------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `removed` | no | Examples include: at the Provider's warehouse, in a Provider's truck, or destroyed and in a landfill. | +| `available` | yes | Available for rental via the Provider's app. In PROW. | +| `non_operational` | yes | Not available for rent. Examples include: vehicle has low battery, or currently outside legal operating hours. | +| `reserved` | yes | Reserved via Provider's app, waiting to be picked up by a rider. | +| `on_trip` | yes | In possession of renter. May or may not be in motion. | +| `elsewhere` | no | Outside of regulator's jurisdiction, and thus not subject to cap-counts or other regulations. Example: a vehicle that started a trip in L.A. has transitioned to Santa Monica. | +| `unknown` | unknown | Provider has lost contact with the vehicle and its disposition is unknown. Examples include: taken into a private residence, thrown in river. | + +### Taxi Vehicle States + +| `state` | In PROW? | Description | +|-------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `removed` | no | Vehicle is explicitly removed from the PROW. Examples include: at the shop receiving maintenance, vehicle moved to another fleet | +| `available` | yes | Available for-hire by a passenger. | +| `non_operational` | yes | Not available for-hire. Example: driver's shift ends and vehicle goes out of service | +| `reserved` | yes | Reserved via Provider's app, waiting to be picked up by a rider. | +| `on_trip` | yes | On a trip with passengers in the vehicle. May or may not be in motion. | +| `stopped` | yes | Vehicle is stopped to either pick-up, or drop-off a passenger. | +| `elsewhere` | no | Outside of regulator's jurisdiction, and thus not subject to cap-counts or other regulations. Example: a vehicle that started a trip in L.A. has transitioned to Santa Monica. | +| `unknown` | unknown | Provider has lost contact with the vehicle and its disposition is unknown. Examples include: driving in a tunnel, hardware malfunction | [Top][toc] -### Micromobility Vehicle States & Events +## Vehicle Events -This is the list of `vehicle_state` and `event_type` pairings that constitute the valid transitions of the micromobility vehicle state machine. +This is the list of `vehicle_state` and `event_type` pairings that constitute the valid transitions of the vehicle state machine. -The state-transition table below describes how the `vehicle_state` changes in response to each `event_type`. Most events will have a single `event_type`. However, if a single event has more than one ordered `event_type` entry, the intermediate `vehicle_state` value(s) are discarded. For example, if an event contains [`trip_end`, `battery_low`] then the vehicle transitions from `on_trip` through `available` to `non_operational` per the state machine, but the vehicle is never "in" the `available` state. +The state-transition table below describes how the `vehicle_state` changes in response to each `event_type`. Most events will have a single `event_type`. However, if a single event has more than one ordered `event_type` entry, the intermediate `vehicle_state` value(s) are discarded. For example, in the micromobility state machine, if an event contains [`trip_end`, `battery_low`] then the vehicle transitions from `on_trip` through `available` to `non_operational` per the state machine, but the vehicle is never "in" the `available` state. Note that to handle out-of-order events, the validity of the prior-state shall not be enforced at the time of ingest via Provider or Agency. Events received out-of-order may result in transient incorrect vehicle states. +### Micromobility Vehicle States & Events + | Valid prior `vehicle_state` values | `vehicle_state` | `event_type` | Description | | --- | --- | --- | --- | | `non_operational` | `available` | `battery_charged` | The vehicle became available because its battery is now charged. | @@ -301,43 +322,45 @@ Note that to handle out-of-order events, the validity of the prior-state shall n | `available`, `reserved`, `on_trip`, `non_operational`, `elsewhere` | `unknown` | `missing` | The vehicle is not at its last reported GPS location, or that location is wildly in error | | `available`, `reserved`, `on_trip`, `non_operational`, `elsewhere` | `unknown` | `comms_lost` | The vehicle is unable to transmit its GPS location or other status information | -The *State Machine Diagram* shows how the `vehicle_state` and `event_type` relate to each other and how vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1Ar2-ju8YlddSsTATvQw4YjsSa5108XtidtnJNk-UAfA/edit) for the source file. -![MDS State Machine Diagram](/MDS-state-machine-diagram.svg) +The *Micromobility State Machine Diagram* shows how the `vehicle_state` and `event_type` relate to each other and how micromobility vehicles can transition between states. See [Google Slides](https://docs.google.com/presentation/d/1Ar2-ju8YlddSsTATvQw4YjsSa5108XtidtnJNk-UAfA/edit) for the source file. +![Micromobility State Machine Diagram](/micromobility-state-machine-diagram.svg) ### Taxi Vehicle States & Events -[Top][toc] + | **Previous** `vehicle_state` | `vehicle_state` | `trip_state` | `event_type` | Description | |------------------------------|-------------------|--------------|--------------------------|------------------------------------------------------------------------------------------------------------------| -| `available` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left jurisdictional boundaries while available for use | -| `available` | `non_operational` | N/A | `service_end` | The vehicle has went out of service (is unavailable for use) | +| `available` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left jurisdictional boundaries while available for-hire | +| `available` | `non_operational` | N/A | `service_end` | The vehicle has went out of service (is unavailable for-hire) | | `available` | `reserved` | `reserved` | `reserve` | The vehicle was reserved by a passenger | -| `available` | `unknown` | N/A | `comms_lost` | The vehicle has went out of comms while available for use | -| `elsewhere` | `available` | N/A | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while available for use | +| `available` | `unknown` | N/A | `comms_lost` | The vehicle has went out of comms while available for-use | +| `elsewhere` | `available` | N/A | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while available for-hire | | `elsewhere` | `non_operational` | N/A | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while not operating commercially | | `elsewhere` | `on_trip` | `on_trip` | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while on a trip | | `elsewhere` | `reserved` | N/A | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while reserved by a customer | | `elsewhere` | `unknown` | N/A | `comms_lost` | The vehicle has went out of comms while outside of jurisdictional boundaries | -| `non_operational` | `available` | N/A | `service_start` | The vehicle has went into service (is available for use) | +| `non_operational` | `available` | N/A | `service_start` | The vehicle has went into service (is available for-hire) | | `non_operational` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left jurisdictional boundaries while not operating commercially | +| `non_operational` | `removed` | N/A | `decommissioned` | The vehicle has been removed from the Provider's fleet | | `non_operational` | `removed` | N/A | `maintenance_start` | The vehicle has entered the depot for maintenance | | `non_operational` | `unknown` | N/A | `comms_lost` | The vehicle has went out of comms while not operating commercially | | `on_trip` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left jurisdictional boundaries while on a trip | | `on_trip` | `stopped` | `stopped` | `trip_stop` | The vehicle has stopped while on a trip | | `on_trip` | `unknown` | N/A | `comms_lost` | The vehicle has went out of comms while on a trip | | `removed` | `non_operational` | N/A | `maintenance_end` | The vehicle has left the depot | +| `removed` | `non_operational` | N/A | `recommissioned` | The vehicle has been re-added to the Provider's fleet after being previously `decommissioned` | | `removed` | `unknown` | N/A | `comms_lost` | The vehicle has went out of comms while removed | | `reserved` | `available` | N/A | `driver_cancellation` | The driver has cancelled the reservation | | `reserved` | `available` | N/A | `passenger_cancellation` | The passenger has cancelled the reservation | | `reserved` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation | | `reserved` | `stopped` | `stopped` | `reserve_stop` | The vehicle has stopped to pick up the passenger | -| `reserved` | `unknown` | N/A | `comms-lost` | The vehicle has went out of comms while reserved by a passenger | +| `reserved` | `unknown` | N/A | `comms_lost` | The vehicle went out of comms while being reserved by a passenger | | `stopped` | `available` | N/A | `driver_cancellation` | The driver has cancelled the trip while either waiting for the passenger, or dropping them off | | `stopped` | `available` | N/A | `passenger_cancellation` | The passenger has cancelled the trip while the vehicle is waiting to pick them up, or they are being dropped off | | `stopped` | `available` | N/A | `trip_end` | The trip has been successfully completed | | `stopped` | `on_trip` | `on_trip` | `trip_resume` | Resume a trip that was previously stopped (e.g. picking up a friend to go to the airport with) | | `stopped` | `on_trip` | `on_trip` | `trip_start` | Start a trip | | `stopped` | `unknown` | N/A | `comms_lost` | The vehicle has went out of comms while stopped | -| `unknown` | `available` | N/A | `comms_restored` | The vehicle has come back into comms while available for use | +| `unknown` | `available` | N/A | `comms_restored` | The vehicle has come back into comms while available for-hire | | `unknown` | `elsewhere` | N/A | `comms_restored` | The vehicle has come back into comms while outside of jurisdictional boundaries | | `unknown` | `non_operational` | N/A | `comms_restored` | The vehicle has come back into comms while not operating commercially | | `unknown` | `on_trip` | `on_trip` | `comms_restored` | The vehicle has come back into comms while on a trip | @@ -345,7 +368,12 @@ The *State Machine Diagram* shows how the `vehicle_state` and `event_type` relat | `unknown` | `reserved` | `reserved` | `comms_restored` | The vehicle has come back into comms while reserved by a passenger | | `unknown` | `stopped` | `stopped` | `comms_restored` | The vehicle has come back into comms while stopped | +The *Taxi State Machine Diagram* shows how the `vehicle_state` and `event_type` relate to each other and how taxi vehicles can transition between states. + +![Taxi State Machine Diagram](/taxi-state-machine-diagram.svg) + #### Trip State Notes + When there is only one trip ongoing, `trip_state == vehicle_state` In cases where there are multiple trips ongoing, please follow the trip state model pseudocode for determining what the vehicle state should be: @@ -364,6 +392,9 @@ else: ``` `trip_state` mappings should be the same as in the table above. +[Top][toc] + + ## Vehicle Types The list of allowed `vehicle_type` values in MDS. Aligning with [GBFS vehicle types form factors](https://github.com/NABSA/gbfs/blob/master/gbfs.md#vehicle_typesjson-added-in-v21-rc). diff --git a/MDS-state-machine-diagram.svg b/micromobility-state-machine-diagram.svg similarity index 100% rename from MDS-state-machine-diagram.svg rename to micromobility-state-machine-diagram.svg diff --git a/taxi-state-machine-diagram.svg b/taxi-state-machine-diagram.svg new file mode 100644 index 00000000..5069d6c1 --- /dev/null +++ b/taxi-state-machine-diagram.svg @@ -0,0 +1,94 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +