18-649 Project 5 - Implementation and Test

Please submit all project-related correspondence to 

Assignment:

1. Download and Read about the Simulator

2.  Controller Implementation

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:

• All Java files you write must be placed in the simulator.elevatorcontrol package. 
  
• You may implement additional utility classes in the simulator.elevatorcontrol package, provided that these do not create an additional communication channel between the controllers.  The Utility class provided (in Utility.java) has some examples of how to build arrays to receive and process all the copies of replicated network messages.
  
• Your portfolio has a place to include your elevator code.  You must submit ONLY the contents of the simulator.elevatorcontrol package, and the files must be placed in the elevatorcontrol/ folder of your portfolio.  See this note in the portfolio layout page for details.
  
• Your code must be compatible with the latest required code release.  (Note the details of this in the bug handling policy).
  

• Although you are going to be able to define your own bit-level message payloads, you are still required to adhere to the message dictionary and interface requirements we have provided.  This means that you may not do any of the following:
• • Add more information (e.g. another variable value) to a message that has already been defined
  • Define a new message.
  • Use a message for a purpose other than its stated purpose.
• If you violate these constraints, it will result in a significant point deduction.
  
• Regarding CAN payload translators and message IDs, the acceptance tests for this project will be run on a simulated CAN bus with 'infinite' bandwidth, so performance and message prioritization will not be an issue.  There will be a project later in the semester where you will deal with optimizing the network performance.   For this project and the next project, it is acceptable to use the CAN Translators and CAN message ID's that we have provided, even though they do not make efficient use of network bandwidth.  If you need to write additional translators for messages sent by your controllers, you may do so.
• All this is spelled out in more detail in the simulator development overview. 
  

3.  Traceability - Statecharts to Code

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'

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.
Hint:  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. 

• Create unit tests that tests (a configuration / .cf file and one or more message injector / .mf files) that exercise all transitions of the statechart. 
  

• If you have transitions with guard conditions combined by OR operator, you must separately test each OR term.
• Each state you test must use assertions to test all controller outputs (both network and framework messages).  You may optionally use state assertions to verify the state of the controller as well.
  

• Traceability - injections to exercise transitions and assertions to test state outputs must be preceded by comments of the format described in the Testing Requirements document.
  
• Execute the test and record the test results in the Unit Test Log in your portfolio. 
  

• For this project, you are not required to pass all assertions of the tests. If you don't pass any particular test you must explain what went wrong in your submission.
• All the tests you turn in (for this and all future projects) must by syntactically valid.  That is, they must not cause a runtime exception.
  
• You will eventually be required to pass these tests.  Don't blow them off now, you'll just make more work for yourself later.

• 
  
• Add your unit tests to the Unit Test Summary File
  
• If the unit test identifies bugs in your design, add the bug to the Issue Log, and add a note in the Unit Test Log stating "This test identified issue #X in the Issue Log."

5.  Integration Testing

• Create a sequence diagram test (one configuration /.cf file and one message injector/.mf  file) to test each sequence diagram.
• Traceability - each message injection or assertion must be preceded by a comment of the format described in the Testing Requirements.
• Execute the test and record the test results in the Integration Test Log in your portfolio. 
  

• You are not required to pass the tests for this project.
• All the tests you turn in (for this and all future projects) must by syntactically valid.  That is, they must not cause a runtime exception.
• You will eventually be required to pass these tests.  Don't blow them off now, you'll just make more work for yourself later.

• Add your integration tests to the Integration Test Summary File
  
• If the unit test identifies bugs in your design, add the bug to the Issue Log, and add a note in the Integration Test Log stating "This test identified issue #X in the Issue Log."

6. Peer Review

• As a group, peer review 4 controller implementations.
• As a group, peer review 4 unit tests.
• All peer reviews must be added to the Peer Review Log.
• If a defect is found in a peer review but not fixed this week, it must be logged in the Issue Log.
  

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.

• Changes requested by the TAs in previous projects have been applied.
• All required documents are complete and up-to-date to the extent required by the projects (you do not need to update files or links related to future projects).
  
• All documents include group # and member names at the top of the document.  (This includes code, where this information should appear in the header field)
• Individual documents have a uniform appearance (i.e., don't look like they were written by 4 individual people and then pieced together)
• The issue log is up-to-date and detailed enough to track changes to the project.

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

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:

• 30 points - Implementation of DoorControl, DriveControl, HallButtonControl, and CarButtonControl. (One object per team member)
  
• 30 points - Complete traceability of statecharts to code for the four objects. (One object per team member)
  
• 40 points - Complete unit tests (all states and transitions) for the four objects and pass all assertions. (One object per team member)
  
• 20 points - Completing two integration tests (OK to have pairs of team members work on integration tests)
• 20 points - Completing the peer reviews (One object per team member)
  
• 5 points - A list of which points corresponding to which tasks were primarily completed by each team member (every point must be assigned to a specific team member). Entry in the Improvements Log that tells us what can be improved about this project. If you encountered any minor bugs that we haven't already addressed, please mention them so we can fix them. If you have no suggestions, say so in your entry for this project.

Back to course home page