Overview:

In this project, you and a teammate will modify an active application
running on the CANEs/Bowman active networking platform. As supplied, the
active application provides application specific congestion control (ASCC)
for a simplified image format. Your task will be to enhance the supplied
application and the image decoder in ways that attempt to maximize the
image quality received, while minimizing the load on the network. You will
be given a relatively isolated environment to run your application which
will introduce network delays and losses. You will have the ability to
compete against other teams by posting your performance results on the
class newsgroup.


Timeline:

03/21/02	assignment made available on class website.
03/24/02	initial project plan due no later than 11:59PM Sunday.
03/26/02	TA will return project plans with comments as needed.
03/27/02	TA office hours for project 9-11AM in CoC commons area.
04/03/02	TA office hours for project 9-11AM in CoC commons area.
04/04/02	project due no later than 11:59PM Thursday.


Environment:

You will be developing code in the C language within the CANEs execution
environment (EE) running on the Bowman node operating system (NodeOS).
In this environment, active applications are called injected programs
and are dynamically loaded into a running active node as shared object
files (.so). Applications are loaded into an active node by sending a
signaling message to the node containing the specification for running
the application. In CANEs, we provide the CANEs user interface (CUI),
which specifies a syntax for the signaling message. The CUI includes the
components of the program to be run, parameters to the application, and
a filter specification which determines which packets are to be exposed
to the active application.

Our intention is that you will not need to be concerned with the
administration of the active node or network, instead we will provide you
with a fixed topology on which to run your experiments. Be aware that some
of you will use active nodes running on Solaris and others will be using
Linux. Each team will be assigned a set of machines and a virtual node
number, it is imperative that you only use these resources and no other.
A tar file will be made available containing source code, makefiles,
skeleton configuration files, and scripts for instantiating your topology
and running your tests. 

More information on the environment can be found in the CANEs paper
located on the course web site. Support for the programming environment
and general questions about the project will be provided on the course
newsgroup. You should not discuss your specific solution with others;
instead, visit office hours, or email msanders@cc and rjc@cc directly.


Application:

One example of ASCC is the modification of streaming video flows between
the server and client to reduce the number of frames per second, and/or
the resolution, size, or color granularity of the picture. The goal is
to reduce bandwidth intelligently, to produce better image quality than
randomly dropping packets.

Because video encoding is complicated and would require far more time
than is afforded by this project, we have selected a very simple image
format (ppm) running at very low rates so that you can focus on the
project. While simplified, this format provides you with the same variety
of encoding opportunities, only on a different time and bandwidth scale.
A more detailed description of the ppm format, and the supplied
applications and injected programs, can be found in the
Protocol.Description document in the ppm directory.

Your goals are to:
	0) maximize picture quality. For this project, we measure this
	 by comparing the pixel values sent with the pixel values
	 received. Thus you are also minimizing lost data.
	1) minimize the transfer time of the file.
	2) limit the resources used by your active applications and
         injected programs such as CPU, memory, and network activity.

You may not:
	0) use a topology other than the one provided to you.
	1) use code from other sources.
	2) re-transmit packets from the source.


Getting Started:

0) find a partner and send email to msanders@cc and ewz@cc with both of
   your names.
1) you will then receive your TEAM name, which is the concatenation of
   your SET and VNODE identifiers. SET identifiers [A-D] map to a
   particular four node topology. VNODE identifiers [1-4] map to a
   collection of unique port numbers for your use on the topology.
2) create a working directory and "cd" into it, untar the files with:
	gtar xvzf /net/at71/CANES/build/cs7270/ppm.tgz
3) "cd" into the ppm directory, read the HOWTO.setup file and follow
   the subsequent instructions. The setup script will generate local,
   team-specific versions of the scripts, makefiles, and configuration
   files needed for the project, as well as HOWTO scripts for building
   and running the applications and injected programs.


Grading and Turnin:

There will be three deliverables for this project, a project plan, the
code you have written, and a report. The project plan and source code
can be written and submitted as a team; however each team member is
required to write and submit the report individually. Grades will be
assigned individually based on the following weights:

project plan	 5%
source code	50%
project report	45%

The project plan should be a one paragraph description of how you intend
to complete the project. Some indication of the modifications you plan
to make and the motivation for these modifications should be included.
The paragraph should be submitted to msanders@cc in plain ASCII text
format, not as an attachment, no later than Sunday 03/24/02 at 11:59PM.

To turn in your code, execute "~msanders/pub/turnin ppm", where ppm is
your modified ppm directory. This will send everything in the ppm
directory and all its subdirectories to me, and will "cc:" you so that
you can verify that you sent what you intended to send. The code should
be cleaned of .o, binary, or .so files prior to running the turnin script.
You should include a file called "ppm/MODIFICATIONS" with a list of all
of the files you have modified or added, as well as a description of how
we can run your code.

The report should contain descriptions of at least two modifications to
the application that you have attempted. For each attempted modification
you should include your motivations and reasoning for making the change,
implementation details, design decisions made, challenges encountered,
experimental results, and an analysis of these results. You will be
graded on the technical merits of your attempts, your experimental
method, as well as the creativity you have shown. Negative performance
results should be included in your report, and will not be counted
against you, provided they are based on reasonable assumptions, and your
analysis is objective. Some type of graph comparing the performance of
your modifications to our supplied application should be included. Your
report should be in pdf or gzipped postscript format, readable with "gv"
or "acroread" on a college solaris or linux machine, and should be sent
as an email attachment to msanders@cc.

You are encouraged to share your performance results with other teams via
the class newsgroup. You can also reveal a URL for the image associated
with the results. You may not discuss what changes you have made to the
applications and injected programs. Because of platform differences,
varying system loads, and differences in solutions, you should not be
surprised if these results vary widely between teams. The best opportunity
for team competitions should be between teams with the same SET identifier.