4 May 2017

IRIS Administrator Guide

Overview

IRIS is an open source advanced traffic management system. It provides an integrated platform for transportation agencies to manage traffic monitoring and control devices. The software is written in Java and licensed for anyone to use under the GPL. In addition, all dependencies required to install and operate an IRIS system are available as free software. IRIS stands for Intelligent Roadway Information System.

The IRIS software presents an intuitive map-based interface to system operators. This user interface has been refined over many iterations by getting feedback from operators to streamline their workflow.

System Architecture

System Architecture IRIS System Architecture IRIS Clients Apache Server - Client JARs - Map Tiles IRIS Server Authentication Server (LDAP) (Optional) Traffic Monitoring and Control Devices Database (PostgreSQL)

The software has a client/server architecture. System configuration data is stored in a PostgreSQL database, and managed by the IRIS server. The server also handles communication with all traffic control and data collection devices. The client software is distributed by an Apache web server, using Java Web Start. All communication between the server and clients is encrypted using secure socket layer (SSL). The server may be configured to pass authentication requests off to an external LDAP server, allowing IRIS to integrate into an existing authentication system.

Device Types

IRIS is able to manage several different types of traffic monitoring and control devices. These include:

Protocols

Many different protocols are supported for communicating with the various device types. Additional protocols can be added for any existing device type by programming a simple driver interface. These are some existing protocols:

Advanced Features

IRIS also contains some higher-level traffic management features:

Installation

Operating System

Install Fedora onto the server computer. Other operating systems, such as Red Hat Enterprise Linux, can also be used, but the procedures may vary slightly. This machine should have a minimum of 2 GB of RAM and 200 GB hard drive storage space. The IRIS server does not have a GUI interface, so this computer can be set up headless.

After the operating system is installed, make sure the hostname is configured correctly in DNS. The hostname is needed for some configuration files in the following steps. The following command should display the hostname that can be used to access the server:

hostname -f

Install IRIS

Download and install the IRIS package. This should be a file called iris-{major}.{minor}.{micro}-{build}.{arch}.rpm. The {major}, {minor}, and {micro} version numbers and the {build} number can change with each release. The system architecture, {arch}, will be noarch, since Java is architecture independent. It can be installed with the following command (as root):

dnf install iris-{major}.{minor}.{micro}-{build}.noarch.rpm

This will install dependencies not already installed, including OpenJDK, PostgreSQL and Apache.

Initialize IRIS

Next, you must initialize the IRIS server installation. Run the following command (as root):

iris_ctl init

This command will perform the following steps:

  1. Update the /etc/iris/iris-client.properties file with the server's hostname.
  2. Create an SSL key pair for encrypted communication between the server and clients. The keystore files are /etc/iris/iris-server.keystore and /etc/iris/iris-client.keystore. The keystore passwords are put into /etc/iris/iris-server.properties and /etc/iris/iris-client.properties.
  3. Create a symbolic link to the PostgreSQL JDBC driver to make it available to the IRIS server.
  4. Create the database cluster and start the PostgreSQL server.
  5. Create the "tms" PostgreSQL user, which IRIS uses to connect to the database.
  6. Create the "tms" database and populate it using a template SQL script.
  7. Configure the apache (httpd) and IRIS services to start automatically.
  8. Create symbolic links to the current IRIS software version.

The command should finish with the following message:

Successfully initialized the IRIS server

Server Properties

The IRIS server has a configuration file which controls some of its basic settings — /etc/iris/iris-server.properties. Most of the default settings should work, but it may be necessary to make some changes. The file can be modified using a text editor, such as gedit or vi.

Internationalization

There are three properties which control internationalization (i18n). They are language, country and variant. These should only be changed if the IRIS software has been localized for a specific locale.

District

This property is used when multiple IRIS servers are running within the same organization.

HTTP Proxy

These properties can be used when IRIS must connect to HTTP servers using a proxy server, due to organization firewall policies.

Database Connection

The db.url, db.user and db.password properties control how the IRIS server connects to the PostgreSQL database. None of these properties should be changed, since they were configured earlier by the iris_ctl script.

SONAR Configuration

The sonar.ldap.urls property can be used to let IRIS pass user authentication requests to one or more LDAP servers. Multiple URLs must be separated by a space. IRIS can manage user accounts and passwords without an LDAP server, but this feature allows operators to log into IRIS without requiring them to remember an additional user name and password. If your organization already has an LDAP server, such as Active Directory, you should use that.

The URL protocol is normally ldap:, but must be ldaps: for encrypted communication over SSL. To use ldaps, you must first import the SSL certificate into the IRIS keystore. Once you have obtained the SSL certificate for the LDAP server, save it as ldap.cert. Now you can import it with the following command (as root):

keytool -import -alias ldap-cert -keystore /etc/iris/iris-server.keystore -file ldap.cert

The keystore.password is used for accessing keys in /etc/iris/iris-server.keystore. This password is automatically generated by the iris_ctl script. It will not need to be changed.

Start Services

Finally, the IRIS server can now be started with the following command:

systemctl start iris

Check that everything started OK:

tail /var/log/iris/iris.stderr
systemctl status iris

This should indicate that IRIS is active and running.

Initial Login

From a client computer with Java installed, point your web browser at http://YOUR_SERVER_NAME/iris-client/. From there, you should be able to launch the IRIS client Web Start application and log in.

Enter admin as the username and atms_242 as the password for the initial login. After creating and logging in with a real administrator account, the admin user account should be disabled.

Basic Setup


Client Properties

The IRIS server has a configuration file which contains default properties for clients — /etc/iris/iris-client.properties. These properties include internationalization, network proxy, and other system configuration. Note that even though IRIS has been internationalized, it has not yet been translated to languages other than english.

language
ISO 639 alpha-2 or alpha-3 language code. E.g., "en", "es", "fr".
country
ISO 3166 alpha-2 country code or UN M.49 numeric-3 area code. E.g., "US", "MX", "CA".
variant
IETF BCP 47 language variant subtag.
district
District name. Useful in cases where multiple IRIS servers exist within the same organization.
http.proxy
List of HTTP proxy settings (used for downloading map tiles, XML files, etc.)
http.proxy.whitelist
A list of addresses to bypass using proxy server. Addresses are in CIDR notation (exact IP, or ranges specified such as 192.168.1.0/24).
keystore.file
URL for the client keystore file.
keystore.password
Password for the client keystore.
sonar.host
IP or hostname of the SONAR server.
sonar.port
TCP port number of the SONAR server.
tdxml.detector.url
URL for XML detector stream.
map.tile.url
Base URL for map tileset. Must end in "/".
video.host
IP or hostname of video server/proxy.
video.port
TCP port number of video server/proxy.
video.extviewer
External video viewer.
autologin.username
A username to be used for automatic login upon client startup. Note: use of this property is a security risk.
autologin.password
A password to be used for automatic login upon client startup. Note: use of this property is a security risk.
tab.list
A list specifying the visibility and ordering of the primary UI tabs in the IRIS client. The default value is: incident, dms, camera, lcs, ramp.meter, gate.arm, r_node, action.plan, comm
scale
User interface scaling factor (0.25 to 4.0). Useful for Hi-DPI screens.

User Properties

The IRIS client also reads a property file on client computers. The file is named "user.properties", and can be found in the "iris" folder of the user's home directory. It can contain overrides for any of the default values in the client properties file. The file is overwritten when logging out. The window geometry and last selected tab will be updated, but all other properties will be left unchanged.

Edit Mode

There is an edit mode toggle button on the lower-right corner of the IRIS client. When the edit mode is OFF, all configuration changes will be disallowed. This feature prevents administrators from accidentally modifying the system while looking up information. It is recommended to only turn the edit mode ON while updating the system configuration. Note: edit mode does not grant any capabilities which are not already associated with the user's role.

System Attributes

A system attribute is a configurable value which can be used to customize an IRIS system. Each system attribute has a corresponding type: string, boolean, integer or floating point number. String values are limited to 64 characters or less. Boolean values must be specified as either "true" or "false". Many numeric system attributes are constrained to a range of values within a minimum and maximum bound, depending on the attribute. A system attribute can be customized by updating the value in the table on the System Attributes form. When a system attribute has been modified from its default value, it will be displayed in bold. Most attribute changes take effect immediately, but some require the IRIS client or server to be restarted. Some System Attributes are described in more detail below.

map_segment_max_meters

This is used for two distinct purposes: 1) specifying the maximum distance between adjacent stations to draw segments on the map and 2) specifying the maximum distance from a station to another downstream station for associating density, speed, etc. data with a segment.

Users and Roles

When a user logs into the IRIS system, the user is checked for validity. The user account must be enabled, and be assigned to an enabled role for a log in to succeed. If the user has a "distinguished name" (dn), then authentication is performed using LDAP. Otherwise, IRIS checks the password against the stored password hash for that user account.

The template SQL database contains one administrator role, called admin. This role is assigned capabilities which allow unfettered access to the IRIS system. Other roles can be created by an administrator, to allow users with a specific set of capabilities, as needed. For example, there are capabilities defined for each of the main tabs on the user interface: camera_tab, dms_tab, lcs_tab, meter_tab, etc. Also, these capabilities can be disabled, preventing any user from having access to them. So, if a system does not contain any LCS devices, the lcs_tab capability could be disabled globally, to prevent that tab from appearing in the user interface for any users. WARNING: changes take effect immediately — if the user_admin capability is disabled or removed from the administrator role, the administrator will lose access to change roles and capabilities.

Mapping

The IRIS client can use map tiles to display high-quality maps as a background layer. The map tiles are fetched from a web server on demand as the client map is panned and zoomed. The tiles can be generated from data downloaded from OpenStreetMap. The following instructions describe one method of generating the map tiles on Fedora 20.

Get planet file

Download the latest planet file (about 32GB).

wget http://planet.openstreetmap.org/planet/planet-latest.osm.bz2

Download and install PostGIS

sudo dnf install postgis postgis-docs postgis-utils

Configure PostGIS and create spatial DB

# Create DB named gis
su - postgres
createdb --encoding=UTF8 gis
psql -d gis -f /usr/share/pgsql/contrib/postgis-64.sql

# Edit kernel parameters to increase max size of shared memory
sudo sysctl -w kernel.shmmax=268435456
sudo sysctl -p /etc/sysctl.conf
sysctl -a | grep kernel.shmmax

# Update postgresql config
vim /var/lib/pgsql/data/postgresql.conf
	checkpoint_segments = 20
	maintenance_work_mem = 256MB # 256000 for 8.1 and earlier
	autovacuum = off
	shared_buffers = 4GB
	temp_buffers = 128MB
	maintenance_work_mem = 4GB
service postgresql restart

Build and install osm2pgsql from source

su - tms
sudo dnf -y install git
sudo dnf -y install geos-devel proj-devel postgresql-devel libxml2-devel bzip2-devel
sudo dnf -y install gcc-c++ protobuf-c-devel autoconf automake libtool
mkdir ~/osm; cd ~/osm
git clone https://github.com/openstreetmap/osm2pgsql.git
cd ~/osm/osm2pgsql
./autogen.sh
./configure
make
sudo make install

Import OSM planet file into PostGIS

This process takes a long time (around 30 hours). See performance comparisons here. Determine the bounding box for the region of interest. For Minnesota it is: -97.5, 43.0, -89.0, 49.5.

su - postgres
osm2pgsql -v --number-processes=16 -d gis -s --bbox -97.5, 43.0, -89.0, 49.5 planet-140522.osm.bz2

Build and install mapnik library from source

See the mapnik install docs. The Springmeyer docs are also very useful.

su - tms
# Install dependencies
sudo dnf -y install make gcc47 gcc-c++ bzip2-devel libpng-devel libtiff-devel \
      zlib-devel libjpeg-devel libxml2-devel python-setuptools git-all \
      python-nose python27-devel python27 proj-devel proj proj-epsg \
      proj-nad freetype-devel freetype libicu-devel libicu
# Install optional deps
sudo dnf -y install gdal-devel gdal postgresql-devel sqlite-devel sqlite \
      libcurl-devel libcurl cairo-devel cairo pycairo-devel pycairo
# Build recent version of Boost
export JOBS=`grep -c ^processor /proc/cpuinfo`
mkdir -p ~/osm/src; cd ~/osm/src
export BOOST_VERSION="1_55_0"
export S3_BASE="http://mapnik.s3.amazonaws.com/deps"
curl -O ${S3_BASE}/boost_${BOOST_VERSION}.tar.bz2
tar xf boost_${BOOST_VERSION}.tar.bz2
cd boost_${BOOST_VERSION}
./bootstrap.sh
./b2 -d1 -j${JOBS} \
    --with-thread \
    --with-filesystem \
    --with-python \
    --with-regex -sHAVE_ICU=1  \
    --with-program_options \
    --with-system \
    link=shared \
    release \
    toolset=gcc \
    stage
sudo ./b2 -j${JOBS} \
    --with-thread \
    --with-filesystem \
    --with-python \
    --with-regex -sHAVE_ICU=1 \
    --with-program_options \
    --with-system \
    toolset=gcc \
    link=shared \
    release \
    install
cd ~/osm/src
# Set up support for libraries installed in /usr/local/lib
sudo bash -c "echo '/usr/local/lib' > /etc/ld.so.conf.d/boost.conf"
sudo ldconfig
# Build and install mapnik stable branch: 2.3.x
mkdir -p ~/osm/src; cd ~/osm/src
git clone https://github.com/mapnik/mapnik -b 2.3.x
cd ~/osm/src/mapnik
./configure
make
make test-local
sudo make install
# Verify everything is good
echo “import mapnik” | python

Install mapnik tools

See docs.

sudo dnf -y install svn
cd ~/osm
svn export http://svn.openstreetmap.org/applications/rendering/mapnik
# Install prepared world boundary data
cd ~/osm/mapnik
mkdir world_boundaries
wget http://tile.openstreetmap.org/world_boundaries-spherical.tgz
tar xvzf world_boundaries-spherical.tgz
wget http://tile.openstreetmap.org/processed_p.tar.bz2
tar xvjf processed_p.tar.bz2 -C world_boundaries
wget http://tile.openstreetmap.org/shoreline_300.tar.bz2
tar xjf shoreline_300.tar.bz2 -C world_boundaries
wget http://www.naturalearthdata.com/http//www.naturalearthdata.com/download/10m/cultural/ne_10m_populated_places.zip
unzip ne_10m_populated_places.zip -d world_boundaries
wget http://www.naturalearthdata.com/http//www.naturalearthdata.com/download/110m/cultural/ne_110m_admin_0_boundary_lines_land.zip
unzip ne_110m_admin_0_boundary_lines_land.zip  -d world_boundaries

Patch osm.xml to create iris_osm.xml

cd ~/osm/mapnik/
cp osm.xml iris_osm.xml
patch -p0 < ../01_drop_junc_power_layers.patch
patch -p0 < ../02_interstate_shields.patch
patch -p0 < ../03_trunk_shields.patch
patch -p0 < ../04_cty_rd_shields.patch
patch -p0 < ../05_motorway_color.patch
patch -p0 < ../06_trunk_color.patch
patch -p0 < ../07_primary_color.patch
patch -p0 < ../08_secondary_color.patch
patch -p0 < ../09_tertiary_color.patch

Copy symbols used for roadway shields

FIXME

Generate tiles

Generating tiles takes about 2 hours on a 16 processor system, or about 13K tiles/min.

su - tms
cd ~/osm/mapnik
export MAPNIK_MAP_FILE=~/osm/mapnik/iris_osm.xml
export MAPNIK_TILE_DIR=/home/tms/osm/tiles
# Customize osm.xml
./generate_xml.py  --dbname gis --accept-none
vim generate_tiles_multiprocess.py
	NUM_THREADS = number of processors in your server
	bbox = (-97.5, 43.0, -89.0, 49.5)
	minZoom = 6
	maxZoom = 16
	# comment all of the european cities listed
timer ./generate_tiles_multiprocess.py
# Copy tiles to server hosting them
scp -rp ~/osm/tiles/* root@tilehost:/var/www/html/

Create Map Extents in IRIS database

This form enables the creation of map extents, which are buttons allowing quick selection of a map location and zoom level. Each map extent will be displayed as a button on the upper right area of the map (next to the zoom in/out buttons). First, a "Home" extent should be created, which is selected by default when a user logs in. Other extents can also be created for commonly selected map spots.

Road Topology

R_Nodes R_Nodes

For many of the features IRIS provides, a model of the road network topology is required. This model consists of a set of roadway nodes, or r_nodes, which describe all the points of interest on the road network. For instance, each entrance or exit ramp, detector station or intersection would be represented by an r_node.

All r_nodes with the same road and direction-of-travel are grouped into corridors. The r_nodes within a corridor are automatically sorted based on their coordinates. Corridors are linked to each other by exit and entrance r_nodes. For example an exit r_node from Northbound road A to Eastbound road B would automatically link to an entrance onto Eastbound road B from Northbound road A.

Road Setup

Before creating r_nodes, some roads must be created. With edit mode ON, enter the road name into the text box at the bottom of the form and press the Create button. Road names must be unique, and can be up to 20 characters in length. It's a good idea to capitalize each word, and abbreviate any designators — for example, "Main St".

When a road is created, it will be added to the Roads table. Other road attributes can be changed here. The second column is Abbrev, which is an abbreviation of the road name (up to 6 characters). This is used for labeling detectors and stations.

The Road Class determines the presentation of the road on the map. For example, a road marked "Freeway" would be drawn thicker and more prominent than an "Expressway" or "Arterial".

Direction and Alt Dir determine the primary and secondary compass directions of the road.

R_Node Location

Select the R_Nodes tab on the client interface to create or edit r_nodes. In the Selected Roadway Corridor frame, there is an Add button. Press the button to start creating a new r_node. The mouse cursor will change to a target while over the map. Select the point on the map where the r_node should be located and left-click the mouse. The new r_node will appear on the map, and in the list for the selected corridor.

In the Selected Roadway Corridor frame, there is a Corridor widget containing a list of all corridors which contain at least one r_node. When a corridor is selected, the r_node list will be populated with all r_nodes on the corridor. Also, any new r_nodes created will be on the selected corridor.

Once an r_node is selected, any fields on the Location tab can be edited. Changing the roadway or direction will move the r_node to another corridor. Other attributes are nearest cross-street, cross-street direction, and notes.

R_Node Setup

The r_node Setup tab contains several more attributes.

node_type
There are six different r_node types:
Code Node Type Description
0 station Mainline detector station or shape node
1 entrance Entrance ramp onto corridor
2 exit Exit ramp off corridor
3 intersection At-grade intersection with another corridor
4 access Network access (for traveler information)
5 interchange Freeway interchange (for traveler information)
transition
An r_node transition describes how entrance or exit nodes connect with linked nodes.
Code Transition Description
0 none No transition — non-entrance or -exit r_nodes
1 loop Interchange loop ramp — "leaf" part of cloverleaf
2 leg Typical "leg" ramp
3 slipramp Transition ramp between parallel corridors
4 CD Transition to/from collector/distributor road
5 HOV Bypass ramp for high-occupancy-vehicles
6 common Common section joining two corridors
7 flyover Flyover ramp (bridge over mainline)
lanes
Number of lanes at r_node. For a ramp node, this is the number of lanes entering or exiting the mainline.
shift
Lane shift is the difference (number of lanes) between the corridor reference lane and the attach side of the r_node. This value is used for lane continuity analysis within a corridor. Each corridor has a reference lane, which corresponds to the leftmost lane along the entire corridor.
station_id
The station_id is a unique identifier for the detectors associated with the r_node. It is displayed on the traffic layer, and is also used for identifying travel time destinations.
speed_limit
This is the posted speed limit at the r_node. The units are miles per hour, but should in future be dependent on locale (KPH). For ramp r_nodes, it may be used to indicate the advisory speed limit on the ramp. The limit is used in travel time estimation.
pickable
For deploying DMS from incidents, an r_node can be marked pickable if the road name should be used on the sign message.
above
When rendering the traffic layer, r_nodes are rendered in two passes. The second pass consists of r_nodes which have been marked above. This prevents overpasses from being drawn incorrectly.
attach_side
This flag indicates whether the r_node is attached to the left side of the road. This can be used to create left entrance or exit ramps.
active
This flag allows an r_node to be deactivated. An inactive r_node will not be included in any corridor or drawn on the traffic layer.

R_Node Detectors

The r_node Detectors tab allows vehicle detectors to be created and associated with an r_node.

A comm link is a network connection to an external device or system. IRIS is capable of supporting hundreds of simultaneous comm links. Each comm link has a number of attributes, including URI and protocol.

The URI includes a DNS host name or network IP address, and port number, using the standard "host:port" convention. The URI can also contain an optional "scheme" prefix, which can be either "udp://", "tcp://" or "modem://". If present, the scheme will override the default URI scheme for the selected protocol. For example, to use the Pelco D protocol over TCP (instead of the default UDP), add a "tcp://" scheme prefix to the URI.

The protocol determines what type of device or system is on the other end of the comm link. The following table contains the communication protocols supported by IRIS.

Protocol Description Default Scheme Multidrop
NTCIP A DMS control, ILCS (no HDLC) UDP No
NTCIP B DMS control, ILCS over serial (HDLC) TCP Yes
NTCIP C DMS control, ILCS (no HDLC) TCP No
DMS XML DMS control to external system TCP Yes
Addco DMS control (NodeComm) TCP Yes
Msg feed DMS messages from external system HTTP No
MnDOT 170 4 VDS, metering, DLCS, beacons, alarms TCP Yes
MnDOT 170 5 VDS, metering, DLCS, beacons, alarms TCP Yes
Canoga VDS (GTT Canoga Traffic Sensing System) TCP Yes
SS105 VDS (original Wavetronix SmartSensor) TCP Yes
SS125 VDS (Wavetronix SmartSensor HD) TCP Yes
RTMS G4 VDS (RTMS G4 sensor) TCP Yes
DR-500 VDS (Houston Radar DR-500 doppler) TCP No
Axis PTZ PTZ for Axis cameras HTTP No
Pelco D PTZ for Pelco cameras UDP Yes
Manchester PTZ for AD cameras UDP Yes
Vicon PTZ for Vicon cameras UDP Yes
Infinova PTZ for Infinova cameras TCP Yes
Cohu PTZ for Cohu cameras TCP Yes
Pelco P KBD Video switching and PTZ input TCP No
Pelco Switcher Video switching for Pelco TCP No
MonStream Video switching for simple streaming decoders UDP No
STC Gate Arm control for HySecurity SmartTouch Controllers TCP Yes
E6 Tag Reader (Transcore E6) UDP No
Org 815 RWIS (ORG 815 sensor) TCP No
SSI RWIS (SSI RWIS sensor) HTTP No
DLI DIN Relay DLCS, beacons HTTP No
CBW beacons (Control by Web) HTTP No
Incident feed Incidents from external system HTTP No

DMS Msg Feed Protocol

The "msg feed" protocol can be used to interface IRIS with an external system that generates DMS messages. Periodically, IRIS will poll the URI (using HTTP) for DMS messages. The external system should respond with an ASCII text file, with one line per message to be deployed.

Each line must contain 3 fields, separated by tab characters "\t" (ASCII 0x09), and terminated with a single newline character "\n" (ASCII 0x0A). The fields are DMS name, MULTI string, and expiration time. The DMS name must exactly match one of the DMS as identified by IRIS. The MULTI string specifies a message to display on the sign, using the MULTI markup language, from NTCIP 1203. For example, "ROAD CLOSED[nl]AHEAD[nl]LEFT LANE CLOSED" is a valid three-line MULTI message. The expiration field indicates the date and time that the message should expire. It is in "yyyy-MM-dd HH:mm:ssZ" format, which includes date, time and time zone. A valid expiration time would be 2012-05-15 11:37:00-0600.

There are a couple of other required steps to enable a message feed to operate. First, an action plan must be created which associates a DMS action with the message feed. The DMS action must be associated with a quick message that references the message feed, using a feed action tag. So, if the message feed is on a Comm Link called "LFEED", then the quick message MULTI string must be "[feedLFEED]". Also, the action plan must be active and deployed. This requirement allows only administrator-approved DMS to be controlled by the message feed.

The other requirement for message feeds is that all messages used by the feed must be defined in the DMS message library. This requirement allows only administrator-approved messages to be deployed by the message feed. In some circumstances, it may be appropriate to disable this checking. For example, if the message feed host is fully trusted and there is no possibility of man-in-the-middle attacks between IRIS and the feed host. In this case the msg_feed_verify system attribute can be set to false to disable this check.

To control DMS beacon activation through a message feed, configure 2 message feeds. One message feed is for DMS containing messages with activated beacons and the other for messages with deactivated beacons. There is no way to control which message feed is executed first, so each message feed must list each DMS and at least one of the message feeds must contain a blank MULTI for each DMS.

DIN Relay

DIN relay is a product by DLI which allows simple devices to be turned on of off through an HTTP (web) interface. Each device can control up to 8 outlets, which for a DLCS means 2 lanes with 3 indications each.

Control By Web

Control By Web is a web-based relay controller made by Xytronix. It can be used to control beacon devices.

HTTP Basic Authentication can be used to connect with the controller if enabled on the setup page of the device (setup.html). To allow IRIS to authenticate, the password field must have none: prepended to the actual password (user name "none").

Incident Feed Protocol

The "inc feed" protocol can be used to interface IRIS with an external system that generates incidents. Periodically, IRIS will poll the URI (using HTTP) for incidents. The external system should respond with an ASCII text file, with one line per active incident.

Each line should contain 6 fields, separated by comma characters "," and terminated with a single newline character "\n" (ASCII 0x0A). The fields are incident ID, type, incident detail, latitude, longitude, and camera ID. The type must be CRASH, STALL, ROADWORK, or HAZARD. The detail may be blank, or one of the incident detail names. Latitude and longitude must be coordinates of the incident. Camera ID may be blank, or the ID of a camera to view the incident.

Controllers

A controller is an end-point for a comm link. Each controller can have one or more associated devices, depending on the protocol. Sometimes a controller represents a separate physical "box", which is connected to devices, and other times the controller may be embedded within the device. In any case, IRIS requires a controller for any communication to a device. Controllers can be assigned to a cabinet, which has location information, to allow displaying on a map.

Drop Address

Some protocols support multi-drop addressing, and others are single-drop only. Multi-drop addressing allows multiple controllers to share the same comm link. It is typically used with serial communication protocols. Each controller is assigned a unique (to the comm link) drop address, which is used to route all messages sent to the controller. For single-drop protocols, the drop address is ignored.

Controller Password

Some protocols allow or require authentication. The controller Password field is used to enter this authentication data. For example, NTCIP requires the use of an SNMP "community" name. If no controller password is selected, IRIS will use "Public" for the community name. Web-based devices may require HTTP Basic Authentication. For these types of devices, the password field should contain both the user name and password, separated by a colon (user:password).

I/O Pins

Each controller has a set of I/O pins, to which devices can be assigned. The function of these pins is protocol specific — see the following table.

Device Type Protocol I/O Pin(s)
DMS, ILCS NTCIP (A, B, C), DMS XML, Addco 1
DLCS MnDOT 170 (4, 5) 19 - 36
DIN Relay 1 - 8
Camera Pelco D, Manchester, Vicon, Infinova, Cohu 1
VDS MnDOT 170 (4, 5) 39 - 62
Canoga 1 - 4
SS105, SS125 1 - 8
RTMS G4 1 - 12
Ramp Meter MnDOT 170 (4, 5) 2 or 3
Gate Arm STC 1
Tag Reader E6 1
Beacon MnDOT 170 (4, 5) 2
DIN Relay 1 - 8
CBW 1 - 8
RWIS Org 815, SSI 1
Video Switcher Pelco 1

Fonts

A font is a set of bitmapped glyphs for displaying text on a dynamic message sign (DMS). Each font can contain any of the printable characters in the ASCII character set (0x20 to 0x7E).

When selecting a font, a few parameters must be considered, such as pixel pitch, desired character height, and font weight. Pixel pitch can vary from 66 mm down to 20 mm or smaller. Typically, for freeway signs, characters should be between 350 and 400 mm (about 14 or 15 inches) high. See the table below for character heights based on these common sizes.

Font Height Pixel Pitch
20 mm 33 mm 50 mm 66 mm
7 px 120 mm 198 mm 300 mm 396 mm
8 px 140 mm 231 mm 350 mm 462 mm
10 px 180 mm 297 mm 450 mm 594 mm
12 px 220 mm 363 mm 550 mm 726 mm
14 px 260 mm 429 mm 650 mm 858 mm
16 px 300 mm 495 mm 750 mm 990 mm
18 px 340 mm 561 mm 850 mm 1122 mm
20 px 380 mm 627 mm 950 mm 1254 mm

In the past, DMS have been used with upper-case only fonts, but with smaller pixel pitch, it is possible to create legible fonts which also include lower-case characters. If a message containing lower-case characters is used with an upper-case only font, IRIS will replace those characters with their equivalent.

Fifteen fonts are included in the IRIS template SQL script. These fonts are designed to have a similar visual style.

Number Font Name Description
1 07_char 7x5 character matrix
2 07_line 7 pixel high line-matrix
3 08_full 8 pixel high full-matrix
4 09_full 9 pixel high full-matrix
5 10_full 10 pixel high full-matrix
6 11_full 11 pixel high full-matrix
7 12_full 12 pixel high full-matrix
8 12_full_bold 12 pixel high full-matrix bold
9 13_full 13 pixel high full-matrix
11 14_full 14 pixel high full-matrix
13 16_full 16 pixel high full-matrix
14 18_full 18 pixel high full-matrix
15 20_full 20 pixel high full-matrix (numerals only)
16 24_full 24 pixel high full-matrix (numerals only)
17 _09_full_12 9 pixel high (12 with lower case descenders)

The IRIS client also contains a font editor which can be used to design new DMS fonts.

Devices

A device is a hardware field control or sensing system. IRIS supports several different device types: dynamic message signs, cameras, vehicle detection, lane-use control signs, ramp meters, gate arms, tag readers, beacons, alarms, road weather information systems, and lane marking.

For any device to be activated, it must first be connected to one of the I/O pins on a controller. The controller must also be associated with a comm link which communicates using the appropriate protocol for the device.

Dynamic Message Signs (DMS)

A dynamic message sign (DMS) is a sign which is capable of changing the message displayed to motorists. They can be classified as character-matrix, line-matrix and full-matrix, depending on the spacing between pixels. Some are monochrome, and some support full color display. All of these configurations are supported by IRIS.

The following operations can be performed on a DMS:

DMS Setup

FIXME

MULTI (Markup Language for Transportation Information)

DMS messages are specified using MULTI, as defined by the NTCIP 1203 standard. In MULTI, messages are simple ASCII strings, with formatting or other instructions denoted by tags inside square brackets. For example, the tag [nl] indicates a new line. Most of the useful MULTI tags are supported.

Tag Description Supported
[cbx] Message background color Yes
[pbz] Page background color Yes
[pbr,g,b]
[cfx] Foreground color Yes
[cfr,g,b]
[crx,y,w,h,z] Color rectangle Yes
[crx,y,w,h,r,g,b]
[fx,y] Field data No
[fltxoy] Flashing text No
[floytx]
[fox] Change font Yes
[fox,cccc]
[gn] Place graphic Yes
[gn,x,y]
[gn,x,y,cccc]
[hcn] Hexadecimal character No
[jln] Line justification Yes
[jpn] Page justification Yes
[msx,y] Manufacturer specific No
[mv] Moving text No
[nl] New line Yes
[nls]
[np] New page Yes
[ptn] Page time Yes
[ptnof]
[scx] Character spacing Yes
[trx,y,w,h] Text rectangle Yes

Quick Messages

A quick message is a fully composed DMS message which can be associated with a sign group. When a DMS is selected, a drop-down list is populated with quick messages from sign groups of which that DMS is a member. Quick messages are also be used for DMS actions as part of an action plan. For these messages, it is best to leave the sign group blank.

Cameras

Closed-circuit television cameras are commonly used to monitor traffic conditions. These cameras can transmit video to a traffic management center using either an analog signal (with dedicated cabling) or a digital stream (using an IP network). There are advantages to both approaches. Analog video has high picture quality and very low latency, while digital video is much cheaper and easier to route around.

To display camera video in IRIS, it must be digitally encoded.

Camera Setup

The camera Setup tab contains attributes to configure the encoded stream.

encoder_type
The type of encoder for the video stream.
encoder
The encoder stream URI. Usually, only the host name (or ip address) is needed here. For GENERIC encoder types, the path is also required. The default URI scheme is determined by the encoder type, but can be overridden here (for example "mms://" or "axrtsp://").
enc_mcast
Multicast stream URI.
encoder_channel
For encoders with more than 1 channel.
publish
Flag to allow stream to be published.

Pan / Tilt / Zoom

Some cameras have a built-in pan/tilt/zoom (PTZ) functionality. IRIS can perform the following PTZ operations:

For PTZ control to function, the camera must be associated with a controller on a PTZ protocol comm link.

Video Switching

IRIS can also be configured to send commands to a video switcher system. This allows camera video (or streams) to be routed to a number of video monitors. Each monitor can be assigned to display the video from any specific camera. IRIS allows an operator to select one video monitor to be linked with their camera selection on the user interface. This way, every time the user selects a camera, it's video is immediately displayed on the associated monitor.

Camera Selector Tool

There is a simple camera selector tool on the toolbar just below the map. It has a text entry field with an icon and label. This tool allows quick switching of the selected camera.

Numpad Hotkeys

The keyboard "numpad" can be used from anywhere within IRIS to control the camera selector tool. When the Num Lock key is off, all numpad keystrokes are directed to the tool. Pressing the * key (on the numpad) changes to video monitor selection — the icon will change to indicate this change. The + and - keys can select the next and previous cameras, respectively.

Vehicle Detection Systems

There are several types of vehicle detection systems (VDS) — also called traffic sensing systems. The oldest of these is the inductive loop detector, which is a wire placed under the surface of the road. It is able to magnetically detect the metal in vehicles as they pass over. Another type of sensor uses radar mounted on the side of the road. This type is non-intrusive, since the road surface does not need to be cut to install the detector. A third type – also non-intrusive – is video detection. These systems use video cameras and computer vision software to detect vehicles.

VDS Configuration

To create a detector, first select the r_node at the location of the detector. Then, select the Detectors tab for the r_node. Type the detector name in the text entry widget just above the Create button, and press that button. After selecting the new detector in the r_node detector table, its properties, such as lane type and lane # can be changed. In IRIS, lanes are numbered from right-to-left, starting with the right lane as 1.

When a detector fails, fake data may be used for flow, speed and density. In the simplest case, one or more detectors can be used to calculate the fake data. To do this, put the detector ID(s) in the fake field (separated by spaces).

VDS Protocols

IRIS supports several different protocols for communicating with vehicle detection systems. For most VDS protocols, traffic data is binned at a fixed time interval. Some protocols allow the binning interval to be adjusted. IRIS collects traffic data including volume (traffic counts), occupancy, speed, and vehicle classification. Some protocols do not use binning at all — instead they record timestamps and headway for each vehicle passing by the sensor. The following table summarizes features of each protocol.

Protocol Addressing Binning Speed
MnDOT 170 4 4-bit (1-15) 30 seconds (+5 minute) No
MnDOT 170 5 5-bit (1-31) 30 seconds (+5 minute) No
Canoga 8-bit (1-255) No (vehicle logging) Double loops only
SS105 4-digit (0001-9999) 5 seconds to 1 month Yes
SS125 32-bit (0-65535) ??? Yes
RTMS G4 32-bit (0-65535) 10 seconds to 1 hour Yes

VDS Data Archiving

Every 30 seconds, an XML file is generated containing the most recent sample data from all defined detectors. The file is called det_sample.xml.gz, and it is written to the XML output directory

Sample data is archived only if the sample_archive_enable system attribute is set to true. Sample archive files are stored in /var/lib/iris/traffic, in a directory with the district ID name.

Lane-use Control Signs (LCS)

A lane-use control sign (LCS) is a sign which is mounted over a single lane of traffic (typically one for each lane). It can display a set of indications which either permit or restrict use of that lane.

"Intelligent" Lane-use Control Signs (ILCS)

An "intelligent" LCS is a full-matrix color DMS which is mounted directly over a lane of traffic. In addition to being used as an LCS, it can display variable speed advisories, or any operator-defined message as a regular DMS.

"Dumb" Lane-use Control Signs (DLCS)

A "dumb" LCS device is much simpler than an ILCS. It can display one of a fixed set of indications — typically a green arrow  ↓ , a yellow arrow  ↓  or a red X  X ). Each indication must be assigned to a separate I/O pin on a controller, as well as the DMS which represents the LCS.

Ramp Meters

A ramp meter is a traffic signal at an on-ramp which controls the rate of vehicles entering a freeway. Typically, one vehicle is permitted to enter for each green indication displayed on the signal.

The following operations can be performed on a ramp meter:

Gate Arms

Gate arms are traffic control devices which restrict access to a section of roadway. They can be used, for example, for reversible lanes which can be changed by time of day.

Gate arms are controlled as arrays of 1-8 gate arms. Opening or closing an array will control all gate arms in the array.

Up to two cameras can be associated with a gate arm array. This allows operators to verify the status and check traffic conditions before opening or closing a gate arm array.

A DMS can be associated with a gate arm array, to inform motirists. Two quick messages, for open and closed will be automatically sent to the DMS.

Interlocks

Great care must be taken to prevent traffic conflicts when using gate arms. Two types of interlock are available for this purpose. An open interlock is a constraint which prevents the gate arm from being opened within IRIS. Similarly, a close interlock prevents the gate arm from being closed.

When a gate arm is open, all other gate arms on the same roadway, but in any other direction will have an open interlock.

Each gate arm can be assigned a prerequisite gate arm (on the same roadway and direction). This configuration prevents the gate arm from opening until the prerequisite has been opened, using an open interlock. Once a gate arm and its prerequisite are both open, the prerequisite gate arm will have a close interlock until the other gate arm is closed.

If communication is lost to a gate arm, the state will be unknown by IRIS. After 90 seconds, it will be treated as possibly open, causing interlocks to be checked. Also, an email will be sent to the address in the email_recipient_gate_arm system attribute.

Conflicts

If a conflict is detected, an alert email will be sent to the address in the email_recipient_gate_arm system attribute. An open conflict exists when an open interlock constraint is broken. Similarly, a close conflict exists for close interlock constraints. IRIS will not automatically try to resolve conflicts.

Gate Arm Security

There are a couple of extra security features to restrict access to gate arm control. There is a whitelist of IP addresses from which IRIS clients are allowed to control gate arms. It is specified as a property in the /etc/iris/iris-server.properties configuration file. The property is gate.arm.whitelist, and it contains a list of addresses in CIDR notation (exact IP, or ranges specified as 192.168.1.0/24).

Another gate arm security feature causes the entire "gate arm system" to be disabled whenever any configuration change is made to a gate arm. This includes any changes to a gate arm array, controller or associated comm link. IRIS will not send any command to open or close any gate arm in this state. The only way to re-enable gate arm control is to create a file at /var/lib/iris/gate_arm_enable (using touch).

Tag Readers

A tag reader is a sensor for in-vehicle transponders (tags). When a tag is read, an event is logged in the database. The event includes the date and time, tag ID, toll zone and tollway. This information can be used for tolling operation.

Beacons

A beacon is a light or set of lights that flashes toward oncoming traffic. Its purpose is to draw attention to a DMS or static sign. Sometimes, they are called flashers or wig-wags. Internal and external beacons are supported. Internal beacons are controlled through the DMS controller, are activated through the NTCIP DMS protocol and are considered part of the DMS. External beacons use dedicated controllers and protocols (e.g. MnDOT 170 4, MnDOT 170 5).

Alarms

An alarm is a simple device triggered by an event. The event might be an equipment failure, high temperature, or low voltage in a field controller. Alarms can be monitored to help maintain field devices. Device drivers trigger alarms based on field controller states, information read from controllers (e.g. voltages), etc. Users can view the status of alarms on the Alarm Form. The Status Column indicates the state of each alarm, which can be Clear or Triggered. Alarms are created using the Alarm Form and can only be created for controllers using a protocol driver that generate alarms. For example, the MnDOT ramp meter drivers.

Road Weather Information Systems

Road Weather Information Systems (RWIS) can sense data such as precipitation rate, road surface temperature, wind speed, etc.

Lane Marking

A lane marking device is also called in-road lighting. It allows the lane striping to be changed dynamically, by turning on and off lights embedded in the road.

Features

Traffic Map Layer

The IRIS client user interface includes a traffic map layer which is created automatically from the road topology. By default, this "segment" layer uses traffic density to determine the color of each segment in the layer. Other themes are available for speed and flow. The Legend menu at the top of the map can be used to view the thresholds used for each color in a theme.

Every 30 seconds, the client will make an HTTP request for the current traffic sample data XML file. The URL to locate that file is declared as a property in the /etc/iris/iris-client.properties file (on the IRIS server). The property is tdxml.detector.url, and it should point to the location of det_sample.xml.gz, as made available by apache on the IRIS server.

The appearance of the traffic map layer changes depending on the current map zoom level. If the zoom level is below 10, the layer will not be visible. At zoom levels 10 through 13, the layer will display segments as aggregate of all detectors in each mainline station. At zoom level 14 or above, each mainline detector will be displayed as a separate segment.

Incident Management

The Incident tab on the client interface is used to manage incidents within IRIS. Traffic incidents have several attributes, including location, type, detail, camera and lane impact. Active incidents are written to an XML file, which can be processed by external systems.

Creating an Incident

The user interface for creating incidents is streamlined to allow operators to process them quickly. First, click one of the incident type buttons: Crash, Stall, Road Work or Hazard. Then, the lane type can be selected — Mainline is the default, but Exit, Entrance and CD Road are available. Now, the incident location must be selected on the map (the mouse cursor will change to a crosshair). After that the incident detail, verification camera and lane impact can be selected (if required). The camera list will be populated with a few cameras near the location selected. The lane impact is represented by boxes for each lane at the incident location, including both shoulders. Each lane can be marked clear (default), blocked (red) or partially blocked (yellow) by clicking on the box. Once the attributes have been set, press the Log button to create the incident. A triangular icon will appear on the map pointing in the direction of travel, color-coded with the incident type.

Editing an Incident

To change the location or verification camera, the Edit button must be pressed first. To change the lane impact or to clear the incident, the Edit button is not required. After making changes, be sure to press the Log button again. Once an incident has been cleared, it will be removed from the list after 5 minutes. This allows a cleared incident to be reactivated if necessary.

Deploying Devices

Devices can be deployed based on the incident impact by pressing the Deploy button. This will bring up a form with a list of suggested devices to deploy for the incident. The list may include Lane-use control signals or Dynamic Message Signs. All DMS within the range of the incident are checked. Each of these DMS will be deployed if matching descriptor, locator and advice are found.

Incident Descriptor

An incident matches a descriptor only if all the attributes match. Each matching descriptor will be checked to see if the MULTI string can be rendered on the DMS.

Sign group
A group of signs with similar dimensions
Event Type
CRASH, STALL, ROAD WORD, HAZARD
Lane Type
mainline, exit, merge, CD lane
Detail
animal, debris, ice, etc.
Cleared Flag
yes / no
Incident Locator

The incident is associated with the nearest pickable r_node. If the distance to that node is less than 1 mile, it can be used as a locator. If not, the nearest non-pickable r_node is found. It can be used if distance is less than 1 mile.

An incident matches a locator only if all the attributes match. Each matching locator will be checked to see if the MULTI string can be rendered on the DMS.

Sign group
A group of signs with similar dimensions
Range
near, middle, far
Branched
no / yes
Pickable
no / yes

One "MULTI-like" tag is defined for incident locators.

Tag Value Description
[locrn] Road name
[locrd] Road direction
[locmd] Location modifier (AT, N OF, S OF, etc.)
[locxn] Cross-street name
[locxa] Cross-street abbreviation
[locmi] Miles from DMS to node

Road names are converted to all capital letters. For the `[locrn]` and `[locxn]` tags, certain prefixes and suffixes are replaced with other values. For the `[locxa]` tag, all matching prefixes and suffixes are stripped.

Incident Advice

An incident matches an advice record only if all attributes match.

Sign group
A group of signs with similar dimensions
Range
near, middle, far
Lane Type
mainline, exit, merge, CD lane
Impact
Lane impact code
Cleared Flag
yes / no

A lane impact code is defined for all lanes plus both shoulders. So, for a two-lane r_node, the impact code would be 4 characters.

Code Description
. Not blocked
? Partially blocked
! Fully blocked
: Partially of fully blocked (? or !)
; Not fully blocked (. or ?)
, Any (. ? or !)

Plans and Schedules

Action Plans

Action plans provide a way to coördinate multiple related actions at the same time. Each action plan has a phase, which can be changed at any time. Each phase can be associated with any number of DMS, beacon or ramp meter actions. More advanced plans can have many phases, each with separate actions. If the Sync Actions box is checked, the phase can only be changed if all associated devices are online. If the Sticky box is checked, messages sent with DMS actions will be configured to persist even if communication or power is lost.

Day Plans

A day plan is a set of days which can be used for scheduling. Day plans are specified with a table of day matchers. The matchers for a day plan determine whether a specific day is included in the plan or not. Day matchers flagged as holidays are excluded from a day plan. Day matchers are specified by Month, Day, Week and Weekday. Any day which matches all specified fields will match. Shift is only required for days like Black Friday (Fourth Thursday of November +1).

Plan Phases

The basic phases of an action plan are deployed and undeployed. Additional phases can be added on the Plan Phases tab. Each phase must have a unique name. A transient phase can automatically advance to the Next Phase after a specified Hold Time. Currently, this must be a multiple of 30 seconds.

Schedules

An action plan schedule can automatically change the phase at specified dates and times. These events can be scheduled using either a day plan or a specific date (but not both). A time of day must also be specified (HH:MM in 24-hour format). Whenever the scheduled time occurs, the action plan will be changed to the specified phase.

DMS Actions

DMS actions have an associated sign group to determine which signs are affected by the action. The action happens when the action plan phase matches the phase of the DMS action. The quick message indicates which message is activated by the plan. Activation and run-time priorities determine which of multiple actions will take precedence.

PREFIX_PAGE is a special activation priority which can be used to combine a scheduled message with an operator message. When a DMS action is active with PREFIX_PAGE priority, any user message sent will be modified by inserting the scheduled message on each page of the operator message. Care must be taken to ensure the combined message can be displayed on the sign. This feature could be used, for example, to put a graphic logo on all messages displayed on a sign.

DMS Action Tags

Some "MULTI-like" tags are supported in quick messages used by DMS actions. These tags are interpreted by IRIS before sending the message to the DMS.

Tag Description
[feedn] Message feed
[tts,m,t] Travel time
[vsa] Speed advisory
[slows,b,u,dist] Slow traffic warning
[tz{p,o,c},{tz0},{tzn}] Toll Zone

Beacon Actions

A beacon action can cause a beacon to be deployed when the action plan is set to the specified phase. When the plan is set to any other phase, the beacon will shut off.

Meter Actions

A meter action can cause a ramp meter to begin metering at the specified phase. When the plan is set to any other phase, the meter will shut off.

Travel Time Estimation

The current travel time from a DMS to a downstream station can be estimated and displayed on the sign. A new estimate is made every 30 seconds, based on speed data from vehicle detection systems.

A tt action tag can be used to specify a travel time within a quick message. When the message is deployed, the tag will be replaced by the estimated travel time, in minutes. The tag has three parameters, separated by commas.

  1. Destination station ID
  2. Over limit mode (prepend if omitted)
    • blank: do not display travel time when over limit
    • prepend: prepend over limit text before travel time
    • append: append over limit text after travel time
  3. Over limit text ("OVER " if omitted)

Examples:

Route Pathfinding

This feature requires that the road topology is configured for the entire route. Using this topology, the shortest route is found from the DMS to the destination station. A route consists of one or more corridor trips. Each corridor trip has an origin and a destination, which are r_nodes associated with a single freeway corridor. For the first corridor trip, the origin is the DMS location. A route can only branch if an r_node with exit node type is matched with an entrance r_node. In order to match, the roadway / direction for the exit r_node must equal the cross street / direction for the entrance, and vice versa.

Two system attributes control route pathfinding:

route_max_legs
Maximum number of corridors to branch
route_max_miles
Maximum total route distance

Speed Smoothing

To deal with sampling problems at low speeds, a smoothing procedure is used. For each station, running average and running minimum speeds are calculated from all valid detectors in the station. If a speed higher than the speed limit is recorded, the speed limit is used instead. The sample interval used increases as the speed becomes lower:

Route Travel Time

The distance between each consecutive valid station is divided into 3 links of equal length. If any link is longer than 0.6 miles, a travel time estimate would not be reliable, so the process is aborted. The links which are adjacent to a station are assigned speed from that station. "Middle" links are assigned an average of the immediate upstream and downstream station speeds. Normally, the running average speed is used. If the link is less than 1 mile from the corridor destination, the running minimum is used instead. Travel time for each link is estimated by dividing its length by the assigned speed. If the route branches, each branch adds a 1 minute turning delay.

Travel Time Limit

To prevent unreasonable messages from being displayed due to data errors, a limit is calculated. The total route length is divided by the travel_time_min_mph system attribute (default 15). The result, rounded up the to next 5 minutes, is the travel time limit.

If the calculated travel time is over the travel time limit, the message will be over limit. If the over limit mode is blank, no message will be shown. Otherwise, the tag will be replaced with the travel time limit, with the over limit text either prepended or appended.

Variable Speed Advisory

FIXME

Slow Traffic Warning

A slow action tag allows warnings to be displayed on DMS when traffic is slow. The tag has three parameters, separated by commas.

  1. Highest speed to activate the warning, in mph.
  2. Distance (tenths of mile) to search for slow traffic, relative to the DMS location.
  3. Tag replacement mode (none if omitted)
    • none: a blank string
    • dist: distance rounded to nearest mile
    • speed: speed rounded to nearest 5 mph
[slow35, 10]SLOW[nl]TRAFFIC[nl]AHEAD
Displays if traffic slower than 35 mph within 1 mile
SLOW TRAFFIC[nl][slow40,60,dist] MILES[nl]USE CAUTION
Displays if traffic slower than 40 mph within 6 miles
[slow45,5,speed] MPH[nl]1/2 MILE[nl]AHEAD
Displays if traffic slower than 45 mph within 0.5 miles

Tolling

High-occupancy / toll (HOT) lanes can be operated through IRIS. Functions include calculating tolls in real time based on density, displaying prices on DMS, and logging vehicle transponder (tag) information. Customer accounts and billing are not supported; those features must be provided by an external system.

Toll Zones

A toll zone is a segment of roadway between two stations. All HOT lane detectors between the starting station and ending station can be used to calculate the toll. Every 3 minutes, tolls are calculated using data from the most recent 6 minutes. Within a zone, each station has an associated toll, based on the highest density recorded among HOT lane detectors downstream of that station.

p = α ⋅ k β, where α = 0.045 and β = 1.10

The toll price is then rounded to the nearest $0.25.

Pricing on DMS

A DMS can display pricing information for toll zones. This is accomplished using a tz action tag. The tag has two or more parameters, separated by commas. The first parameter is the tolling mode, and must be "p", "o" or "c". These indicate priced, open or closed, respectively. The second parameter is the (first) toll zone ID. If the toll route spans multiple toll zones, additional zone IDs may be provided after the first.

If the tolling mode is priced, the tag will be replaced with the calculated price, for example "2.75". It will be the sum of prices for all specified toll zones. Two system attributes, toll_min_price and toll_max_price, limit the calculated price.

For open and closed modes, the tag will be replaced with an empty string. If required, a message such as "OPEN" or "CLOSED" may be appended after the tag.

Price events are logged when a message is sent to a DMS, and again when the message is verified. The price event includes the date and time, toll zone, tolling mode (priced, open, closed), price, sent / verified status and next downstream tag reader. The logged toll zone is the last zone specified in the tag. In priced mode, the displayed price is logged. For open or closed, a price of 0 is logged.

Tag Readers

Tag readers can be mounted over a tolled lane to record customer trips. These are typically located just downstream of a pricing DMS. The tag read events can be combined with the logged pricing information to build a list of trips for each tag ID. This information can be used to bill customers.

Ramp Metering Strategies

FIXME

Spell Checker

The system attributes dict_allowed_scheme and dict_banned_scheme enable DMS spell checker functionality. The dict_allowed_scheme system attribute corresponds to the Allowed Word List (white-list) defined on the Dictionary Form. The dict_banned_scheme system attribute provides similar functionality but for the Banned Word List on the Dictionary Form.

When an operator presses the DMS Send Button, each word in the DMS message is compared against words defined in the dictionary. A form appears if the DMS message contains words that don't appear on the Allowed List or do appear on the Banned List. The system attributes control if these rules are enforced or if IRIS merely provides a recommendation to not use the word.

Troubleshooting

Error Logs

FIXME

XML Output

There are a number of XML files which are written by the IRIS server periodically. These files contain configuration information about the system as well as realtime data concerning the current state. These files are stored in the /var/www/html/iris_xml/ directory.

Filename Description Period
tms_config.xml.gz Configuration data for IRIS system. If the district server property is changed, the filename will be changed to match {district}_config.xml.gz. 24 hours
det_sample.xml.gz Sample data from vehicle detection systems 30 seconds
stat_sample.xml.gz Mainline station data from vehicle detection systems 30 seconds
incident.xml.gz Current incident information 30 seconds
sign_message.xml.gz Current DMS sign message information 30 seconds

Database Event Tables

FIXME

Debug Trace Logs

There are some debugging logs which can be enabled in the /var/log/iris directory. To enable a particular log, use the touch command to create a file with the proper name. Some of these logs can grow very large, so be sure to have enough disk space available.

Filename Description
{comm-link-name}.log Comm link log
addco Addco DMS protocol
bottleneck Bottleneck calculation for VSA algorithm
canoga Canoga detector protocol
cbw Control By Web protocol
device Device error log
dinrelay Din-relay protocol
dmsxml DMS-XML protocol
e6 E6 tag reader protocol
e6_pkt E6 tag reader protocol packets
feed Msgfeed protocol
g4 G4 detector protocol
infinova Infinova PTZ protocol
kadaptive K Adaptive metering algorithm
manchester Manchester PTZ protocol
meter Ramp meter configuration errors
mndot170 MnDOT protocol
modem Modem error log
ntcip NTCIP protocols
org815 ORG-815 rain guage protocol
pelco Pelco switcher protocol
pelcod Pelco-D PTZ protocol
polling Generic operaton polling log
prio Operation priority log
profile System profiling log
sched DMS scheduled message log
slow DMS slow warning system log
snmp SNMP error log
sonar SONAR connection log
sql SQL database error log
ss105 Wavetronix SS-105 protocol
ss125 Wavetronix SS-125 protocol
ssi SSI weather protocol
stc SmartTouch Controller gate arm protocol
sys_attr System attribute change log
toll Tolling info log
travel Travel time info log
vsa Variable speed advisory info log

Maintenance

Once an IRIS system is set up, there are a few maintenance tasks which need to be done to ensure reliable operation.

Database Backup & Restore

It is a good idea to backup the IRIS database on a regular basis. This can be done simply with a command such as the following:

pg_dump tms | gzip > tms-20120523.sql.gz

This command can be placed in a simple python or bash script which is run by cron once per day. For off-site backups, the file could be copied to another host, using scp or a similar utility.

To restore the tms database from one of these backup files, you will first need to shut down the IRIS server (and anything else connected to the tms database). Then, run the following commands (as tms user):

dropdb tms
createdb tms
zcat tms-20120523.sql.gz | pgsql tms

IRIS Upgrades

Upgrading an IRIS system to a new version is a simple process. There are two different scenarios to deal with when upgrading: stable versus unstable. Either way, it's advisable to backup the database before attempting an upgrade.

A stable upgrade is when the major and minor IRIS version numbers do not change — just the micro version. So, upgrading from 3.145.0 to 3.145.1 would be a stable updgrade. This type of upgrade never involves a database schema change. With the new rpm file available, a stable upgrade can be accomplished with the following commands (as root):

dnf update iris-{major}.{minor}.{micro}-{build}.noarch.rpm
iris_ctl update
systemctl restart iris

An unstable upgrade is when either the major or minor IRIS version numbers change. Upgrading from 3.144.0 to 3.145.0 would be an unstable upgrade. This type of upgrade always involves a database schema change. To upgrade the database schema, an SQL migrate script must be run for each intervening version. The following commands can be used to perform an unstable upgrade (as root):

dnf update iris-{major}.{minor}.{micro}-{build}.noarch.rpm
psql tms -f /var/lib/iris/sql/migrate-{major}.{minor}.sql
iris_ctl update
systemctl restart iris

Note: when skipping one or more minor versions in an upgrade, all migrate scripts must be run. So, when upgrading from 3.143.0 to 3.145.0, the database upgrade would consist of these commands:

psql tms -f /var/lib/iris/sql/migrate-3.144.sql
psql tms -f /var/lib/iris/sql/migrate-3.145.sql

Warning: there is no supported method of downgrading an IRIS system. If a downgrade is required, the database should be restored from a backup and the IRIS rpm should be reinstalled.

System Software Updates

FIXME

Monitoring Logs

FIXME

Development

Building

Install Fedora onto the development system. Some additional development packages must be installed.

dnf install java-devel-openjdk ant-junit mercurial rpm-build gcc

In a suitable development directory, clone the iris mercurial repository.

hg clone http://iris.dot.state.mn.us/hg/index.cgi/iris

Create lib/ directory in iris development repository.

mkdir iris/lib/

Download the JavaMail API from Oracle. Unzip the JavaMail archive and locate the mail.jar file. Copy the mail.jar file to the lib/ directory in the iris repository.

Copy iris-build.properties from etc/ to lib/. Edit lib/iris-build.properties file as necessary for your organization.

Create the key for signing jar packages. This is required for Java Web Start, which is used by the IRIS client. The key should go into your default keystore (~/.keystore).

keytool -genkeypair -alias signing-key

Put the following lines into your ~/.ant.properties file.

debug=off
sign.store=${user.home}/.keystore
sign.store.pass=password
sign.alias=signing-key
sign.alias.pass=signing-password
hgbase.url=http://iris.dot.state.mn.us/hg/index.cgi/

Now, the IRIS rpm file can be built with the following commands. (The current directory should be the root of the iris repository.

ant rpm

If there are no errors, the new rpm file should be in the build/rpm/RPMS/noarch/ directory.

History

March 1999
Started work on NTCIP DMS control
May 2007
First GPL open source release
May 2008
IRIS live in Caltrans D10
April 2011
Officially adopted by Caltrans

Future Plans

FIXME

Contributing

FIXME

Admin Guide

Please format text so there is a newline after each sentence. This makes patches less cluttered. Also, line length should be 80 characters or less. When patch files are submitted directly, using a .patch file extension is preferred.

Coding Style

The coding style for IRIS is focused on making code more readable. Readability is the most important factor for software maintenance, and it also helps new developers who are unfamiliar with the codebase.

First and foremost, it is recommended that each method fit in one page of text (30 lines by 80 columns). Whenever possible, longer methods should be decomposed to abide by this recommendation. This allows a developer to quickly read and understand the method's logic. It is much easier to spot and correct bugs in shorter methods. There should be no blank lines within a method.

With methods longer than one page, it can be beneficial to have a single exit point (return). But for shorter methods (always the goal), this is not so important, and can reduce readability. It doesn't make sense to add a local "ret" variable with a single return statement at the end when the whole method can be read at a glance.

Each block indent should be 8 columns (using tabs instead of spaces). This makes the blocks more obvious, and is easier to read than the 4 spaces commonly used in other Java projects. Always use an indented block with if, for, while, etc. statements. This makes it much easier to follow the control flow than when it is combined onto the same line as the statement. Don't put an opening curly brace on a line by itself unless the method declaration or loop statement spans multiple lines. For single line blocks (if, for, while), do not use curly braces.

Each method should have a javadoc comment describing its purpose. All parameters and return values should be documented as well. Comments within a method should be used sparingly — never describe what the code is doing, but instead why it was written in a certain way. Code which is "commented out" should never be committed to a repository.

Unary operators, such as ++ -- ! ~ should be adjacent to their operand with no space. Binary operators, such as + - / * % & | && || > = < >> == != << >>> >= <= ^ should be separated from their operands by a space.

Step-by-step

Create a DMS, Comm Link, and Controller

  1. Make sure edit mode is ON.
  2. Create the new DMS
    • Select the View ➔ Message Signs ➔ DMS menu item to display the DMS form.
    • Type the name of the new DMS in the edit field at the bottom of the form and press the Create button.
    • Find the new DMS in the data table and select it.
    • Click the Properties button and the DMS Properties Form will appear.
    • On the Location Tab specify the road and location of the physical DMS.
    • On the Messages Tab select the default DMS font.
    • Close the DMS Properties form.
  3. Create a new comm link
    • Select the View ➔ Maintenance ➔ Comm Links menu item to display the Comm Links form.
    • Type the name of the new comm link in the edit field in the middle of the form and press the Create button.
    • Find the newly created comm link in the data table in the top of the form and select it.
    • Enter a more complete description in the Description field as needed.
    • Enter the controller URI in the URI column, e.g. "tcp://10.20.30.40:1234" or "udp://10.20.30.40:1234" for signs that use UDP.
    • Select the desired protocol.
    • Enter the desired polling period and timeout.
    • Enable the Comm Link by clicking the Enabled Checkbox.
  4. Create a new controller associated with the comm link
    • In the Comm Link Form with the desired comm link selected, click the Create button on the bottom of the form.
    • Select the new controller in the lower data table and click the Properties Button. The Controller Form should appear.
    • On the Controller Form Setup Tab, change the condition to active.
    • On the Cabinet Tab specify the DMS cabinet location and style.
    • On the Controller Form IO Tab, for Pin=1, select DMS in the Type column. In the Device column, select the name of the DMS created above.
  5. View DMS Status
    • If the comm link is enabled (per above) and the controller condition is active (per above), the number of successful and failed operations is visible in real-time on the Controller's Status Tab.
    • View the DMS configuration on the DMS Form Configuration tab. The Query Configuration button on that tab manually queries the sign.
    • The Status Tab on the DMS Form shows additional status information.

Create a Plan to Activate DMS Messages

  1. Make sure edit mode is ON.
  2. Select the View ➔ Plans and Schedules menu item to display the Plans and Schedules form.
  3. Create a Phase (if it doesn't exist already)
    • Click the Plan Phases Tab
    • Type the name of the new phase, e.g. "msg_on"
    • Press the Create Button
    • The new Phase should appear in the upper table
  4. Create an Action Plan
    • Click the "Action Plans" tab
    • Select the phase "msg_on" in the Default Phase combobox.
    • Type the name of the new Action Plan in the edit field, e.g. "slick_roads"
    • Press the Create Button
    • The new Plan should appear in the lower table
  5. Create the DMS Actions
    • Click on the Action Plan just created (e.g. slick_roads)
    • Click the DMS Actions tab
    • In the edit field on the bottom of the form, type the name of an existing sign group
    • Press the Create button
    • The new DMS Action should appear in the table
    • Click on the "Quick Message" column in the DMS Action just created
    • Specify the name of an existing quick message to send to the sign
    • Repeat the above DMS Actions steps as many times as desired to send a message to additional sign groups.
  6. Activate the messages on the signs
    • On the Action Plans tab, click the desired action plan.
    • Click the "Active" checkbox.
    • Signs are activated and deactivated every 30 seconds (at :29 and :59), so wait at least 30 seconds for the messages to appear or disappear.
    • Unselect the Active checkbox to blank the signs.
Notes: