From d2ab9ad22897fdfa3d99f270c49557061f51dc9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Fontolliet?= Date: Mon, 27 Jul 2020 11:28:42 -0400 Subject: [PATCH 1/6] multi car crowding - spec proposal --- gtfs-realtime/proto/gtfs-realtime.proto | 32 +++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index ce7e0ebfa..b46cc6418 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -390,6 +390,10 @@ message VehiclePosition { // The vehicle is not accepting additional passengers. NOT_ACCEPTING_PASSENGERS = 6; + // Used in context of multi car crowding. There is no data available for this car in this vehicle + // Useful for padding, in case a vehicle composed of several cars has data available only for some of those + NO_DATA_AVAILABLE = 7; + } optional OccupancyStatus occupancy_status = 9; @@ -402,6 +406,32 @@ message VehiclePosition { // This field is still experimental, and subject to change. It may be formally adopted in the future. optional uint32 occupancy_percentage = 10; + // Car specific details, used for vehicles composed of several cars + message CarDetails { + + // Occupancy status for this given car, in this vehicle + optional OccupancyStatus occupancy_status = 1; + + // Occupancy percentage for this given car, in this vehicle + // Follows the same rules as "VehiclePosition.occupancy_percentage" + // In addition, value -1 will be used to determine that crowding percentage is currently not available for this given car + // -1 is useful for padding, in case a vehicle composed of several cars has data available only for some of those + optional int32 occupancy_percentage = 2; + + // 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; + + // The following extension IDs are reserved for private use by any organization. + extensions 9000 to 9999; + } + + // Details of the multiple cars of this given vehicle. + // The first occurence represents the first car of the vehicle, given the current direction of travel. + // The number of occurrences of the multi_car_details field represents the number of cars of the vehicle. + repeated CarDetails multi_car_details = 11; + // 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. @@ -470,9 +500,11 @@ message Alert { optional TranslatedString description_text = 11; // Text for alert header to be used in text-to-speech implementations. This field is the text-to-speech version of header_text. + // This field is still experimental, and subject to change. It may be formally adopted in the future. optional TranslatedString tts_header_text = 12; // Text for full description for the alert to be used in text-to-speech implementations. This field is the text-to-speech version of description_text. + // This field is still experimental, and subject to change. It may be formally adopted in the future. optional TranslatedString tts_description_text = 13; // Severity of this alert. From 0bf5bf3983d14035f9211391d0d853d697bc076c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Fontolliet?= Date: Mon, 27 Jul 2020 11:31:23 -0400 Subject: [PATCH 2/6] removed text --- gtfs-realtime/proto/gtfs-realtime.proto | 2 -- 1 file changed, 2 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index b46cc6418..10958dae3 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -500,11 +500,9 @@ message Alert { optional TranslatedString description_text = 11; // Text for alert header to be used in text-to-speech implementations. This field is the text-to-speech version of header_text. - // This field is still experimental, and subject to change. It may be formally adopted in the future. optional TranslatedString tts_header_text = 12; // Text for full description for the alert to be used in text-to-speech implementations. This field is the text-to-speech version of description_text. - // This field is still experimental, and subject to change. It may be formally adopted in the future. optional TranslatedString tts_description_text = 13; // Severity of this alert. From 074dc7fbbc9e730a812104b69565a426531a16b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Fontolliet?= Date: Mon, 27 Jul 2020 11:32:55 -0400 Subject: [PATCH 3/6] modified comment --- gtfs-realtime/proto/gtfs-realtime.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index 10958dae3..0fd5f82a9 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -390,7 +390,7 @@ message VehiclePosition { // The vehicle is not accepting additional passengers. NOT_ACCEPTING_PASSENGERS = 6; - // Used in context of multi car crowding. There is no data available for this car in this vehicle + // There is no data available for this car in this vehicle. Used in context of multi car crowding. // Useful for padding, in case a vehicle composed of several cars has data available only for some of those NO_DATA_AVAILABLE = 7; From def775ca8631762c89721b9650bb85fc6c4a09f0 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 5 Aug 2020 12:02:01 -0400 Subject: [PATCH 4/6] Merge with TfNSW and LIRR proposals Primary changes: * Change terminology to "Coach" and "Status" * Add sequence number to coaches * In case of unknown values, provide the sequence number and do NOT provide the unknown field --- gtfs-realtime/proto/gtfs-realtime.proto | 48 +++++++++++++++---------- gtfs-realtime/spec/en/reference.md | 22 +++++++++--- 2 files changed, 47 insertions(+), 23 deletions(-) diff --git a/gtfs-realtime/proto/gtfs-realtime.proto b/gtfs-realtime/proto/gtfs-realtime.proto index fda509b50..8dfee34dd 100644 --- a/gtfs-realtime/proto/gtfs-realtime.proto +++ b/gtfs-realtime/proto/gtfs-realtime.proto @@ -419,11 +419,6 @@ message VehiclePosition { // The vehicle is not accepting additional passengers. NOT_ACCEPTING_PASSENGERS = 6; - - // There is no data available for this car in this vehicle. Used in context of multi car crowding. - // Useful for padding, in case a vehicle composed of several cars has data available only for some of those - NO_DATA_AVAILABLE = 7; - } optional OccupancyStatus occupancy_status = 9; @@ -436,17 +431,29 @@ message VehiclePosition { // This field is still experimental, and subject to change. It may be formally adopted in the future. optional uint32 occupancy_percentage = 10; - // Car specific details, used for vehicles composed of several cars - message CarDetails { - - // Occupancy status for this given car, in this vehicle - optional OccupancyStatus occupancy_status = 1; - - // Occupancy percentage for this given car, in this vehicle + // Coach-specific status, used for vehicles composed of several carriages + // This message is still experimental, and subject to change. It may be formally adopted in the future. + message CoachStatus { + // Identifies the order of this coach with respect to the other + // coaches in the vehicle's list of CoachStatus. This value is required + // and must be non-negative, and there cannot be duplicate values in the list of + // CoachStatus. The values must be set such that the lowest value + // corresponds to the first coach in the direction of travel, the + // second-lowest value corresponds to the second coach in the direction + // of travel and so forth. For example, the first coach in the direction + // of travel could have a coach_sequence of 4, the second coach could + // have a coach_sequence of 10, the third coach could have a + // coach_sequence of 105, and so forth. + optional uint32 coach_sequence = 1; + + // Occupancy status for this coach, in this vehicle. If OccupancyStatus is unknown, + // this field should not be provided. + optional OccupancyStatus occupancy_status = 2; + + // Occupancy percentage for this coach, in this vehicle // Follows the same rules as "VehiclePosition.occupancy_percentage" - // In addition, value -1 will be used to determine that crowding percentage is currently not available for this given car - // -1 is useful for padding, in case a vehicle composed of several cars has data available only for some of those - optional int32 occupancy_percentage = 2; + // If occupancy_percentage is unknown, this field should not be provided. + optional uint32 occupancy_percentage = 3; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features and @@ -457,10 +464,13 @@ message VehiclePosition { extensions 9000 to 9999; } - // Details of the multiple cars of this given vehicle. - // The first occurence represents the first car of the vehicle, given the current direction of travel. - // The number of occurrences of the multi_car_details field represents the number of cars of the vehicle. - repeated CarDetails multi_car_details = 11; + // Status of the multiple coaches/carriages of this vehicle, ordered by CoachStatus.coach_sequence + // with the first occurrence represents the first coach of the vehicle, given the current direction of travel. + // The number of occurrences of the coach_status field represents the number of coaches of the vehicle. + // If a coach has no data, it should still be included in this list with a coach_sequence but without + // the remaining fields for which data is lacking. + // This field is still experimental, and subject to change. It may be formally adopted in the future. + repeated CoachStatus coach_status = 11; // The extensions namespace allows 3rd-party developers to extend the // GTFS Realtime Specification in order to add and evaluate new features and diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 428442889..7e79b70ef 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -228,10 +228,10 @@ Realtime positioning information for a given vehicle. | **stop_id** | [string](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Identifies the current stop. The value must be the same as in stops.txt in the corresponding GTFS feed. | | **current_status** | [VehicleStopStatus](#enum-vehiclestopstatus) | Optional | One | The exact status of the vehicle with respect to the current stop. Ignored if current_stop_sequence is missing. | | **timestamp** | [uint64](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Moment at which the vehicle's position was measured. In POSIX time (i.e., number of seconds since January 1st 1970 00:00:00 UTC). | -| **congestion_level** | [CongestionLevel](#enum-congestionlevel) | Optional | One | -| _**occupancy_status**_ | _[OccupancyStatus](#enum-occupancystatus)_ | _Optional_ | One | The degree of passenger occupancy of the vehicle.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| -| **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value representing the degree of passenger occupancy of the vehicle. The value 100 should represent total the maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. It's not impossible that the value goes over 100 if there are currently more passenger than the vehicle was designed for. The precision of occupancy_percentage should be low enough that you can't track a single person boarding and alighting for privacy reasons.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | - +| **congestion_level** | [CongestionLevel](#enum-congestionlevel) | Optional | One | +| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | Optional | One | The degree of passenger occupancy of the vehicle. If `coach_status` is populated with per-coach `occupancy_status`, then this field should describe the entire vehicle with all coaches considered.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value representing the degree of passenger occupancy of the vehicle. The value 100 should represent total the maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. It's not impossible that the value goes over 100 if there are currently more passenger than the vehicle was designed for. The precision of occupancy_percentage should be low enough that you can't track a single person boarding and alighting for privacy reasons. If `coach_status` is populated with per-coach `occupancy_percentage`, then this field should describe the entire vehicle with all coaches considered.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **coach_status** | [CoachStatus](#enum-coachstatus) | Optional | Many | Status of the multiple coaches/carriages of this vehicle, ordered by CoachStatus.coach_sequence with the first occurrence represents the first coach of the vehicle, given the current direction of travel. The number of occurrences of the coach_status field represents the number of coaches of the vehicle. If a coach has no data, it should still be included in this list with a coach_sequence but without the remaining fields for which data is lacking.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| ## _enum_ VehicleStopStatus @@ -275,6 +275,20 @@ The degree of passenger occupancy for the vehicle. | _**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._ | +## _message_ CoachStatus + +Coach-specific status, used for vehicles composed of several carriages + +**Caution:** this message is still **experimental**, and subject to change. It may be formally adopted in the future.
. + +#### Fields + +| _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | +|------------------|------------|----------------|-------------------|-------------------| +| **coach_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifies the order of this coach with respect to the other coaches in the vehicle's list of `CoachStatus`. This value is required and must be non-negative, and there cannot be duplicate values in the list of `CoachStatus`. The values must be set such that the lowest value corresponds to the first coach in the direction of travel, the second-lowest value corresponds to the second coach in the direction of travel and so forth. For example, the first coach in the direction of travel could have a coach_sequence of 4, the second coach could have a coach_sequence of 10, the third coach could have a coach_sequence of 105, and so forth.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus)_ | Optional | One | Occupancy status for this coach, in this vehicle. If `OccupancyStatus` is unknown, this field should not be provided.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Occupancy percentage for this coach, in this vehicle. Follows the same rules as `VehiclePosition.occupancy_percentage`. If `occupancy_percentage` is unknown, this field should not be provided.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | + ## _message_ Alert An alert, indicating some sort of incident in the public transit network. From 154bbb88e8852198e6a8e00ffe65b9ef2e47b08b Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 5 Aug 2020 12:06:55 -0400 Subject: [PATCH 5/6] Fix formatting --- gtfs-realtime/spec/en/reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 7e79b70ef..1d7b50b27 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -257,7 +257,7 @@ Congestion level that is affecting this vehicle. | **CONGESTION** | | **SEVERE_CONGESTION** | -## _enum OccupancyStatus_ +## _enum_ OccupancyStatus The degree of passenger occupancy for the vehicle. @@ -286,7 +286,7 @@ Coach-specific status, used for vehicles composed of several carriages | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| | **coach_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifies the order of this coach with respect to the other coaches in the vehicle's list of `CoachStatus`. This value is required and must be non-negative, and there cannot be duplicate values in the list of `CoachStatus`. The values must be set such that the lowest value corresponds to the first coach in the direction of travel, the second-lowest value corresponds to the second coach in the direction of travel and so forth. For example, the first coach in the direction of travel could have a coach_sequence of 4, the second coach could have a coach_sequence of 10, the third coach could have a coach_sequence of 105, and so forth.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus)_ | Optional | One | Occupancy status for this coach, in this vehicle. If `OccupancyStatus` is unknown, this field should not be provided.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | Optional | One | Occupancy status for this coach, in this vehicle. If `OccupancyStatus` is unknown, this field should not be provided.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | | **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Occupancy percentage for this coach, in this vehicle. Follows the same rules as `VehiclePosition.occupancy_percentage`. If `occupancy_percentage` is unknown, this field should not be provided.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | ## _message_ Alert From 08cc128f19bd4b1332153159b0eb926f36264dd2 Mon Sep 17 00:00:00 2001 From: Tim Millet Date: Thu, 6 Aug 2020 18:17:15 -0400 Subject: [PATCH 6/6] Add CoachStatus in Element Index + add missing code text --- gtfs-realtime/spec/en/reference.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 1d7b50b27..b01749c92 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -58,6 +58,7 @@ Fields labeled as **experimental** are subject to change and not yet formally ad * [VehicleStopStatus](#enum-vehiclestopstatus) * [CongestionLevel](#enum-congestionlevel) * [OccupancyStatus](#enum-occupancystatus) + * [CoachStatus](#message-coachstatus) * [Alert](#message-alert) * [TimeRange](#message-timerange) * [EntitySelector](#message-entityselector) @@ -231,7 +232,7 @@ Realtime positioning information for a given vehicle. | **congestion_level** | [CongestionLevel](#enum-congestionlevel) | Optional | One | | **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | Optional | One | The degree of passenger occupancy of the vehicle. If `coach_status` is populated with per-coach `occupancy_status`, then this field should describe the entire vehicle with all coaches considered.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| | **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | A percentage value representing the degree of passenger occupancy of the vehicle. The value 100 should represent total the maximum occupancy the vehicle was designed for, including both seating and standing capacity, and current operating regulations allow. It's not impossible that the value goes over 100 if there are currently more passenger than the vehicle was designed for. The precision of occupancy_percentage should be low enough that you can't track a single person boarding and alighting for privacy reasons. If `coach_status` is populated with per-coach `occupancy_percentage`, then this field should describe the entire vehicle with all coaches considered.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | -| **coach_status** | [CoachStatus](#enum-coachstatus) | Optional | Many | Status of the multiple coaches/carriages of this vehicle, ordered by CoachStatus.coach_sequence with the first occurrence represents the first coach of the vehicle, given the current direction of travel. The number of occurrences of the coach_status field represents the number of coaches of the vehicle. If a coach has no data, it should still be included in this list with a coach_sequence but without the remaining fields for which data is lacking.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| +| **coach_status** | [CoachStatus](#enum-coachstatus) | Optional | Many | Status of the multiple coaches/carriages of this vehicle, ordered by `CoachStatus.coach_sequence` with the first occurrence represents the first coach of the vehicle, given the current direction of travel. The number of occurrences of the `coach_status` field represents the number of coaches of the vehicle. If a coach has no data, it should still be included in this list with a `coach_sequence` but without the remaining fields for which data is lacking.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future.| ## _enum_ VehicleStopStatus @@ -285,7 +286,7 @@ Coach-specific status, used for vehicles composed of several carriages | _**Field Name**_ | _**Type**_ | _**Required**_ | _**Cardinality**_ | _**Description**_ | |------------------|------------|----------------|-------------------|-------------------| -| **coach_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifies the order of this coach with respect to the other coaches in the vehicle's list of `CoachStatus`. This value is required and must be non-negative, and there cannot be duplicate values in the list of `CoachStatus`. The values must be set such that the lowest value corresponds to the first coach in the direction of travel, the second-lowest value corresponds to the second coach in the direction of travel and so forth. For example, the first coach in the direction of travel could have a coach_sequence of 4, the second coach could have a coach_sequence of 10, the third coach could have a coach_sequence of 105, and so forth.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | +| **coach_sequence** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Required | One | Identifies the order of this coach with respect to the other coaches in the vehicle's list of `CoachStatus`. This value is required and must be non-negative, and there cannot be duplicate values in the list of `CoachStatus`. The values must be set such that the lowest value corresponds to the first coach in the direction of travel, the second-lowest value corresponds to the second coach in the direction of travel and so forth. For example, the first coach in the direction of travel could have a `coach_sequence` of 4, the second coach could have a `coach_sequence` of 10, the third coach could have a `coach_sequence` of 105, and so forth.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | | **occupancy_status** | [OccupancyStatus](#enum-occupancystatus) | Optional | One | Occupancy status for this coach, in this vehicle. If `OccupancyStatus` is unknown, this field should not be provided.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. | | **occupancy_percentage** | [uint32](https://developers.google.com/protocol-buffers/docs/proto#scalar) | Optional | One | Occupancy percentage for this coach, in this vehicle. Follows the same rules as `VehiclePosition.occupancy_percentage`. If `occupancy_percentage` is unknown, this field should not be provided.
**Caution:** this field is still **experimental**, and subject to change. It may be formally adopted in the future. |