Skip to content
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

Jump to bottom

Feature: Modes - Delivery #778

Closed
wants to merge 20 commits into from
Closed

Feature: Modes - Delivery #778

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
dcb12c5
Create delivery.md
tristan-charreton Jun 15, 2022
e83fab8
adding robot files
alesantiago98 Jun 16, 2022
7010880
Merge branch 'feature-modes-deliverybot' of https://github.com/kiwibo…
JuanCarlos-TiqueRangel Jun 16, 2022
2ef64d8
upload readme
JuanCarlos-TiqueRangel Jun 21, 2022
23a0ccd
Update delivery.md
tristan-charreton Jun 21, 2022
13e2e25
Update delivery.md
tristan-charreton Jun 21, 2022
bf5145f
Update delivery-robots.md
tristan-charreton Jun 21, 2022
735415a
Update and rename delivery-robots.md to delivery.md
tristan-charreton Jun 22, 2022
3323e89
Update delivery.md
tristan-charreton Jun 30, 2022
c8224ba
Update delivery.md
tristan-charreton Jul 11, 2022
2d4f5f0
Update event_types.md
tristan-charreton Jul 13, 2022
beb5d3e
Update delivery.md
tristan-charreton Jul 13, 2022
68fce9b
Update delivery.md
tristan-charreton Jul 13, 2022
3bb87e8
Update delivery.md
tristan-charreton Jul 13, 2022
394e910
Update README.md
tristan-charreton Jul 19, 2022
274fbbf
Update event_types.md
tristan-charreton Jul 19, 2022
06dccd9
Update delivery.md
tristan-charreton Jul 19, 2022
4ff3453
Update event_types.md
tristan-charreton Jul 19, 2022
2f0e0f9
Update delivery.md
tristan-charreton Jul 19, 2022
ae56309
Merge branch 'delivery' into feature-modes-delivery
tristan-charreton Sep 13, 2022
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
2 changes: 1 addition & 1 deletion agency/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -372,7 +372,7 @@ The Trips endpoint serves two purposes:
| Field | Type | Required/Optional | Field Description |
|-------------------------------|--------------------------------|------------------------| ----------------- |
| trip_id | UUID | Required | UUID for the trip this payload pertains to |
| journey_id | UUID | Optional | A unique ID for associating collections of trips |
| trip_type | Enum | Optional | The type of the trip |
| trip_attributes | `{ [String]: String}` | Optional | Trip attributes, given as mode-specific key-value pairs |
| provider_id | UUID | Required | Provider which managed this trip |
| reservation_method | Enum | Required | Way the customer created their reservation, see [reservation-method](#reservation-method) |
Expand Down
1 change: 1 addition & 0 deletions general-information.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -344,6 +344,7 @@ The list of allowed `vehicle_type` values in MDS. Aligning with [GBFS vehicle ty
| car | A passenger car or similar light-duty vehicle |
| scooter | A standing or seated fully-motorized mobility device intended for one rider, capable of travel at low or moderate speeds, and suited for operation in infrastructure shared with motorized bicycles |
| moped | A seated fully-motorized mobility device capable of travel at moderate or high speeds and suited for operation in general urban traffic |
| delivery_robot | A robot intended for transporting goods |
| other | A device that does not fit in the other categories |

[Top][toc]
Expand Down
262 changes: 262 additions & 0 deletions modes/delivery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,262 @@
# Mobility Data Specification: **Delivery**


**Delivey** refers to all forms of deliveries. Deliveries may or may not have a driver, there can be one or multiple orders on different trips at the same time. The state machine tracks the trip states of the orders separately from the vehicle state.

See the [modes overview](/modes) for how the mode specific information below applies across MDS.

## Robots Vs Other vehicles types
Robots do not require a driver whereas other forms of deliveries do. For most of the robots delivery operators, there is only one order at once. The idea here is to anticipate all forms of deliveries and to accept having many orders at once on one vehicle.


## Table of Contents

- [Mode Attributes](#mode-attributes)
- [Vehicle States](#vehicle-states)
- [Event Types](#event-types)
- [Vehicle State Events](#vehicle-states-events)
- [State Machine Diagram](#state-machine-diagram)

## Mode Attributes

### Mode ID

The short name identifier for deliveries used across MDS is `delivery`.

### Journey ID

Journeys may be point-to-point, multi-segment, or multi-segment overlapping.

### Trip ID Requirements

Events require a valid `trip_id` in events where `event_types` contains `reservation_start`, `reservation_stop`, `trip_start`, `trip_stop`, `trip_end`, `customer_cancellation`, `provider_cancellation`, or `driver_cancellation`.

For the robots, the notion of driver does not exist

Additionally, `trip_id` is required if `event_types` contains a `enter_jurisdiction` or `leave_jurisdiction` event pertaining to a delivery trip.

### Trip Type

The `trip_type` field is used to describe the trip itself. It can be 'delivery' or 'roaming' or 'return' or 'advertising'

### Trip Attributes

The `trip_attributes` array can be used with in delivery.


### Vehicle Attributes

The `vehicle_attributes` array may have the following key value pairs:


- `year` (integer, optional)
- `make` (string, optional)
- `model` (string, optional)
- `color` (string, optional)
- `inspection_date` (date YYYY-MM-DD, optional) - the date of the last inspection of the vehicle


### Propulsion Types

#### Valid for vehicle_types: "bicycle", "cargo_bicycle",


| `propulsion` |
| ----------------- |
| `electric assist` |
| `human` |

#### Valid for vehicle_types: "scooter"

| `propulsion` |
| ----------------- |
| `electric` |
| `electric assist` |
| `human` |

#### Valid for vehicle_types: "car"; "moped"

| `propulsion` |
| ----------------- |
| `electric` |
| `electric assist` |
| `combustion` |


#### Valid for vehicle_types: "delivery_robot"
| `propulsion` |
| ----------------- |
| `electric` |


#### Valid for vehicle_types: "other"
| `propulsion` |
| ----------------- |
| `electric` |
| `electric assist` |
| `combustion` |
| `human` |



## Vehicle States

Valid delivery vehicle states are

- `removed`
- `available`
- `non_operational`
- `reserved`
- `on_trip`
- `stopped`
- `elsewhere`
- `unknown`

See [Vehicle States][vehicle-states] for descriptions.

[Top][toc]

## Event Types

Valid delivery vehicle event types are


- `agency_drop_off`
- `agency_pick_up`
- `battery_charged`
- `battery_low`
- `comms_lost`
- `comms_restored`
- `compliance_pick_up`
- `decommissioned`
- `located`
- `maintenance`
- `maintenance_pick_up`
- `missing`
- `off_hours`
- `on_hours`
- `driver_cancellation`
- `order_drop_off`
- `order_pick_up`
- `decommission`
- `maintenance_end`
- `maintenance_start`
- `customer_cancellation`
- `provider_cancellation`
- `recommission`
- `reservation_cancel`
- `reservation_start`
- `service_end`
- `service_start`
- `trip_cancel`
- `trip_end`
- `trip_enter_jurisdiction`
- `trip_leave_jurisdiction`
- `trip_resume`
- `trip_start`
- `trip_stop`
- `unspecified`


See vehicle [Event Types][vehicle-events] for descriptions.

[Top][toc]

## Vehicle States Events

This is the list of `vehicle_state` and `event_type` pairings that constitute the valid transitions of the vehicle state machine.

| **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 gone out of service (is unavailable for-hire) |
| `available` | `reserved` | `reserved` | `reserve` | The vehicle was reserved by a customer |
| `available` | `unknown` | N/A | `comms_lost` | The vehicle has gone 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 gone out of comms while outside of jurisdictional boundaries |
| `non_operational` | `available` | N/A | `service_start` | The vehicle has gone 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 gone 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` | `stopped` | `stopped` | `order_pick_up` | The vehicle has stopped while on a trip |
| `on_trip` | `unknown` | N/A | `comms_lost` | The vehicle has gone out of comms while on a trip to pick up the order |
| `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 gone out of comms while removed |
| `reserved` | `available` | N/A | `driver_cancellation` | The driver has canceled the reservation |
| `reserved` | `available` | N/A | `customer_cancellation` | The customer has canceled the reservation |
| `reserved` | `available` | N/A | `provider_cancellation` | The provider has canceled 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 delivery |
| `reserved` | `unknown` | N/A | `comms_lost` | The vehicle has gone of comms while being reserved by a customer |
| `stopped` | `available` | N/A | `driver_cancellation` | The driver has canceled the trip while waiting |
| `stopped` | `available` | N/A | `customer_cancellation` | The customer has canceled the trip while the vehicle is waiting |
| `stopped` | `available` | N/A | `provider_cancellation` | The provider has canceled the trip while the vehicle is waiting |
| `on_trip` | `available` | N/A | `order_drop_off` | The delivery vehicle has stopped to wait for the customer to pick up the order |
| `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 an order |
| `stopped` | `on_trip` | `on_trip` | `trip_start` | Start a trip |
| `stopped` | `unknown` | N/A | `comms_lost` | The vehicle has gone 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` | `removed` | N/A | `comms_restored` | The vehicle has come back into comms while removed |
| `unknown` | `reserved` | `reserved` | `comms_restored` | The vehicle has come back into comms while reserved by a customer |
| `unknown` | `stopped` | `stopped` | `comms_restored` | The vehicle has come back into comms while stopped |
| `on_trip` | `stopped` | `stopped` | `order_pick_up` | The vehicle has come to pick up the order at the restaurant |
| `on_trip` |`available` | N/A | `order_drop_off` | The vehicle is at the customer's place and is waiting for them |
| `on_trip` | `stopped` | `stopped` | `order_pick_up` | The vehicle has come to pick up the order at the restaurant |





### State Machine Diagram

The *Delivery Diagram* shows how the `vehicle_state` and `event_type` relate to each other and how delivery vehicles can transition between states.

#### Delivery 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:
```
t = for the one vehicle, all on-going trips which are 'delivey' or undefined trips (we do not take into account 'roaming', 'return' or 'advertising' trips)
v = vehicle state
if t.any(state == ‘stopped’):
v = ‘stopped’
else:
if t.any(state == ‘on_trip’):
v = ‘on_trip’
else:
if t.any(state == ‘reserved’):
v = ‘reserved’
else:
if t=[]:
v = ‘available’

```
`trip_state` mappings should be the same as in the table above.

[Top][toc]

---

[Modes Overview][modes]

---

[MDS Home][home]

[home]: /README.md
[modes]: /modes/README.md
[toc]: #table-of-contents
[vehicle-states]: /modes/vehicle_states.md
[vehicle-events]: /modes/event_types.md
6 changes: 5 additions & 1 deletion modes/event_types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ As with all MDS definitions, they should be described in a way that maximizes th
| `comms_lost` | Communications lost |
| `comms_restored` | Communications restored |
| `compliance_pick_up` | Pick up for compliance (rule violation) |
| `order_drop_off` | Pick up of the order at the restaurant or shop or warehouse |
| `order_pick_up` | Delivery of the order at the customer's |
| `decommissioned` | Decommissioned |
| `driver_cancellation` | Driver cancelled a trip |
| `located` | Located (opposite of Missing) |
Expand All @@ -21,7 +23,7 @@ As with all MDS definitions, they should be described in a way that maximizes th
| `missing` | Missing |
| `off_hours` | Off hours - end of service |
| `on_hours` | On hours - start of service |
| `passenger_cancellation` | Passenger cancelled a trip |
| `customer_cancellation` | Customer cancelled a trip |
| `provider_cancellation` | Provider cancelled a trip |
| `provider_drop_off` | Drop off by the provider |
| `rebalance_pick_up` | Pick up for rebalancing |
Expand All @@ -34,6 +36,8 @@ As with all MDS definitions, they should be described in a way that maximizes th
| `trip_enter_jurisdiction` | Trip enters a jurisdiction |
| `trip_leave_jurisdiction` | Trip leaves a jurisdiction |
| `trip_start` | Start trip |
| `trip_stop` | Stop trip |
| `trip_resume` | Resume trip |
| `unspecified` | Unspecified |

### Limitations on the Use of Certain Values
Expand Down