|
CSCI P545
Embedded & Real-Time Computing
|
Thu Sep 24 12:57:06 EDT 2009
[SDJ]
|
Lab Reports
Over time, I have posted descriptions and templates to suggest ways
to organize the lab reports. These are just suggestions of ways
you might organize your reports..
These reports are for you!
First, the primary purpose of all written documentation in this class is
to have a record of your accomplishments. Think of the lab
assignments as initial steps in a project whose ultimate goal is exploring
some aspect of autonomous navigation in the real world that interests
you.
The individual assignments, then, are progressively testing some component
of the goal. By the end of the course, you will have accomplished something
significant—even if you go no further&mdasy;so wouldn't it be
of value to have a coherent written record of that accomplishment? b
With this in mind, I suggest writing your reports in such a way that you
can put them together into a coherent "journal" of your work on this project.
System Documentation and Test Reports
Of course, Lab Reports are a means of evaluation. Furthermore, the topic
of "documentation" is important, especially in critical embedded systems.
We will continue to look at aspects of documentation throughout this course.
As a starting point, here are two guidelines on writing I have posted:
- I have
System Documentation Guidelines [PDF]
for projects I supervise. This excerpt specifies the expected outline.
The examples given below follow this outline, because it was included
in the assignment.
- A better way to document individual field tests is reflected in the
Test Report Template [HTM].
In field testing one should
- Develop a Test Plan with specific objectives.
Overall objectives are given in the Lab N descriptions,
but could be refined by describing a sequence of experiments.
- Execute the Test Plan, recording telemetry and
writing down test observations for each objective;
- Afterward, perform a test analysis of the recorded data
and observations. This typically leads to new objectives for
the next round of field-testing.
Examples from 2008.
All examples are organized according to the
System Documentation Guidelines [PDF],
mentioned above, because that was part of the assignment that year..
Presentation of testing alone (as opposed to design and test)
might be easier and clearer using the
Test Report Template [HTM].
- Arun Autuchirayll's Lab 1 Report
[PDF]
is very good. In addition to a nice presentation of test telemetry,
It includes a useful analysis of dynamic characteristics.
- Josh Yeager's Lab 1 Report
[PDF]
is good. It is clear and informative, but does not go as far as
Arun's in analyzing the test results.
- Yassir Ibrahim's Lab 2 Report [PDF]
satisfactory, but not as good as Josh's in terms of clarity and
content.
What to Turn In
Your SVN area should have a directory,
/class/2009/yourid/lab/N
for each Lab N. Put everything associated with performing
the lab in that directory, such as:
- reports (formatting source, PDF copy, figures, etc.). (I ask for all
sources used to generate documentation, so that it can be used
(with attribution of course) in future course materials.)
- program source code used
- raw data recorded
- graphical visualizations, or other analysis tools.
- scripts,
README files,
a Makefile if you use one.
You may structure the directory as you wish,
with sub-directories and so forth, but
- leave a copy (or link) to a report.pdf at the top level where it can be easily found.
A Comment on Source-code (Implementation) Documentation
You should start exploring the Doxygen source code generator tool.
Position in any directory on the CS/Linux network that contains Python (*.py) source and
- Type doxygen -g to generate a
Doxyfile configuration file.
- Type doxygen Doxyfile to generate
directory html/ of formatted,
hyperlinked source-file documents.
- Change some of the Doxyfile
parameters to explore their effects. Suggestion: set parameter
SOURCE_BROWSER = YES
- Here is an example: [HTM]