Closed j-d-b closed 2 years ago
The camera object describes a camera device deployed in the field, capable of capturing images.
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 |
Property | Object |
---|---|
properties |
FieldDeviceFeature object (see above) |
image_timestamp
necessary, as there is an update_date
in the device_details
?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.
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"
road_event_ids
would be an important elements going forward. EX: a dynamic Speed Limit sign that defines the road impact for a specific road_event. 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.
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 |
Property | Object |
---|---|
properties |
FieldDeviceFeature (see above) |
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. |
Property | Object |
---|---|
pattern |
ArrowBoard (see above) |
animation-mode
with values (static
, flashing
, sequential
, other
)
pattern
would be left-arrow
, right-arrow
, bidirectional-arrow
, left-chevron
, right-chevron
, line
, alternating-diamonds
, four-corners
.animation-mode
and the pattern enumerated type is simpler with less repetition.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. |
Property | Object |
---|---|
function |
ArrowBoard (see above) |
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.
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 |
Property | Object |
---|---|
properties |
FieldDeviceFeature (see above) |
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.
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.
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 |
Property | Object |
---|---|
properties |
FieldDeviceFeature (see above) |
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.
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 |
Property | Object |
---|---|
lane_data |
TrafficSensor (see above) |
collection_interval_start_date
and collection_interval_end_date
we could have one property:
collection_interval_duration
| Positive Integer | The duration in seconds of the data collection interval from which the TrafficSensor data applies to, end at the update_date
provided in the device_details
| Required |The FlashingBeacon object describes a flashing beacon light of any form (e.g. trailer-mounted, vehicle), used to indicate caution and capture driver attention.
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). |
Property | Object |
---|---|
properties |
FieldDeviceFeature (see above) |
device_details
, but is there desire in having it at all/is there much value? I'd like to avoid adding things just because it is easy to do so.function
property for this as well to know what the use of the flashing beacon is for (e.g. vehicle entering, queue warning, reduced speed, worker's present, others?).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.
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 |
Property | Object |
---|---|
properties |
FieldDeviceFeature (see above) |
The MarkedLocation object describes a marked point on a road event, such as the start or end.
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 |
Property | Object |
---|---|
marked_locations |
LocationMarker (see above) |
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. |
Property | Object |
---|---|
type |
MarkedLocation (see above) |
is_in_use
clear? Should it be is_active
? Other options?The above comments list all the proposed field devices for the first version of the SWZFeed, they are in summary here:
Objects
device_details
property)Enumerated Types
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
update-date
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.
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.
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.
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.
Also, Bluetooth devices should be included as one of the types of devices. Those are quite prevalent in smart work zone systems.
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.
The original specification of Road Events and their parent-child relationships seemed quite complex
@devorah-ql please see #197 and continue discussion there.
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.
Resolved in #208 (WZDx v4.0).
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.
@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.
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
id
type
"Feature"
Feature
.properties
geometry
type
of Point.type
property MUST be Point.bbox
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 thegeometry
.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 adetails_details
property which is the FieldDeviceDetails object and in addition, animage_url
property).Properties
device_type
road_names
device_status
update_date
road_event_ids
RoadEventFeature
s which the device is associated with.status_messages
description
name
milepost
Thoughts for discussion
direction
(if applicable, potential issue is it could apply to both directions of travel on a bidirectional roadway)side_of_the_road
(e.g.left
,right
,on-road
,unknown
, others...?)road_event_ids
proposed above).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
).ok
warning
error
unknown
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 InformationAll values represent the device being online exceptoffline
.offline
is used with respect to communication with the device—the server is not attempting to interact with it and does not have current information about the device.offline
means the device is in the producer's system but is not being actively communicated with it and thus no state/warning/error information can be determined.offline
does not represent the state of the device.For example, a flashing beacon device could have a status ofok
when the beacon is not actively flashing. The state information is represented by device-specific properties (e.g. for flashing beacon, anis_flashing
property), not thedevice_status
of its FieldDeviceDetails.Thoughts for discussion
Should offline/online be a separate concept from status? e.g. "is_communicating" or "communication_status"If the device has lost communication, this is different than intentionally "offline", this case would be "error" status. If "is_communicating" is a separate property and the device loses communication, would we want it as false?Should offline device be included in the field devices feed? If not, the value could just be removed, reducing confusion about its use.Edit: strikethroughts due to below comment and co-chairs discussion on not including offline devices in the SWZFeed.
Object Model
Next Steps