From 7670402a28ef032be6f45b625164d3ca49659999 Mon Sep 17 00:00:00 2001 From: Neil Goldader Date: Mon, 15 Mar 2021 12:14:35 -0400 Subject: [PATCH 1/3] Add TNC mode, WIP --- agency/README.md | 6 +++ general-information.md | 47 ++++++++++++++++++- tnc-state-machine-diagram.svg | 87 +++++++++++++++++++++++++++++++++++ 3 files changed, 138 insertions(+), 2 deletions(-) create mode 100644 tnc-state-machine-diagram.svg diff --git a/agency/README.md b/agency/README.md index 73ba2ed4b..40e1e2a53 100644 --- a/agency/README.md +++ b/agency/README.md @@ -17,6 +17,7 @@ This specification contains a collection of RESTful APIs used to specify the dig - [Trip_id Requirements](#trip_id-requirements) - [Micromobility](#micromobility) - [Taxi](#taxi) + - [TNC](#tnc) - [Vehicle - Telemetry](#vehicle---telemetry) - [Telemetry Data](#telemetry-data) - [Stops](#stops) @@ -219,6 +220,9 @@ Required if `event_types` contains `trip_start`, `trip_end`, `trip_cancel`, `tri #### Taxi Required if `event_types` contains `reservation_start`, `reservation_stop`, `trip_start`, `trip_stop`, `trip_end`, `passenger_cancellation`, `driver_cancellation`. Additionally, `trip_id` is also required if `event_types` contains a `enter_jurisdiction` or `leave_jurisdiction` event which pertains to a passenger trip. +#### TNC +Requirements are the same as for the Taxi mode (see above). + [Top][toc] ## Vehicle - Telemetry @@ -371,6 +375,7 @@ The Trips endpoint serves multiple purposes: * Definitively indicating that a Trip (a sequence of events linked by a trip_id) has been completed. For example, from analyzing only the raw Vehicle Events feed, if a trip crosses an Agency's jurisdictional boundaries but does not end within the jurisdiction (last event_type seen is a `leave_jurisdiction`), this can result in a 'dangling trip'. The Trips endpoint satisfies this concern, by acting as a final indication that a trip has been finished, even if it ends outside of jurisdictional boundaries; if a trip has intersected an Agency's jurisdictional boundaries at all during a trip, it is expected that a Provider will send a Trip payload to the Agency following the trip's completion. * Providing information to an Agency regarding an entire trip, without extending any of the Vehicle Event payloads, or changing any requirements on when Vehicle Events should be sent. +At the discretion of the regulating agency some typically required fields may be omitted, and some additional fields may be required. | Field | Type | Required/Optional | Field Description | |-------------------------------|--------------------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | trip_id | UUID | Required | UUID for the trip this payload pertains to | @@ -419,4 +424,5 @@ Payload which was POST'd [vehicle-states]: /general-information.md#vehicle-states [mm-vehicle-events]: /general-information.md#micromobility-vehicle-states--events [taxi-vehicle-events]: /general-information.md#taxi-vehicle-states--events +[tnc-vehicle-events]: /general-information.md#tnc-vehicle-states--events [versioning]: /general-information.md#versioning diff --git a/general-information.md b/general-information.md index 92fa1696b..748ce6a94 100644 --- a/general-information.md +++ b/general-information.md @@ -29,7 +29,8 @@ This document contains specifications that are shared between the various MDS AP - [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) + - [TNC Vehicle States & Events](#tnc-vehicle-states--events) + - [Trip State Notes](#trip-state-notes) - [Vehicle Types](#vehicle-types) - [Propulsion Types](#propulsion-types) - [Valid for vehicle_types: bicycle, scooter, moped, other](#valid-for-vehicle_types-bicycle-scooter-moped-other) @@ -81,6 +82,7 @@ A Modality is an operational model for a form of transportation in MDS. Given th |-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `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 | +| `tnc` | This mode includes Transportation Network Companies who operate and are regulated within an agency's jurisdiction | ## Geographic Data @@ -372,7 +374,48 @@ The *Taxi State Machine Diagram* shows how the `vehicle_state` and `event_type` ![Taxi State Machine Diagram](/taxi-state-machine-diagram.svg) -#### Trip State Notes + +### TNC Vehicle States & Events +| **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-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-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-hire) | +| `non_operational` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left jurisdictional boundaries while not operating commercially | +| `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 | +| `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 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-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 | +| `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 *TNC State Machine Diagram* shows how the `vehicle_state` and `event_type` relate to each other and how TNC vehicles can transition between states. + +![TNC State Machine Diagram](/tnc-state-machine-diagram.svg) +### Trip State Notes +Applicable for Taxi & TNC Modalities When there is only one trip ongoing, `trip_state == vehicle_state` diff --git a/tnc-state-machine-diagram.svg b/tnc-state-machine-diagram.svg new file mode 100644 index 000000000..af3c88fdc --- /dev/null +++ b/tnc-state-machine-diagram.svg @@ -0,0 +1,87 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From a02a7a0e3ad325d3d398fc65a4d44d71dead2eb8 Mon Sep 17 00:00:00 2001 From: Neil Goldader Date: Tue, 16 Mar 2021 12:15:34 -0400 Subject: [PATCH 2/3] Add prediction_timestamp --- agency/README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/agency/README.md b/agency/README.md index 40e1e2a53..626b00ed1 100644 --- a/agency/README.md +++ b/agency/README.md @@ -190,13 +190,14 @@ Path Params: Body Params: -| Field | Type | Required/Optional | Field Description | -|-----------------|------------------------------|------------------------|------------------------------------------------------------------------------------------------------------| -| `vehicle_state` | Enum | Required | see [Vehicle States][vehicle-states] | -| `event_types` | Enum[] | Required | see [Micromobility Vehicle Events][mm-vehicle-events] and [Taxi Vehicle Events][taxi-vehicle-events] | -| `timestamp` | [timestamp][ts] | Required | Date of last event update | -| `telemetry` | [Telemetry](#telemetry-data) | Required | Single point of telemetry | -| `trip_id` | UUID | Conditionally required | UUID provided by Operator to uniquely identify the trip. See [trip_id requirements](#trip_id-requirements) | +| Field | Type | Required/Optional | Field Description | +|------------------------|------------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------| +| `vehicle_state` | Enum | Required | see [Vehicle States][vehicle-states] | +| `event_types` | Enum[] | Required | see [Micromobility Vehicle Events][mm-vehicle-events] and [Taxi Vehicle Events][taxi-vehicle-events] | +| `timestamp` | [timestamp][ts] | Required | Date of last event update | +| `telemetry` | [Telemetry](#telemetry-data) | Required | Single point of telemetry | +| `trip_id` | UUID | Conditionally required | UUID provided by Operator to uniquely identify the trip. See [trip_id requirements](#trip_id-requirements) | +| `prediction_timestamp` | [timestamp][ts] | Conditionally required | Required if this is a predictive event (e.g. hasn't occurred yet, but is a best-estimate of an event that will occur) | 201 Success Response: From d1dc91623b1bad1b8851e00ef1682e09385ca0f4 Mon Sep 17 00:00:00 2001 From: Neil Goldader Date: Fri, 23 Apr 2021 11:28:03 -0400 Subject: [PATCH 3/3] Add TNC Vehicle States list --- general-information.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/general-information.md b/general-information.md index 748ce6a94..d02ec1908 100644 --- a/general-information.md +++ b/general-information.md @@ -26,6 +26,7 @@ This document contains specifications that are shared between the various MDS AP - [Vehicle States](#vehicle-states) - [Micromobility Vehicle States](#micromobility-vehicle-states) - [Taxi Vehicle States](#taxi-vehicle-states) + - [TNC Vehicle States](#tnc-vehicle-states) - [Vehicle Events](#vehicle-events) - [Micromobility Vehicle States & Events](#micromobility-vehicle-states--events) - [Taxi Vehicle States & Events](#taxi-vehicle-states--events) @@ -277,6 +278,18 @@ In a multi-jurisdiction environment, the status of a vehicle is per-jurisdiction | `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 | +### TNC Vehicle States + +| `state` | In PROW? | Description | +|-------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `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] ## Vehicle Events