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

Add repeated CarriageDescriptor to VehicleDescriptor to encapsulate carriage specific information #66

Closed
wants to merge 11 commits into from
Closed

Add repeated CarriageDescriptor to VehicleDescriptor to encapsulate carriage specific information #66

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
b7bb2f6
whatevs
Jul 11, 2017
59f7c4c
Add CarriageDescriptor.
Jul 11, 2017
141479a
Fix up TOC and formatting.
Jul 11, 2017
b228b28
Add extensions and fix documentation for CarriageDescriptor.
Jul 11, 2017
37e1f68
Added CarriageDescriptor to Spanish reference.
Jul 11, 2017
daa7b3c
Fixed anchors in spanish reference.
Jul 11, 2017
c840c75
cleanup.
Jul 11, 2017
75829dd
Revert Spanish anchor fixes. This is in PR #67.
Jul 13, 2017
e811fd4
Merge branch 'master' into gtfs_rt_carriage_info
RachM Jul 14, 2017
9acd8bc
Add carriage_sequence to explicitly define the carriage ordering.
Jul 17, 2017
314773c
Clarify that single-carriage vehicles (e.g. a standard bus) should ha…
Jul 17, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
121 changes: 120 additions & 1 deletion gtfs-realtime/proto/gtfs-realtime.proto
View file
Open in desktop
Expand Up @@ -215,7 +215,7 @@ message TripUpdate {
NO_DATA = 2;
}
optional ScheduleRelationship schedule_relationship = 5
[default = SCHEDULED];
[default = SCHEDULED];

// The extensions namespace allows 3rd-party developers to extend the
// GTFS Realtime Specification in order to add and evaluate new features
Expand Down Expand Up @@ -574,6 +574,125 @@ message VehicleDescriptor {
// The license plate of the vehicle.
optional string license_plate = 3;

// Contains amenities and other information about an individual carriage that
// is part of a vehicle.
message CarriageDescriptor {
// Internal system identification of the carriage. Should be unique per
// vehicle, and can be used for tracking the carriage as it proceeds through
// the system.
optional string id = 1;

// User visible label that may be shown to the passenger to help identify
// the carriage.
optional string label = 2;

// Identifies the order of this carriage with respect to the other
// carriages in the vehicle's list of CarriageDescriptors. The values must
// be non-negative, and there cannot be duplicate values in the list of
// CarriageDescriptors. The values must be set such that the lowest value
// corresponds to the first carriage in the direction of travel, the
// second-lowest value corresponds to the second carriage in the direction
// of travel and so forth. For example, the first carriage in the direction
// of travel could have a carriage_sequence of 4, the second carriage could
// have a carriage_sequence of 10, the third carriage could have a
// carriage_sequence of 105, and so forth.
optional int32 carriage_sequence = 3;

// The degree of passenger occupancy of the carriage.
optional VehiclePosition.OccupancyStatus occupancy_status = 4;

// Whether the carriage is wheelchair accessible.
enum WheelchairAccessible {
// It is unknown if the carriage is wheelchair accessible. This is the
// default case.
UNKNOWN = 0;

// The carriage is wheelchair accessible.
WHEELCHAIR_ACCESSIBLE = 1;

// The carriage is not wheelchair accessible.
NOT_WHEELCHAIR_ACCESSIBLE = 2;
}

optional WheelchairAccessible wheelchair_accessible = 5 [default = UNKNOWN];

// Whether the carriage has toilet facilities onboard.
enum ToiletFacilities {
// It is unknown if the carriage has toilet facilities. This is the
// default case.
UNKNOWN = 0;

// The carriage has toilet facilities onboard.
TOILET_ONBOARD = 1;

// The carriage does not have toilet facilities onboard.
NO_TOILET_ONBOARD = 2;
}

optional ToiletFacilities toilet_facilities = 6 [default = UNKNOWN];

// Whether the carriage has WiFi onboard.
enum WifiAvailability {
// It is unknown if the carriage has WiFi. This is the default case.
UNKNOWN = 0;

// The carriage has free WiFi available for passengers to use.
FREE_WIFI = 1;

// The carriage has WiFi available for passengers to purchase.
PAID_WIFI = 2;

// The carriage has no WiFi available for passengers to use.
NO_WIFI = 3;
}

optional WifiAvailability wifi_availability = 7 [default = UNKNOWN];

// Whether the carriage is air conditioned.
enum AirConditioning {
// It is unknown if the carriage is air conditioned. This is the default
// case.
UNKNOWN = 0;

// The carriage has air conditioning.
AIR_CONDITIONED = 1;

// The carriage does not have air conditioning.
NOT_AIR_CONDITIONED = 2;
}

optional AirConditioning air_conditioning = 8 [default = UNKNOWN];

// Whether bicycles are allowed in the carriage.
enum BicyclesAllowed {
// It is unknown if the carriage allows bicycles. This is the default
// case.
UNKNOWN = 0;

// Bicycles are allowed to be transported, but must be stored outside of
// the carriage.
ALLOWED_OUTSIDE_CARRIAGE = 1;

// Bicycles are allowed to be transported, and can be stored inside the
// carriage.
ALLOWED_INSIDE_CARRIAGE = 2;

// Bicycles are not allowed to be transported in this carriage.
NOT_ALLOWED = 3;
}

optional BicyclesAllowed bicycles_allowed = 9 [default = UNKNOWN];

// The extensions namespace allows 3rd-party developers to extend the
// GTFS Realtime Specification in order to add and evaluate new features and
// modifications to the spec.
extensions 1000 to 1999;
}

// A set of CarriageDescriptor. Vehicles with only one carriage/compartment
// (e.g. a standard bus) will only have one CarriageDescriptor.
repeated CarriageDescriptor carriage_descriptor = 4;

// The extensions namespace allows 3rd-party developers to extend the
// GTFS Realtime Specification in order to add and evaluate new features and
// modifications to the spec.
Expand Down
113 changes: 104 additions & 9 deletions gtfs-realtime/spec/en/reference.md
View file
Open in desktop
Expand Up @@ -20,13 +20,27 @@ Version 1.0 of the feed specification is discussed and documented on this site.
* [TripDescriptor](#message-tripdescriptor)
* [ScheduleRelationship](#enum-schedulerelationship-1)
* [VehicleDescriptor](#message-vehicledescriptor)
* [CarriageDescriptor](#message-carriagedescriptor)
* [OccupancyStatus](#enum-occupancystatus)
* [WheelchairAccessible](#enum-wheelchairaccessible)
* [ToiletFacilities](#enum-toiletfacilities)
* [WifiAvailability](#enum-wifiavailability)
* [AirConditioning](#enum-airconditioning)
* [BicyclesAllowed](#enum-bicyclesallowed)
* [StopTimeUpdate](#message-stoptimeupdate)
* [StopTimeEvent](#message-stoptimeevent)
* [ScheduleRelationship](#enum-schedulerelationship)
* [VehiclePosition](#message-vehicleposition)
* [TripDescriptor](#message-tripdescriptor)
* [ScheduleRelationship](#enum-schedulerelationship-1)
* [VehicleDescriptor](#message-vehicledescriptor)
* [CarriageDescriptor](#message-carriagedescriptor)
* [OccupancyStatus](#enum-occupancystatus)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There was a design decision made when originally adding OccupancyStatus that VehicleDescriptor should only contain immutable information, while VehiclePosition should contain mutable statuses (discussion starting at https://groups.google.com/d/msg/gtfs-realtime/_HtNTGp5LxM/86U3GGxDbngJ).

This proposal breaks from that design decision by putting OccupancyStatus as a child element of VehicleDescriptor->CarriageDescriptor. You could also argue that some of the other elements are mutable as well (e.g., bathroom closed for cleaning/maintenance, bikes allowed only at certain times of the day).

At the time of the OccupancyStatus proposal, I actually argued for including OccupancyStatus in VehicleDescriptor instead of VehiclePosition, but was overruled :). I bring this up for discussion - please discuss :).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the context Sean!

My reasoning for putting it in VehicleDescriptor:

  • It seems like a property of the vehicle, and I (perhaps naively) thought VehicleDescriptor encapsulated properties of vehicles. I don't see why we should strive to maintain immutability, especially when this isn't mentioned (or enforced?) anywhere.
  • By putting it in VehicleDescriptor, it gets to be in either/both TripUpdates and VehiclePositions.

I didn't realise VehicleDescriptor was intended to be immutable. If people care deeply about maintaining this, then perhaps we should at least document this in the spec?

Keen to hear others thoughts :-)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@RachM That was my exact same reasoning for originally proposing OccupancyStatus in VehicleDescriptor. So, I'm also interested to hear others thoughts :).

* [WheelchairAccessible](#enum-wheelchairaccessible)
* [ToiletFacilities](#enum-toiletfacilities)
* [WifiAvailability](#enum-wifiavailability)
* [AirConditioning](#enum-airconditioning)
* [BicyclesAllowed](#enum-bicyclesallowed)
* [Position](#message-position)
* [VehicleStopStatus](#enum-vehiclestopstatus)
* [CongestionLevel](#enum-congestionlevel)
Expand Down Expand Up @@ -208,21 +222,21 @@ Congestion level that is affecting this vehicle.

## _enum OccupancyStatus_

The degree of passenger occupancy for the vehicle.
The degree of passenger occupancy for the vehicle or carriage.

**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.

#### _Values_

| _**Value**_ | _**Comment**_ |
|-------------|---------------|
| _**EMPTY**_ | _The vehicle is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers._ |
| _**MANY_SEATS_AVAILABLE**_ | _The vehicle has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer._ |
| _**FEW_SEATS_AVAILABLE**_ | _The vehicle has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer._ |
| _**STANDING_ROOM_ONLY**_ | _The vehicle can currently accomodate only standing passengers._ |
| _**CRUSHED_STANDING_ROOM_ONLY**_ | _The vehicle can currently accomodate only standing passengers and has limited space for them._ |
| _**FULL**_ | _The vehicle is considered full by most measures, but may still be allowing passengers to board._ |
| _**NOT_ACCEPTING_PASSENGERS**_ | _The vehicle can not accept passengers._ |
| _**EMPTY**_ | _The vehicle/carriage is considered empty by most measures, and has few or no passengers onboard, but is still accepting passengers._ |
| _**MANY_SEATS_AVAILABLE**_ | _The vehicle/carriage has a large percentage of seats available. What percentage of free seats out of the total seats available is to be considered large enough to fall into this category is determined at the discretion of the producer._ |
| _**FEW_SEATS_AVAILABLE**_ | _The vehicle/carriage has a small percentage of seats available. What percentage of free seats out of the total seats available is to be considered small enough to fall into this category is determined at the discretion of the producer._ |
| _**STANDING_ROOM_ONLY**_ | _The vehicle/carriage can currently accommodate only standing passengers._ |
| _**CRUSHED_STANDING_ROOM_ONLY**_ | _The vehicle/carriage can currently accommodate only standing passengers and has limited space for them._ |
| _**FULL**_ | _The vehicle/carriage is considered full by most measures, but may still be allowing passengers to board._ |
| _**NOT_ACCEPTING_PASSENGERS**_ | _The vehicle/carriage can not accept passengers._ |

## _message_ Alert

Expand Down Expand Up @@ -340,9 +354,90 @@ Identification information for the vehicle performing the trip.

| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ |
|------------------|------------|-------------------|-------------------|
| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the vehicle. Should be **unique** per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field |
| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the vehicle. Should be **unique** per vehicle, and is used for tracking the vehicle as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field. |
| **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that must be shown to the passenger to help identify the correct vehicle. |
| **license_plate** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | The license plate of the vehicle. |
| **carriage_descriptor** | [CarriageDescriptor](#message-carriagedescriptor) | repeated | A set of carriage information. Vehicles with only one carriage/compartment (e.g. a standard bus) will only have one CarriageDescriptor. When there are more than one CarriageInformation, **carriage_sequence** defines the ordering of the carriages. |

## _message_ CarriageDescriptor

Information for a carriage that is part of a vehicle.

#### Fields

| _**Field Name**_ | _**Type**_ | _**Cardinality**_ | _**Description**_ |
|------------------|------------|-------------------|-------------------|
| **id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Internal system identification of the carriage. Should be **unique** per vehicle, and is used for tracking the carriage as it proceeds through the system. This id should not be made visible to the end-user; for that purpose use the **label** field. |
| **label** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | User visible label, i.e., something that can be shown to the passenger to help identify the correct carriage. |
| **carriage_sequence** | [int32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | optional | Identifies the order of this carriage with respect to the other carriages in the set of the vehicle's CarriageDescriptors. The values must be non-negative, and there cannot be duplicate values in the set of CarriageDescriptors. The values must be set such that the lowest value corresponds to the first carriage in the direction of travel, the second-lowest value corresponds to the second carriage in the direction of travel and so forth.|
| _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _optional_ |The degree of passenger occupancy of the carriage.<br>**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.|
| **wheelchair_accessible** | [WheelchairAccessible](#enum-wheelchairaccessible) | optional | Whether the carriage is wheelchair accessible. |
| **toilet_facilities** | [ToiletFacilities](#enum-toiletfacilities) | optional | Whether the carriage has toilet facilities onboard. |
| **wifi_availability** | [WifiAvailability](#enum-wifiavailability) | optional | Whether the carriage has WiFi onboard. |
| **air_conditioning** | [AirConditioning](#enum-airconditioning) | optional | Whether the carriage is air conditioned. |
| **bicycles_allowed** | [BicyclesAllowed](#enum-bicyclesallowed) | optional | Whether bicycles are allowed in the carriage. |

## _enum_ WheelchairAccessible
Copy link
Collaborator

@barbeau barbeau Jul 12, 2017 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wheelchair accessibility always seems to be a tricky one to tackle. I'd love to see this included, although I'd be curious to hear from producers whether or not carriage wheelchair accessibility can be appropriately modeled as a boolean (effectively, given the below enumerations). For example, does WHEELCHAIR_ACCESSIBLE mean that a wheelchair can board the carriage (i.e., travel through the doorway)? Or does it mean that there is accessible seating/tiedowns for a wheelchair? Are toilet facilities accessible to a wheelchair? All / some / none of the above?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi everyone, Sean asked me to comment on this thread. I lead a research center on accessible transportation which includes both IT and vehicle accessibility research. Being able to specify a vehicle is wheelchair accessible is important but there are some subtle nuances you all might want to consider.

As Sean mentioned, there's a difference between accessible boarding and there being accessibility features inside the vehicle. There are also cases where the accessible boarding is only at certain stations that have the right height platforms or portable lifts. Furthermore, wheelchair access is sometimes limited to specific cars on a train. Since boarding is often tied to stations or even train platforms, you may want to split boarding out from vehicle interior. Perhaps something like AccessibleBoarding (yes, no, accessible platforms only, unknown) and WheelchairParkingArea (integer from 0). These are just brainstorms since I don't know the rest of the vehicle spec discussions.

I recommend adding something to the toilet and dining car elements (if any) to indicate whether those facilities are accessible, rather than trying to fold it into a single accessibility element.

As an aside, you may also want to think about in-vehicle announcements as an element too. Visual message signs, audio announcements, etc. Those have universal value beyond just deaf and blind riders.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks so much for the insightful comments! It's fantastic to have an accessibility expert weigh in; I'm keen to get this right.

In regards to having the accessible boarding tied to the vehicle; I've experienced both a stop/station needing to be accessible as well as the vehicle. We already capture stop accessibility (wheelchair_boarding in stops.txt), but I thought it would be useful to capture vehicle as well (for the scenario where only some vehicles servicing the stop are wheelchair-boarding accessible). The use case I have in mind is buses in Sydney; not all are wheelchair accessible, and I think it would be great to show this information to users so they can better plan their trips.

I think it's clear that my original accessibility field is too simplistic. Maybe we need a whole message to encapsulate all of the relevant accessibility information? Maybe it doesn't all belong in a message? I'll think more about this....

Summarizing the potentially important accessibility features:

  • Accessible boarding
  • Accessible boarding instructions?
  • Wheelchair parking area
  • Accessible seating
  • Accessible toilet facilities
  • Braille signage
  • Audio announcements
  • Visual announcements

Anything else that I'm missing?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Potentially hearing "T" loop for the audio announcements as well?

A common complaint from wheelchair users is that there's no way to determine if the designated wheelchair spaces on-board are already occupied. It's one thing to have a wheelchair parking space, but they're only useful if they're available. It's a similar scenario for accessible seating.

Perhaps availability of wheelchair parking can be expressed as:

  • There is a parking space, but they are all occupied
  • There is a parking space, and there is at least one available
  • There is a parking space, and its availability is unknown (if the operator cannot determine its availability in real-time)
  • There is no parking space

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great point! One concern; are producers able to capture this type of information?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that audio announcements can vary between computer announcements and operator announcements. The latter are notoriously unintelligible in most systems since operators frequently mumble or fail to speak loudly.

We've looked at wheelchair space occupancy in our crowdsourcing transit information app (Tiramisu) and intentionally opted for overall vehicle loading instead. In most cases there is a direct relationship between loading and wheelchair space availability. Our concern about about using wheelchair space in a crowdsource system was twofold. First, most non-experts might not properly classify an opening if people without disabilities are seated in those areas. Second, we were concerned about malicious reporting that spots were full so people with wheelchairs would opt for another bus, thereby discouraging long dwell times for ingress/egress.


Whether the carriage is wheelchair accessible. The default is UNKNOWN.

#### Values

| _**Value**_ | _**Comment**_ |
|-------------|---------------|
| **UNKNOWN** | It is unknown if the carriage is wheelchair accessible. This is the default case. |
| **WHEELCHAIR_ACCESSIBLE** | The carriage is wheelchair accessible. |
| **NOT_WHEELCHAIR_ACCESSIBLE** | The carriage is not wheelchair accessible. |

## _enum_ ToiletFacilities

Whether the carriage has toilet facilities onboard. The default is UNKNOWN.

#### Values

| _**Value**_ | _**Comment**_ |
|-------------|---------------|
| **UNKNOWN** | It is unknown if the carriage has toilet facilities. This is the default case. |
| **TOILET_ONBOARD** | The carriage has toilet facilities onboard. |
| **NO_TOILET_ONBOARD** | The carriage does not have toilet facilities onboard. |

## _enum_ WifiAvailability

Whether the carriage has WiFi onboard. The default is UNKNOWN.

#### Values

| _**Value**_ | _**Comment**_ |
|-------------|---------------|
| **UNKNOWN** | It is unknown if the carriage has WiFi. This is the default case. |
| **FREE_WIFI** | The carriage has free WiFi available for passengers to use. |
| **PAID_WIFI** | The carriage has WiFi available for passengers to purchase. |
| **NO_WIFI** | The carriage has no WiFi available for passengers to use. |

## _enum_ AirConditioning

Whether the carriage is air conditioned. The default is UNKNOWN.

#### Values

| _**Value**_ | _**Comment**_ |
|-------------|---------------|
| **UNKNOWN** | It is unknown if the carriage is air conditioned. This is the default case. |
| **AIR_CONDITIONED** | The carriage has air conditioning. |
| **NOT_AIR_CONDITIONED** | The carriage does not have air conditioning. |

## _enum_ BicyclesAllowed

Whether bicycles are allowed in the carriage. The default is UNKNOWN.

#### Values

| _**Value**_ | _**Comment**_ |
|-------------|---------------|
| **UNKNOWN** | It is unknown if the carriage allows bicycles. This is the default case. |
| **ALLOWED_OUTSIDE_CARRIAGE** | Bicycles are allowed to be transported, but must be stored outside of the carriage. |
| **ALLOWED_INSIDE_CARRIAGE** | Bicycles are allowed to be transported, and can be stored inside the carriage. |
| **NOT_ALLOWED** | Bicycles are not allowed to be transported in this carriage. |

## _message_ EntitySelector

Expand Down
1 change: 1 addition & 0 deletions gtfs-realtime/spec/en/vehicle-positions.md
View file
Open in desktop
Expand Up @@ -57,3 +57,4 @@ Vehicle descriptor describes a precise physical vehicle and can contain any of t
* **ID** - internal system of identification for the vehicle. Should be unique to the vehicle
* **Label** - a user visible label - for example the name of a train
* **License plate** - the actual license plate of the vehicle
* **Carriage descriptor** - an ordered list where each item specifies information about a carriage