18-649 Project F.A.Q
Last updated January 12, 2009
*Please submit all project-related questions to
Online File Submissions (for projects)
Use the AFS space for handing in assignments:
- File submissions will be made using the course AFS space.
- Handins will be made to the location: /afs/ece/class/ece649/Public/handin/
. You should be
able to access this space when logged in with your ECE username on
any of the ECE systems (e.g. ece000 machines).
- There will be separate subdirectory for each project (proj1,
- Since Project 1 is an individual assignment, the proj1 folder
will contain a folder for each student in the class. Only that
student will have read or write permissions on the folder. Your
will not be viewable by the rest of the class.
- Starting with project 2, all projects will be group
assignments. Within each
project folder will be a folder for each group. You will only have
permissions to access your group's folder. Your project submissions
will not be viewable by the rest of the class.
- Each individual or group folder will contain an ontime/ and late/
subdirectory. You should submit your assignments in the ontime
directory, unless you have missed the deadline. Then you should
use the late/ folder. See the details below.
Starting with project 2, you will download the portfolio
template and build on it throughout the semester.
- For each
project, you will submit the entire portfolio (even the incomplete
parts). We will only grade the parts relevant to the current
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.
- When you submit the project portfolio, you must submit the
portfolio so that the root of the project portfolio is the handin
directory. You may NOT submit a zip file of your portfolio, put
it in a subdirectory, or deviate from these requirements in any other
- Correct example:
you are in group 2 and submitting project 2 on time, so the portfolio
table of contents (portfolio.html) appears in /afs/ece/class/ece649/Public/handin/proj2/group2/ontime/portfolio.html,
located in /afs/ece/class/ece649/Public/handin/proj2/group2/ontime/reqs/,
example: you are in group 2 and submitting project 2 on
time, so you turn your portfolio in as a zip file: /afs/ece/class/ece649/Public/handin/proj2/group2/ontime/group2_proj2.zip
example: you are in group 2 and submitting project 2 on
time, so you turn your portfolio in so that the portfolio is in a
subdirectory of the ontime directory, and the portfolio table of
contents is located in /afs/ece/class/ece649/Public/handin/proj2/group2/ontime/our_portfolio/portfolio.html
It is important that you follow these guidelines because the course
staff may use automated scripts to parse your portfolio directories and
run your elevator code. If you do not follow these guidelines,
you may have points deducted from your score.
glitches can (and probably will) occur during the course of the
semester. We will try to be reasonable, but it is your
responsibility to submit your work on time. You should plan
ahead enough so that you can turn your work in comfortably before the
deadline. Report any problems with the submission as soon as
you are aware of them. Most technical issues, especially those
avoidable with reasonable planning, will not result in an extension
of the deadline.
Late submissions will be treated in accordance with the course
late policy. Within each group's folder, there is an “ontime” and
“late” folder. You should submit your solutions in the
“ontime” folder, which will be locked by the TAs after
the assignment is due. The “late” folder is provided in
case you wish to submit an assignment after the “ontime”
directory has been locked.
Late penalties increase over time. The late penalty assessed
for your handin will be determined by a combination file timestamps and
the time when you send the second email notifying the course staff that
your late submission is ready (see below). If you overwrite or
otherwise update a file, the
latest timestamp displayed on any file will be treated as the hand-in
date and time for
the entire assignment.
If you wish to submit your project late, you must send two emails.
If you fail to follow these steps and
properly notify the course staff, then whatever grading the TAs do for
your project will stand, regardless of what you may later submit.
- You should send email to the staff email list as soon as you know
there will be
a late submission. If the TAs have already graded your ontime
submission when they receive your email, they will NOT regrade your
- You should send the second email as soon as your late submission
is complete so that the TAs know they can lock your late
directory. The late penalty increases quickly, so the sooner you
notify the TAs, the better!
- Be sure to send all emails to the staff list, not to an
Process Correctness vs. Good Design
Why do we grade on process instead of
On any given project, the primary grading criteria will be
whether you followed the design process thoroughly and correctly.
We grade on process because this provides objective grading
criteria. However, it is important to remember that good design
does not guarantee good
process! You could follow the process requirements to the letter
still produce a design that omits significant functional or safety
aspects of the elevator.
Why does good design matter if you
only grade on process correctness?
In addition to the process requirements, you must have a working
elevator at the midterm project and at the final project. A
working elevator passes acceptance tests. That is, it delivers
all passengers and doesn't trigger the emergency break. The
quality of your design is what will determine whether or not your
elevator can pass these tests. That is why the design matters!
Why do I have to follow the
process? Why can't I just get into writing the code?
This project is NOT about writing code. It's not even really
about elevators. The elevator is just a convenient example.
It is about learning to follow a software process and to use that
software process to produce a reliable distributed system that meets
high level (customer) requirements. If you learn the right
lessons, you will see that the code is probably the least important
part of the design, and that the code will practically write itself
once you have completed the other parts of the design.
Also, because one of the process requirements is that the code must
trace to the rest of the design, you will lose significant points if
the code you write doesn't match up with your design, even if you do
somehow manage to pass acceptance tests.
What if I don't believe you? Can
I just scrape by, doing the minimum amount of work to meet the process
requirements? Then when we get to the code projects, I can hack
together a working elevator.
Every semester, there are a couple of teams that take this
approach. These are some of the consequences we have observed:
Wait! I don't know anything
about design or software process! You're making this sound
- It takes a lot more time to
skimp on the design because you have to keep revisiting earlier
phases: Every phase of the project has a forward and
backward traceability requirement to the previous phase. So if
you skimp on your sequence diagrams, you'll find that you have to go
back and revise them when you write requirements. And if your
requirements are skimpy, you'll have to rewrite requirements and sequence diagrams when you
start making statecharts. And when you go to implement your
statecharts, if they are incomplete, you'll have to make changes to the
whole design! Every week, you'll be doing more and more
work. Don't say we didn't warn you!
- It's a lot harder to have
consistent design: All this revising means it's more and
more likely that errors will creep into your process. Then you'll
either leave them in there, where they will come back to haunt you
later, or you'll have to spend even more time going back over the
design end-to-end to catch them. Remember that in the final
project, there is only one bonus award for performance, but every team
is eligible for a bonus if they have a completely consistent design.
- The design is less
reliable: Good process does not guarantee good design,
but without good process, it's almost impossible to do good
design. Each phase of the design process clarifies your
understanding of the elevator function, reduces ambiguity, and gives
you an ordered way to understand a large and complex system. That
means that if you try to do the project "backward", you won't have this
understanding, and the chaos in your code will result in chaos in your
requirements. Even if your system is "mostly working", there will
be elusive bugs that you'll spend a lot of time tracking down.
This project and course is aimed to teach you software process, not
expect you to already be a master designer. Here are some tips to
- Buy in to the process! Don't just say, "that's probably
good enough". Try to think about how real elevators function and
be as thorough as you can at each stage.
- Carefully read the documentation provided (especially the object
descriptions and interfaces in the Requirements I and II
documents). The more familiar you are with the system objects,
the easier you will find the project.
- Remember that in distributed design, the object interfaces are
among the most important parts of the architecture. When you
think about the role an object plays in the system, realize that its
role is dictated by the information that it is allowed to receive and
the information that it must send.
- Discuss the design with your team. Four heads are better
than one! A little time spent at the beginning figuring out what
the elevator should do will save you time and revisions down the
- Keep it simple!
- The first half of the semester is focused on a non-optimized
elevator that provides basic functionality. You'll get a chance
to improve the elevator in the second half. It's good to think
about what improvements you might make, but don't get bogged down in
advanced features until you have the basic elevator working.
- The high level requirements (even the advanced ones) are pretty
basic. If you have time and you want to add some "cool" features
to optimize performance, that's great. But only do the extra
features if you are caught up on your design process. A simpler
elevator that is reliable and is backed by complete and consistent
design documents will get you a better grade than a fancy elevator with
a shoddy or unreliable design.
Simulator Debugging Tips
Here are a few ideas for things to look at when you are having trouble
getting your design up and running in simulation. You can also
consult the simulator debugging page
for more specific tools available in the simulator to help you debug
- Compare your code structure to the examples
provided. If you're having trouble with a specific aspect of the
code (e.g. the timer or the network interface), then use the "find"
feature to find all the parts of the example code that are related to
that object. The Netbeans IDE also provides a "find usages"
feature that is useful.
- Re-read the documentation related to network and physical
interfaces. The proper creation and use of network messages and
physical payloads is a common source of problems.
- Have one or more teammates review your code. Sometimes a fresh
set of eyes can find a problem you are overlooking.
- Don't let your first assumption be that there must be a problem
with simulator, or that by submitting a bug report, that we will debug
your code for you. The simulator code has been vetted by previous
semesters' projects. It's certainly possible that there are simulator
bugs (as demonstrated by the multiple releases), but it's much more likely that the problem
is in your own code, especially early in the semester when you are
still learning how to use the simulator framework. It's also
possible that there is an idiosyncratic behavior (especially in the
passenger objects) that you will have to accommodate in your
design. This is just like the real world.
Bug Handling Policy
We make every effort to
provide you with an accurate, reasonably
bug-free simulator. However, as you will find out, all software
has bugs. This section describes procedures you should follow in
reporting them and how to handle simulator bugs with respect to project
How do I make a bug report?
If you find a bug in the simulator, please notify us as
soon as possible. Include as much detail as you can, such as:
Be as detailed as possible in your bug report. For example, "Line
X in file Y is causing this specific problem. Here is my code and
a specific test case that reproduces the problem." A detailed bug
report is much more likely to get resolved quickly. A generic bug
report like "I can't make Module X work, so there must be a problem
with the simulator." will probably just result in us asking you to come
to office hours for clarification.
- A zip file or tarball containing your entire source code tree
- The exact command line you were using to invoke the simulator,
including the random seed you were using.
- Any input files you were using
- A description of how the problem manifests itself and the
approximate time during the simulation when it does so.
You are encouraged to debug the simulation yourself (to the extent that
you can) and determine the source of the problem. If you believe
you have found a fix, please submit the details of the fix along with
the above information.
What happens when bugs in the simulator affect my ability to hand
in code that compiles and runs correctly?
Note that, ultimately, you are
responsible for the correct function of your elevator simulation.
We will gladly work with you to identify and remove bugs from
the simulation, but do not try to "game the system" by waiting until
the last minute to report a bug to us. It is in your best
interest to report bugs to us as soon
Because of the possibility that there will be bugs in the simulator, we
will likely be releasing newer versions of the code on an ongoing
basis. Most bug fixes and improvements will likely not affect the
compatibility of your code. However, it is possible that a change
will require you to modify your code to maintain compatibility.
Therefore, we have established the following policies related to bugs
in the simulator. Note that you can always visit the download page for a history of code
releases and brief description of the changes in each release.
Simulator releases at the beginning of a project
In general, we will try to wait to release a new version until the
beginning of the next project. For versions released along with
the new project, your group will be responsible for making any
necessary change to make their code function correctly with the latest
version of the simulator.
Simulator releases between projects
If we (or one of the project groups) identifies a serious bug in the
simulator, we may need to release a fix while one of the projects is in
progress. In that case:
For releases more than 48
hours before the deadline:
For releases within 48 hours
of the deadline:
- Your group is responsible for making their code compatible with
the latest release.
- If you elevator will function correctly with the earlier version
and you choose not to update it, then you must make a prominent note in
your portfolio documentation indicating which version of the code your
submission is compatible with.
- As noted above, you are responsible for the correct function of
your simulation. If you choose not to update your code to the
latest release and your elevator does not pass acceptance tests (even
if it is because of the bug), then you will not receive credit
to the grade breakdown for that project) for whatever parts failed to
Here are some recommendations and links for tools that you may find
useful. Please note that we do not support ANY of these tools or
programs ourselves. If you have trouble with a tool, ask a
teammate or classmate. If you are having trouble with
department resources (e.g. AFS) on department supported machines, you
can also send mail to email@example.com
Most on-campus Windows PCs already have your personal AFS space
mounted as a drive letter. Most on-campus linux machines use your
AFS space as your home directory. We recommend that you use the
AFS space for your project development because it is easy to move from
computer to computer and share code with your teammates.
A note on privacy:
You should use the Private folder for your code. Please read the AFS ece wiki page
for information on how to add permissions that will allow your
teammates to view your code. DO NOT put your code
in your Public or home directories. Anyone with AFS access,
including people from other teams, can view these directories.
You can use the OpenAFS
client to access
the AFS space in windows. Sometimes this can be
unreliable. Another simple way to transfer files to AFS space is
the use the 'scp' command (linux) or WinSCP (Windows) to
transfer files to one of the ECE cluster machines like
ece007.ece.cmu.edu (these machines use AFS for your home directory by
Subversion (SVN) is a version control system that is already
installed and configured on most of the campus machines. Once you
create a repository (in your private AFS space), you can check out a
copy of the code, modify it, and submit your changes. The version
control system keeps track of all changes made so you can roll back or
access earlier versions. It also helps you resolve conflicts if
more than one person has modified the same file. SVN has a
significant learning curve, but if you take the time to figure it out,
it can provide significant benefits in helping you keep your code
synchronized and up-to-date.
DO NOT put your code
on GitHub or Google Code. Anyone, including people from other teams, can
view code hosted on these services. This is NOT ALLOWED by course policy.
Note: SVN is useful for
maintaining code files, but the .svn control directories can
significantly to the size of your portfolio directories. Because
space is limited, if you use SVN (or another version control system),
you must turn in a clean copy created
using the export feature. You may be penalized if
your submission includes the version control directories.
- There is an excellent, free O'Reilly book about SVN that you can
read online here.
Some key topics you should read about are list, checkout, commit,
merge, branch, and export.
- TortoiseSVN is a
windows SVN client.
- Here is a tutorial for
accessing SVN repositories over ssh.
Here are a few tips if you keep your SVN repository on an AFS
- If you get an error like "Can't
open file '/afs/ece/class/ece649/Private/repository/db/revprops/0/10':
permission denied", log in to one of the linux machines and
navigate to your repository. Then execute the command "fs
flushvolume". Note that although the Windows OpenAFS client
includes a flushvolume command in the context menu, it does not always
resolve this problem.
- The way ECE servers are configured, if you set up passwordless
authentication (using Pageant or other key file methods), you will NOT
get a Kerberos token, so non-public AFS directories won't be
reachable. The solution to this problem is to use interactive
login methods (Just live with it!), or place the repository on a
machine where you have local disk space allocated. You should NOT
put your repository in a public AFS directory.
The cluster machines have vi and emacs / Xemacs, which are useful
text editors that can be run on the cluster machines in a terminal or
over a forwarded X11 session. If you have your AFS directories
mapped to a local drive letter, you can also used any locally installed
are a few suggestions for Windows users:
Even if you use netbeans for Java, you may find it useful to have a
plain text editor available for writing configuration files and reading
simulator output (stats) files.
- PSPad - code highlighting and
tabbed interface for editing multiple files
- you can install a local copy which may run faster than the
- Netbeans - (see below)
All the project code development is done with Java. In order
to receive credit, your code and tests must compile and run on the
games cluster machines (e.g. chess.lab.ece.cmu.local) as described in
the simulation overview.
own development and testing
on a local machine. This may also be helpful if you are somewhere
with a slow, unreliable, or nonexistent internet connection or if the
cluster is temporarily unavailable. Here are some links and tips
to get you started.
- Java JDK - you can download the Java jdk from here (JDK 6
download). Note that the latest version is JDK 1.6.
You should use the same version as is running on the course machines
(usually the deadmath or games cluster). You can check the
current version with the command
should not be any compatibility issues if you are using a different
minor version (e.g. 1.6.0_17 instead of 1.6.0_20), but always be sure
your code on the cluster before turning it in to make sure you have not
used any classes or features that are not available in the version used
on the department machines.
- Netbeans - netbeans is a full featured and powerful Java IDE
provided (for free) by Sun. You can download a Netbeans installer
that includes the Java JDK. Click here to download: Netbeans
+ JDK 6. Netbeans makes it easy to compile and run the
simulator code. It also has useful features such as interactive
completion, on-the-fly syntax checking and refactoring tools.
Here is a short tutorial on how to get the project code into
Netbeans. These steps were tested on version 6.7.1 (the latest
version as of January 2010), but earlier versions had slightly
different library handling capabilities, so you may have to adjust
these instructions slightly for those versions:
Right away, you'll notice that the project fails to compile. This
is because the simulator download only contains class files (not source
files) for the elevator control objects. Eventually, you will
include these objects yourself. You can avoid this headache by
just using the makefile from the commandline for the early
projects. But if you want to go through the trouble, you can get
Netbeans to see the class files them by executing the following steps:
- Create a new project. Choose "Java" from the categories and
"Java Application" for the type and click Next. Choose a location
and uncheck the "create main
- Navigate to the project directory and find the 'src'
directory. Copy the contents of the 'code' directory from the
elevator simulator codebase into the 'src' folder (which should be
empty if you created the project correctly). After the copy, you
should see the simulator classes appear in the project navigator in
Netbeans. You may need to expand the "src" folder to see them.
- Right click on the project name in the navigator pane and select
'properties'. Go to "Run" and set the main class to
'simulator.framework.Elevator'. Note that you can also set
command line arguments here, and specify the working directory (useful
if you want to use a folder which contains your test files). The
default working directory is the project directory.
A few final tips:
- In the netbeans project folder (where you see the folders "src"
and "nbproject", create a folder called "lib".
- In the "lib" folder, create a subdirectory called
"simulator". In "simulator", create a subdirectory called
"elevatorcontrol". This creates a package hierarchy that mimics
the one in the project framework.
- Copy all the class files from the code/simulator/elevatorcontrol/
directory (in the files you downloaded) to this new elevatorcontrol
- In the Projects overview pane, right-click on the "Libraries"
entry and choose "Add JAR/Folder". Navigate to the "lib" folder
you just created and add it.
- If you followed these directions correctly, you should be able to
compile and run the project. As you create your own source files
for the controllers, you will want to remove them from the "lib"
directory to avoid confusion.
- The make file included with the code uses the -Xlint:all setting,
which generates additional warnings. This is not the default
setting in Netbeans. To add it, right-click on the project (in
the project explorer) and choose Properties. Then go to Build
> Compiling, and add the following to Additional Compiler
Options: "-source 1.5 -O -Xlint:all". This will make sure
that the code compiles the same way in the IDE as it will using the
- Sometimes Netbeans gets confused and will mark a file as having a
compilation error even though the syntax is correct. If this
happens, close Netbeans, go into your user directory, and delete the
.netbeans directory (or, ro be safe, you may want to save a copy of it
elsewhere first). Removing this directory gets rid of Netbeans'
cache, which will usually resolve the problem.
you must submit the source
code only in accordance with the project portfolio
guidelines. You may NOT submit your Netbeans project.
It's up to you to understand which parts of the project are the project
source and which parts are the related to the Netbeans IDE. If
you feel you cannot do this, then you should do your development using
the cluster machines and a basic text editor.
HTML / Webpage Editing
There are numerous HTML editing tools available, and you are free to
use whatever tool you like.
- Remember that you should avoid flashy designs or layouts.
The purpose of the project portfolio is to communicate your design and
project documentation to your teammates and the course staff. Use
the project portfolio
template as a guide for style.
- The SeaMonkey suite (formerly Mozilla Suite) includes a simple
editor (the "compose" feature). This is what was used to develop
the portfolio templates. You can download Seamonkey here. You can
only). If you add "-edit" to
the command line, you can start SeaMonkey in the Compose mode.
- One of the eccentricities of Seamonkey composer is that it
includes the width and height tags with the size of an image, even if
you specify the "Actual Size" option. If you modify the image in
a way that cause its size to change, you'll find the image oddly
distorted because the img tag still has the old image dimensions in
it. To fix this, open the HTML document in Seamonkey
Composer. Right click on
the image and choose "Image and Link Properties". Even if you
don't change any settings, the act of
opening the dialog and clicking Ok will cause Seamonkey to re-read the
image file and assign the correct size to it.
Image Editing Tools
There are several choices for creating and editing UML diagrams.
You will find it easiest if you pick a tool that is available to all
members of your team and use that tool exclusively. This makes it
easier to edit the source files for your images later in the
project. Here are a few suggestions
The example sequence diagrams in the portfolio template were generated
Dia. You are not required to use Dia. Visio is available in
campus labs and there are many other drawing programs out there.
only criteria is that you produce legible diagrams in your portfolio
and in your presentations (although these two types of documents have
different requirements relating to font size). Regardless of the
eccentricities of Dia
or any other tool, you are ultimately responsible for finding a tool
and making it work to produce the required figures.
- Dia - simple, free,
cross-platform diagram editor
- Inkscape - free,
cross-platform vector graphics editor. Note that this tool has
difficulty producing a blue arrow with a blue arrowhead on it.
- Visio - MS windows only. Not free, but available on the
- Many others...
A few notes on Dia
These notes were generated based on our experience with version 0.97
for Windows, but will likely be applicable to other platforms and
versions as well.
There are basically two approaches to making figures in Dia:
- Using built-in UML primitives.
Use the native drawing elements
(lines, boxes, etc)
- There are built in UML objects that have properties associated
with them. In particular, this is handy for the messages in the
sequence diagrams because the message text is attached to the
arrow. This is the approach used in the example
- However, if you use the default objects, note that you cannot
change the font size, so when you try to export your diagrams to
powerpoint, the text will come out too small. You will probably
have to remake (or significantly manipulate) the diagrams to get
something that will look good in your PowerPoint presentations.
You can investigate the WMF export discussed below as a way to save
- If you use the native dia drawing objects (text fields and
lines with arrow endings) then you have more control over fonts and
line widths. This will let you create diagrams with larger fonts
(30 or 40 point seems to be a good choice).
- If you take this approach, you will find it easier to generate
a presentation graphic that meets the presentation requirements, but
the initial setup of the diagrams may be more work.
- To set the defaults for a tool (like adding an arrow to the
or the default text size) just double-click the icon in the toolbar for
- When exporting, the "Export PNG (anti-aliased)" choice works
well. There are several different types of PNG export, and you
are welcome to try them all, but in our experience, this one seems to
work the best.
- If you want a vector format you can import into powerpoint and
manipulate, you can try the .wmf (windows metafile) export. If
you insert a WMF file into powerpoint, you can convert it into drawing
elements, then ungroup the drawing to manipulate individual elements
(e.g. resize fonts).
- In the Export dialog (reached with File > Export), after you
click Save, you will be presented with a warning if the target filename
presented with another dialog asking you about the
dimensions of the saved object. The defaults work quite well, but
you have to make sure you find this dialog and and click Export.
Sometimes it will appear in strange places on the screen, especially on
- Occasionally, when a shape is exported, it will be truncated and
oddly scaled. This appears to be related to a bug when a UML
objects is used to determine the bounding box for the
drawing. If this happens, draw an ordinary rectangle,
change the border to white, and size it so it just larger than the
entire diagram. Then use the Objects > Send To Back command to
place it behind the other diagram objects. This will void the
bounding box bug and allow the diagram to export correctly.
Back to Course home page