diff --git a/agency/README.md b/agency/README.md index 174212a2..2d56efa8 100644 --- a/agency/README.md +++ b/agency/README.md @@ -158,8 +158,9 @@ Body Params: | Field | Type | Required/Optional | Field Description | | ----------- | ---------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| `event_type` | Enum | Required | [Vehicle Event](#vehicle-events) | -| `timestamp` | Timestamp | Required |Date of last event update | +| `event_type` | Enum | Required | see [Vehicle Events](#vehicle-events) | +| `event_type_reason` | Enum | Required if Available | see [Vehicle Events](#vehicle-events) | +| `timestamp` | Timestamp | Required | Date of last event update | | `telemetry` | [Telemetry](#telemetry-data) | Required | Single point of telemetry | | `trip_id` | UUID | Optional | UUID provided by Operator to uniquely identify the trip. Required for `trip_start`, `trip_end`, `trip_enter`, and `trip_leave` event types | @@ -241,24 +242,24 @@ Query Params: List of valid vehicle events and the resulting vehicle status if the event is sucessful. -| `event_type` | description | valid initial `status` | `status` on success | status_description | -| ---------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------- | ----------------------------------------------------------------------- | -| `service_start` | Vehicle introduced into service at the beginning of the day (if program does not operate 24/7) | `unavailable`, `removed`, `elsewhere` | `available` | Vehicle is on the street and available for customer use. | -| `trip_end` | Customer ends trip and reservation | `trip` | `available` | | -| `rebalance_drop_off` | Vehicle moved for rebalancing | `removed` | `available` | | -| `maintenance_drop_off` | Vehicle introduced into service after being removed for maintenance | `removed` | `available` | | -| `cancel_reservation` | Customer cancels reservation | `reserved` | `available` | | -| `reserve` | Customer reserves vehicle | `available` | `reserved` | Vehicle is reserved or in use. | -| `trip_start` | Customer starts a trip | `available`, `reserved` | `trip` | | -| `trip_enter` | Customer enters a service area managed by agency during an active trip. | `unavailable`, `removed`, `elsewhere` | `trip` | | -| `trip_leave` | Customer enters a service area managed by agency during an active trip. | `trip` | `elsewhere` | | -| `register` | Default state for a newly registered vehicle | `inactive` | `unavailable` | A vehicle is in the active fleet but not yet available for customer use | -| `low_battery` | A vehicle is no longer available due to insufficient battery | `available` | `unavailable` | | -| `maintenance` | A vehicle is no longer available due to equipment issues | `available`, `reserved` | `unavailable` | | -| `service_end` | Vehicle removed from street because service has ended for the day (if program does not operate 24/7) | `available`, `unavailable`, `elsewhere` | `removed` | A vehicle is removed from the street and unavailable for customer use. | -| `rebalance_pick_up` | Vehicle removed from street and will be placed at another location to rebalance service | `available`, `unavailable` | `removed` | | -| `maintenance_pick_up` | Vehicle removed from street so it can be worked on | `available`, `unavailable` | `removed` | | -| `deregister` | A vehicle is deregistered | `available`, `unavailable`, `removed`, `elsewhere` | `inactive` | A vehicle is deactivated from the fleet and unavailable. | +| `event_type` | `event_type_reason` | description | valid initial `status` | `status` on success | status_description | +| -------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------- | ----------------------------------------------------------------------- | +| `register` | | Default state for a newly registered vehicle | `inactive` | `removed` | A vehicle is in the active fleet but not yet available for customer use | +| `service_start` | | Vehicle introduced into service at the beginning of the day (if program does not operate 24/7) | `unavailable` | `available` | Vehicle is on the street and available for customer use. | +| `service_end` | `low_battery`, `maintenance`, `compliance`, `off_hours` | A vehicle is no longer available due to `event_type_reason` | `available` | `unavailable` | | +| `provider_drop_off` | | Vehicle moved for rebalancing | `removed`, `elsewhere` | `available` | | +| `provider_pick_up` | `rebalance`, `maintenance`, `charge`, `compliance` | Vehicle removed from street and will be placed at another location to rebalance service | `available`, `unavailable`, `elsewhere` | `removed` | | +| `city_pick_up` | | Vehicle removed by city | `available`, `unavailable` | `removed` | | +| `reserve` | | Customer reserves vehicle | `available` | `reserved` | Vehicle is reserved or in use. | +| `cancel_reservation` | | Customer cancels reservation | `reserved` | `available` | | +| `trip_start` | | Customer starts a trip | `available`, `reserved` | `trip` | | +| `trip_enter` | | Customer enters the municipal area managed by agency during an active trip. | `removed`, `elsewhere` | `trip` | | +| `trip_leave` | | Customer leaves the municipal area managed by agency during an active trip. | `trip` | `elsewhere` | | +| `trip_end` | | Customer ends trip and reservation | `trip` | `available` | | +| `deregister` | `missing` | A vehicle is deregistered | `available`, `unavailable`, `removed`, `elsewhere` | `inactive` | A vehicle is deactivated from the fleet. | + +The diagram below shows the expected events and related `status` transitions for a vehicle: +![Event State Diagram](images/MDS_agency_event_state.png?raw=true "MDS Event State Diagram") ## Telemetry Data diff --git a/agency/images/MDS_agency_event_state.png b/agency/images/MDS_agency_event_state.png new file mode 100644 index 00000000..d5aeb019 Binary files /dev/null and b/agency/images/MDS_agency_event_state.png differ