18-649 Elevator Design Project

Portfolio Layout

*Please submit all project-related questions to

-- thanks!

General Guidelines

You must follow these hand-in instructions.
Deviations from this portfolio structure will result in grading penalties, especially if the deviations break any automated grading scripts used by the TAs.
To receive full credit, all links must be working and all inline images must display correctly.

It is okay to have broken links in pages that are stubs for future projects.
Use the project to portfolio matrix to get a sense of which parts of the portfolio are required for which projects

All files in the portfolio must be reachable via hyperlinks from either the main page or a summary or status page that is linked to the main page.
We do our best to provide thorough information about our expectations. If you are unsure about how to follow these guidelines, reread the project instructions, the Project FAQ, and the Course Administrative Information page. You can also refer to the Soda Machine Example. If you are still uncertain, ask us during office hours.

Change Log

Whenever part of the portfolio is updated, we will make a list of the updates here and post an announcement on Blackboard. For some documents (like the requirements II document), you will probably want to manually copy the changes into your current portfolio. If you have not modified the template, you can just copy the new file from the template into your portfolio.

Dated entries will appear here if the portfolio needs to be updated.
9/26/2013: Fixed typo in reqs/requirements 1 - Output message from DoorControl is mDoorMotor, not mDoorMotorCommand

Portfolio Template

The portfolio template provides a framework of HTML files and directories which you will fill in over the semester. Most of the required files are included in the template, but you will likely add supporting files, such as image files, test files, and test results. The template is intended to be consistent with all the project instructions. If you find a discrepancy between this document and the template or between the template and instructions in some project writeup, please email the staff list to resolve the issue.

The following list shows the subfolders and the contents of each folder. Consult the file stubs in the portfolio template for details. To see how these files are mapped to the projects, check the portfolio-project-matrix.

portfolio.html - annotated table of contents for the portfolio
acceptance_test/

acceptance_test_log.html
this folder also contains acceptance test .pass files and .stats result files.

architecture/

architecture.html - class diagram for the elevator

usecases.html - use cases for the elevator
this folder also contains supporting image files

elevatorcontrol/

package.html
all java code files -- do NOT include .class files in your submission

fault_tolerance/

fmea.html

fta.html

integration_test/

integration_test_log.html

integration_tests.txt
this folder also contains the integration test .cf and .mf files, and .stats result files.

logs/

issuelog.html
improvements.html
peerreviewlog.html
peer_review.xls - a blank peer review checklist

network_schedule/

network_schedule.html

presentations/

This folder contains your mid-term and final presentation

reqs/

requirements1.html - system object descriptions and message dictionary

requirements2.html - controller requirements

scen_sd/

scen_sd.html

This folder also contains sequence diagram images.

traceability/

req_const_traceability.html

sc_code.html

sd_req_traceability.html

unit_test/

unit_test_log.html

unit_tests.txt
This folder also contains unit test .cf and .mf files, and .stats result files.

verify/

verification.html
This folder may also contain other files if you use a method other than runtime monitoring to do your verification.

Formatting Your Portfolio

Except for code files, all of your portfolio submissions shall be in the form of HTML documents with inline images, unless otherwise noted in the project writeups. Your submissions must be formatted as follows:

Your portfolio must be viewable in MS Internet Explorer and Mozilla Firefox
Use relative links, not absolute paths, so that the portfolio files correctly reference each other regardless of their location.
All HTML pages must have descriptive HTML header titles. The title we mean is the one in the head/title HTML tags, as in "<head><title>Descriptive Title</title></head>".
Use "vanilla" HTML in your submissions. Here are some general guidelines, but use common sense. If in doubt, ask a TA before investing long hours creating complex formatting.

Text formatting tags, ordered and unordered lists, and HTML tables are acceptable.
Don't use frames, popout or drop-down menus. Don't use javascript.
Basically, follow the format of the files given in the portfolio template.
We are interested in the content of your portfolio and how you follow the process, not in how attractive your portfolio is.

All images should be in non-animated PNG or 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. JPEG should be avoided because the compression algorithm doesn't handle line drawings very well.

Each inline image shall be enclosed in a link to the image file, so that clicking on the image opens the image file. This is already done in with the example sequence diagrams in the portfolio template if you need an example.

Tables (e.g. for traceability) in your portfolio shall have grid lines between all cells. The grid lines shall be at least 1 pixel and no more than 3 pixels in width. Tables must be readable (readable font size and no extraneous columns or rows that hinder readability).
When an Excel document is required, the excel document MUST be in Excel2003 (.xls) format. Later versions of Excel have the capability to save a backward-compatible format.
You should choose font sizes so that your portfolio is easily readable when printed on a black-and-white laser printer, and in no event smaller than 8 point font as printed on the page. (8 point font has capital letter height of 0.11 inches; 2.8 mm)".

Some of the larger images (such as sequence diagrams) may be too wide to print properly in the browsers listed above. It is acceptable if these are cut off during printing, as long as the image is not cut off because of excessive white space around the image content.

Your portfolio may NOT include version control information (e.g. .svn or .git directories). These add bloat to the project handin directories for no reason. Use a function like svn export to create a clean copy of your portfolio for handing in.

File Headings

Each file in your portfolio shall include a heading with your team information

The heading shall include:

Course name and semester
Group number
Names and andrewIDs of all team members

Headings must be included in all files, including HTML files, code files, simulation output files, and images.
For automatically generated files, you should investigate the -head option in the simulator.
For HTML files, this heading must be included in the body text (so it is visible from the browser), NOT in an HTML comment.
Note: Project 1 is an individual project, and has different heading requirements. See Project 1 for details

Including Code in Your Portfolio

The elevatorcontrol/ subdirectory is where you will include the code for your project. You should include all the java files from the simulator.elevatorcontrol package (even the ones we provided, since you may end up modifying them later). You should not include class files (yours or those provided by the course staff). Make sure that all java files in your handin are listed and hyperlinked in the elevatorcontrol/package.html file, and that each file has a description. Make sure your code files include the appropriate headings.

The portfolio includes logging features that allow the logging for different modules to be turned on and off through the use of verbose parameters and commandline flags. You MUST use this logging framework and you MUST NOT print anything to the command line otherwise. Basically, if the verbose options are disabled, the controllers should not print anything to the screen. The purpose behind this requirement is to keep your code from generating huge log files when we run tests on your elevator, although it is to your advantage to follow these instructions because the logging output slows the tests significantly. If you fail to follow these directions, you may have points deducted from your project grade.

If you want to verify that the grading TAs will be able to compile your code, you can recreate the steps that they will follow when grading your project:

Download the latest required simulator tarball from the course website.
Unpack the simulator.
Copy the entire contents of your elevatorcontrol/ directory (in the portfolio) into the code/simulator/elevatorcontrol/ folder (of the simulator). Make sure you overwrite any of the existing files of the same name with the files from your portfolio.
Run 'make' in the code directory and see if the simulator compiles without errors.
Run any unit, integration, or acceptance tests required by the project writeup.

Complete and Consistent Design

The following is a partial list of the characteristics your portfolio should exhibit:

Changes requested by the TAs in previous projects have been applied.
All documents are complete and up-to-date (to the extent required by each project).
All documents include group # and member names at the top of the document. This includes code, test files, output files, and images.
Individual documents have a uniform appearance. They should not look like they were written by 4 individual people and then pieced together.
Change and defect logs are up-to-date and detailed enough to track changes to the project.

Handing in your Portfolio

You will start out at the beginning of the semester with the portfolio template. You will build on this template every week. For each project, you should submit the entire portfolio (even the incomplete parts). We will only grade the parts relevant to the current project, although the nature of the design process is such that we will be looking back at previous design phases to make sure that your design remains consistent and correct. You will submit your portfolio into the handin directories on the course AFS spaces.

See the Project FAQ for details.

Back to course home page