Revised March 18, 2008:
18-649 Project Assignment #5

Implementation & Test

Due Thursday February 21, 2008 at 11:59 PM

Please submit all project-related correspondence to ece649-staff "at" ece.cmu.edu

Assignment:

In project 5 you will build half of your elevator system and informally test one sequence diagram.  The purpose of this exercise is to get you started writing code for the elevator system.

An important new part of project 5 is defect tracking. When you test your code, you will no doubt run into errors. These errors will have many possible sources, they could simply be syntax errors in Java, but we are interested in the errors caused by problems in your original requirements and design, these are defects. Since you have all been keeping track of changes in a change log, this should just be a small outgrowth of that exercise. When a defect is located that requires changes to earlier steps in the project, say you created a scenario in project 2 that needs to be expanded, we want you to track this. You will write in your change log the files you had to update. However, the important aspect of defect tracking is that you will also state where the problem was discovered (at this stage, probably in coding), and what previous project turn-ins had to be changed to correct the problem. By having this tracability you will be able to see where this problem was originally created.

To perform defect tracking, create a separate file, called 'defect_track.txt'. This file will include the above information, namely:
1. What file the error was discovered in.
2. Brief description of the problem.
3. What documents had to be updated in response.
4. First document to include this fault, and thus the source of the error.


What you need to create:

1) Implement (in Java) the DoorControl, DriveControl, HallButtonControl, and CarButtonControl objects. These correspond to some of objects you have previously designed in state charts.

Things you are allowed to do:

Things you are NOT allowed to do:
(NOTE: Please refer to the Elevator Simulation API for important information on the differences between Framework and Network messages.) Additionally, you are REQUIRED to mark the line in each code that causes each and every state transition (i.e. forward traceability) you have designed on your state charts. This marking will be accomplished with comments. So that these lines are easily distinguished from other comments, you shall begin the line with the character '#' followed by the word 'transition' followed by the transition name as described on your state machine backward traceability matrix in single quotes.

For example, on the line of code that corresponds to the A() transition on your Drive Controller statechart traceability matrix, you would add the comment: 

// #transition 'A()'
to the line in your code that actually CAUSES this transition.

This is done so that it is possible to easily check to ensure all of the arcs in your state transition diagram are implemented as you have described them.

We will provide you three acceptance test files to test against your elevator system: proj5acceptance1.pass, proj5acceptance2.pass, and proj5acceptance3.pass.  Part of your grade for this project will be based on whether or not your elevator system can pass these three tests and two other generally comparable ones we will not provide you.  You are encouraged to make up your own tests to exercise your elevator system.  If you do, your acceptance test file must have the extension .pass (e.g., people.pass) for the simulator to run it.

The system acceptance test file format is:

<seconds>,<start_floor>,<start_hallway>,<destination_floor>,<destination_hallway>  ;  <comment_field>
Where each line of the file creates a single passenger to appear at time <seconds>.  That passenger starts on floor <start_floor> and hallway <start_hallway>, and will behave in such a way as to go to  floor <destination_floor> and hallway <destination_hallway>. <start_floor> and <destination_floor> should be integers in the range [1...MaxFloor].  <start_hallway> and <destination_hallway> should be 0 for the front hallway and 1 for the back hallway.  Tests with this input file are run with all modules in the system loaded.  The entire system is initialized before the testing begins.  An example input for the system integration test is:

15,1,1,3,0    ; person A going up
15,7,1,1,1    ; person B going down

Which means that at the same time, t = 15, two people show up, 1 person on the 1st floor back hallway wanting to go to the 3rd floor front hallway, and 1 person on the 7th floor back hallway wanting to go down to the 1st floor back hallway.  Keep in mind that certain floors do not have certain hallways, and if you mistakenly assign people to hallways that do not exist, they are likely to get stranded in the elevator or may not get on the elevator at all!  Here is the hoistway setup.  Keep this handy when making your integration tests.

Floor #
8 FH
7 FH and BH
6 FH
5 FH
4 FH
3 FH
2 BH
1 FH and BH

You are not required to use FAST speed for the main drive motor. You do not have to have a "smart" dispatcher. You just need to deliver the people without tripping the emergency shutdown mechanism. Use the .class files from project 1 for any module you haven't yet written.


2) Write tests to informally test one sequence diagram from project 2.  The sequence diagram you choose must contain at least one of the four control objects created in this project (DoorControl, DriveControl, HallButtonControl, and CarButtonControl) and must not contain any of the other three control objects (Dispatcher, LanternControl, CarPositionControl). 

The assignment is to generate a set of files that are sufficient to completely test one sequence diagram from project 2.   Although this is not exactly "unit testing"  (see project step 3 below), you will use the unit test file format as outlined in section 3 to test the sequence diagram.   We're going to leave the details of how to accomplish things to you, but to be correct a test must somehow address all the below points:


3) Write unit tests to informally test the DriveControl statechart. 
Create tests that exercise all transitions of your DriveControl design (i.e., all arcs on your state diagram).

Unit test for this project means testing the behavior of a single system object such as a door controller or the dispatcher.  These tests are derived from the system design, and should completely cover all states and transitions in your state diagrams to ensure that code that is written actually implements the intended design.

The general format of the system implementation will be that there is a simulation framework that "glues" together all the different system objects, both ones you design and ones we're designing for you.  You are responsible for implementing and testing the objects you've designed in previous assignments; we're responsible for implementing and testing objects we provided complete requirements for back in Project #2 as well as the simulation framework.  You do not have to provide tests for the objects we're providing to you.  For this particular assignment you will only design tests for the DriveControl object.  However, you will be required to produce similar tests for the other objects in future projects.

We will be providing a special diagnostic object to you which has the purpose of taking a plain text file describing messages to be sent on the network and actually sending them out on the network at specific times.  This diagnostic object also records all network messages and places them in an output file.  If you put this diagnostic object and one or more other objects into the system framework you can run single-module tests by sending specific messages at specific times and observing that correct outputs are produced.

The unit test file format is the following:

<seconds>,<rep_interval>,<message_type>,<data_field1>,..,<data_fieldN>,<context> ; <comment_field>
Where each line of the file generates a single copy of a single message onto the network at the time specified.  <seconds> is a floating point number of seconds; <rep_interval> is the repetition interval (in floating point seconds) for the message, with zero being a single event message; <message_type> is the name of a message; the data fields are as documented.  Context will be N for network, F for framework.  Comments are indicated by a ";", with the comment extending to the end of a physical line. Any modules in the system will be fed an "initialize" signal before the testing begins.

CLICK HERE TO SEE EXAMPLES OF ALL SUPPORTED MESSAGE TYPES.

The assignment is to generate a set of files that are sufficient to completely test your DriveControl design.  Each file can test more than one thing, but ideally you have several short tests rather than just a few long complex tests. We're going to leave the details of how to accomplish things to you, but to be correct a test must somehow address all the below points:

CLICK HERE FOR AN EXAMPLE TEST FILE.

Team Design Portfolio:  

1) Organize your design portfolio.

Your project5 directory should contain the most up-to-date design package for your elevator system organized into the following directories.  This directory structure will develop as the semester progresses. This is to organize things for the rest of the course -- you'll be keeping this same organization and updating things for each subsequent project phase.

2) Ensure your design portfolio is complete and consistent.  If you have been keeping up with updates in the previous project stages, most of this work will already be done. The following is a partial list of the characteristics your portfolio should exhibit:

Handing In Results

Each team shall submit exactly one copy of the assignment.

Please include at the top of each file the assignment number, your group number, the names of your group members, and the file name.

Projects shall be submitted by copying all needed files into your group's directory in the course AFS space in the following directory:  /afs/ece/class/ece649/Public/project/group#/project#/
(group# is your group number and proj# is the number of this project.  you may need to create this directory yourself)

Any submission that contains files with modification dates after the project deadline will be considered late and subject to a grade deduction (see course policy page for more information).

Submission shall be electronically in the form of a web page with text and in-lined images, in HTML 2.0 format, viewable from both MS Internet Explorer and Netscape Navigator. HTML 2.0 does NOT include java or javascript or some of the more esoteric functions (frames, etc.). (In other words, we want "plain-vanilla" html to eliminate problems printing and viewing.) Any drawings shall be in non-animated GIF format. (You can use other graphics formats at your own risk, but we must be able to view them in the web browsers mentioned above).  You can also submit your project in pdf format, but make sure it prints correctly on a postscript printer.    A regular text editor should be sufficient for this assignment - you may want to make the traceability tables in Excel or Word and use the 'Save as HTML' or 'Save as Web Page' feature in the File menu. If you need some help with HTML please come to Office Hours :)

Additionally, the result should be easily readable when printed on a black-and-white laser printer. Each HTML file AND picture shall include the team number and names of all members of the team.

Grading (75 points)

This assignment counts as one team grade. If you choose to divide the work, remember that you will be graded on the whole assignment.

Back to course home page