18-649 Project 5 - Implementation and Test

Check the course webpage for due dates

Please submit all project-related correspondence to staff email address


In project 5 you will build half of your elevator system and begin testing your design with unit and integration tests.

This project is more challenging than the previous ones!!! Please start on this project as early as possible.  You will find that many parts of this (especially testing) cannot be rushed, so please do not wait until the last minute.

1. Download and Read about the Simulator

First, download and compile the latest version of the simulator code from the download page

Run the simulator with no parameters to print the command line documentation.  Study the flags and features available in the simulator. 

Read the simulator development overview.

Read the bug handling policy in the project FAQ.

2.  Controller Implementation

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

Each controller object you write interfaces with the simulated physical system and the simulated network.  Here are some requirements for the controllers:
  1. Each controller shall extend the simulator.framework.Controller class.
  2. Each controller shall be placed in the simulator.elevatorcontrol package.
  3. Each controller shall use the network and physical interface objects provided in the Controller super class and no other network connection objects.
  4. Each controller shall receive, at most, one physical input and generate, at most, one physical output.  This means that each physical message payload shall be sent by, at most, one object and received by, at most, one object.  For example, if your DriveController listens to the DriveSpeed framework message, your Dispatcher may NOT listen to DriveSpeed framework message as well.  If your DriveController sends Drive framework messages, your Dispatcher may NOT send Drive Framework messages as well.
  5. Each controller shall receive and send network and framework messages according to the interfaces defined in the Elevator Behavioral Requirements document.
  6. You may not create additional communication channels of any kind between the controllers.  This includes creating shared references to static/global variables and any method where a controller may directly modify the state of another controller.  If you are in doubt as to whether something you are doing violates this requirement, consult a TA in office hours.
  7. Each controller shall execute at most one transition per execution of the control loop, and the control loop must execute periodically.  To schedule controller code in real systems, there must be a worst-case bound on the execution time.  If the controller is allowed to make multiple transitions, then there is (theoretically) no upper bound on how long it takes to execute the controller.  The one-transition-per-loop rule also approximates the limited processing power of the small microcontrollers you would likely see in a highly distributed application.

In addition to the above:

A couple of notes regarding the CAN network implementation:
As you continue to develop your project, you should also continue to log defects and changes in the logs that you started during project 4.

3.  Traceability - Statecharts to Code

You are REQUIRED to mark the line of 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 '//' (to start the comment), followed by the character '#', followed by the word 'transition', followed by a space, 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 DC.1 transition on your Drive Controller statechart traceability matrix, you would add the comment:

//#transition 'DC.1'
just above the line in your code that actually CAUSES this transition.  The appropriate line may depend on your implementation, but in general, it would be appropriate to place the traceability comment just above the if statement that tests the guard conditions for the transition.

The purpose of the traceability is 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.

In order to ensure that you have traced all your arcs, you will add an entry to the Statecharts to Code Traceability file ( traceability/sc_code.html in the portfolio template)

Controller Name (e.g. DoorControl)
Module Author:  Module author's name
Traceability performed by:  Team member's name
Line Number    Transition #
Line Number    Transition #

You may use a table or other basic formatting to organize this information. The line number refers to the line that the comment appears on.  Line numbering shall include empty lines.
the following linux commands may help you generate some of the required output:  
        nl -b a Dispatcher.Java | grep "#transition"
where Dispatcher.Java is the name of the controller Java file.

Someone other than the person who authored the module must generate this check and verify that every transition traces to the code.

4.  Unit Testing

You will write and execute a unit test for each controller you have implemented (DoorControl, DriveControl, HallButtonControl, and CarButtonControl objects).  The list below summarizes the steps you must follow.  These steps are explained in more detail in the Unit Test section of the Testing Requirements

Note: This list is just a summary.  You are required to follow all the steps and procedures in the Testing Requirements document!

5.  Integration Testing

Choose TWO sequence diagrams to write integration tests.  The sequence diagrams you choose for this test 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). 

A summary of the steps you must follow is given below.  Read the Integration Test section of the Testing Requirements for more details.
Note: This list is just a summary.  You are required to follow all the steps and procedures in the Testing Requirements document!

6. Peer Review

You must perform peer reviews of the 4 controller implementations and 4 unit tests that you have created. Another member of the group that was not the author of the implementation or unit test should conduct the peer review.

For this week's peer review you must complete the following:

Team Design Portfolio

The portfolio you submit should contain the most up-to-date design package for your elevator system organized and formatted according to the portfolio guidelines.   You are going to update your portfolio every week, so be sure to keep an up-to-date working copy. 

Ensure your design portfolio is complete and consistent.

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.

Follow the handin instructions detailed in the Project FAQ to submit your portfolio into the afs handin directory ( /afs/ece/class/ece649/Public/handin/project5/group#/ontime/).

Be sure you follow the required format for the directory structure of the portfolio and its location in the handin directories.

Be sure to follow ALL the portfolio guidelines detailed in the Portfolio Layout page.

Don't forget to include your message defines! This is a common failure mode for handin of this project and will result in your tests throwing runtime errors.

Make sure you compile and run everything on the cluster machine! Murphy's Law of Grading states that anything that is not tested on the clutser machine won't work when your TA tries to grade it on the cluster.

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).

Grading (145 points):

Here's the minimum requirement spread sheet.

This assignment counts as one team grade. If you choose to divide the work, remember that your team will all receive the same grade.

Pay special attention that you submit code that will compile correctly with the current version of the simulator.  You stand to lose at least 10% of the grade if your code will not compile!

A detailed grading rubric is available here (PDF). Grading will be as follows:

Each team member must satisfy the minimum stated per-member requirements. Team members who omit any required per-member activity will receive a zero contribution grade.

Back to course home page