Using the Instructor Tool

The Instructor Tool website allows instructors to manage the use of the HVAC ePrimer within a course and classroom setting. The site is password-protected so that only administrators and instructors have access. Students will not have access to the Instructor Tool.

For rapid and efficient software development a set of open source software tools were used to create the Instructor Tool, including:

  • MySQL
  • Ruby
  • Ruby on Rails
  • WebORB for Rails
  • Related supporting modules for Ruby and Ruby on Rails

A community college could set up the Instructor Tool at a number of Internet Service Providers (ISP) at relatively low cost ($10-$20 month) or host the application on a local server. Depending upon IT resources at a community college, administrative costs of maintaining a local server might be significantly higher than the cost of maintaining the Instructor Tool at an ISP.

Setting Up the Site

Setting up a server to run the Instructor Tool is a somewhat involved process. We are planning to release documentation and helper tools to make this process as easy as possible. However, the process will still involve a basic understanding of UNIX servers, Ruby on Rails, and MySQL. Alternatively, alpha testers can contact us to have users set up on the existing alpha-version site.

Once an Instructor Tool is set up, the default administrator password should be changed. This administrator should then create Instructor and Student users. Instructors should then login and create Scenarios for students to use.

Signing In

All administrators and instructors can use a browser to navigate to the Instructor Tool website once it's set up.



Enter a valid login and password. Welcome to the Instructor Tool!

Main Menu

The menu gives access to the main functions of the site: managing user, adding or updating scenarios, altering the system variables, or viewing usage graphs.

Managing Users

The instructor needs to create an ID for each student to enable the student to access scenarios.



Once the student has an ID the student can access scenarios created or identified by an instructor. However, students have no access to the site location used by the instructor.

Editing Scenarios

A scenario is a group of settings that customizes HVAC ePrimer. An instructor can create and modify scenarios on the Instructor Tool website. The Scenarios are then available for download within the client.

The Scenario section of the Instructor Tool has the following functions:

  • View a list of scenarios
  • View a scenario's details
  • Editing an existing scenario
  • Creating a new scenario from an existing one
  • Creating a new scenario from scratch
  • Deleting an existing scenario


A scenario is composed of a complete set of System Variables, each of which can be customized. It also has some meta-data such as name, description, location of an explanatory movie (if one exists) and so on.

When creating or editing a scenario, the main task is to set the low, default and high values for each input variable. These values restrict what the student can enter into each input variable when running the simulation. Essentially, by controlling the default values for a group a input variables, the instructor can create a certain HVAC situation for the student to experiment with.

But can't the user change input values before they start the simulation? Well, yes, but only if you let them. By using the PUBLIC/PRIVATE setting and the DISABLED checkbox, you can further tailor your scenario for a certain learning task by selectively hiding information and/or disallowing changes.

PUBLIC and PRIVATE variables

Setting a system variable to PUBLIC means that the user can view the system variable within the client. PRIVATE means that the system variable is hidden within the client...it's still used to drive SPARK with the values set on this screen. It just isn't displayed to the student in the INPUT window or on the visualization window.

This feature was included to allow the instructor greater flexibility in creating certain learning situations. The instructor may want to create a Scenario where the student is asked to find out what's wrong with the system with only a few variables to analyze.

DISABLED checkbox

The DISABLED checkbox is used to disable the ability to change a system variable. A disabled system variable is still shown to the student, the input field is simply turned off.

This feature was included to allow the instructor to show the student the values that are driving the system, but disallow them to change them before or during the simulation.

System Variables

System Variables are the variables that drive the SPARK simulation. There are approximately 230 of them, and each has it's own set of meta-data, including a simple description, low and high values, default value and so on. Some of this meta-data is directly displayed to the user -- the description, for example, is displayed when the user rolls over the small yello question mark icon next to an input variable. Other meta-data is used behind the scenes, such as the conversion factor from SI to IP.

System variable editing screen shot

System Variable information is sensitive and setting the values incorrrectly can cause SPARK to crash or behave erratically. Therefore, only administrators have the ability to edit System Variable information. Instructors can only view this information.

Usage Reports

If desired, basic usage reports can be set up. This feature is in basic form and is being explored. Currently, user login fequency is the only report.