Skip to content

Add TNC mode #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
avatarneil wants to merge 4 commits into
base: add-taxi-mode
Choose a base branch
from
Draft

Add TNC mode #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7670402
Add TNC mode, WIP
avatarneil Mar 15, 2021
a02a7a0
Add prediction_timestamp
avatarneil Mar 16, 2021
d1dc916
Add TNC Vehicle States list
avatarneil Apr 23, 2021
bd5f76a
Merge branch 'add-taxi-mode' into add-tnc-mode
avatarneil May 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 14 additions & 7 deletions agency/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -189,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:

Expand All @@ -219,6 +221,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
Expand Down Expand Up @@ -371,6 +376,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 |
Expand Down Expand Up @@ -419,4 +425,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
60 changes: 58 additions & 2 deletions general-information.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,12 @@ 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)
- [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)
Expand Down Expand Up @@ -81,6 +83,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

Expand Down Expand Up @@ -275,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
Expand Down Expand Up @@ -372,7 +387,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`

Expand Down
Loading