18-649 Project F.A.Q

Last updated January 12, 2009

*Please submit all project-related questions to -- thanks!

Online File Submissions (for projects)

• 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, proj2, etc).
• 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 project submissions 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 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.
• 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 way.
  
• 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, requirements documents are located in /afs/ece/class/ece649/Public/handin/proj2/group2/ontime/reqs/, etc.
• Wrong 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
• Wrong 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.

Late submissions:

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

• 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 late submission.
• 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 individual TA.

Process Correctness vs. Good Design

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

• 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 road. 
  
• 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

• 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

How do I make a bug report?

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

What happens when bugs in the simulator affect my ability to hand in code that compiles and runs correctly?

Simulator releases at the beginning of a project

Simulator releases between projects

• 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 (according to the grade breakdown for that project) for whatever parts failed to execute properly.
  

Useful Tools

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 gripe@ece.cmu.edu

AFS

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

Version Control

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.

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

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

Text editors

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 editor. Here are a few suggestions for Windows users:

• PSPad - code highlighting and tabbed interface for editing multiple files
• Xemacs - you can install a local copy which may run faster than the X11-over-ssh version
• Netbeans - (see below)

Java

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.  However, you may prefer to do some of your 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
  java -version
  There 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 to test 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 debugging, code 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:

1. 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 class" option.
2. 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.
   
3. 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.

1. In the netbeans project folder (where you see the folders "src" and "nbproject", create a folder called "lib".
2. 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.
   
3. Copy all the class files from the code/simulator/elevatorcontrol/ directory (in the files you downloaded) to this new elevatorcontrol folder.
4. 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.
5. 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 make file.
• 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.
  

HTML / Webpage Editing

• 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 WYSIWYG editor (the "compose" feature).  This is what was used to develop the portfolio templates.  You can download Seamonkey here. You can also download a portable version here (Windows only).  If you add "-edit" to the command line, you can start SeaMonkey in the Compose mode.

Seamonkey Tips

• 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

• 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 cluster machines.
• Many others...
  

A few notes on Dia

1. Using built-in UML primitives. 
   
• 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 diagrams. 
  
• 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 some time.
2. Use the native drawing elements (lines, boxes, etc)
• 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 line tool or the default text size) just double-click the icon in the toolbar for that tool.
  

• 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 exists.  IMPORTANT:  You will then be 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 multi-monitor systems.
• 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