18-649 Project 10

Check the course webpage for due dates

Please submit all project-related correspondence to




In this project, you will develop a network schedule for your design and continue to test your design.


A Recommendation About Design Verification

Runtime monitoring was introduces in Project 7.  In Project 11, you will use runtime monitoring to verify that your design meets the new high-level requirements.  Although you are not required to do so, you should look ahead at the monitoring requirements and think about how you can use monitoring to verify your improved design.  We strongly recommend that you start using a monitor for verification as soon as you have a complete design.  Dispatcher algorithms are very complex and have many corner cases.  You probably won't find all the problems without runtime monitoring.  You should also consider generating additional acceptance tests to further exercise your design.  Again, these are not requirements, but remember that the sooner you identify problems in your design, the easier they are to fix!

RMA Network Scheduling for CAN

Up to this point, the simulator has provided unlimited bandwidth for network messages.  This effectively means that any network message is delivered instantly.  Real CAN networks have limited bandwidth which results in finite delays for messages.
In order to make sure that your system can meet the bandwidth requirements of the network and the timing requirements of the elevator system, you will develop a network schedule using Rate Monotonic Analysis (RMA) with harmonic periods and deadline=period.  Sometimes this is called Deadline Monotonic Analysis or Deadline Monotonic Scheduling.  For details, refer to the lecture material on scheduling and the two CAN lectures.

Network Schedule Overview

The total worst-case bandwidth required by your elevator must be less than 200,000 bits/second.  This means that beginning with this project, you must run your acceptance tests with the additional flag "-b 200".  You do NOT need to execute unit or integration tests with this flag enabled. 

In order to meet the bandwidth requirements, you will need to use network bandwidth efficiently.  This may require changes to your implementation to reduce the bandwidth consumed by some messages.  You may also need to combine some messages.

Message periods/deadlines are specified in the Project 7 writeup and in the code.  You must use the controller period for the period of network messages sent by that controller.  If you wish to change the controller or message periods, you must obtain prior approval of the course staff.

A few notes about optimizing your network schedule:

The reamaining sections describe the structure for the tables you will use to describe your network schedule and analyze its bandwidth requirements.  You will submit these tables with your portfolio.  The soda machine example has a complete network schedule (for that system), so you can see how the two tables have been completed in that case.  Note that we intentionally omit the excel document used to produce the schedule, since this is something you are supposed to develop on your own.

Message Dictionary Table

You will start by constructing a message dictionary table.  You CAN IDs shall have the structure described in the table below.  Fields are listed MSB first, so the Criticality field is bits 28-29 of the message ID:

CAN ID Breakdown Size (bits)
Criticality (always 01) 2
Message ID 11
Sender Node ID 8
Replication ID 8
Total # of bits 29

Note that you may assign arbitrary values for the Message and Source Node IDs within the constraints dictated by the RMA schedule.
Note 2:  In this document, the term "CAN ID" refers to the entire 29 bit message ID specified by the above table.  The term "Message ID" refers to the 11 bit field in the second row of the table above. 

Your message dictionary will be similar to the tables shown in the simulator development overview, although the rows for all messages (even for the module messages) should be contained in a single table. 

The message dictionary table shall have the following columns**:

**IMPORTANT NOTE:  There are a few strict requirements for this table:
  1. The columns must be in the order listed above
  2. The rows in the table must be in ascending order of message deadline (shorter deadlines appear first in the table).  For messages that have the same deadline, they can appear in any order, but the order must be consistent between this table and the Network Schedule Analysis table below.
  3. Each row of the table shall describe a message type and every message shall be included in the table (messages sent by controllers and messages sent by the modules and smart sensors).
  4. The values in the underlined columns also appear in the Network Schedule Analysis table (below).  The two tables must have the consistent values for these columns.

Network Schedule Analysis Table

Next, construct a network schedule analysis table. 

The table shall have the following columns***:

***IMPORTANT NOTE:  There are a few strict requirements for this table:

  1. The columns must be in the order listed above.
  2. Each message (row) listed in the Message Dictionary table must also appear in this table, and the rows must be in the same order. 
  3. The values in the underlined columns also appear in the Message Dictionary table.  The two tables must have the consistent values for these columns.
  4. Columns marked with an asterisk (*) and highlighted in purple must contain an extra row at the bottom that contains the total of all values in the column.
  5. The purpose of "Field X bit length" column is to describe how many bits are actually used to store the information.  You will need to analyze the source code of the translators used the system modules (in the elevatormodules package) to determine the field sizes and formats of those messages.
**** A note on worst-case message length computation:
When computing the worst-case message length, use the bit-stuffing formulas from lecture since they provice the most conservative upper bound.  Even though some hard coded values (like message ID) might not actually be stuffed because of the distribution of 1's, assume that the message IDs are subject to change, so that you can't count on the bit stuff performance of a particular ID value.

Notes on Updating Design and Implementation with The New Network Schedule

You should conduct the analysis above to make your design as efficient as possible.  For example, the provided BooleanCanPayloadTranslator uses a 32-bit payload to send a Boolean value that could be represented in just one bit.  This is extremely wasteful.  The CAN spec specifies that CAN payloads must be a whole number of bytes, so you cannot have a payload with fewer than 8 bits (one byte).  That means that you have reduce the "wasted" bandwidth from 31 bits to 7 bits.  If the controller in question has sends multiple messages that can be combined (and still meet the restrictions above), you could also use these 7 bits to send the other message value.

There is a special challenge to converting numeric values into bit representations for sending.  You should spend some time thinking about what representation (and precision) might be appropriate for the various network messages with numeric values.

In order to meet the bandwidth requirements of the system, you will need to rewrite your message translators to match the reduced the size of the CAN payloads in your network schedule.  At this point, you will need to stop using the BooleanCanPayloadTranslator and IntegerCanPayloadTranslator, which are very inefficient.  You may store data in the translators any way you wish, as long as you send the required information (and no additional information).  Remember that all your code (including translator classes) must be included in the elevatorcontrol package and that no modifications to the rest of the simulator may be included in your submission. 

You will also need to modify the elevatorcontrol.MessageDictionary file with the CAN IDs required by your schedule.

You should consider your completed Network Schedule Analysis to be a specification for your implementation.  It is VERY IMPORTANT that your implementation matches your design.  If you were working in the real world, it would be important to follow the network spec so that other distributed modules could decode your network messages if needed.  This includes:

A few more notes regarding adding, removing, and combining messages and how this can affect your design documents :

*You may only add messages after obtaining permission from a the course staff.

Assignment:

This assignment has two parts:  network scheduling, and complete testing of your design.

Before you begin, be sure you download the latest release of the simulator from the download page.  The new release contains the drive modifications and some necessary upgrades for the network schedule analysis.

1.  Network Schedule

1.1  Make a Network Schedule

Read the discussion about network scheduling above. Fill in the two tables:  Message Dictionary Table and Network Schedule Analysis Table.  You can find a template for the two tables here:  network-schedule-template.xls.  Consult the technical notes page for some Excel hints on constructing these tables. 

After you have finished the new network schedule, add a vanilla HTML version of the Message Dictionary Table and Network Schedule Analysis table to the Network Schedule document in your portfolio.  You should also your completed Excel worksheet and include a link to the excel sheet on the Network Schedule page of your portfolio.  The Excel document you submit must be in Excel 2003 format. 

1.2  Update Design and Implementation

Once you have settled on a schedule that will meet the bandwidth requirement (less than the 200,000 bits/sec), you will need to update your design and implementation as described above.

1.3. Compare your analysis with simulation results

Run one or more acceptance tests with the "-b 200" flag and record the network utilization (you can combine this part with step 2.3 below).  Use the utilization and the the network bandwidth to compute the actual number of bits/s used by the controllers in your design.  Record the simulation results along with the total best- and worst-case total bandwidth in the summary HTML file and include 1-2 paragraphs (no more than 500 words) of discussion that addresses the following points:

Notes: 

2.  Complete Testing

2.1  Complete Unit Testing

Update your unit tests to reflect changes to the CAN IDs and translators in your implementation.  The technical notes page contains a script that can replace the old CAN IDs with the new ones in all your test files with one command. 

Run all unit tests.  For this project, all unit tests must pass (0 failed assertions).  Note that you do not need to specify the "-b 200" flag for unit tests. 

2.2  Write and Execute Integration Tests

First, double check your sequence diagrams to requirements traceability to make sure it is up-to-date.  Make sure your sequence diagrams are consistent with the design changes introduced in project 8 and 9.

If needed, review the Integration Testing section of the Testing Requirements document. 

Once your sequence diagrams are fully up-to-date, you will update your current integration tests and create new integration tests for any additional sequence diagrams that you created for the fast elevator design.  If you have been keeping up with your issue log, it should be easy for you to use it to identify which integration tests need to be created or updated.  You should also make sure that the the traceability comments in all your integration tests are complete and up-to-date. 

When updating your integration tests, make sure you use the new CAN IDs and translators required by changes related to the new CAN network schedule. The technical notes page contains a script that can replace the old CAN IDs with the new ones in all your test files with one command. 

Update your Integration Test Summary File with the new integration tests.  Use the verification script to ensure that the summary file is correct and complete.

When you have completed this part of the project, you should have at least one integration test for every sequence diagram.  Have someone other than the test author complete a peer review of the updated tests and update the peer review section of the Peer Review Log . For this project you must perform at least 4 formal peer reviews and log them although it is encouraged for you to do more if necessary. Remember any peer reviews that result in unfixed issues, should be added to the Issue Log.

Execute your integration tests and record the results in the Integration Test Log.  Note that you do not need to specify the "-b 200" flag for integration tests.  Each test must be syntactically valid (generate no Java runtime errors when executed against your code), but you are not required to pass Integration tests for this project.  You will need to pass these tests next week, so don't blow this part of the project off.

2.3.  Execute Acceptance Tests

You will re-run your acceptance tests (and some new ones) with the new network schedule and the bandwidth limitation of 200,000 bits/s. 

Execute the following tests (make sure you use the "-b 200" command line option) and record the results in your Acceptance Test Log:
You do NOT need to pass these tests (deliver all passengers), but the tests must be able to be run.  There must be no java runtime errors when running acceptance tests (especially those related to the network schedule).

You must have an up to date Acceptance Test Log entry for each test, including a detailed description of the outstanding design issues for any tests that do not deliver all passengers.

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


Grading Criteria:

This project counts as one team grade. Points are assigned as follows.  A detailed grading rubric is available here.
The contributions spreadsheet is available here.

This project assignment is worth 115 points:

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