18-649 Project 1 Simulation Exercise

(Project 1 part B)

Please submit all project-related correspondence

Simulation Exercise:

Test the elevator system.

The purpose of this assignment is for you to become familiar with the simulation framework.  For this assignment you will not be working with the fully functional elevator, but rather you will see how a sample module works within the simulation framework.  You will need to perform the following high level steps (details are provided below):

1) Download the simulator code into your AFS directory from:
/afs/ece/class/ece649/Public/project/proj1/code

2) Compile & run the simulator with the gui using the sample integration test file basicpass.pass . Let it run a while; it will eventually complete (you can start step 3 while you are waiting for it to run).

3) Open the simulator/elevatorcontrol/TestLight.java code and look through it.  Try to understand what it does.  (If you have trouble with the text file format due to Unix to Windows conversion, try viewing it in a web browser.)

4) Open the simulator/elevatorcontrol/Control.java code and make the following additions:

a) Define your testLight object by adding the following line of code to the corresponding section:

               TestLight testLight;

               b) Instantiate your testLight object by adding the following line of code to the corresponding section:

               testLight = new TestLight(h, TEST_LIGHT_PERIOD, testMode);

5) Compile the code & run the two sample module tests for the testlight object testlight_01f.test and as testlight_02f.test.

What we provide:

All of the basic simulation infrastructure is provided for you. Specifically, we provide the discrete-time simulation tools, the constructs needed to communicate with other objects in the simulation, environmental actuators that will respond to your commands and standardized message definitions.

A detailed API document that further describes how to interface with the simulation can be found HERE.

All provided code can be found in the directory:

/afs/ece.cmu.edu/class/ece649/Public/project/proj1/code/

You should find 5 packages:

• jSimPack
• simulator.framework
• simulator.payloads
• simulator.elevatormodules
• simulator.elevatorcontrol

As well as two  .test files to be used for testing.

Detailed descriptions of each package can be found in the API DOCUMENTATION.

All source code is provided (except for the control modules you will be creating later in the semester)

• simulator.framework.Elevator - provides command line interface and instantiates all objects.

Provided so that you may add additional command-line switches as you see fit. We're going to use these switches for grading, so you're NOT permitted to change the operation of existing switches/switch values.

• simulator.elevatormodules.Modules - instantiates all environmental objects.

Provided so that you can instantiate individual objects for unit testing, and for your module periods.

• simulator.elevatorcontrol.Control - instantiates all controller objects.

This is where you will instantiate all control objects you will create later in the semester, as well as supply the control periods. The following section provides more detail on this topic.

• simulator.payloads.MessagePayload - contains size and priority information.
  Implement your message sizes and priority (as in Project 5) here.
  Note: You are also required to turn in an updated schedule, including modifications required in Project 5. See Grading Criteria for more detail.

• simulator.elevatorcontrol.AsciiDisplay - the GUI for the simulator
  The display is implemented as just another network node that listens to all the messages and prints out information. Feel free to modify it as much or as little as you like for your purposes. Please be aware that in order to display actuator outputs correctly, you'll have to broadcast them on the network as well as the framework for the display to work properly.

Please see the Example section of this document for more details and an example on how everything fits together.

Detailed Steps For Running the simulator:

In order to run the simulation, first make sure that you are running an appropriate version of Java on an appropriate machine. We recommend using the "color" computers based on your account for black.ece.cmu.edu . You can get a list of all the color machines by sshing to black:

ssh black.ece.cmu.edu 

You'll probably want to telnet to a color machine other than black for running the simulator, as black is the main machine and thus the most heavily loaded.
More information on using Unix machines can be found at https://www.ece.cmu.edu/facilities/ and http://www.cmu.edu/computing/

All the color machines have Java 1.5.0 installed, the version is REQUIRED for this assignment. This version of java can be found by entering the following on the command line:

java -version

Java should already be in your command path. If the above results in java not being found, see if "/usr/bin" and "/usr/local/bin" are in your PATH environmental variable. You can check your PATH variable by typing:

 printenv PATH 

from the Unix prompt. If not, you may add this to your path by typing the following command when logged into a color machine:

 set PATH = (/usr/bin /usr/local/bin $PATH)

Copy all code from the repository, making sure that you preserve the original package hierarchy. For example, if you wanted to put all the files in a directory called project1code, you would first make a directory by typing:

 mkdir project1code

then copy all files to that directory by typing:

 cp -R /afs/ece.cmu.edu/class/ece649/Public/project/proj1/code/* ./project1code/

*NOTE: ( This code will be the framework used for all future projects.  It is highly suggested that you copy it to a new directory for each project phase (that requires code) before you start implementing the changes for that phase.:p>

Then, set your CLASSPATH environmental variable to the directory to which you have just copied the files so Java knows where to look for class files.  Following the above example in the bash shell you would type:

cd project1code
 CLASSPATH=$PWD 
 export CLASSPATH

  if you are using tcsh or the above doesn't work, try this instead:

 cd project1code
setenv CLASSPATH $PWD

(if you are using another shell, you might need to use another syntax to set the environment variable).  Come to office hours if you are having problems setting up the simulator.

Compiling:

To compile a particular file, use:

 javac filename.java 

I usually compile one directory at a time, for example:

 javac simulator/elevatorcontrol/*.java 

Check which subdirectories are present and compile all of them. A bug that bites people sometimes is one where source code has been modified but not recompiled (sometimes even TAs make this mistake!) So if you ever notice something weird or broken, be sure to recompile ALL the java files before concluding there is a bug. For example:

 javac simulator/*/*.java 

You will need to compile all the directories with code you have changed in them. Note this may not work correctly if your CLASSPATH is set incorrectly.  (see note above)

Running:

The simulation is invoked on the command line from the base project directory (project1code in this case) with:

 java simulator.framework.Elevator

(The above command by itself will display a list of options).

Where the command line options for the test files are:

Elevator {options} [-t testfile]/[-p passfile]
-t testfile.test enables module test mode
-p passfile.pass enables system test mode

NOTE: The default amount of time the simulator runs is 300 seconds (5 min) 'sim time', or until all passengers are delivered (whatever comes first). If you have undelivered passengers you can tell the simulator to run longer using -rt time#, e.g. this will give you 10000 sim seconds:

 java simulator.framework.Elevator -gui -b 200 -rt 10000 -p yourintegrationtest.pass 

(If you try this now you might get messages saying "enqueueing event in FI" that mess up the GUI display; thats expected until you edit files as required by this assignment.)

Only one input stimulus file is allowed per simulation run. A module test (message injection) may be specified by using the '-t' switch, while a system integration test (passengers) is specified with the '-p' switch.

Input files have the following formats:

• Module test - The file format is:

<seconds> <rep_interval> <message_type> <data_field1>{...<data_fieldn>} <context>

Where <seconds> is the time the message will be sent, <rep_interval> is the message repeat rate in seconds, <message_type> is the type of message to be sent (e.g., carcall), <data_field1..n> are the values of the data fields for the message (see API), and <context> is either F for framework messages or N for network messages.

• System integration test - The passenger stimulus file format is as follows:

<seconds>,<start_floor>,<start_hallway>,<exit_floor>,<exit_hallway>

Where <seconds> is the time in seconds that the passenger should enter the simulation, <start_floor> is the starting floor for that passenger, <start_hallway> is 0 for the front hallway and 1 for the back hallway, <exit_floor> is the floor the passenger wishes to be delivered to, and <exit_hallway> is 0 for the front hallway and 1 for the back hallway.

NOTE: Specifying a system integration test will result in the generation output file elevator.stats at the completion of a simulation run. This output file contains statistics regarding the performance of your elevator, including detailed information on passenger delivery.

Running:

java simulator.framework.Elevator

without any command line options will list options for you.

For example, to run the module test for testlight given in file testlight_01f.test, you would type:

 java simulator.framework.Elevator -t testlight_01f.test

(but, this particular file wont necessarily do anything interesting until youve made the edits required by this assignment.)

To run the integration test given in file basicpass.pass, you would type:

 java simulator.framework.Elevator -p basicpass.pass

with the gui, you would have:

 java simulator.framework.Elevator -gui -p basicpass.pass 

**Note that the TestLight object writes information to the screen so it will over-write the gui. For this lab when you module test TestLight,  don't use the gui. :p>

Example:

An example controller simulator.elevatorcontrol.TestLight is provided that simply turns on and off the first floor CarLight once per second. If a CarCall message is received that indicates that the first floor front CarCall button has been pressed, the CarLight is then instructed to remain on.

This example demonstrates several important details that will be important in implementing all of your designs:

• What to do when you instantiate your object - it will be necessary to register to receive messages of one kind or another, and the constructor illustrates how to do this.
• How to send messages - your objects will need to communicate not only with the object you are controlling, but other objects as well. This example describes how to send messages you'll need.
• How to receive messages - your objects will need to receive messages from the outside world. This example illustrates how to receive that information as well as how to utilize it.
• How to utilize the concept of 'time' - it will be important for your objects to have some notion of time. This example details how to set Timers to wake your objects up after a specified period of time.
• How and when to send/receive Framework and Network messages - realizing the subtle differences between Framework and Network messages is an important aspect of this project. This example illustrates important concepts, such as why it is important to in some cases re-broadcast Framework messages over the Network.

Please see the comments within the file for more detailed information.

The source file simulator.elevatorcontrol.Control has this object instantiated for the purposes of this project phase.  In future project phases it should be removed.

Here is the TestLight Statechart (you will learn more about statecharts in lab 4):

The module testing files for TestLight can be found here as test file 1 and as test file 2 . The .test file is just text so if your computer gets confused, you can open the file with any text editor.

Note that the TestLight object writes information to the screen so it will over-write the gui - if you are just trying out TestLight (as you should be in this lab) don't use the gui. 

Reference Information:

You may find the following information useful in completing this assignment:

Elevator Simulation API

Sun's Java Tutorial

Back to Course home page