usdot-jpo-ode / wzdx

The Work Zone Data Exchange (WZDx) Specification aims to make harmonized work zone data provided by infrastructure owners and operators (IOOs) available for third party use, making travel on public roads safer and more efficient through ubiquitous access to data on work zone activity.
Creative Commons Zero v1.0 Universal
89 stars 61 forks source link

Smart Work Zones Feed (SWZFeed): "Field Device" structure, details, and specific device objects #195

Closed j-d-b closed 2 years ago

j-d-b commented 2 years ago

This issue addresses the base information that is shared by all field devices in the SWZ Field Devices Feed (see #191). All field devices will be described by this information along with other information specific to the field device type.

As the Smart Work Zones Feed (SWZFeed) is a collection of GeoJSON features, the field device requires a container object to represent the GeoJSON feature as well as the field device details, alike to how a road event in a WZDx feed is represented by both the RoadEventFeature object and the child RoadEvent object (the road event details).

The following objects are based on the WZDx feed, MassDOT's SWZ Vendor API specification, Ver-Mac's current device XML feed, TMDD v3.1, and IBI's ATMS software.

FieldDeviceFeature Object

The FieldDeviceFeature object is a GeoJSON feature representing a field device deployed in a work zone. This object contains the specific details of the field device, alike to how the RoadEventFeature object in a WZDx Feed contains the RoadEvent object via the properties property. For the first release of the Field Devices Feed, only point devices are supported.

Properties

Name Type Description Conformance Notes
id String A unique identifier issued by the data feed provider to identify the field device. Required This is a GeoJSON property.
type String; "Feature" The GeoJSON object type. This MUST be the string Feature. Required This is a GeoJSON property.
properties Any field device object (list TBD) The specific details of the field device. Required This is a GeoJSON property.
geometry GeoJSON Geometry object with type of Point. The geometry of the field device, indicating its location. The Geometry object's type property MUST be Point. Required This is a GeoJSON property.
bbox GeoJSON Bounding Box Information on the coordinate range for this field device. Must be an array of length 2*n where n is the number of dimensions represented in the geometry property, with all axes of the most southwesterly point followed by all axes of the more northeasterly point. The axes order of a bbox follows the axes order of the geometry. Optional This is a GeoJSON property.

FieldDeviceDetails Object

The FieldDeviceDetails object represents the details—both configuration and current state—of a field device. The FieldDeviceDetails object does not occur directly in a field devices feed. It is used as the value of the device_details property on every specific type of field device. The specific types of field device (represented by their own object, e.g. Camera) occur in a field devices feed (e.g. a Camera has a details_details property which is the FieldDeviceDetails object and in addition, an image_url property).

Properties

Name Type Description Conformance Notes
device_type FieldDeviceType Enumerated Type (TBD) The type of field device. Required
road_names Array; [String] A list of publicly known names of the road on which the device is located. This may include the road number designated by a jurisdiction such as a county, state or interstate (e.g. I-5, VT 133). Required
device_status FieldDeviceStatus Enumerated Type (proposed below) The operational status of the field device. The value of this property indicates if the device is Required
update_date String; date-time The UTC time and date when the field device information was updated. Required
road_event_ids Array; [String] A list of one or more ids of a RoadEventFeatures which the device is associated with. Optional This can be used if the field devices feed producer also produces a WZDx feed to represent road events. If not, this field should not be populated.
status_messages Array; [String] A list of status messages associated with the devices status, if applicable. Used to provide additional information about the status such as specific warning or error messages. Optional The content of this property is up to the producer.
description String A description of the field device. Optional
name String A human-readable name for the field device. Optional
milepost Number The linear distance measured against a milepost marker along a roadway where the device is located. Optional

Thoughts for discussion

FieldDeviceStatus Enumerated Type

The FieldDeviceStatus enumerated type describes the operational status of a field device. The status indicates the health of the device as well as if it is being communicated with (if not, it should be given the status offline).

Value Description
ok The device is turned on and working without issue.
warning The device is functional but is impaired or impacted in a way that is not critical to operation.
error The device is impaired such that it is not able to perform one or more necessary functions.
unknown The device's operational status is not known.
offline The device is not being communicated with. The device may be deployed or in-use but current state information can not be determined remotely.

Additional Information

Thoughts for discussion

Edit: strikethroughts due to below comment and co-chairs discussion on not including offline devices in the SWZFeed.

Object Model

image

Next Steps

j-d-b commented 2 years ago

Camera Object

The camera object describes a camera device deployed in the field, capable of capturing images.

Properties

Name Type Description Conformance Notes
device_details FieldDeviceDetails object (see above) The core details of the field device, not specific to cameras. Required This property appears on all field devices.
image_url String; uri A URL pointing to an image file for the camera image still. Optional
image_timestamp String; date-time The UTC date and time when the image was captured. Conditional; required if image_url is provided

Used By

Property Object
properties FieldDeviceFeature object (see above)

Thoughts for discussion

tfoster-vm commented 2 years ago

I do not think the image_timestamp is needed. Most camera providers can also imbed the timestamp in the image itself as another optional way to provide that information.

sergebeaudry commented 2 years ago

Overall the structure makes sense as the intent. We checked and we would have no issue creating such feed. As for the few items in the "to be discuss portion"

j-d-b commented 2 years ago

ArrowBoard Object

The ArrowBoard object describes a smart arrow board (example image) which can display an arrow pattern to direct traffic. Arrow boards are often placed at the beginning of a lane closure—thus knowing the location of an arrow board can assist in programmatically generating a WZDx road event with verified spatial information.

Properties

Name Type Description Conformance Notes
device_details FieldDeviceDetails object (see above) The core details of the field device, not specific to arrow boards. Required This property appears on all field devices.
pattern ArrowBoardPattern enumerated type (see below) The current pattern displayed on the arrow board. Note this includes blank, which indicates that nothing is shown on the arrow board. Optional

Used By

Property Object
properties FieldDeviceFeature (see above)

ArrowBoardPattern Enumerated Type

The ArrowBoardPattern enumerated type defines a list of options for the posted pattern on an ArrowBoard. The following list of values is based on Ver-Mac's device XML feed and IowaDOT's Smart Arrow Boards specification. If the arrow board pattern does not exactly match one of the values described, the producer should use the closest pattern.

Value Description
blank No pattern; the board is not displaying anything.
right-arrow-static Merge right represented by an arrow pattern (e.g. -->) that does not flash or move.
right-arrow-flashing Merge right represented by an arrow pattern (e.g. -->) that flashes on/off.
right-arrow-sequential Merge right represented by an arrow pattern (e.g. -->) that is displayed in a progressing sequence (e.g. > -> --> or - -- -->).
right-chevrons-static Merge right represented by a pattern of chevrons (e.g. >>>) that does not flash or move.
right-chevrons-flashing Merge right represented by a pattern of chevrons (e.g. >>>) that flashes on/off.
right-chevrons-sequential Merge right represented by a pattern of chevrons that is displayed in a progressing sequence.
left-arrow-static Merge left represented by an arrow pattern (e.g. <--) that does not flash or move.
left-arrow-flashing Merge left represented by an arrow pattern (e.g. <--) that flashes on/off.
left-arrow-sequential Merge left represented by an arrow pattern (e.g. <--) that is displayed in a progressing sequence (e.g. < <- <-- or - -- <--).
left-chevron-static Merge left represented by a pattern of chevrons (e.g. <<<) that does not flash or move.
left-chevron-flashing Merge left represented by a pattern of chevrons (e.g. <<<) that flashes on/off.
left-chevron-sequential Merge left represented by a pattern of chevrons that is displayed in a progressing sequence.
bidirectional-arrow-static Split (merge left or right) represented by arrows pointing both left and right (e.g. <-->) that does not flash or move.
bidirectional-arrow-flashing Split (merge left or right) represented by arrows pointing both left and right (e.g. <-->) that flashes on/off.
line-flashing A flashing line or bar (e.g. ---), indicating warning/caution, not a merge.
diamonds-alternating An alternating display of two diamond shapes (e.g. ◇ ◇), indicating warning/caution, not a merge.
four-corners-flashing Four dots on the corners of the board which flash, indiciating warning/caution, not a merge.

Used By

Property Object
pattern ArrowBoard (see above)

Thoughts for discussion

ArrowBoardFunction Enumerated Type (possible addition, for discussion)

The ArrowBoardFunction enumerated type defines a list of options for the function of an arrow board deployed in a work zone. This value facilitates knowing if the arrowboard is used for marking the start/end of a lane closure or the start of the work zone.

Value Description
lane-closure The arrowboard is placed at the beginning of a lane closure.
start-marker The arrowboard is placed at the beginning of a work area.

Used By

Property Object
function ArrowBoard (see above)
j-d-b commented 2 years ago

DynamicMessageSign Object

The DynamicMessageSign object describes a dynamic message sign [DMS] (also known as changeable message sign [CMS] and variable message sign [VMS]) (example image) which is an electronic traffic sign deployed on the roadway, used to provide information to travelers. This object is intended to be general and can be used to describe signs within variable speed limit signs (VSLS) and other similar systems.

Properties

Name Type Description Conformance Notes
device_details FieldDeviceDetails object (see above) The core details of the field device, not specific to dynamic message signs. Required This property appears on all field devices.
message_multi_string String The MULTI (Mark-Up Language for Transportation Information, see NTCIP 1203 v03) formatted string describing the message currently posted to the sign. Optional

Used By

Property Object
properties FieldDeviceFeature (see above)

Thoughts for discussion

j-d-b commented 2 years ago

online/offline I don't think offline would have any value for such feed. it is typically done, on our side, to flag a device that is "off duty". EX: a traffic control company will use this status to differentiate the unit that are on jobs versus the one in his inventory. This is different from an "online" device that is not responding which is more an "error" state

@sergebeaudry thanks for this comment, it is definitely cleaner to not have offline be an option as then more of the individual device state can be required. I like removing offline as we can always add that later if the desire to represent devices that are not in use arises.

j-d-b commented 2 years ago

TrafficSensor Object

The TrafficSensor object describes a traffic sensor deployed on the roadway which captures traffic metrics includes speed, volume, and/or occupancy over a collection interval. The TrafficSensor can describe lane-level if available.

Properties

Name Type Description Conformance Notes
device_details FieldDeviceDetails object (see above) The core details of the field device, not specific to dynamic message signs. Required This property appears on all field devices.
collection_interval_start_date String; date-time The UTC date and time where the TrafficSensor data began being collected at. The averages and totals contained in the TrafficSensor data apply to the inclusive interval of collection_interval_start_date to collection_interval_end_date Required
collection_interval_end_date String; date-time The UTC date and time where the TrafficSensor collection interval ended. The averages and totals contained in the TrafficSensor data apply to the inclusive interval of collection_interval_start_date to collection_interval_end_date Required
average_speed Positive Integer The average speed of traffic across all lanes over the collection interval. Optional
total_vehicle_count Integer The total number of vehicles counted by the sensor during the collection interval. Optional
occupancy_percent Postive Number The percent of time the roadway section monitored by the sensor was occupied by a vehicle over the collection interval. Optional
lane_data Array; [TrafficSensorLaneData] (see below) Provides lane-level traffic data through a list of objects each pointing to a road event lane and indiciating the metrics of that lane. Optional

Used By

Property Object
properties FieldDeviceFeature (see above)

TrafficSensorLaneData Object

The TrafficSensorLaneData object describes data for a single lane measured by a traffic sensor (see TrafficSensor object) deployed on the roadway. Note this structure allows a single TrafficSensor to provide data across lanes on multiple road events.

Properties

Name Type Description Conformance Notes
road_event_id String The ID of a RoadEventFeature within the same SWZFeed which the measured lane occurs in. Required
lane_order Positive Integer The lane's position in sequence within the road event (specified by road_event_id). The value of this property corresponds to the RoadEvent's Lane's order property. Required
average_speed Positive Integer The average speed of traffic in the lane over the collection interval. Optional
total_vehicle_count Integer The total number of vehicles counted by the sensor in the lane during the collection interval. Optional
occupancy_percent Postive Number The percent of time the lane monitored by the sensor was occupied by a vehicle over the collection interval. Optional

Used By

Property Object
lane_data TrafficSensor (see above)

Thoughts (and remaining items) for discussion

j-d-b commented 2 years ago

FlashingBeacon Object

The FlashingBeacon object describes a flashing beacon light of any form (e.g. trailer-mounted, vehicle), used to indicate caution and capture driver attention.

Properties

Name Type Description Conformance Notes
device_details FieldDeviceDetails object (see above) The core details of the field device, not specific to dynamic message signs. Required This property appears on all field devices.
is_flashing Boolean A yes/no value indicating if the flashing beacon is currently in use and flashing. Optional The is_flashing property is optional as it should not be provided if the producer does not know if the beacon is flashing (e.g. if it's in error state or similar).

Used By

Property Object
properties FieldDeviceFeature (see above)

Thoughts for discussion

j-d-b commented 2 years ago

LocationMarker Object

The LocationMarker object describes any GPS-enabled ITS device that is placed at a point in a work zone (usually the beginning or end). To be included in an SWZFeed, the LocationMarker needs to be related to a RoadEvent (which it marks the start or end of) within the same SWZFeed. This enables accurately and remotely verifying the road event's location.

Properties

Name Type Description Conformance Notes
device_details FieldDeviceDetails object (see above) The core details of the field device, not specific to dynamic message signs. Required This property appears on all field devices.
is_in_use Boolean A yes/no indicating if the marker is currently on and in use. If this value is true the locations the marker is marking is indiciated by the parent FieldDeviceFeature's geometry. Required
marked_locations Array; [MarkedLocation object] (see below) A list of locations that this marker is marking. Required

Used By

Property Object
properties FieldDeviceFeature (see above)

MarkedLocation Object

The MarkedLocation object describes a marked point on a road event, such as the start or end.

Properties

Name Type Description Conformance Notes
road_event_id String The ID of a RoadEventFeature(https://github.com/usdot-jpo-ode/wzdx/blob/main/spec-content/objects/RoadEvent.md) within the same SWZFeed as the LocationMarker the MarkedLocation appears on. Required
type MarkedLocationType enumerated type (see below) The type of location (e.g. start or end) that is marked. Required

Used By

Property Object
marked_locations LocationMarker (see above)

MarkedLocationType Enumerated Type

The MarkedLocationType enumerated type describes options for what a marked location is marking, such as the start or end of a road event.

Value Description
start The start point of the road event.
end The end point of the road event.

Used By

Property Object
type MarkedLocation (see above)

Thoughts for discussion

j-d-b commented 2 years ago

The above comments list all the proposed field devices for the first version of the SWZFeed, they are in summary here:

Objects

Enumerated Types

sknick-iastate commented 2 years ago

Great work @j-d-b and others. I still need to go through some of the discussion but below are a few considerations after initial review:

For asset tracking: for the id we may consider some guidance on how this should be structured. In the smart arrow board protocol we use: controller make, model, and serial number into a single string containing three semicolon-separated attributes (i.e. Front Road Signs;AB3;1234-567-010).

For the FieldDeviceDetails: Consider adding owner contact information fields such as owner company, owner contact, owner phone and owner email. This would allow for easier access by the agency to contact the owner of the device (not the manufacturer) if the device gets hit or needs to be moved.

For the GPS: I think there should be an ability to identify if the GPS has been manually updated (i.e. in a bridge or urban area). I don't think we should use the existing verification enumerations (verified or estimated) since they don't accurately describe this situation. My thought is we could just add a boolean override or manual

For arrow boards and dynamic message signs: I'd recommend adding a boolean deployed or stowed field. In discussion with contractors, they frequently see arrow boards stowed but the display still on. There needs to be indication that the display is being shown to traffic.

The direction of traffic the board is facing or compass was also brought up in the meeting today. I think it may be beneficial to add the compass but know there were a lot of accuracy issues when we were testing smart arrow boards as well as push back from some manufacturers on including it in the first place.

For timestamps: In the smart arrow board protocol there are a few different timestamps intended to provide additional details including

I'm not sure it is necessary for all devices but for arrow boards and location markers I think it is valuable to have some additional GPS details since one of their primary functions is reporting location. Knowing the time the GPS was updated allows for quality checks when using this information to report work zone locations. This has helped us in at least testing smart arrow boards to ensure that the location information is updating in line with other details. If we only have the update-date, it wouldn't be possible to identify how old the GPS reading is if other attributes change for the device. I think there are probably other ways to accomplish this but would like to hear others thoughts.

devorah-ql commented 2 years ago

Quality work on this. These elements all now appear very clean and executable. I can see the refinement in how the specification here has progressed. The essential data is represented, without adding significant extra data that makes things overly complex or onerous to implement. To me, this is a mark of good design.

With regard to the Flashing Beacon Object, agreed that it should have a function property so it is clear what it is flashing to indicate. It may also be worth having an optional field to enter the specific message displayed on the sign.

Everything here looks very good to me with regard to the Field Device information. One thing I hope the group will address in upcoming meetings is the Road Event object. The original specification of Road Events and their parent-child relationships seemed quite complex, and perhaps not practical for vendors to actually implement. Those are a bit of a different topic, but since Field Devices will need associated Road Events, I did want to mention them. I hope they structure and intent can be clarified in future meetings.

Thanks for all your hard work here. Good progress.

rdsheckler commented 2 years ago

On the arrow board object there needs to be a designation for whether it is mobile or stationary. There are a ton of arrow boards that are mounted on TMA's, striping trucks, sweepers, etc. These may indicate moving operations and therefore have other properties not included here.

rdsheckler commented 2 years ago

We are missing stuff like striping trucks, TMA trucks, flaggers, AFAD's, rumble strips (though that could go under marked location), an array of delieators (which has multiple locations for one object, I assume we don't want each cone to be it's own object), utility trucks (which have their own list of characteristics), attenuators, ets.

devorah-ql commented 2 years ago

Also, Bluetooth devices should be included as one of the types of devices. Those are quite prevalent in smart work zone systems.

j-d-b commented 2 years ago

Also, Bluetooth devices should be included as one of the types of devices. Those are quite prevalent in smart work zone systems.

@devorah-ql is a "Bluetooth device" a type of traffic sensor that uses Bluetooth technology to detect vehicles? If so, it would be represented by the TrafficSensor object.

j-d-b commented 2 years ago

The original specification of Road Events and their parent-child relationships seemed quite complex

@devorah-ql please see #197 and continue discussion there.

devorah-ql commented 2 years ago

Also, Bluetooth devices should be included as one of the types of devices. Those are quite prevalent in smart work zone systems.

@devorah-ql is a "Bluetooth device" a type of traffic sensor that uses Bluetooth technology to detector vehicles? If so, it would be represented by the TrafficSensor object.

@j-d-b Yes, a Bluetooth device could potentially be included as a TrafficSensor, but if so, the TrafficSensor object would need to be revised to include Bluetooth Data. I can also see going either way with this. On the one hand, it might be nice to include it as part of the current object. But on the other hand, BlueTooth data is typically reporting a travel time across a segment of road. Since this is quite different from the format of the point data acquired by a radar sensor, it might be easiest just to create a new object for it (which I suppose could also apply to any other type of device that can handle travel times). Either way could potentially work.

j-d-b commented 2 years ago

Resolved in #208 (WZDx v4.0).

Dunge commented 2 years ago

Hello @j-d-b

Just a quick question about road_event_id. It exists in FieldDeviceCoreDetails, in MarkedLocation and in TrafficSensorLaneData. I assume the last two is to be more precise when the FieldDeviceCoreDetails contains a list (for example same device in two RoadEvent going in opposite directions). My question is about the Conformance flag, it is Optional everywhere except in TrafficSensorLaneData where it is Required. Shouldn't it be Optional too? I see for the MarkedLocation that it was Required in the draft in this issue, but is Optional in the final document.

j-d-b commented 2 years ago

@Dunge refactoring TrafficSensorLaneData to allow a producer to provide lane data without linking it to a road event is on the development plan for the next release—in fact, it's on my todo list to make an issue for it prior to the first SWZ subgroup meeting.

In the development of v4.0, road_event_id was required to avoid having to enumerate lanes in the SwzDeviceFeed like is done for a road event in the WZDx feed. Frankly, we sort of ran out of time to come up with a better way to represent which lane the traffic data is associated with without the lanes definition from the road event. However from your comment and other discussion it is clear now that this requirement is not ideal and it will be addressed for the next release.