Skip to content

Commit 435b2e0

Browse files
schnuerleschnuerle
authored
Merge pull request #788 from tristan-charreton/delivery
Bringing Delivery work into Delivery Robots
2 parents 8881a1d + 7080f69 commit 435b2e0

File tree

4 files changed

+269
-2
lines changed

4 files changed

+269
-2
lines changed

‎agency/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -372,7 +372,7 @@ The Trips endpoint serves two purposes:
372372
| Field | Type | Required/Optional | Field Description |
373373
|-------------------------------|--------------------------------|------------------------| ----------------- |
374374
| trip_id | UUID | Required | UUID for the trip this payload pertains to |
375-
| journey_id | UUID | Optional | A unique ID for associating collections of trips |
375+
| trip_type | Enum | Optional | The type of the trip |
376376
| trip_attributes | `{ [String]: String}` | Optional | Trip attributes, given as mode-specific key-value pairs |
377377
| provider_id | UUID | Required | Provider which managed this trip |
378378
| reservation_method | Enum | Required | Way the customer created their reservation, see [reservation-method](#reservation-method) |

‎general-information.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -342,6 +342,7 @@ The list of allowed `vehicle_type` values in MDS. Aligning with [GBFS vehicle ty
342342
| car | A passenger car or similar light-duty vehicle |
343343
| 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 |
344344
| moped | A seated fully-motorized mobility device capable of travel at moderate or high speeds and suited for operation in general urban traffic |
345+
| delivery_robot | A robot intended for transporting goods |
345346
| other | A device that does not fit in the other categories |
346347

347348
[Top][toc]

‎modes/delivery.md‎

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
# Mobility Data Specification: **Delivery**
2+
3+
4+
**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.
5+
6+
See the [modes overview](/modes) for how the mode specific information below applies across MDS.
7+
8+
## Robots Vs Other vehicles types
9+
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.
10+
11+
12+
## Table of Contents
13+
14+
- [Mode Attributes](#mode-attributes)
15+
- [Vehicle States](#vehicle-states)
16+
- [Event Types](#event-types)
17+
- [Vehicle State Events](#vehicle-states-events)
18+
- [State Machine Diagram](#state-machine-diagram)
19+
20+
## Mode Attributes
21+
22+
### Mode ID
23+
24+
The short name identifier for deliveries used across MDS is `delivery`.
25+
26+
### Journey ID
27+
28+
Journeys may be point-to-point, multi-segment, or multi-segment overlapping.
29+
30+
### Trip ID Requirements
31+
32+
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`.
33+
34+
For the robots, the notion of driver does not exist
35+
36+
Additionally, `trip_id` is required if `event_types` contains a `enter_jurisdiction` or `leave_jurisdiction` event pertaining to a delivery trip.
37+
38+
### Trip Type
39+
40+
The `trip_type` field is used to describe the trip itself. It can be 'delivery' or 'roaming' or 'return' or 'advertising'
41+
42+
### Trip Attributes
43+
44+
The `trip_attributes` array can be used with in delivery.
45+
46+
47+
### Vehicle Attributes
48+
49+
The `vehicle_attributes` array may have the following key value pairs:
50+
51+
52+
- `year` (integer, optional)
53+
- `make` (string, optional)
54+
- `model` (string, optional)
55+
- `color` (string, optional)
56+
- `inspection_date` (date YYYY-MM-DD, optional) - the date of the last inspection of the vehicle
57+
58+
59+
### Propulsion Types
60+
61+
#### Valid for vehicle_types: "bicycle", "cargo_bicycle",
62+
63+
64+
| `propulsion` |
65+
| ----------------- |
66+
| `electric assist` |
67+
| `human` |
68+
69+
#### Valid for vehicle_types: "scooter"
70+
71+
| `propulsion` |
72+
| ----------------- |
73+
| `electric` |
74+
| `electric assist` |
75+
| `human` |
76+
77+
#### Valid for vehicle_types: "car"; "moped"
78+
79+
| `propulsion` |
80+
| ----------------- |
81+
| `electric` |
82+
| `electric assist` |
83+
| `combustion` |
84+
85+
86+
#### Valid for vehicle_types: "delivery_robot"
87+
| `propulsion` |
88+
| ----------------- |
89+
| `electric` |
90+
91+
92+
#### Valid for vehicle_types: "other"
93+
| `propulsion` |
94+
| ----------------- |
95+
| `electric` |
96+
| `electric assist` |
97+
| `combustion` |
98+
| `human` |
99+
100+
101+
102+
## Vehicle States
103+
104+
Valid delivery vehicle states are
105+
106+
- `removed`
107+
- `available`
108+
- `non_operational`
109+
- `reserved`
110+
- `on_trip`
111+
- `stopped`
112+
- `elsewhere`
113+
- `unknown`
114+
115+
See [Vehicle States][vehicle-states] for descriptions.
116+
117+
[Top][toc]
118+
119+
## Event Types
120+
121+
Valid delivery vehicle event types are
122+
123+
124+
- `agency_drop_off`
125+
- `agency_pick_up`
126+
- `battery_charged`
127+
- `battery_low`
128+
- `comms_lost`
129+
- `comms_restored`
130+
- `compliance_pick_up`
131+
- `decommissioned`
132+
- `located`
133+
- `maintenance`
134+
- `maintenance_pick_up`
135+
- `missing`
136+
- `off_hours`
137+
- `on_hours`
138+
- `driver_cancellation`
139+
- `order_drop_off`
140+
- `order_pick_up`
141+
- `decommission`
142+
- `maintenance_end`
143+
- `maintenance_start`
144+
- `customer_cancellation`
145+
- `provider_cancellation`
146+
- `recommission`
147+
- `reservation_cancel`
148+
- `reservation_start`
149+
- `service_end`
150+
- `service_start`
151+
- `trip_cancel`
152+
- `trip_end`
153+
- `trip_enter_jurisdiction`
154+
- `trip_leave_jurisdiction`
155+
- `trip_resume`
156+
- `trip_start`
157+
- `trip_stop`
158+
- `unspecified`
159+
160+
161+
See vehicle [Event Types][vehicle-events] for descriptions.
162+
163+
[Top][toc]
164+
165+
## Vehicle States Events
166+
167+
This is the list of `vehicle_state` and `event_type` pairings that constitute the valid transitions of the vehicle state machine.
168+
169+
| **Previous** `vehicle_state` | `vehicle_state` | `trip_state` | `event_type` | Description |
170+
|------------------------------|-------------------|--------------|--------------------------|------------------------------------------------------------------------------------------------------------------|
171+
| `available` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left jurisdictional boundaries while available for-hire |
172+
| `available` | `non_operational` | N/A | `service_end` | The vehicle has gone out of service (is unavailable for-hire) |
173+
| `available` | `reserved` | `reserved` | `reserve` | The vehicle was reserved by a customer |
174+
| `available` | `unknown` | N/A | `comms_lost` | The vehicle has gone out of comms while available for-use |
175+
| `elsewhere` | `available` | N/A | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while available for-hire |
176+
| `elsewhere` | `non_operational` | N/A | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while not operating commercially |
177+
| `elsewhere` | `on_trip` | `on_trip` | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while on a trip |
178+
| `elsewhere` | `reserved` | N/A | `enter_jurisdiction` | The vehicle has entered jurisdictional boundaries while reserved by a customer |
179+
| `elsewhere` | `unknown` | N/A | `comms_lost` | The vehicle has gone out of comms while outside of jurisdictional boundaries |
180+
| `non_operational` | `available` | N/A | `service_start` | The vehicle has gone into service (is available for-hire) |
181+
| `non_operational` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left jurisdictional boundaries while not operating commercially |
182+
| `non_operational` | `removed` | N/A | `decommissioned` | The vehicle has been removed from the Provider's fleet |
183+
| `non_operational` | `removed` | N/A | `maintenance_start` | The vehicle has entered the depot for maintenance |
184+
| `non_operational` | `unknown` | N/A | `comms_lost` | The vehicle has gone out of comms while not operating commercially |
185+
| `on_trip` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left jurisdictional boundaries while on a trip |
186+
| `on_trip` | `stopped` | `stopped` | `trip_stop` | The vehicle has stopped while on a trip |
187+
| `on_trip` | `stopped` | `stopped` | `order_pick_up` | The vehicle has stopped while on a trip |
188+
| `on_trip` | `unknown` | N/A | `comms_lost` | The vehicle has gone out of comms while on a trip to pick up the order |
189+
| `removed` | `non_operational` | N/A | `maintenance_end` | The vehicle has left the depot |
190+
| `removed` | `non_operational` | N/A | `recommissioned` | The vehicle has been re-added to the Provider's fleet after being previously `decommissioned` |
191+
| `removed` | `unknown` | N/A | `comms_lost` | The vehicle has gone out of comms while removed |
192+
| `reserved` | `available` | N/A | `driver_cancellation` | The driver has canceled the reservation |
193+
| `reserved` | `available` | N/A | `customer_cancellation` | The customer has canceled the reservation |
194+
| `reserved` | `available` | N/A | `provider_cancellation` | The provider has canceled the reservation |
195+
| `reserved` | `elsewhere` | N/A | `leave_jurisdiction` | The vehicle has left the jurisdiction while in a reservation |
196+
| `reserved` | `stopped` | `stopped` | `reserve_stop` | The vehicle has stopped to pick up the delivery |
197+
| `reserved` | `unknown` | N/A | `comms_lost` | The vehicle has gone of comms while being reserved by a customer |
198+
| `stopped` | `available` | N/A | `driver_cancellation` | The driver has canceled the trip while waiting |
199+
| `stopped` | `available` | N/A | `customer_cancellation` | The customer has canceled the trip while the vehicle is waiting |
200+
| `stopped` | `available` | N/A | `provider_cancellation` | The provider has canceled the trip while the vehicle is waiting |
201+
| `on_trip` | `available` | N/A | `order_drop_off` | The delivery vehicle has stopped to wait for the customer to pick up the order |
202+
| `stopped` | `available` | N/A | `trip_end` | The trip has been successfully completed |
203+
| `stopped` | `on_trip` | `on_trip` | `trip_resume` | Resume a trip that was previously stopped (e.g. picking up an order |
204+
| `stopped` | `on_trip` | `on_trip` | `trip_start` | Start a trip |
205+
| `stopped` | `unknown` | N/A | `comms_lost` | The vehicle has gone out of comms while stopped |
206+
| `unknown` | `available` | N/A | `comms_restored` | The vehicle has come back into comms while available for-hire |
207+
| `unknown` | `elsewhere` | N/A | `comms_restored` | The vehicle has come back into comms while outside of jurisdictional boundaries |
208+
| `unknown` | `non_operational` | N/A | `comms_restored` | The vehicle has come back into comms while not operating commercially |
209+
| `unknown` | `on_trip` | `on_trip` | `comms_restored` | The vehicle has come back into comms while on a trip |
210+
| `unknown` | `removed` | N/A | `comms_restored` | The vehicle has come back into comms while removed |
211+
| `unknown` | `reserved` | `reserved` | `comms_restored` | The vehicle has come back into comms while reserved by a customer |
212+
| `unknown` | `stopped` | `stopped` | `comms_restored` | The vehicle has come back into comms while stopped |
213+
| `on_trip` | `stopped` | `stopped` | `order_pick_up` | The vehicle has come to pick up the order at the restaurant |
214+
| `on_trip` |`available` | N/A | `order_drop_off` | The vehicle is at the customer's place and is waiting for them |
215+
| `on_trip` | `stopped` | `stopped` | `order_pick_up` | The vehicle has come to pick up the order at the restaurant |
216+
217+
218+
219+
220+
221+
### State Machine Diagram
222+
223+
The *Delivery Diagram* shows how the `vehicle_state` and `event_type` relate to each other and how delivery vehicles can transition between states.
224+
225+
#### Delivery State Notes
226+
227+
When there is only one trip ongoing, `trip_state == vehicle_state`
228+
229+
In cases where there are multiple trips ongoing, please follow the trip state model pseudocode for determining what the vehicle state should be:
230+
```
231+
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)
232+
v = vehicle state
233+
if t.any(state == ‘stopped’):
234+
v = ‘stopped’
235+
else:
236+
if t.any(state == ‘on_trip’):
237+
v = ‘on_trip’
238+
else:
239+
if t.any(state == ‘reserved’):
240+
v = ‘reserved’
241+
else:
242+
if t=[]:
243+
v = ‘available’
244+
245+
```
246+
`trip_state` mappings should be the same as in the table above.
247+
248+
[Top][toc]
249+
250+
---
251+
252+
[Modes Overview][modes]
253+
254+
---
255+
256+
[MDS Home][home]
257+
258+
[home]: /README.md
259+
[modes]: /modes/README.md
260+
[toc]: #table-of-contents
261+
[vehicle-states]: /modes/vehicle_states.md
262+
[vehicle-events]: /modes/event_types.md

‎modes/event_types.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ As with all MDS definitions, they should be described in a way that maximizes th
1313
| `comms_lost` | Communications lost |
1414
| `comms_restored` | Communications restored |
1515
| `compliance_pick_up` | Pick up for compliance (rule violation) |
16+
| `order_drop_off` | Pick up of the order at the restaurant or shop or warehouse |
17+
| `order_pick_up` | Delivery of the order at the customer's |
1618
| `decommissioned` | Decommissioned |
1719
| `driver_cancellation` | Driver cancelled a trip |
1820
| `located` | Located (opposite of Missing) |
@@ -21,7 +23,7 @@ As with all MDS definitions, they should be described in a way that maximizes th
2123
| `missing` | Missing |
2224
| `off_hours` | Off hours - end of service |
2325
| `on_hours` | On hours - start of service |
24-
| `passenger_cancellation` | Passenger cancelled a trip |
26+
| `customer_cancellation` | Customer cancelled a trip |
2527
| `provider_cancellation` | Provider cancelled a trip |
2628
| `provider_drop_off` | Drop off by the provider |
2729
| `rebalance_pick_up` | Pick up for rebalancing |
@@ -34,6 +36,8 @@ As with all MDS definitions, they should be described in a way that maximizes th
3436
| `trip_enter_jurisdiction` | Trip enters a jurisdiction |
3537
| `trip_leave_jurisdiction` | Trip leaves a jurisdiction |
3638
| `trip_start` | Start trip |
39+
| `trip_stop` | Stop trip |
40+
| `trip_resume` | Resume trip |
3741
| `unspecified` | Unspecified |
3842

3943
### Limitations on the Use of Certain Values

0 commit comments

Comments
 (0)