Intelligent Roadway Information System

Natch Protocol

Natch is a protocol for communicating with ATC devices. It may or may not stand for New Advanced Traffic Controller, Howdy.

The controller listens and accepts a single TCP connection on port 8001. The IRIS server connects and keeps the same connection open continuously.

After connecting, IRIS will send configuration messages for enabled detectors and ramp meters.


Each message is a single line of comma-separated parameters (UTF-8), terminated with a newline character \n (U+000A). General message format:

Parameter Description
1 Code
2 Message ID
Remaining parameters

Code indicates the message type. For polls (from IRIS) these are upper-case, but for responses or asynchronous detector status (from the controller), they are lower-case.

Code Descripton
CS / cs Clock status
DC / dc Detector configure
DS / ds Detector status
MC / mc Meter configure
MS / ms Meter status
MT / mt Meter timing table
PS / ps Pin status
SA / sa System attributes
SC / sc System command
V. / v. Firmware version

Message ID is used to match polls with responses, but is otherwise not interpreted by the controller (except for ds messages, see below).

Polls can be made in two ways:

Responses from the controller include all parameters, for both store and query polls.

CS - Clock Status

Parameter Description
1 Code: CS / cs
2 Message ID
3 † Date / time

The date / time is formatted according to RFC 3339.


DC - Detector Configure

Parameter Description
1 Code: DC / dc
2 Message ID
3 Detector Number (0-31)
4 † Input Pin Number (0-104; 0 means deleted)

If the input pin number is not valid, the detector is deleted, and this is indicated in the response.

The input pin number can also be set to a ramp meter output pin (2 or 3). In this case, whenever a green indication (on either head) is displayed, it generates a detector status event.


DS - Detector Status

Parameter Description
1 Code: DS / ds
2 Message ID
3 † Detector Number (0-31)
4 † Duration (ms)
5 † Headway (ms)
6 † Time (HH:MM:SS, local 24-hour)

The detector status message works differently from the others; there are no store/query polls. Instead, messages are initiated by the controller, and IRIS responds with an ACK or NAK.

Vehicle events waiting to be sent to IRIS are stored in a buffer of ds messages. It is fixed-size, with head and tail pointers. Head is incremented when a new message is added, and tail is incremented when the oldest message is deleted.

A one second buffer timer is used to delay sending ds messages to IRIS. After it expires, up to 24 buffered messages are sent, in order from oldest to newest.

When a vehicle leaves a detector, the message ID is incremented as a 4-digit hex value. A ds message is added to the buffer, and if the buffer timer is not already running, it is started.

When a DS is received from IRIS, the message ID is compared with the oldest ds message in the buffer. If it matches, the poll is an ACK, otherwise it is a NAK. In either case, the buffer timer is reset.

See vehicle logging for details on duration, headway and time.


MC - Meter Configure

Parameter Description
1 Code: MC / mc
2 Message ID
3 Meter number (0-3)
4 † Heads (0: deleted, 1: single, 2: dual)
5 † Release (0: alternating, 1: simultaneous / drag-race)
6 † Turn on output pin (usually 2 or 3)
7 † Left head, red output pin (1-104)
8 † Left head, yellow output pin (1-104)
9 † Left head, green output pin (1-104)
10 † Right head, red output pin (1-104)
11 † Right head, yellow output pin (1-104)
12 † Right head, green output pin (1-104)

If any of the parameters are not valid, the meter is deleted, zeroing out values 4-12, and the response indicates this.


MS - Meter Status

Parameter Description
1 Code: MS / ms
2 Message ID
3 Meter number (0-3)
4 † Red dwell time (0.1 sec)

If red dwell time is set to zero, metering is disabled. If the meter is not configured, red dwell time in a response will be INV (invalid).


MT - Meter Timing Table

Parameter Description
1 Code: MT / mt
2 Message ID
3 Table entry number (0-15)
4 † Meter number (0-3)
5 † Start time (minute of day; 0-1439)
6 † Stop time (minute of day; 0-1439)
7 † Red dwell time (0.1 sec)

If any of the parameters are not valid, the table entry is deleted, zeroing out values 4-7, and the response indicates this.

These meter timing values take effect when there has been no successful communication for longer than the Comm fail time system attribute.


PS - Pin Status

Parameter Description
1 Code: PS / ps
2 Message ID
3 Pin number (1-104)
4 † Pin status (0 or 1)

Note: Input pins and pins associated with meters (Meter Configure) cannot be controlled with this command.


SA - System Attributes

Parameter Description
1 Code: SA / sa
2 Message ID
3 † Comm fail time (0.1 sec), default 1800
4 † Start up green time (0.1 sec), default 80
5 † Start up yellow time (0.1 sec), default 50
6 † Metering green time (0.1 sec), default 13
7 † Metering yellow time (0.1 sec), default 7

The meter timing attributes apply to all meters.


SC - System Command

Parameter Description
1 Code: SC / sc
2 Message ID
3 Command

The command restart causes the controller program to be restarted.


V. - Firmware Version

Parameter Description
1 Code: V. / v.
2 Message ID
3 † Firmware version
4 † Build date / time