The MS2Data format is an XML file format that allows the transfer of data between traffic counter equipment and the MS2’s system. Since version 1.19.0, FLOW supports the following formats of the MS2Data Import Format Specification version 1.8:
Per Vehicle Records (PVR) from the Traffic Count Database System (TCDS) module
Volume data from the TCDS module
Turning Movement Counts (TMC) from the module of the same name
This article will guide you through the set-up process for sending each of these formats.
Setting up the MS2 interface
In FLOW Insights, you can find the MS2 interface overview page in the left menu among the other interface types.
When you add a new MS2 interface and go to the edit screen, you'll be able to set up its various options.
Fill the address and port of the target MS2 server. The username and API key will be used as part of the request to authenticate FLOW messages. The protocol used will always be HTTPS.
Example: If the fields are filled as follows:
Address:
example.ms2server.com
Port:
443
Username:
JohnDoe
API key:
FooBar
Then MS2 data HTTPS requests will be sent to https://example.ms2server.com:443/api/Import/v1/tcds/Upload/Ms2Data?username=JohnDoe
with the ApiKey: FooBar
header.
There's no conclusive mapping of FLOW vehicle categories to the 13 FHWA classes that MS2 uses. That's why the interface lets you define your own mapping if the default one doesn't suit your needs. Note that when sending TMC messages, FLOW presents its own category types and the mapping isn't used.
When you select Save settings and go Back to the interface overview, the Connection status column will show you whether FLOW has successfully connected and authenticated with the server using its /api/Import/v1/tcds/Upload/Ping
endpoint.
Setting up topics
To actually send data to the server, you first need to create a topic and connect it with an existing Traffic events widget or an Event expression widget.
For this example, a zone has been created over each traffic lane that approaches the intersection and an Events widget has been attached to each one.
You may want to change this setup depending on the chosen MS2 data format. You can find details about appropriate setups for each format below in the corresponding format sections.
Now you can go back to editing the MS2 interface. Add a topic, edit it, fill the required fields, and select the Events widget that should act as a source of data. Then select Apply on the bottom.
From now on, data collection starts for the new topic and, once the minimum duration has elapsed, it'll be sent to the MS2 server. In the topic table, the Last processed data timestamp column shows the timestamp of the end of the time interval before the current one. Alternatively, you can think of it as the start of the current data collection interval. Last message sent timestamp shows when data has last been successfully delivered to the MS2 server. All times are UTC.
Topic setup details
The MS2 data module lets you select the data format as listed at the start of this article. Each format has specific fields to fill and determines FLOW's data collection and sending behavior as required by the MS2 format specification.
Location specifiers (site ID, sensor ID, MS2 location ID, and TMC intersection ID) are assigned and provided by the MS2 company. Generally, an intersection ID is provided and the MS2 location ID is derived from it by appending the abbreviation of the cardinal direction of the intersection leg or roadway direction from the center of the intersection or road. E.g. if the TMC intersection ID is 133, then the northern leg's MS2 location ID would be 133N etc. Semi-cardinal directions are also supported. E.g. a northwestern leg's MS2 location ID would be 133 NW.
If you opt to specify the location with the MS2 location, direction, and lane number, you may omit one or both of the latter to select the level of detail that the topic provides. I.e.:
Roadway level: Only MS2 location ID is specified
Directional level: MS2 location ID and direction are specified
Lane level: MS2 location, direction, and lane number are specified
Lane numbers start with 1 at the lane closest to the curb in the given direction and increases towards the middle of the road. The opposite direction of the same leg has its own numbering starting at the curb. Other legs also don't share lane numbers and have their own numbering.
Depending on the level on which you want to provide data, you should adjust the layout of the gates or zones in the associated analytic. E.g. if you provide only roadway-level data, create a zone that covers an area that all vehicles must pass. For directional-level data, create a gate for each leg of the intersection that covers all approach lanes. For lane-level data, make a gate for each approach lane separately. For each spatial operator/widget pair, you need to create a separate topic and assign the widget to it.
Analytics let you specify their WGS 84 coordinates in Analytics settings. In Topic settings, you may then choose to include these coordinates in data exports to the MS2 server. If you georegister the analytic, you can also include vehicles' average speed in the exports. Alternatively, you can pair a topic with an Events widget that is attached to a Movement operator and set the length of this operator. This lets you send Section speed of passing vehicles.
The Send only data newer than field lets you setup a survey for a specific time in the future—older data won't be sent. Keep in mind that the specified time will be considered UTC and compared to the current time of the analytic's video source (usually a camera).
PVR data format
This format lets FLOW send information about each passing vehicle on the chosen level of detail, namely: time when the vehicle trajectory has ended, FHWA class, and speed (its type is based on your choice during topic setup). Information that you entered during topic setup will also be included.
Due to MS2 server limitations, FLOW must collect at least 24 hours of continuous data from midnight to midnight before sending it. Therefore, video stream availability disruptions of a cumulative length larger than 72 minutes per 24 hours will cause FLOW to discard all collected data and start again. Restarting FLOW will also cause you to lose collected data that hasn't yet been sent to the server. As soon as FLOW has midnight to midnight of continuous data, it sends it to the MS2 server with a grace period of 10 seconds. The data collected in the interval since starting FLOW to the first midnight won't be sent to the MS2 server. Therefore it's possible that in the topic table you could see that the Last processed data timestamp is in the future, just before midnight. This means that FLOW is waiting for the current incomplete interval to end so that it can start the next one.
To provide MS2 with even more statistics calculation options, try to provide data for both traffic directions of each intersection leg, with the appropriate MS2 direction setting. You can find details in the PVR example below.
Volume data format
This format simply aggregates counts of passing vehicles for the specified roadway/direction/lane in 1, 15, or 60-minute intervals. It provides lower level of detail than the PVR format, but is less data transfer intensive. The same limitations regarding having data from midnight to midnight as with the PVR data format are also true with this format.
TMC data format
This arguably most detailed format is similar to PVR, but additionally it includes the direction in which vehicles travel through the intersection (left, straight, right etc.) and enables FLOW to send its own vehicle category name instead of using the FHWA class number. The location specifiaction must include a MS2 location ID, direction (i.e. vehicles approaching from the north leg travel in the southern direction regardless of their actual turning movement), and TMC intersection ID. This format doesn't distinguish between individual lanes.
Unlike with the previous formats, minimum length of collected TMC data before sending to the MS2 server is 15 minutes. That's also the interval in which FLOW will send the collected data to the server, with a grace delay of 10 seconds. However, the 15-minute time blocks must be complete (the maximum allowed cumulative video interruption gap is 45 seconds per 15 minutes) and aligned to the whole hour (intervals start at 0 minutes, 15 minutes, 30 minutes, and 45 minutes each hour).
Practical example: PVR data
This section will walk through the process of setting an example scenario for data collection. Consider the following scene, which represents the northeastern leg of intersection 133.
You can see part of the image is gray, because a ROI has been created in the analytic settings to allow for detection of vehicles that are further away. To get vehicle data on a per-lane basis, a gate must be created for each lane.
Gates are named by their approach direction and number to increase readability and decrease possibility of error during setup. Some've been also created for traffic leaving the intersection. All gates are shifted further from the stop line, because sometimes a passing truck may occlude a large part of the screen and prevent detection of some cars passing through a gate.
Let's take a closer look at the gate creation process. You may find it useful to display a discretisation grid during this part.
The grid represents the smallest elements at which FLOW is able to distinguish between trajectory positions. Red cells mean they're occupied by a trajectory, light gray cells mean they're occupied by a spatial element, in this case a gate. You can see the gates have been positioned in such a way that they occupy neighboring cells and their areas don't overlap.
To further help you with positioning the gates, you can turn on trajectory history display.
FLOW considers a trajectory as having passed the gate when its position (red cell) or an interpolation between its two positions passes the gate area (light gray cell). This means it's still possible for a vehicle to pass two gates, e.g. when switching lanes, and be counted twice. To prevent this, a lane priority system needs to be set up on the operator canvas.
This setup ensures that vehicles passing through two gates will only be counted in one event widget. You can see an example of this working in the difference between the NE leave lane 1 vehicle count (32) and the Intersection operator count (31) that's below it.
The first gate operator in the chain and each intersection operator have an Event widget attached to them that serves as an input for individual MS2 topics. Check that they're named in a way that lets you discern them apart.
Now the analytic is ready for use by MS2 topics. A topic has been created for each lane and each topic has been paired with a different Event widget. Here's an example of a topic configuration.
Again, check that the topic name is descriptive enough. As the intersection ID is 133 and the analytic is analyzing its northeastern leg, the MS2 location ID is 133NE
. The vehicles are travelling southwest (before crossing the intersection). The WGS 84 location has been assigned to the analytic in its Analytic settings, so Include analytic's WGS 84 coordinates can be switched on in the topic settings.
To increase MS2 servers' statistic calculating capabilities, gates for the direction leaving the intersection have also been created. Here's an example configuration for one of their topics.
You can see that as opposed to the approaching lanes, here the MS2 direction is northeast.
The above steps are repeated for each lane of each leg of the intersection to complete the data collection configuration. Check that the MS2 server status is marked as Online in the MS2 interface overview and FLOW will handle the rest.
Practical example: TMC data
This section will walk through the process of setting an example scenario for TMC data collection for the southwestern leg of intersection 133. Its layout is similar to the northeastern leg in the previous example.
Again, a ROI has been created to increase the distance in which FLOW is able to detect traffic objects. However, enough space must remain beyond the border gates so that FLOW is able to register that vehicles have passed through them—about one vehicle width of free space.
The above picture already shows the layout of the spatial operators. A common gate has been created for all lanes of the approach direction and another gates for each direction that the vehicles could take. The approach gate and each exit gate are connected by a movement. The movement operators are dragged to the operator canvas and each one is assigned an event widget.
Vehicles doing a U-turn pass through the left movement gate, so to prevent double counting, a priority system has again been implemented here.
Now that the Event widgets are separated by target direction, four different MS2 topics can be created, each being paired with a different Event widget. Here's an example of the right turn topic.
Keep in mind that the MS2 direction code corresponds to the vehicle's direction of travel before turning.
The above steps are repeated for each turning movement of each leg of the intersection to complete the data collection configuration.
If you need further clarification or help, click the button on the bottom right to chat with us or contact us here. We're happy to help!