Add field device feature and specific field device objects in new SwzDeviceFeed

[j-d-b]

This draft PR addresses #191 and #195 by defining models for smart work zone field devices and integrating them into the WZDx specification through a new feed called the SwzDeviceFeed.

Specifically, this PR adds a new GeoJSON feature type called FieldDeviceFeature. The FieldDeviceFeature can describe several types of field devices as enumerated by the new FieldDeviceType enumerated type and more can be added as the specification evolves.

Previously, WZDx only defined one type of feature, the RoadEventFeature, which occurs within the WZDxFeed. To not modify the WZDxFeed which is designed for providing work zone road event information to the traveling public, the FieldDeviceFeature occurs within a new SwzDeviceFeed (see #191 for background discussion) designed for providing deployed field device information.

The only effect to the WZDxFeed is that the RoadEventFeedInfo and RoadEventDataSource objects were renamed to FeedInfo and FeedDataSource as they now apply to more than just road events. Note this has no change in the structure or content of a WZDx feed.

New Objects

Object	Description
ArrowBoard	An electronic, connected arrow board which can display an arrow pattern to direct traffic.
Camera	A camera device deployed in the field, capable of capturing still images.
DynamicMessageSign	An electronic traffic sign deployed on the roadway, used to provide information to travelers.
FlashingBeacon	A flashing beacon light of any form (e.g. trailer-mounted, vehicle), used to indicate something or capture driver attention.
FieldDeviceFeature	The GeoJSON Feature container object for a deployed field device.
FieldDeviceCoreDetails	The core details—both configuration and current state—of a field device that are shared by all types of field devices.
HybridSign	A hybrid sign that contains static text (e.g. on an aluminum sign) along with a single electronic message display, used to provide information to travelers.
LocationMarker	Describes any GPS-enabled ITS device that is placed at a point on a roadway to dynamically know the location of something (often the beginning or end of a work zone).
MarkedLocation	Describes a specific location where a LocationMarker is placed, such as the start or end of a work zone road event.
SwzDeviceFeed	The root (highest level) object of a smart work zone devices feed.
TrafficSensor	A traffic sensor deployed on a roadway which captures traffic metrics (e.g. speed, volume, occupancy) over a collection interval.
TrafficSensorLaneData	Data for a single lane within a RoadEvent measured by a TrafficSensor deployed on the roadway.

New enumerated types

Enumerated Type	Description
ArrowBoardPattern	A list of options for the posted pattern on an ArrowBoard.
FlashingBeaconFunction	Describes options for what a FlashingBeacon is being used to indicate.
HybridSignDynamicMessageFunction	Describes options for the function of the variable message displayed by the electronic display on a HybridSign.
FieldDeviceStatus	The operational status of a field device.
FieldDeviceType	The type of a field device.
MarkedLocationType	Describes options for what a MarkedLocation can mark, such as the start or end of a road event.

WZDx Feeds

Feed Name	Description	Producer	Consumer	Uses	Content
WZDxFeed (existing)	Provides information about events ocurring on roadways (called "road events") such as work zones that impact the characteristics of the roadway and involve a change the roadway from the default state (e.g. a lane closure). The WZDxFeed is the original work zone data exchange feed, focused on describing high-level information about road work.	Agencies responsible for managing roadways and road work, typically state and local DOTs.	Traveling public via third parties such as mapping companies and CAVs.	Route planning; increased awareness; "put work zones on the map"	Work zone and detour road events (see RoadEventFeature).
SwzDeviceFeed (new)	Provides information (location, status, live data) about field devices deployed on the roadway in work zones.	Smart work zone equipment manufacturers or vendors.	Agencies responsible for managing roadways and permitting work, typically state and local DOTs who are often interested in producing a WZDxFeed. Third-parties such as mapping companies and CAVs may also be interested in field device information.	Simplifies design process for agencies wanting to interface with equipment manufacturers; aids in dynamically generating a WZDx feed with accurate information; reduces effort for manufacturers to conform to different agencies requirements.	Field devices (see FieldDeviceFeature).

Data Flow

                                                                                 |
                                                                                 | Various
                                                                                 | Additional Inputs
                                                                                 v
                                                                       +------------------+            +----------------+
                                                                       |                  |    WZDx    |                |
                                                                       |     DOT or       |    Feed    |    Traveling   |
                                                           +---------> |  Similar Agency  | ---------> |     Public     |
  Deployed Field    Lower-Level   +------------------+     |           |                  |            |                |
     Devices       Communication  |                  |     |           +------------------+            +----------------+
+---+ +---+ +---+    Protocols    |    Equipment     | ----+  Swz                |
|   | |   | |   |  -------------> |   Manufacturer   |       Device              | WZDxFeed                     ^
+---+ +---+ +---+                 |    or Vendor     | ----+  Feed               v                              |
                                  |                  |     |           +------------------+                     |
                                  +------------------+     |           |   Third-Party    |                     |
                                                           +---------> |   Stakeholders   | --------------------+
                                                                       |  (e.g. mapping   |
                                                                       |  companies, CAVs)|
                                                                       +------------------+

This PR is a draft for demonstration of the new models and how they will be integrated into the WZDx specification. The PR is a draft as it can not be finalized or merged until other v4.0 PRs are merged to the release branch (v4.0-release) as it would create a huge amount of unresolvable merge conflicts and a lot of manual work. This PR does not update examples files or the object diagram. It does include fully complete documentation for all the new objects and a new JSON schema for the new smart work zone device feed.

[j-d-b]

Following a comment from @sknick-iastate in the SWZ Subgroup meeting on 2021-09-27, it is clear that there should be an equivalent of the RoadEventDataSource for field devices.

Since the RoadEventDataSource is becoming generic in #209, it can be used for field device features. Thus if #209 passes, the only change needed in this PR is for a data_source_id property to be added to the FieldDeviceCoreDetails object. This change cannot be implemented until #209 is resolved.

Edit: I struck out the above line and added the data_source_id in this PR.

[j-d-b]

Following spec update co-chairs discussion on 2021-09-30 and swz co-chairs discussion on 2021-10-01 regarding #191, this PR was updated to include the FieldDeviceFeature in a new feed.

[j-d-b]

Should HybridSign dynamic_message_text property be optional to be consistent with DynamicMessageSign message_multi_string being optional to allow representing HybridSign devices that don't current have a message posted?

Edit: I decided yes, so I made the change.

[j-d-b]

I made some small formatting/typo changes and added some comments - please review when you get a chance. Thanks.

Thank you @chuehlien for some critical fixes and quality changes 🎉

[sergebeaudry]

I would suggest to change the DynamicMessagesSign object name to ChangeableMessageSign or simply MessageSign.

Those terms are in process to be refined by ASHTO, MUTCD and NEMA TS4. currently they are mixed and they should not. The umbrella term is going to be CMS (ChangeableMessageSign) as currently used in MUTCD (chapter 2L)

Changeable Message Sign—a sign that is capable of displaying more than one message (one of which might be a “blank” display), changeable manually, by remote control, or by automatic control. Electronic-display changeable message signs are referred to as Dynamic Message Signs in the National Intelligent Transportation Systems (ITS) Architecture and are referred to as Variable Message Signs in the National Electrical Manufacturers Association (NEMA) standards publication.

Dynamic Message Sign term will be reserved in the next MUTCD and NEMA TS-4 revision for high definition CMS.

The latest proposal at NEMA and ASHTO is based on this

[RHolt-RIDOT]

following up on @sergebeaudry's input above, I would support using the ChangeableMessageSign (CMS) object name.

[j-d-b]

@sergebeaudry your comment is valuable but was added too late to change what was approved for v1.0 of the SwzDeviceFeed specification. If you think it is important enough to be worth changing the naming of the DynamicMessageSign object to ChangeableMessageSign for the next specification release, please create an issue for that discussion.

Thank you.

[j-d-b]

I made changes to the file location and organization of the JSON schema to remove duplication between the schemas for the WZDxFeed and the SwzDeviceFeed. This will also facilitate the addition of the schema for the RoadRestrictionFeed in #205. Specifically:

• Moved the schemas directory to the project root for visibility and shorter URIs for schema $ids.
• Added a 4.0 subdirectory for the the WZDx version 4.0 schema. New releases should add a directory matching the version. This avoids having to have the version in every file name which also simplifies URIs. It also clarifies that the SwzDeviceFeed is part of WZDx v4.0, which is necessary since it shares objects (FeedInfo and FeedDataSource) with the WZDxFeed.
• Moved the schemas for WZDx objects that appear in both feeds (FeedInfo, FeedDataSource, BoundingBox) to separate files and referenced those files in the schema for each feed to avoid duplication.
• Updated the use of oneOf within the RoadEventFeature and FieldDeviceFeature properties to check the core_details event_type and device_type respectively to validate the rest of the object according to the type provided. It looks a bit messier, but it provides valuable functionality.

[j-d-b]

I did a bit of refactoring of the project README to describe that WZDx now defines multiple feeds. There is more I want to do with regards to visibility of important information and clarifying what WZDx is, however, that is better implemented in a separate PR to avoid cluttering this one.

[j-d-b]

I did two more things as part of helping clarify that there are now multiple "WZDx Feeds":

• Move the examples out of the create-feed directory and into the project root for visibility—after this create-feed contained only a README Markdown file.
• Move the create-feed README to Creating_a_WZDx_Feed.md for clarity and visibility.
• Remove duplicate content between the project root README.md and Creating_a_WZDx_Feed.md.
• Update references.

What we should do as part of the v4.0-release editorial changes is review the Creating_a_WZDx_Feed.md vs project README.md vs /spec-content/README.md and see if we can make each of those files have a clear message without much overlap to facilitate new users being able to understand what the repository/wzdx is defining and how to use it.

[j-d-b]

@mark-mockett thanks for reviewing. We can discuss the schema in our meeting next week.