ScriptBuilder Tool and Instructor Electronic Notebook

Requirements, Concept Development, and Scope
California Polytechnic State University
San Luis Obispo, California

Table of Contents

1. Glossary
   
2. Script Builder Tool Requirements
   1. Scripts, Incidents, and Events
      
   2. Graphical User Interface Requirements
      
   3. Support for TMC Simulation Control
      
   4. Support for Student Evaluation
      
   5. Supporting Realism in Training
      
   6. Specifying Expected Traffic Network Performance
      
   7. Instructor Support
      
   8. Other Training Goals
      
3. Instructor Electronic Notebook Requirements
   1. General Requirements
      
   2. Simulation Summary Window
      
   3. Simulation Script Window
      
   4. CHP CAD Terminal Window
      
   5. ATMS Display Window
      
   6. Simulation Area Reference Roadway Map Window
      

1. Glossary

ATMS

Advanced Traffic Management System – a tool utilized within Caltrans

CHP CAD

California Highway Patrol (CHP) Computer Aided Dispatch (CAD)

CCTV

Closed circuit television – used to monitor roadways remotely from a TMC.

CMS

Changeable Message Sign

Control Event

Control events cause the TMC Simulation Manager to perform actions which affect the simulation environment as seen on the simulation floor, e.g. modify the Paramics simulation, play an audioclip, send a message to CHP CAD, etc.

Evaluation Event

Evaluation events are used to prompt instructors to perform an evaluation action for students in training, e.g. grade their CMSmessage, phone response, etc.

Event

An occurrence at a particular time of an incident. Control events and evaluation events are kinds of event.

Event Icon

An image that represents an event. AKA Icon.

Incident

A complete set of events associated with a specific incident number within the TMC Simulator. This ID number shall match the CHP CAD log identifier.

Noise

Background events within a simulation which may not have a significant immediate effect on traffic but require attention and resources from traffic managers working in the TMC. Examples of noise are things like a stalled vehicle on the shoulder, sprinklers spraying in the roadway,maintenance crews working on roadway in structure, etc.

Icon

An image that represents an event. AKA Event icon.

Incident Number

A number that identifies an incident.

Incident Name

A short name that is used to refer to an incident.

Incident Line

A graphical line in the timeline. An incident line represents an incident.

LCS

Lane Closure System – a tool used by Caltrans to manage lane closures within the highway system.

Paramics

A tool which performs microscopic traffic simulation of the traffic network. Note that Paramics is planned for deprecation from the TMCsimulator.

Script

A chronological list of hypothetical traffic incidents for training purposes that can be played through the Simulation Manager.

Script File

A script saved to XML file in a format conformant with the Simulation Manager & Script XML Schema. An XML file containing all details for all events within one or more incidents. The events are saved in chronological order (not grouped by incident).

Timeline

A horizontal line in a graphical display that represents the chronology of incidents in a script.

Traffic Dot

A colored dot as displayed on the ATMS with green indicating free-flow traffic, yellow indicating moderate reductions in speed/flow, and red indicating sever reductions in speed/flow. TMT::Traffic Management Team

2.Script Builder Tool Requirements

2.1 Scripts, Incidents, and Events

2.1.1 Creating a new Script

Creating a new script clears any current script and makes the workspace available for incidents to be added or inserted. A script title must be provided when a new script is created.

2.1.2 Load an existing Script

Load an existing Script from a saved XML file and display an overview of all the incidents. (Clears any current script).

Saving a Script

Saving a script causes the script and all the incidents it contains to be saved in XML format to an external file in conformance with the standard as detailed in the *Simulation Manager & Script XML Schema. (Look in Google Drive).

Adding a new Incident

A new incident may be added to the script. When an incident is created the user will enter the properties of that incident: incident number, incident name, color of the incident's line, a description of the incident, the start time of the Incident, and the length of the incident. (Note, we are considering omitting incident number).

Update Incident Properties

An incident's properties may be modified after it has been created, including adjusting starting time.

Editing Incident Events

Editing an incident makes it available for events to be added, modified, and removed.

Deleting an Incident

Erases all the incident properties and events from the timeline.

Inserting an Incident

Inserting an incident displays a pool of available incidents (on auxiliary storage) and allows the user to select one for inclusion in the script being edited. (Shall we disallow inserting the same incident twice in the same script?)

Saving an Incident

Saving an incident saves all the incident properties and the events it contains in XML format to an external file. Saving also includes all associated resources like audiofiles. Saving will present a custom dialog (instead of a standard file chooser) that constrains the filename that can be used to store the incident data.

Incident Extractor Wizard

This wizard allows the user to load a script and extract incidents from it. (Elaboration needed).

Add New Event

The user shall be able to add events to an incident line by selecting the desired type of event using a button on the main GUI then placing the event to the desired location on the timeline. When the user places an event, dialog boxes will appear to allow the user to enter information regarding the event. The user shall be able to place events at any location on an incident line.

Modify Event Group

A group of events occurring at the same time may be modified. Each event appears in a separate tab and its properties individually updated.

Deleting Event

The user shall be able to remove events from incidents, by right-clicking on the event's icon and selecting “remove” from a pop-up menu. The user shall be able to remove an event by clicking on it and pressing the delete key.

2.2 Graphical User Interface requirements

See StoryBoards for illustration of proposed GUI screens.

The Script Builder shall allow the entry and modification of scripts using a timeline. The timeline will show each incident in the script as a line. Each event, represented by an icon,will be positioned on its corresponding incident's line. This display shall show all individual events within a script, e.g. CADdata population, radio traffic, instructor/student phone call, etc.,with icons for each type of event.

All time shall be displayed in hours, minutes, and seconds from the beginning of the timeline, e.g. the beginning of the script. The time into the incident and the script shall be displayed to the user as they move their cursor along an incident within the timeline.

Details of an event shall be displayed in a floating tooltip which appears when the user places their cursor over the event's icon. All details of an event shall be editable when the user clicks on an event icon.

Color Coding of Incidents

Each incident line shall be color-coded. The color of each incident line shall be selectable by the user. A color may be shared by multiple lines.

Control Event and Evaluation Event Icons

The Script Builder shall utilize distinct icons to represent all events on the timeline. The icons shall be sufficiently small so that they can be displayed on the incident lines in the timeline. The icons shall be sufficiently distinctive from one another so that they may be easily differentiated from one another by the user. Evaluation event icons shall be identical to their corresponding control event icons, except that they will be differentiated by a unique feature such as an easily visible addition to the icon, e.g. a checkmark, a dot, etc.

Merging Multiple Scripts onto Timeline

The Script Builder shall be capable of merging multiple independent scripts into a single timeline. A user shall be able to select which incidents to include into the timeline at import. The start times of these incidents shall be selectable by the user. (What I think I heard was there are two features needed: import incident and merge script. Import incident is used when building a new script by selecting from a pool of incidents in external files. Merge script actually merges the XML by chronology of events. Unclear why the latter is needed because it seems to duplicate what can be done with import. The saved incidents all start at time zero and can be assigned a relative start time when imported. During editing the incident can be shifted along the timeline. )

Extracting a Script from the Timeline

The Script Builder shall be capable of extracting a script from the timeline. (I think this means exporting incidents, because the timeline has nothing to be extracted from it but incidents. )

2.3 Support for TMC Simulation Control

Simulation Control Events - Overview

The Script Builder shall allow for insertion of control events which drive TMC simulator systems, including the Paramics traffic simulator, the CHP CAD simulator, the TMC Simulator Audio System, the Activity Log, the Electronic Instructor Notebook, and the CCTV video playback system. When the user adds a control event, a dialog box shall be presented to the user allowing entry of details regarding the added event. The details regarding the added event are specified by the XML element corresponding to the added event. These XML elements are found in the TMC Simulator XML Script Schema.

Paramics Control Event

The Script shall allow for the entry of Paramics control events. Paramics control events allow modification of Paramics simulation parameters to create incidents, remove incidents,etc.

CHPCAD Control Event

The Script Builder shall allow for the entry of CHP CAD control events. CHP CAD Control Events allow automated entries and hence automatic population of the data into the TMCSimulator CHP CAD database, as if it were typed by a CHP Dispatcher.

Tow Truck Control Event

The Script Builder shall allow for the entry of Tow Truck Control Events. Tow Truck control events allow tows to be added to the CHP CAD log. Where do these appear in CAD Client?

Witness Control Event

The Script Builder shall allow for the entry of Witness Control Events. Witness Control Events allow witness reports to be added to the CHP CAD log. Where do these appear in CAD Client?

Unit Control Event

The Script Builder shall allow for the entry of Unit Control Events. Unit Control Events allow CHP units to be dispatched on the CHP CAD.

CCTV Control Event

The Script Builder shall allow for the entry of CCTV control events. CCTV control events allow direct control of TMCSimulator DVD players to play incident video, resume normal operations, etc.

CHP Radio, Caltrans Radio, TMT Radio Control Event

The Script Builder shall allow for the entry of radio control events. Radio control events can be CHP, Caltrans, or TMT Events. The Script Builder will be able to generate a printable “voice-actor script” from the XML to support the recording of the radio traffic based upon the radio Event. The “voice-actor script” will include the following: the specific words to be read by the voice actor, including call numbers, etc., the file name that the voice recording should be saved as, any special instructions to the actor(s), and actor identifier to ensure that all recordings for a given role in the field are made by the same person.

Telephone Call Control Event

The Script Builder shall allow for the entry of Telephone control events. Telephone Call control events allow the generation of “voice scripts” to be included in the instructor’s notebook which allow the instructor to make relevant telephone calls, e.g. radio reporter, Caltrans headquarters, etc. into the TMC at appropriate times during a simulation.

Activity Log Control Event

The Script Builder shall allow for the entry of Activity Log control events. Activity Log control events allow automated entries and hence automatic population of the TMC Simulator Activity Log, as if it were entered by TMC operators. (Ask Neil: Is this still required?)

Generic Run Script Event suggested by Neil so Sim Mgr can execute a predefined shell script at a given time.

(Future) Traffic Model Control Events

The Script Builder shall allow for control of the Traffic Model. Script Builder control shall provide the ability to create traffic events, e.g. traffic dots changing from to green to yellow to red as necessitated by the script. Currently this is supplied by a separate traffic event file but ideally would require some form of automated congestion generation.

2.4 Support for Student Evaluation

(ALL INSTRUCTOR NOTEBOOK) or grading sheets. None of this requires anything by Simulation mgr.

(For version 1 it may be adequate to define a“generic” evaluation event that allows a prompt to instructor and then a choice of how to score: yes/no, 1-5, A-F, 0-100).

Decision Tree Support

Have they done X yes/no, have they done Y yes/no, have they done Z yes/no,

probably only 3 levels, then assigns score or grade.

The Script Builder shall support the concept of a decision tree for script that it is used to build. The content/structure of the decision tree will be developed in conjunction with the development of the script while using the Script Builder, allowing the team designing the new script to articulate what preferred decisions to be made by the students in the simulator are. It is anticipated that information such as this decision tree will provide some of the basis for a future trainee scoring scheme. Note that this section requires further elaboration.

Support for Instructor Electronic Notebooks

The xml files generated by the Script Builder should be able to used as input by Electronic Notebook without any modification.

Traffic Network Scoring

The Script Builder shall support trainee scoring aggregated by highway, direction, time, and speed. (not sure about the speed here) The end result of such a scheme is that performance will be scored based on the activity in the traffic network, hence indirectly scoring trainee actions as these actions will affect the traffic network score. Unclear about this.

Assignment of Scoring Metrics to Specific Instructors

The Script Builder shall support the generation of a script notebook with evaluation events and other evaluation metrics assigned to specific instructors. Other evaluation metrics includes items to score such as CMS signs, HAR messages, queue protection,etc.

Associate Score with Feedback

The Script Builder shall support the ability to associate a quantitative score assigned to trainees with feedback,e.g. “Here is your score, here is what you did do correctly, and here is what you did not do”

Debrief by Position

The Script Builder shall support the ability to debrief students at the end of a training session by position, e.g.CHP CAD, ATMS, Maintenance Radio, PIO, MIO, Facilitator, etc.

Aggregate TMC Operator Functions

The Script Builder shall support the ability to aggregate multiple TMC operator functions into a individual positions, allowing the TMC simulator to be run with a smaller group of trainees on the floor. All scoring, trainee debriefing functionality, etc. shall be aggregated so that scoring options are coherent with position aggregation, which will be set via GUI controls.

Student Evaluation Events – General

The Script Builder shall allow for insertion of Evaluation Events which allow instructors to quantitatively and qualitatively measure the performance of student trainees in the TMCSimulator. These Evaluation Events create points in the TMCSimulator instructor notebooks, which can either be printed or electronic, where instructors will be prompted to evaluate student performance in their use of any TMC Simulator system. Instructor evaluations will be a quantified numerical rating, such as a scale from 1 to 5, and a written qualitative rating where the instructor can give direct commentary regarding student performance. Specific measures of performance available for each event are articulated within the *TMC Simulator XML Script Schema*. Each criteria to evaluate each Evaluation Event is specified in the* *TMCSimulator XML Script Schema*.

ATMS Utilization

Student Performance Evaluation Event

The Script Builder shall allow for instructors to evaluate student use of the ATMS. ATMS evaluation events allow instructors to determine how effectively students utilized the ATMS to interpret traffic conditions, set CMSmessages, etc.

Activity Log

Utilization Student Performance Evaluation Event

The Script Builder shall allow for instructors to evaluate student use of the Activity Log.

CHP CAD

Utilization Student Performance Evaluation Event

The Script Builder shall allow for instructors to evaluate student use of the CHP CAD.

Such a system might utilize modifications of the Simulator CHP CAD system to allow it to report back when and what CADlogs were utilized to determine if the trainees utilized CHP CAD to the maximum extent possible. These features would seek to understand if students responded properly to CHP CAD messages. Was their response delayed? Were they prompted? Was their response correct?

CMS Utilization

Student Performance Evaluation Event

The Script Builder shallallow for instructors to evaluate student use of Changeable Message Signs. (and HAR?)

Facilitator

Student Performance Evaluation Event

The Script Builder shall allow for instructors to evaluate student performance as aFacilitator.

Caltrans Radio, TMTRadio, TMT Radio Utilization Student Performance Evaluation Event

The Script Builder shall allow for instructors to evaluate student use of the each of theradio systems available to them.

CCTV Utilization

Student Performance Evaluation Event

The Script Builder shall allow for instructors to evaluate student use of the TMC SimulatorCCTV camera selection and viewing capabilities. These evaluation events would allow instructors to document how trainees utilized available CCTV imagery as part of their verification of a reported incident.

Telephone Utilization Student Performance Event

The Script Builder shall allow for instructors to evaluate student use of the telephone.Telephone evaluation events shall allow instructors to determine ifstudents have provided them complete answers to their phone calls,including information such as callback numbers, number of lanesclosed, fatalities, etc.

Sigalerts

The Script Builder shall allow for instructors toevaluate student use of SigAlerts? as appropriate to the simulation environment.

2.5 Supporting Realism in Training

Background Noise

The Script Builder shall allow background noise to be added to a script. Background noise will not be attached to an incident. It enhances the realism of the simulation by adding unimportant and unrelated events. Background noise shall include maintenance radio chatter audio clips, lane closures, TMCAL logs, etc. Specific background noise events will include animals in the roadway, a wild sprinkler on the freeway, a vehicle with a flat tire,etc.

Automatic Generation of Organization Chart for Training District (D14 – SantaLucia?) Not Needed by Fall

The Script Builder shall support the automatic generation of an organizational chart which will be used by both students and instructors in the back room and be coherent with all events in the generated instructor scripts.

Injection of Minor Incidents

The Script Builder shall support the automatic generation of secondary incidents if queue protection is not implemented by trainees as appropriate. This requirement implies that the Script Builder can encode for and the Simulation Manager shall be capable of dynamically adding an incident during a simulation.

Minor Incidents

The Script Builder shall be capable of generating a false incident which students will discover is such when the attempt to user available verification tools. Potential steps to implement a false incident are: 1.) start a log entry 2.) dispatch a unit 3.) survey area with surveillance tools, ATMS, etc. 4.)discover the incident does not exist. Comment

(Minor incidents are simply incidents but narrower in scope than typical incidents. Ideally they are displayed at the bottom of the edit canvas. Perhaps be able to “flag” an incident as minor.)

2.6 Specifying Expected Traffic Network Performance

Determining Queue Length - amount of traffic backup May be obsolete as we are replacing paramics.

The Script Builder shall allow the desired queue length for an incident to be specified. Potential methods t oaccomplish this feature are yet to be determined. Please note that this is related to the ATMS Driver and the control it asserts upon the ATMS.

2.7 Instructor Support

Assignment of Reporter Roles to Specific Instructors

The Script Builder shall allow reporter roles to be assigned to individual instructors.

Color Coding Instructor Manuals

The Script Builder shall support showing instructor roles in the instructor manuals using a unique identifier such as color.

2.8 Other Training Goals

Dedicated CHP CAD Training

The Script Builder shall be capable of supporting the development of CAD scripts, which the Simulation Manager can use to populate the CAD for the purpose of CAD specific training.

EOC Training

The Script Builder shall support EOC training.

Training for TMC & District Management

The Script Builder shall support the development of training scenarios customized to TMC and District Management.

Generalized Transportation Training

The Script Builder shall support the development of training scripts related to other modes of transportation, e.g.buses, trains, etc.

3.ATMS Driver

3.1General Requirements

Control of the ATMS

The ATMS Driver shall allow direct control traffic speed data into the ATMS.

Interface Description

The ATMS Driver shall control the ATMS based on the yet to be obtained interface descriptions from Caltrans.

Simulation Manager Interface

The ATMS Driver shall receive all control from the Simulation Manager

Traffic Modeling Capability

Do we want the ATMS Driver to have some trafficmodeling capability or should all control come from the SimulationManager?? Maybe we want to have the simulation manager give it commands for a section of roadway such as: initiate free-flow trafficon roadway segment x, begin backing up traffic at rate y on roadwaysegment z, etc.?

Note: ATMS expects update every 30 sec or it will display white dots instead of colored ones.

4.Instructor Electronic Notebook Requirements

4.1 General Requirements

Information Displays

The Instructor Electronic Notebook shall have displays of a simulation summary, the simulation script as it is progressing, a TMC Simulator CHP CAD terminal, an ATMS display, and a navigable roadway map, e.g. Mapquest, Google Maps, etc.

The Instructor Electronic Notebook shall display the current simulation time in hours, minutes, and seconds on a prominent clock which is always visible.

Touch Screen Display

The Instructor Electronic Notebook shall utilize atouch-screen display allowing user interaction via finger touch, stylus, etc. as is appropriate to the platform selected.

Instructor Login and Simulator Operation Duties

The Instructor Electronic Notebook shall automatically synchronize to the script that the TMC SimulationManager? is running.

The Instructor Electronic Notebook shall allow the operator to log in as a specific instructor, binding them to pre-determined TMC Simulation support roles and evaluation responsibilities.

Indoor Operation

The Instructor Electronic Notebook shall be readable and useable in all indoor lighting conditions.

Keyboard and Voice Input

The Instructor Electronic Notebook shall allow keyboard input, either through an actual keyboard or an electronic screen-based keyboard.

The Instructor Electronic Notebook shall allow instructors to record voice messages during a simulation via individual microphones for the purposes capturing qualitative feedback.

The Instructor Electronic Notebook shall be capable of automatically performing voice recognition functions for recorded instructor qualitative feedback. Comment

Battery Powered Operation

The Instructor Electronic Notebook shall be capable of battery powered operation for periods of at least eight hours.

Finger Size Accessibility

The Instructor Electronic Notebook shall accommodate a variety of finger sizes for instructor input of data and navigation between displays/windows. Small and large fingers shall work equally well for making GUI selections.

4.2 Simulation Summary Window

Listing of Incidents

The Instructor Electronic Notebook shall provide a listing of all incidents in the script that is running at the present time on the Simulation Manager.

Incident Information Displayed

The Instructor Electronic Notebook shall display the time the incident starts, the incident number, the name of the incident, and the description of the incident. Incident summaries shall be able to be collapsed and expanded with simple GUI controls.

4.3 Simulation Script Window

Display and Highlighting of Events on Running Script Window

The Instructor Electronic Notebook shall display the events in the script. Each event shall be displayed within a clearly delineated boundary. Using simple GUI controls, the user shall be able to collapse and expand any event. The current event shall be highlighted with a colored header bar.

The Instructor Electronic Notebook shall allow all the events belonging to an incident in the script window to be collapsed or expanded using simple GUI controls.

Student Evaluations Performed by Instructor

The Instructor Electronic Notebook shall automatically prompt the user with pop-up windows for quantitative and qualitative student evaluations which are currently required by the instructor logged into the given Instructor Electronic Notebook. Instructors shall only be shown pop-up windows that are applicable to them.

The Instructor Electronic Notebook shall allow the instructor to enter quantitative scoring, e.g. on a scale of 1 to 5, with simple one-touch GUI actions.

The Instructor Electronic Notebook shall allow the instructor to enter qualitative text via a keyboard.

Jumping to Different Simulation Times in the Display

The Instructor Electronic Notebook shall allow the user to jump directly to the current event using a one-touch GUI action.

The Instructor Electronic Notebook shall allow the user to jump directly to a specified time as inputted by the user.

4.4 CHPCAD Terminal Window

Standard Functionality

The Instructor Electronic Notebook shall provide a CHP CAD terminal with functionality similar to that of the “standard”TMC Simulator CHP CAD terminal.

The Instructor Electronic Notebook hall allow the instructor to view all CHP CAD entries made by students.

The Instructor Electronic Notebook shall allow the instructor to make CHP CAD entries during a simulation.

The Instructor Electronic Notebook shall automatically update as CHP CAD entries are made within the TMC simulation environment.

Flexibility in CHP CAD Control Implementation

The Instructor Electronic Notebook may utilize different CHP CAD controls than those used by the “standard” CHPCAD window as required by the limitations and capabilities of the specific device used for the Instructor Electronic Notebook.

4.5 ATMS Display Window

Display Simulation Roadway Area

The Instructor Electronic Notebook shall provide an ATMS display window which allows instructors to see vehicle detector status of roadways in the simulation area.

Limited ATMS Functionality

The Instructor Electronic Notebook ATMS display shall not be zoomable.

The Instructor Electronic Notebook shall not allow control of various field devices, e.g. CMS, CCTV.

4.6 Simulation Area Reference Roadway Map Window

The Instructor Electronic Notebook shall provide a roadway map with incidents from the simulation area clearly marked for instructor reference.

Limited Functionality

The Instructor Electronic Notebook shall not be zoomable.